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

  • The console is started by lockhub’s lox run with its hub flags, as the lockssh account, in a container whose egress reaches only the profile’s SSH host (and Vault, for credentials = "vault"). It refuses to start without its hub.
  • The agent side is the lockssh CLI and the lockssh mcp server, 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

  1. 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.toml loosens nothing.

  2. 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.

  3. 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.

  4. It checks the account. id -u: a root login is refused on production, and asks a typed continue elsewhere.

The life of a request

  1. The agent sends an argv: the program and its arguments, one string each. There is no shell: ;, |, >, $VAR, $(...), *.log and ~ reach the program as literal arguments.

  2. The console matches it against the approved allow rules. A match runs at once (run = "auto", the default).

  3. Anything else is refused (E_NOT_ALLOWED), or, on a profile with exec = true, becomes a signed ticket on lockhub. The agent gets pending with the ticket id, and runs the same argv again with ticket once you decided it in lox run. It runs once, for that agent, under that policy.

  4. The console runs it in an SSH session of its own, as exec followed by the quoted argv: no PTY, no stdin, no forwarding, bounded in time and output.

  5. 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.

Allow rule examples
RuleAllowsNot
uptimeuptimeuptime -p
systemctl status *systemctl status nginxsystemctl restart nginx, systemctl status a b
cat /var/log/*cat /var/log/syslogcat /var/log/../../etc/shadow
ls *ls srcls .., ls -la
git log *git log maingit log --output=/home/u/.bashrc
journalctl --since=*journalctl --since=todayjournalctl --until=now
journalctl -u * -n * --no-pagerjournalctl -u nginx -n 50 --no-pagerjournalctl -u nginx
echo **echo, echo a b cecho -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

What happens to each request
RequestWhat happensAuto rule (default)
an allow rule matchesruns at once; with run = "ask", a ticketrun (auto)
no rule matches, exec = falserefused, E_NOT_ALLOWED; nothing runsnone
no rule matches, exec = truea 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 ticketunmask (ask); never decided by an auto rule
the SSH session’s first usea connect ticket; the first of each console run is yours under the default askconnect (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
Agent commands and MCP tools
CommandMCP toolWhat
lockssh statuslockssh_statusthe console of each profile, its allow rules, exec, the SSH account
lockssh run [--] PROGRAM [ARG]…lockssh_runrun a command (argv, intent, dry_run, ticket, unmask)
lockssh pii listlockssh_pii_listthe PII mask and allow rules in force
lockssh pii add "REGEXP"lockssh_pii_addadd a mask rule: masks more, applied at once
lockssh request "CHANGE"lockssh_request_changequeue a policy change for you; never applied by itself
lockssh logoutend 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

Refusal codes
CodeMeaningWhat to do
E_BAD_ARGVempty program or one starting with -/+, a control character, too many or too long argumentsrewrite the argv
E_NOT_ALLOWEDno allow rule matches and exec is offuse an allowed command, or ask the user for a rule
E_AUTO_DENIEDthe profile’s auto rules deny this actiononly the user changes them
E_UNMASK_OFFclear output is off in this consolework with the masked output, or ask the user
E_STALEthe profile changed after the approvalask again
E_POLICYno policy in force, or it does not parseask 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.
  • :results or 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.