How it works
How lockssh works
Two sides in two OS accounts. Only the console holds the key and opens the SSH connection.
The key or password, the connection, the approved policy and the audit log live in the console account lockssh, in a container of its own. The agent side holds none of them: it sends an argv and gets the exit status and the masked output.
Two sides
agent account (CLI / MCP) lockssh account (console)
lockssh run -- PROGRAM ARG… ──UDS──▶ allow rules ─▶ SSH session ─▶ server
▲ │ no match (no PTY, no stdin)
│ ▼ │
│ ticket ─▶ lox run (you) │
└──── exit status, masked stdout/stderr ◀── mask ◀──────────┘
- The console is started by lockhub’s
lox runwith its hub flags, as thelocksshaccount, in a container whose egress reaches only the profile’s SSH host (and Vault, forcredentials = "vault"). It refuses to start without its hub. - The agent side is the
locksshCLI and thelockssh mcpserver, run as another account. It reaches the console only through its socket, in a volume mounted read-only; the kernel’s peer credentials say who asks.
When the console starts
You approve the policy. The console shows the profile’s policy: host, login, key, allow rules, exec, detectors, limits, auto rules. Later, a change that tightens applies at once; one that loosens waits for you (
:review). An agent that edits.lockssh/config.tomlloosens nothing.It reads the secret. A passphrase or password is asked in its terminal, or read from Vault with a token it asks for. It is wiped after use.
It logs in and checks the host key. A key it has never seen is shown to you and trusted only on your answer (on production, the last 8 characters of its fingerprint, typed). A changed key is always refused.
It checks the account.
id -u: a root login is refused on production, and asks a typedcontinueelsewhere.
The life of a request
The agent sends an argv: the program and its arguments, one string each. There is no shell:
;,|,>,$VAR,$(...),*.logand~reach the program as literal arguments.The console matches it against the approved allow rules. A match runs at once (
run = "auto", the default).Anything else is refused (
E_NOT_ALLOWED), or, on a profile withexec = true, becomes a signed ticket on lockhub. The agent getspendingwith the ticket id, and runs the same argv again withticketonce you decided it inlox run. It runs once, for that agent, under that policy.The console runs it in an SSH session of its own, as
execfollowed by the quoted argv: no PTY, no stdin, no forwarding, bounded in time and output.The output is masked, then returned with the exit status (or the signal, or
timed_out), the truncation flags, the duration and the count of masked values by kind. The request goes to the audit.
The first request of each SSH login (the console’s connection, a reconnection), and the first after the policy changed, also waits for a connect ticket. With the default connect = "ask", the first one of each console run is always yours.
Allow rules
An allow rule is an argv pattern, its tokens separated by spaces. The first token, the program, is always literal, and never a shell builtin or keyword. A token is an exact argument, a glob for one argument (* and ? never match /), or a last ** for the remaining arguments.
A glob never matches an argument that starts with - or + (unless the glob itself starts so, or follows a literal --; the policy review warns on both), and never covers a . or .. segment.
| Rule | Allows | Not |
|---|---|---|
uptime | uptime | uptime -p |
systemctl status * | systemctl status nginx | systemctl restart nginx, systemctl status a b |
cat /var/log/* | cat /var/log/syslog | cat /var/log/../../etc/shadow |
ls * | ls src | ls .., ls -la |
git log * | git log main | git log --output=/home/u/.bashrc |
journalctl --since=* | journalctl --since=today | journalctl --until=now |
journalctl -u * -n * --no-pager | journalctl -u nginx -n 50 --no-pager | journalctl -u nginx |
echo ** | echo, echo a b c | echo -e a |
The policy review warns on a rule that gives a glob to a program that runs code from its arguments (find, awk, sed, less, sudo, env, sh, python…). The list is a safety net, not a complete one. All the rules.
What runs, what waits, what is refused
| Request | What happens | Auto rule (default) |
|---|---|---|
| an allow rule matches | runs at once; with run = "ask", a ticket | run (auto) |
no rule matches, exec = false | refused, E_NOT_ALLOWED; nothing runs | none |
no rule matches, exec = true | a ticket you decide (risk write, prod-write on production) | exec (ask); never auto on production |
the output in clear (unmask) | only once you switched it on in the console; then a ticket | unmask (ask); never decided by an auto rule |
| the SSH session’s first use | a connect ticket; the first of each console run is yours under the default ask | connect (ask) |
Each action takes auto, ask or deny in the profile’s [profiles.NAME.auto] table. deny is enforced by the console whatever decides the ticket. lockssh profile rules prints the rules lox run applies.
Output
stdout and stderr are each cut at max_output_bytes (64 KiB by default) before masking, and flagged truncated. A command running past request_timeout (30 s by default) is killed.
What the profile’s detectors find (card, email, iban, ip, phone, secret by default) becomes a keyed pseudonym, ⟦email:7F3KQ2M9ZD4X⟧; secrets become ⟦secret⟧.
The project’s .lockssh/pii.toml adds mask rules of its own. The agent may add one (lockssh_pii_add): it masks more, so it applies at once. Keeping a value in clear waits for you.
There is no streaming: output is masked whole when the command ends, so commands that never end (tail -f) are out of scope.
From the agent’s side
# The profiles, their allow rules, exec, the SSH account
lockssh status --json
# Run an allowed command; flags come before the program
lockssh run --intent "check nginx" -- systemctl status nginx
# Would it run, wait or be refused?
lockssh run --dry-run -- systemctl restart nginx
# Once the ticket is decided in lox run, the same argv with the ticket
lockssh run --ticket T -- systemctl restart nginx
| Command | MCP tool | What |
|---|---|---|
lockssh status | lockssh_status | the console of each profile, its allow rules, exec, the SSH account |
lockssh run [--] PROGRAM [ARG]… | lockssh_run | run a command (argv, intent, dry_run, ticket, unmask) |
lockssh pii list | lockssh_pii_list | the PII mask and allow rules in force |
lockssh pii add "REGEXP" | lockssh_pii_add | add a mask rule: masks more, applied at once |
lockssh request "CHANGE" | lockssh_request_change | queue a policy change for you; never applied by itself |
lockssh logout | end the console’s SSH session |
All take --profile P when several profiles are configured, and --instance NAME to reach one lockssh lock among several.
Exit codes: 0 ok, 1 refused, denied or failed, 2 no console, 3 usage or configuration error.
Refusals the agent can act on
| Code | Meaning | What to do |
|---|---|---|
E_BAD_ARGV | empty program or one starting with -/+, a control character, too many or too long arguments | rewrite the argv |
E_NOT_ALLOWED | no allow rule matches and exec is off | use an allowed command, or ask the user for a rule |
E_AUTO_DENIED | the profile’s auto rules deny this action | only the user changes them |
E_UNMASK_OFF | clear output is off in this console | work with the masked output, or ask the user |
E_STALE | the profile changed after the approval | ask again |
E_POLICY | no policy in force, or it does not parse | ask the user |
In the console
Reach it with lox attach NAME (detach: Ctrl-P Ctrl-Q), then:
:review: approve a pending loosening of the policy.:status: the console state.:resultsor Ctrl-O: show the clear output, on the console only.:unmask: switch clear output on, so the agent may ask for it on a ticket.:quit: stop the console.
The console serves until logout, :quit, the idle timeout (20 minutes by default) or the maximum session (4 hours by default).
More:
- Usage guide: profiles, allow rules, output, auto rules, every command.
- Docker guide: the image, the launcher, Vault, an agent in its own container.
- Security model: what lockssh enforces, and what it does not.