Locks · lockssh

Decisions

What lockssh guards, what the agent may do over SSH, and why. These are the answers to the design questions of issue #1. Most of them shipped in v0.1.0 (#8); the few that change v0.1.0 are marked change and are tracked in the issue named next to them. security-model.md states the resulting promise; usage.md the configuration.

Requirements (not negotiable) #

The agent's surface #

Output #

Credentials and host keys #

Egress #

One profile is one host:port. The lock's egress gateway (lockhub#123, closed) allows only the endpoints of the reviewed profiles: each profile's SSH host:port, and the Vault address for a profile with credentials = "vault". Bastions (ProxyJump) are out of scope. The lockssh lock type in lox, its compose and its egress are lockhub#133.

Approvals and routing #

• deny refuses before any ticket (E_AUTO_DENIED) in auto and manual mode. The rules are the approved policy's, never the files the agent can edit; lockssh profile rules --json gives them to lox run.
• A chat facade (Slack, Telegram) never answers prod-write, policy-loosen or unlock, and never sees a clear value: lockhub's routing table, which a workspace can narrow only.
• Production defaults: exec off (no writes), clear output off (the console's switch, :unmask or --allow-unmask), root login refused, host key typed.
• Change (#4): on a production profile, auto.exec = "auto" (and the full-auto preset) is refused when the policy loads. v0.1.0 accepts it, so lox run's auto mode could approve a prod-write ticket. A write on production is always a human's decision.

Injection #

• The agent sends a JSON array of strings. At most 64 arguments, 4 KiB each, 16 KiB in all; valid UTF-8; no NUL, control or format character (tab excepted), no U+2028/U+2029; refusals name the argument's position, never its text (E_BAD_ARGV).

• The remote command line is every argument in POSIX single quotes (' written '\''): ;, |, $(…), * stay literal arguments of argv[0].

• Change (#4): argv[0] is a literal program, never a shell builtin. The server's login shell reads the line, and quoting does not stop it from running a builtin named by argv[0]: in v0.1.0 a rule eval * lets the agent send ["eval", "id;rm x"], the line 'eval' 'id;rm x', and eval runs id then rm x. The same goes for exec, command, builtin, ., source, trap, fc, enable, let, alias, typeset/declare and every other builtin that evaluates a string or binds a name. So, in internal/command:

  • Line writes exec before the quoted argv: exec 'eval' 'id;rm x'. exec looks argv[0] up on the PATH and runs that file; it never runs a builtin, keyword, alias or function of that name (there is no /usr/bin/eval: the command fails, exit_status 127). The shell is replaced by the program, so nothing after it in the line can run.
  • Validate refuses an argv[0] that starts with - or + (E_BAD_ARGV), so it is never read as an option of exec itself (exec -c, exec -a).
  • An allow rule whose program is a builtin-only name (the list above, tested) is refused when the policy loads: under exec it could only fail, and the human should see why.

  What exec does not cover: the account's startup files (sshd's bash reads ~/.bashrc), its PATH and the files on it are the host's configuration, outside the lock's reach.

• An allow rule matches the argv, not the line, so a quoted ; never makes a second command match.

• What a program does with its arguments is outside the lock's reach. The two rules below take the generic routes away (an option the human never wrote, a path that climbs out); the warning after them covers the programs whose plain operands are code.

Allow-rule globs #

In v0.1.0 a glob token is path.Match on the whole argument: * and ? stop at /, nothing else. That lets a "free read" (auto.run = "auto") write or climb out:

Change (#4), both in internal/command (Rule.Match), for every glob token (*, ?, […]) and for every argument a last ** covers:

1. No options. A glob never matches an argument that starts with - or +, unless the token itself starts with the same character (--since=* matches --since=today, +%* matches +%F; -* matches any option, and the policy review warns on it, below). + is in the rule for every program, not for a list of them: less +!id, more +cmd, vim +'!id' and ex +cmd run a command, and a rule that wants one (date +*) is easy to write. An option the agent may set is one the human wrote. Exception: after a literal -- token in the rule, globs and ** match operands, and an operand may start with - or + (the program reads everything after -- as an operand). ** without a literal -- before it matches no option either: echo ** allows echo a b, not echo -e a.
2. No . or .. segments. A glob-matched argument, split on /, is refused when a segment the glob covers is . or ... A segment the rule spells literally is the human's (cat ../x allows ../x). cat /var/log/*/*/* then allows /var/log/nginx/old/error.log, never /var/log/../../etc. Symlinks on the host are outside the lock's reach: a link under /var/log reads wherever it points (the security model says so).

A refusal is the usual E_NOT_ALLOWED; with exec = true the command becomes an exec ticket like any other unlisted command. The policy review shows the rules unchanged. The comment in Rule.Match said * keeps /var/log/* from reaching /var/log/../../etc/shadow: true for one *, not for /var/log/*/*/*; this PR corrects the comment, #4 the behaviour. #4 updates usage.md's glob table and examples with the two rules and adds their tests (a table of the arguments above, each refused).

Programs that run code from their arguments #

The two rules close options and climbing; they cannot close a program whose plain operand is a program or a script (sed -n * f with 1e id, awk * with BEGIN{system("id")}, env * with sh). Change (#4): the policy review warns on an allow rule that names one of these programs with any glob or **, and on any rule, whatever its program, that lets a glob choose an option: a token starting with - whose glob character comes before any = (-*, --*, -[a-z]), or a glob or ** after a literal --. It is a warning, the human's call, as v0.1.0's documentation already says; the list is a fixed table in internal/command, matched on the program's base name (/usr/bin/sed is sed) with a version suffix stripped: a last run of digits, ., - and _ that starts with a digit (python3.11, perl5.36, php8.2, node18, lua5.4, sqlite3 match python, perl, php, node, lua, sqlite). It is not a prefix match: sh must not match shred, nor at attr. Tested with those names.

The table is a safety net, not a complete list. No list of programs can be: a host has its own interpreters, wrappers and tools, under names nobody can predict. A program missing from the table gets no warning, and that says nothing about it being safe. For every program in the table, and for any program whose arguments can be code, the rule stays literals only: the human writes each argument, no glob and no **. The warning reminds; it does not decide.

Rule 1 closes most of the option routes in the table by itself; the warning stays for the ones it cannot (operands that are code, a rule that writes -* or a literal -- before a glob).

Image ids #

Console lockssh uid 10041, group lockssh-clients gid 10040, image agent uid 10042; free in lockhub's Kinds and lea's image. Shipped in v0.1.0.

lockkit #

Nothing missing for lockssh: lockkit v0.14 has the SSH tunnel with sessions (tunnel.Tunnel.NewSession), host-key confirmation, the PII pipeline, hub tickets with never_auto, the policy review and the audit. Streaming is not needed (above). What lockssh still needs is lox support (lockhub#133).

Left to do, by issue #

Recommended order: #4 (the production refusal first), #5, a pre-release (#6, #11), then lockhub#133, then #7's site and the lox add lockssh quick start.