Security
Security model
The promise is narrow: the agent never holds the SSH key or password, never opens an SSH connection, and runs only what you allowed, with the output masked before it leaves the console.
You approve the policy and decide every ticket your auto rules leave to you in lox run, outside the agent. The console runs in an account and a container the agent cannot read or drive.
Skills, rules and MCP tool descriptions only guide the agent; the console’s checks are the guarantee. This page summarises the full security model.
Parties
| Party | Holds | Can |
|---|---|---|
| You | the console’s terminal, lockhub (lox run) | approve the policy and its loosenings, decide tickets, trust a host key, unmask |
The console (lockssh account, own container) | the key or password, the SSH connection, the approved policy, the audit log | run an argv on the host, mask its output |
The agent (lockssh-clients, or an --allowed-uids uid), run confined | a socket in a read-only volume | ask the console; propose a policy change |
| The server | the SSH account’s rights | run what it is sent |
The boundary between the agent and the console is the operating system’s: separate accounts, the kernel’s peer credentials on the socket, separate containers. The lockkit console framework holds it; lockssh adds the SSH side.
What lockssh enforces
| Guarantee | Enforced by |
|---|---|
| The key never reaches the agent | it lives in the console account’s home volume (no group or other permission bits, refused otherwise); a passphrase or password is asked by the console or read from Vault; a key passphrase is wiped after use, an SSH password too but for the string copy the SSH library needs; nothing the agent reads (the socket volume, the project, a result, an error, the audit log) carries it, and errors are scrubbed |
| No shell syntax from the agent | an argv, never a command string; every argument quoted in POSIX single quotes and the line run through exec, so argv[0] is always a program (looked up on the host’s PATH unless it holds a /), never a builtin, keyword, alias or function; control and invisible characters refused |
| Only allowed commands run unasked | the approved allow rules; anything else is refused, or on exec = true waits for a signed ticket bound to the argv, the agent and the policy fingerprint, and runs once; you decide it, or lox run does when a non-production profile sets auto.exec = "auto" (refused on production) |
| Confined agents only | the console serves only an agent that reports running confined (in a container, no host container runtime socket, no Lock Family state); the report is the client’s own, sent in its handshake; a non-production profile with unconfined = true serves one anyway (a loosening you approve, a red banner, audited); a production profile with it does not start |
| The policy is yours | the approved policy is the one in force; a loosening of .lockssh/config.toml waits for your :review; the agent can only queue a change request |
| Bounded runs | one SSH session per command, with no PTY, no stdin, no port, agent or X11 forwarding and no subsystem; a timeout (then SIGKILL) and an output cap per stream |
| Masked output | every byte of stdout and stderr goes through lockkit’s detectors before it leaves the console; clear output needs your switch in the console and a decided ticket, never an auto rule, except the values a PII allow rule of the approved policy names (never a secret) |
| Pinned host keys | an unknown key is trusted only by you, on the console; with a known_hosts file the profile names, it is refused; a changed key is always refused |
| Audit | every run, refusal of a run and decision in an append-only, hash-chained log, never the output (a dry run is not logged); the command is masked with a fixed set (secret, email, phone, IBAN, card), so an IP address or a custom-masked value in an argument is logged in clear |
No shell, no climbing, no options
The remote line is exec followed by the quoted argv: exec 'systemctl' 'status' 'nginx'. Nothing after it in the line can run, and an argv[0] that starts with - or + is refused.
In an allow rule, a glob never matches an argument that starts with - or +, unless the glob itself starts with that character (-*, +%*) or follows a literal --; the policy review warns on both. So it cannot choose an option you never wrote: git log * does not allow git log --output=/home/u/.bashrc. A glob never covers a . or .. segment, so cat /var/log/* does not reach /etc/shadow.
The SSH account’s login shell must be a POSIX shell (sh, dash, bash, ksh, zsh): another one may read the quoted arguments differently.
Production profiles
- A command outside the allow list is a write, and a write on production is always a human’s decision:
auto.exec = "auto"(andauto = "full-auto") is refused when the policy loads. - Its tickets carry the
prod-writerisk. - Trusting a new host key takes the last 8 characters of its fingerprint, typed.
- A root login is refused.
What is not masked
The default detectors find cards, emails, IBANs, public IP addresses, phone numbers and secrets (password=..., tokens, PEM keys, URL userinfo). They do not find person names, postal addresses, free-text personal data, or secrets without a known shape or label: those reach the agent.
Command output can be anything. Prefer commands whose output you know (status, counts, metrics) over reading files, and add mask rules for the project’s own identifiers in .lockssh/pii.toml.
What Docker does and does not separate
The agent’s container holds no key, has no SSH connection and reaches the console only through the socket. A process that is neither the console account nor in lockssh-clients (nor an allowed uid) is refused, and so is an agent that does not report running confined.
Your own account is another matter: whoever can run docker commands can attach to the console, exec into it or open its home volume. An agent that runs shell commands as you usually can. The console refuses an agent that does not report running confined (in a container of its own without the Docker socket, as lea runs it), but the report is the client’s own: a process of your account can lie in it. Details.
What lockssh does not do
- It does not know what a program does. A program that runs other programs or writes files from its arguments (
find -exec,awk,less,vim,tar,sudo,env,sh -c,xargs,gitwith hooks) turns a narrow rule into a shell. Allow such programs only with literal arguments. The policy review warns; its list is a safety net, not a complete one. - It does not resolve paths on the host. A rule’s path is text: a symlink under an allowed directory reads wherever it points.
- It does not confine the SSH account. What a command can do is what the account can do: give it only the rights the allow list needs.
- It does not mask what its detectors miss (above).
- It does not prevent exfiltration by an allowed command. An allowed command that sends data elsewhere (
curl, a mail command) does so. - It does not separate you from your own account (above).
Read the source documents:
- docs/security-model.md: the security model in full.
- docs/decisions.md: each design decision and its rationale.
- SECURITY.md: how to report a vulnerability.