linbit-tunl: Security at a glance

A short, customer-facing summary of the trust model behind a linbit-tunl session. For the full analysis -- including the relay-operator perspective, the API surface, brute-force defences, and known limitations -- see security.html.

Two parties, one shared session

Two principals share an interest in a session:

• The customer -- grants access, wants control over what the relay and support can do, and wants to be able to audit it later.
• LINBIT support -- needs enough access to diagnose and fix the customer's system.

The relay is operated by LINBIT. In share mode it is not trusted to enforce access limits on its own: every command the relay sends must pass through an allowlist on the customer side, in code the customer can read. If the relay were compromised tomorrow, the limits below would still hold.

What a third party cannot do

A third party is anyone who is neither you nor a LINBIT support engineer -- a random internet host, an unrelated customer, a compromised website. They cannot:

• Reach the relay's per-session broker socket. It lives on the relay's local filesystem and is not exposed to the network.
• Authenticate to the relay as support without a LINBIT-managed SSH key.
• Impersonate the relay to your script. Every connection your script makes pins the relay's host certificate to the LINBIT Host CA that ships with the linbit-tunl package.

The session ID itself is not a secret -- it is spoken aloud on support calls. What an attacker who learned the ID could actually do is covered in the caveat below.

What the relay can and cannot do

Even a compromised relay can only do what the customer-side allowlist permits. The allowlist is enforced by your local linbit-tunl script, on your machine, under your account.

A relay (compromised or not) can:

• Request a screen snapshot (returns the current visible content; harmless).
• Inject keystrokes into the main shell pane or the chat pane -- the two panes you can already see.
• Resize the tmux window.
• Write text into the chat-pane status header (visible to you).
• In default share mode: ask for a reverse-tunnel upgrade, which pops up a Grant/Deny confirmation on your screen.

A relay cannot:

• Create new tmux sessions, windows, or panes outside the two you see.
• Send keys to a pane the producer did not register.
• Issue arbitrary tmux commands.
• Read your local audit log.
• Hide or suppress the chat pane's status header. It is rendered by your local script, not by the relay.

In --restricted mode the allowlist is tighter: keystroke injection and tunnel upgrades are both refused.

What is recorded

Every session is recorded. The customer-side recording lives on your machine; the path is printed at session end. The relay also keeps a recording, the chat transcript, and a short audit log of open/close/tunnel events.

Password prompts and other no-echo input are not in the recording. When the kernel terminal layer disables echo (during sudo, ssh, password prompts, etc.), keystrokes never make it into the terminal output stream and so never reach the cast file.

What you can audit afterwards

• Your local cast file -- a faithful replay of everything visible in the shared pane.
• The chat transcript.
• Your local ssh.log under the session's temp directory -- timestamped, append-only, includes every command the relay sent you and whether it was accepted or dropped.

These are yours to keep and to share (or not) on your own terms.

Session-ID secrecy: an honest caveat

The four-word session ID is what your script presents to the relay's tunl SSH user. A third party who learned the session ID before you connected could authenticate as tunl themselves and impersonate a customer to support.

Two important consequences to be clear about:

• That third party still cannot reach your machine. The producer end of the relay is the customer side; the relay has no channel into a customer host that has not chosen to open one. An attacker with the session ID gains a path to the support engineer, not to you.
• The realistic attack in that case is social engineering against the support engineer (capturing what they type, rendering misleading content on their terminal). The mitigation is operational: support should confirm out-of-band ("Are you on the call? Did you start the session just now?") before doing anything sensitive in a freshly attached session.

For the full threat model -- including the relay's brute-force defences, the support-side authentication path, the API surface, and known limitations -- see security.html.