diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index baab52c..87e4390 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,8 @@ Participation is governed by the [code of conduct](CODE_OF_CONDUCT.md). Releases are built by GoReleaser (`.goreleaser.yaml`) when a `v*` tag is pushed: `.github/workflows/release.yml` runs the unit tests, then builds linux and darwin on amd64 and arm64, signs `checksums.txt` with cosign -(keyless), attaches an SBOM per archive and the Linux packages. A tag +(keyless) and attaches an SBOM per archive (no Linux packages: lockssh +runs in Docker). A tag with a semver pre-release suffix (`v0.3.0-rc.1`) is published as a GitHub pre-release; any other tag (`v0.3.0`) is a full release, marked Latest (GoReleaser's `prerelease: auto`). To check the configuration locally diff --git a/README.md b/README.md index 0479b42..29cafbd 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,14 @@ harness security for AI agents. Allow-listed commands run at once, the rest waits for you, and the SSH key never leaves the console. It works with any MCP client (Claude Code, Codex, Cursor, Gemini CLI, …) or -through the `lockssh` CLI. +through the `lockssh` CLI, run confined (as lea runs agents). > [!NOTE] > **0.x**: flags and the policy format may still change between minor versions. v0.3.0 is the latest release. `lox add lockssh` and `lox run` > serving it ship in lockhub v0.11.0 -> ([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)); an -> older `lox` does not know lockssh. +> ([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)), and +> lockssh v0.3.0's confined agents in v0.12.0; an older `lox` does not know +> lockssh. ## Why lockssh @@ -66,7 +67,7 @@ brew install davidgodefroid/tap/lockssh The formula installs the `lockssh` launcher and pins the release images by digest, checked with cosign when the formula was bumped. Upgrade with `brew upgrade lockssh`, not `lockssh update`. The `lockfamily` meta formula -installs the whole family, lockssh included, with lockhub's `lox` v0.11.0: +installs the whole family, lockssh included, with lockhub's `lox`: ```sh brew install davidgodefroid/tap/lockfamily @@ -94,9 +95,10 @@ launcher, which runs every command in the signed image ## Quick start -It takes lockhub's `lox` v0.11.0 or later, the first that knows +It takes lockhub's `lox` v0.12.0 or later: v0.11.0 is the first that knows the lockssh lock type -([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)): the +([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)), and +v0.12.0 the first that supports lockssh v0.3.0's confined agents. The console runs hub-attached only, and an older `lox` cannot start it. 1. In your project, write a `lockfamily.yaml` with the hub alone (once): @@ -112,7 +114,7 @@ console runs hub-attached only, and an older `lox` cannot start it. lox add lockssh ``` - It pins lockssh v0.2.0, runs `lockssh profile add`, `lockssh init claude` and `lockssh doctor` + It pins the latest signed lockssh release, runs `lockssh profile add`, `lockssh init claude` and `lockssh doctor` for you, declares the lock in `lockfamily.yaml`, offers to copy your key into the console's home, and shows the lock's review as it starts. Another agent: `lockssh init codex`, `lockssh init cursor` or `lockssh init gemini`. @@ -154,8 +156,8 @@ the agent's account, the socket, a result, an error or the audit log. **✅ Allow rules, no prompt**
`systemctl status *`, `journalctl -u * -n * --no-pager`: a command an allow -rule of the approved policy matches runs at once. Globs never cross `/`; -the program is always literal. +rule of the approved policy matches runs at once. `*` and `?` never cross +`/`; the program is always literal. @@ -182,7 +184,7 @@ public IPs, cards, IBANs, phones, secrets. ## How it works 1. `lox run` starts the console in its own container, as the `lockssh` - account, with an egress to the profile's host only (lockhub v0.11.0 or later, + account, with an egress to the profile's host only (lockhub v0.12.0 or later, [lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)). It shows the profile's policy for approval, logs in over SSH (trusting the host key only on your answer), and checks the account. 2. The agent's `lockssh mcp` (or CLI) runs as another account and reaches @@ -220,7 +222,8 @@ The same value gets the same pseudonym for the whole console run, so the agent can still correlate; the next run draws new ones. Clear output needs your switch in the console and a decided ticket, never -an auto rule. +an auto rule, except the values a PII allow rule of the approved policy +names (never a secret). ## Safety model diff --git a/SECURITY.md b/SECURITY.md index 4e0b626..0860709 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -27,9 +27,11 @@ The threat model is in [docs/security-model.md](docs/security-model.md). Issues of interest include, among others: - a way for a client (CLI or MCP) to run a command no allow rule of the - approved policy matches without a human's decision, to run a decided - ticket twice or with another argv, or to loosen the policy without - confirmation; + approved policy matches without a human's decision where the profile's + auto rules require one, to run a decided ticket twice or with another + argv, or to loosen the policy without confirmation; +- an agent that reports running unconfined served by a profile without + `unconfined = true`; - an argv that the server's shell reads as more than one simple command (quoting), or any way to open a PTY, a shell, a forward or a subsystem; - the SSH key, a passphrase or a password reaching the agent's side, argv, @@ -49,7 +51,9 @@ of scope, as documented in the threat model. `scripts/install.sh` and `lockssh update` check the cosign signatures of `checksums.txt` and of the image `ghcr.io/davidgodefroid/lockssh:X.Y.Z` against the release workflow run for that tag, then pin the launcher to the -verified image digest. To check the image by hand: +verified image digest, unless cosign is absent and `LOCKSSH_SKIP_COSIGN=1` +is set (then only the archive checksum is checked, and the image runs by +its tag). To check the image by hand: ```sh cosign verify \ diff --git a/docs/configuration.md b/docs/configuration.md index 3ad7a7c..ab52d5c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -60,14 +60,23 @@ known_hosts = "/etc/lockfamily/known_hosts" limits = { max_session = "2h" } [lockssh.profiles.prod-web] -host = "web1.corp.example" -user = "ops" -key = "/etc/lockfamily/lockssh/id_ed25519" -known_hosts = "/etc/lockfamily/known_hosts" -production = true -allow = ["uptime", "systemctl status *"] +host = "web1.corp.example" +user = "ops" +key = "/etc/lockfamily/lockssh/id_ed25519" +known_hosts = "/etc/lockfamily/known_hosts" +production = true +credentials = "vault" +vault_path = "secret/data/lockssh/prod-web" +credentials_ttl = "1h" +allow = ["uptime", "systemctl status *"] +auto = { unmask = "deny" } ``` +A managed profile must sit within the bounds itself: `vault.required` +needs its `credentials = "vault"`, the `credentials_ttl` bound a TTL, and +an action left at its default counts against an `auto` ceiling (an unset +`unmask` is `ask`, looser than `deny`). + ### Bounds `[lockssh.bounds]`: every key is optional; a key left out bounds nothing. diff --git a/docs/decisions.md b/docs/decisions.md index 05d6893..c3a29ec 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -2,8 +2,8 @@ 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](security-model.md) +v0.1.0 (#8); the few that changed v0.1.0 are marked **change (shipped)** +with the issue that shipped them. [security-model.md](security-model.md) states the resulting promise; [usage.md](usage.md) the configuration. ## Requirements (not negotiable) @@ -12,26 +12,26 @@ states the resulting promise; [usage.md](usage.md) the configuration. |---|---| | The console runs **apart from the agent**: its own account (`lockssh`, uid 10041) and container, started by `lox run` only (hub-attached, as every lock since lockkit v0.13). The agent reaches it through a socket in a read-only volume, as `lockssh-clients` (gid 10040), the image's `agent` (uid 10042) or an `--allowed-uids` uid; the kernel's peer credentials say who asks. | `Dockerfile`, `scripts/lockssh`, `cmd/lockssh/console.go` (lockkit `console.Run`) | | **The agent never holds the credential or the connection.** The key or password lives in the console account only; nothing the agent reads (socket volume, project, result, error, audit) carries it. | `internal/sshconsole/connect.go`, lockkit `tunnel`, `secrets`, `sanitize` | -| **No shell from the agent.** An argv, never a command string; every argument quoted for a POSIX shell and the line run through `exec`, so argv[0] is always a program on the host's `PATH`, never a shell builtin, keyword or function; control and invisible characters refused. | `internal/command` | +| **No shell from the agent.** An argv, never a command string; every argument quoted for a POSIX shell 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 shell builtin, keyword or function; control and invisible characters refused. | `internal/command` | | **Fail closed.** No approved policy, an unknown action, a host key that does not match, a server that closes without an exit status: refused. | `internal/config/auto.go` (`Rule`), `internal/sshconsole` | -| **Every byte the agent reads is masked**, unless a human decided a clear-output ticket on a console where clear output is switched on. | `internal/outmask`, `internal/sshconsole/handlers.go` | +| **Every byte the agent reads is masked**, unless a human decided a clear-output ticket on a console where clear output is switched on, or a PII allow rule of the approved policy names the value (never a secret). | `internal/outmask`, `internal/sshconsole/handlers.go` | ## The agent's surface | Question | Decision | Rationale | |---|---|---| | What runs on the host | **One argv per request**, in an SSH session of its own: no PTY, no stdin, no environment from the agent, no port, agent or X11 forwarding, no subsystem. Never an interactive shell. | A session per command keeps each run bounded and audited on its own; without PTY and stdin nothing can turn it into a shell. | -| Free reads | **The profile's allow list.** A command an allow rule matches runs at once when `auto.run = "auto"` (the default): the human approved the list in the policy review. A rule is a literal program and one pattern per argument (`*`, `?`, `[`; `*` and `?` never match `/`), a last `**` for the rest. **Change (#4):** a glob never matches an option (an argument starting with `-`) or a `.`/`..` path segment; see [Allow-rule globs](#allow-rule-globs). | Free reads are what makes the lock useful (status, logs, counts); the list is the human's and the program is never a glob. | -| Other commands | **Refused (`E_NOT_ALLOWED`)**, or on a profile with `exec = true` a ticket for the human (`lox run`), bound to the argv, the agent and the policy fingerprint, run once. `exec` is off by default. | A command outside the list may change the host: it is a write. | +| Free reads | **The profile's allow list.** A command an allow rule matches runs at once when `auto.run = "auto"` (the default): the human approved the list in the policy review. A rule is a literal program and one pattern per argument (`*`, `?`, `[`; `*` and `?` never match `/`), a last `**` for the rest. **Change (#4, shipped):** a glob never matches an option (an argument starting with `-` or `+`) unless the glob starts with that character or follows a literal `--`, nor a `.`/`..` path segment; see [Allow-rule globs](#allow-rule-globs). | Free reads are what makes the lock useful (status, logs, counts); the list is the human's and the program is never a glob. | +| Other commands | **Refused (`E_NOT_ALLOWED`)**, or on a profile with `exec = true` a ticket for the human (`lox run`; on a non-production profile with `auto.exec = "auto"`, `lox run`'s auto mode decides it), bound to the argv, the agent and the policy fingerprint, run once. `exec` is off by default. | A command outside the list may change the host: it is a write. | | File transfer (scp, sftp) | **Out of scope.** lockssh opens no subsystem and has no upload or download verb. SFTP reads are lockfile's (an `sftp` source); a file the agent needs to write goes through a command on an `exec` ticket. | lockfile already masks and gates file reads; a second path would need its own rules for paths and sizes. | -| MCP tools | `lockssh_status`, `lockssh_run` (with `unmask` for a clear-output ticket), `lockssh_request_change`; **add** `lockssh_pii_list` and `lockssh_pii_add` (#4). No separate host or unmask tool: status lists the profiles, unmask is a property of a run. | As the sibling locks; the PII allow list is the one piece of locksql's surface lockssh still lacks. | +| MCP tools | `lockssh_status`, `lockssh_run` (with `unmask` for a clear-output ticket), `lockssh_request_change`, `lockssh_pii_list` and `lockssh_pii_add` (#4, shipped). No separate host or unmask tool: status lists the profiles, unmask is a property of a run. | As the sibling locks; the PII rules complete locksql's surface. | ## Output | Question | Decision | Rationale | |---|---|---| -| Masking | stdout and stderr, in full, go through lockkit's detectors (default `card`, `email`, `iban`, `ip`, `phone`, `secret`) before they leave the console: keyed pseudonyms, `⟦secret⟧` for credentials. The command is masked on screens and in the audit. | Command output can hold anything; masking happens where the agent cannot read. | -| Bounds | Per command: `request_timeout` 30 s (ceiling 10 min; then SIGKILL and the session closed), `max_output_bytes` 64 KiB per stream (ceiling 512 KiB), kept from the start, the rest counted and flagged truncated. Per session: `idle_timeout` 20 min, `max_session` 4 h. | A command that never ends or floods its output must not hold the console. | +| Masking | stdout and stderr, in full, go through lockkit's detectors (default `card`, `email`, `iban`, `ip`, `phone`, `secret`) before they leave the console: keyed pseudonyms, `⟦secret⟧` for credentials. The command is masked on screens and in the audit with a fixed set (`secret`, `email`, `phone`, `iban`, `card`), not the profile's detectors nor the `pii.toml` mask rules. | Command output can hold anything; masking happens where the agent cannot read. | +| Bounds | Per command: `request_timeout` 30 s (ceiling 10 min; then SIGKILL and the session closed), `max_output_bytes` 64 KiB per stream (ceiling 512 KiB), kept from the start, the rest dropped and the stream flagged truncated. Per session: `idle_timeout` 20 min, `max_session` 4 h. | A command that never ends or floods its output must not hold the console. | | Non-zero exit | **A result, not an error**: `exit_status`, or `signal`, or `timed_out`, with the masked stdout and stderr and their truncation flags. Errors are for refusals and failures of the lock itself. | The agent needs a failing command's stderr to do its job; it is masked like stdout. | | Streaming | **None.** Output is buffered, masked whole, returned when the command ends. Commands that never end (`tail -f`) are out of scope. | A detector needs the whole value; chunking would split a secret across two pieces. lockkit needs nothing new for this. | @@ -39,7 +39,7 @@ states the resulting promise; [usage.md](usage.md) the configuration. | Question | Decision | Rationale | |---|---|---| -| Where the credential is | A private key in the console account's home volume (0600, refused otherwise), unencrypted (`credentials = "none"`) or with a passphrase; or a password. Passphrase or password asked at start (`ask`), read from the keychain or from Vault; wiped after use. | The siblings' `credentials` modes; the agent never sees a prompt. | +| Where the credential is | A private key in the console account's home volume (no group or other permission bits, refused otherwise), unencrypted (`credentials = "none"`) or with a passphrase; or a password. Passphrase or password asked at start (`ask`), read from the keychain or from Vault. A passphrase is wiped after use; a password too, but for the string copy the SSH library needs. | The siblings' `credentials` modes; the agent never sees a prompt. | | Forwarding | **No agent forwarding, ever**, nor port or X11 forwarding. | A forwarded agent socket on the server is a credential the server's other users can use. | | Host keys | Pinned per profile: with a `known_hosts` file the profile names, an unknown key is **refused**; with the console account's default file, an unknown key is trusted **only by the human on the console** (`yes`, or on production the last 8 characters of the fingerprint typed), never by a ticket or a chat facade. A changed key is **always refused**. | The human must be able to start on a new host; nothing the agent or a remote approver does can trust a key. | | The login | `id -u` at login; a root login is refused on production and asks a typed `continue` elsewhere. The account's login shell must be a POSIX shell (sh, dash, bash, ksh, zsh): another one may read the quoted arguments differently (never as a second command). | What a command can do is what the account can do. | @@ -71,7 +71,7 @@ lockssh lock type in lox, its compose and its egress are lockhub#133. - **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 +- **Change (#4, shipped): 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. @@ -84,7 +84,7 @@ lockssh lock type in lox, its compose and its egress are lockhub#133. 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.** +- **Change (#4, shipped): 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 @@ -129,7 +129,7 @@ the whole argument: `*` and `?` stop at `/`, nothing else. That lets a | `ls *` | `..` | lists the parent | | `less *` | `+!id` | runs a command | -**Change (#4), both in `internal/command` (`Rule.Match`), for every glob +**Change (#4, shipped), 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 `-` @@ -157,16 +157,16 @@ 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](usage.md)'s glob table and examples with the two rules and adds -their tests (a table of the arguments above, each refused). +`*`, not for `/var/log/*/*/*`; the comment was corrected, and #4 fixed +the behaviour, updated [usage.md](usage.md)'s glob table and examples with +the two rules and added 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 +`awk *` with `BEGIN{system("id")}`, `env *` with `sh`). **Change (#4, shipped): 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 @@ -190,13 +190,13 @@ reminds; it does not decide. | Kind | Programs | Route | |---|---|---| -| Shells and interpreters | `sh`, `bash`, `dash`, `ksh`, `mksh`, `zsh`, `fish`, `csh`, `tcsh`, `busybox`, `perl`, `python`, `pypy`, `ruby`, `irb`, `node`, `nodejs`, `deno`, `bun`, `php`, `lua`, `luajit`, `tclsh`, `wish`, `expect`, `Rscript`, `R` | `-c`/`-e` or a script operand | +| Shells and interpreters | `sh`, `ash`, `bash`, `dash`, `ksh`, `mksh`, `yash`, `zsh`, `fish`, `csh`, `tcsh`, `busybox`, `perl`, `python`, `pypy`, `ruby`, `irb`, `node`, `nodejs`, `deno`, `bun`, `php`, `lua`, `luajit`, `tclsh`, `wish`, `expect`, `Rscript`, `R`, `java`, `jshell` | `-c`/`-e` or a script operand | | Database clients | `sqlite` (`sqlite3`: `.shell`, `.system`, `.output`), `mysql`, `mariadb` (`\!`, `system`), `psql` (`\!`, `\o \|`) | a statement or meta-command operand | -| Text tools with a command or write verb | `sed` (`e`, `w`, `s///e`), `awk`, `gawk`, `mawk`, `nawk` (`system()`, `print >`), `ed`, `ex` | the script operand | -| Runners of another argv | `env`, `sudo`, `su`, `runuser`, `sg`, `newgrp`, `doas`, `pkexec`, `systemd-run`, `xargs`, `parallel`, `nice`, `chrt`, `nohup`, `timeout`, `stdbuf`, `time`, `watch`, `setsid`, `flock`, `chroot`, `nsenter`, `unshare`, `bwrap`, `firejail`, `ionice`, `taskset`, `strace`, `ltrace`, `gdb`, `script` | the rest of the argv | +| Text tools with a command or write verb | `sed` (`e`, `w`, `s///e`), `awk`, `gawk`, `mawk`, `nawk` (`system()`, `print >`), `ed`, `ex`, `dd` (`of=`), `tee` | the script operand, or the file it writes | +| Runners of another argv | `env`, `sudo`, `sudoedit`, `su`, `runuser`, `sg`, `newgrp`, `doas`, `pkexec`, `systemd-run`, `xargs`, `parallel`, `nice`, `chrt`, `nohup`, `timeout`, `stdbuf`, `time`, `watch`, `setsid`, `flock`, `chroot`, `nsenter`, `unshare`, `bwrap`, `firejail`, `ionice`, `taskset`, `strace`, `ltrace`, `gdb`, `script` | the rest of the argv | | Find and archive | `find` (`-exec`, `-execdir`, `-ok`, `-fprint`, `-delete`), `tar` (`--to-command`, `--checkpoint-action`, `-I`/`--use-compress-program`), `zip` (`-TT`), `rsync` (`-e`, `--rsync-path`) | options (closed by rule 1, unless a token starts with `-`) and actions | | Network clients | `ssh`, `scp`, `sftp` (`-oProxyCommand=…`, `LocalCommand`; `*` matches spaces), `curl`, `wget` (`-o`/`-O` write) | options and URLs | -| Version control and builds | `git` (`-c core.pager=…`, `core.sshCommand`, `--upload-pack`, aliases, hooks), `make`, `npm`, `pip` | configuration and the project's own scripts | +| Version control, builds and package runners | `git` (`-c core.pager=…`, `core.sshCommand`, `--upload-pack`, aliases, hooks), `make`, `npm`, `npx`, `yarn`, `pip` | configuration and the project's own scripts | | Pagers, editors, viewers | `less`, `more`, `most`, `man` (`-P`), `vi`, `vim`, `nvim`, `emacs`, `nano`, `view` | `+cmd` (closed by rule 1), `!` and editor commands, `LESSOPEN` | | Orchestrators | `docker`, `podman`, `kubectl`, `systemctl`, `crontab`, `at`, `tcpdump` (`-z`) | `exec`, `run`, unit or job definitions | @@ -212,23 +212,20 @@ 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). +Nothing missing for lockssh: lockkit (v0.14 then, v0.20.0 pinned in +`go.mod` now) has the SSH tunnel with sessions +(`tunnel.Tunnel.NewSession`), host-key confirmation, the PII pipeline, hub +tickets with `never_auto`, the policy review, the audit and, since v0.20.0, +the confined-agent check. Streaming is not needed (above). lox support +(lockhub#133) shipped in lockhub v0.11.0. -## Left to do, by issue +## Done, by issue -| Issue | State after v0.1.0 | Left | -|---|---|---| -| #3 Console | Shipped (`internal/config`, `internal/sshconsole`, hub mode, audit; `hub_test.go`, `integration_test.go`) | nothing beyond #4's changes | -| #4 Agent surface | Shipped but for the items marked change | `lockssh_pii_list` / `lockssh_pii_add` and `.lockssh/pii.toml` through the reviewed policy; production `auto.exec` refusal; `exec` before the remote line, an argv[0] starting with `-`/`+` refused, builtin-only rule programs refused at load; globs that match no `-`/`+` option and no `.`/`..` segment; the policy-review warning on code-running programs (version suffixes stripped) and option globs; leak, injection and equivalence suites named as locklog#63 | -| #5 Launcher verbs | Shipped, with `version --json` and golden tests of each verb's output (`cmd/lockssh/testdata/`) | nothing; none of the injection or glob rules | -| #6 Release | v0.1.0 tagged and published, image signed, tap dispatched | the next pre-release with #4 and #5 | -| #7 Docs and site | README, security model, usage, Docker, demo, banners | `site/`, `pages.yml`, `scripts/check-site.py`, domain | -| #11 lox | Docs say what is true; the quick start is `lox add lockssh` + `lox run` (lockhub#133, merged, in lockhub's release after v0.10.1) | its end-to-end test with that release | - -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. +| Issue | State as of v0.3.0 | +|---|---| +| #3 Console | Shipped (`internal/config`, `internal/sshconsole`, hub mode, audit; `hub_test.go`, `integration_test.go`) | +| #4 Agent surface | Shipped: `lockssh_pii_list` / `lockssh_pii_add` and `.lockssh/pii.toml` through the reviewed policy; production `auto.exec` refusal; `exec` before the remote line, an argv[0] starting with `-`/`+` refused, builtin-only rule programs refused at load; the glob rules above; the policy-review warning on code-running programs (version suffixes stripped) and option globs | +| #5 Launcher verbs | Shipped, with `version --json` and golden tests of each verb's output (`cmd/lockssh/testdata/`) | +| #6 Release | Shipped: v0.2.0 to v0.3.0 are full releases, image signed, tap bumped | +| #7 Docs and site | Shipped: README, security model, usage, Docker, `site/`, `pages.yml`, `scripts/check-site.py` | +| #11 lox | Shipped: the quick start is `lox add lockssh` + `lox run` (lockhub#133, in lockhub v0.11.0; lockssh v0.3.0 takes v0.12.0) | diff --git a/docs/docker.md b/docs/docker.md index 437c95f..3f2fd27 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -51,8 +51,10 @@ lockssh update vX.Y.Z ``` `lockssh update` checks the signatures and the checksum as `install.sh` -does, and needs cosign the same way. With `LOCKSSH_SKIP_COSIGN=1` nothing is -verified and the launcher runs the image by its tag. +does, and needs cosign the same way. Without cosign, `LOCKSSH_SKIP_COSIGN=1` +skips the signature checks (the archive checksum is still checked) and the +launcher runs the image by its tag; with cosign installed it changes +nothing. ### What runs where @@ -63,9 +65,9 @@ runs each command with the account it needs: | Command | Runs as | Volumes | |---|---|---| | `console` | `lockssh`, in a container of its own per project (`lockssh-console-`; `LOCKSSH_CONSOLE_NAME` names it), with `--add-host=host.docker.internal:host-gateway`, no log driver, no capability, `no-new-privileges`, a read-only root with a 64 MB `/tmp`, at most 256 processes and 1 GB of memory | `lockssh-run`, `lockssh-home` | -| `init` | you (your uid and gid), with your home mounted: it writes the agents' files | | +| `init` | you (your uid and gid), with your home mounted so that a bare `lockssh init` detects your agents; it writes the agents' files in the project | | | `profile add` | you, with `HOME=/tmp` | | -| the agent commands: `mcp`, `status`, `run`, `request`, `doctor`... | `agent` | the socket volume of the workspace's lockssh lock that `lox run` runs, read-only ([below](#the-socket-of-lox-runs-lock)) | +| the agent commands: `mcp`, `status`, `run`, `request`, `logout`, `doctor` (not `pii` yet: it runs with no socket) | `agent` | the socket volume of the workspace's lockssh lock that `lox run` runs, read-only ([below](#the-socket-of-lox-runs-lock)) | | `doctor --fix` | root for its repairs only, then `agent` for every check, as `doctor` | as `doctor` | | everything else: `help`... | `agent` | none | @@ -121,7 +123,7 @@ under compose, with its socket in the volume names in `/.lockfamily/up.json` (lockhub's `docs/lox-run.md`). The agent commands mount that volume on `/run/lockssh`, read-only (connecting to a socket needs no write), and no other: without it they stop -(exit 2) and say why, and what to do (`lox run`), never falling back to the +(exit 2), except `doctor`, which runs its checks anyway, and say why, and what to do (`lox run`), never falling back to the fixed `lockssh-run`. The launcher takes the volume only after the checks lea makes for its own agents: @@ -206,7 +208,11 @@ use `lockssh console`, `lockssh init`, `lockssh profile add` (formerly `lockssh setup`, removed); the `lockssh-run` and `lockssh-home` volumes are the same. An agent entry that runs `sh -c 'exec docker run ... lockssh mcp'` keeps working; `lockssh init` now -writes `lockssh mcp`, which goes through the launcher. +writes `lockssh mcp`, which goes through the launcher. The console itself +is now started by `lox run` only ([Run the console](#run-the-console)), +with volumes of its own. + +### Migrating from a host install From a host install (the release archives and packages of v0.1.0, then `sudo lockssh install`): `install.sh` replaces the binary with the launcher, @@ -246,7 +252,7 @@ may ask for other commands, and appends the profile to - put the private key in the console's home volume, owned by `lockssh` and mode 0600, at the path the profile names (`~/` is `/home/lockssh`): - `docker run --rm -i --user lockssh --entrypoint sh -v lockssh-home:/home/lockssh ghcr.io/davidgodefroid/lockssh -c 'umask 077; mkdir -p ~/.ssh; cat > ~/.ssh/id_ed25519' < key` + `docker run --rm -i --user lockssh --entrypoint sh -v lockssh-home:/home/lockssh ghcr.io/davidgodefroid/lockssh:X.Y.Z -c 'umask 077; mkdir -p ~/.ssh; cat > ~/.ssh/id_ed25519' < key` (under `lox run`, the lock's own home volume); - a host on your machine is `host.docker.internal`, which the launcher maps to your machine; a host in another container is its name on a network @@ -285,8 +291,9 @@ warning while `lox run` starts none. The console runs hub-attached only: lockhub's `lox run` starts it, with its hub flags (`lockssh console` on its own refuses to start: "launched by `lox run` only"). That takes lockhub v0.11.0 or later, the first with the -lockssh lock type ([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)); -an older `lox` starts no lockssh console. From the workspace: +lockssh lock type ([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)), +and v0.12.0 or later for lockssh v0.3.0 (confined agents); an older `lox` +starts no lockssh console. From the workspace: ```sh lox add lockssh events # its questions: host, port, login, key file, allow rules @@ -370,11 +377,19 @@ and Codex in the `[mcp_servers.lockssh]` table `lockssh init codex` prints for `~/.codex/config.toml`. Keep the timeouts there (`timeout`, `tool_timeout_sec`): the console waits up to 5 minutes for an approval. -The client commands run the same way: `lockssh status`, `lockssh run`... +The client commands run the same way: `lockssh status`, `lockssh run`, +`lockssh request`, `lockssh logout`. `lockssh pii` is not routed to the +console by the launcher yet: it gets no socket and finds no console (use +the MCP tools `lockssh_pii_list` and `lockssh_pii_add`; +[#39](https://github.com/DavidGodefroid/lockssh/issues/39)). `lockssh doctor` runs as `agent` (`--fix` makes its repairs as root first); `docker run --rm --user lockssh -v -lockssh-run:/run/lockssh -v lockssh-home:/home/lockssh -ghcr.io/davidgodefroid/lockssh:X.Y.Z doctor` checks the console account. +SOCKET_VOLUME:/run/lockssh -v HOME_VOLUME:/home/lockssh +ghcr.io/davidgodefroid/lockssh:X.Y.Z doctor` checks the console account, +with the lock's socket volume (`socket_volume` in `.lockfamily/up.json`, +`lockfamily-<8 hex>_-run`) and its home volume (`docker volume +ls`); the fixed `lockssh-run` and `lockssh-home` belong to the former +launcher console. ## Agent in its own container @@ -384,28 +399,19 @@ socket, the launcher cannot start the MCP server: the agent runs the console container. The two containers share only the socket volume. The console checks every peer by uid against its own container's accounts, -where the agent's uid has none: name it when you start the console, with -the release image as it is: - -```sh -lockssh console --allowed-uids 1000 -``` - -or at build time, in an image of your own: - -```sh -docker build -t lockssh --build-arg ALLOWED_UIDS=1000 . -LOCKSSH_IMAGE=lockssh lockssh console -``` - -`--allowed-uids` and `ALLOWED_UIDS` are comma-separated lists of uids: the -build writes them to `allowed_uids` in the image's `/etc/lockssh/system.toml`, -the flag adds them to it for that console only (the console prints them at -start). Both refuse root (0), the console's own uid (10041) and 65534 -(nobody, the kernel's overflow uid). Only whoever starts the console sets -them: the human, through the launcher (which passes the flag on) or -through `lox run` (lockhub v0.2.4 or later: a lock's `allowed_uids` in the -lockfamily.yaml `lox run` reviews with you); no client can. It is the uid the kernel reports +where the agent's uid has none: name it in the lock's `allowed_uids` in +`lockfamily.yaml`, which `lox run` reviews with you and passes to the +console as `--allowed-uids` (lockhub v0.11.0 or later; v0.12.0 for lockssh +v0.3.0). `lockssh console` on its own refuses to start ("launched by `lox +run` only"). An image of your own can carry them too: +`docker build --build-arg ALLOWED_UIDS=1000 .` writes them to `allowed_uids` +in the image's `/etc/lockssh/system.toml`. + +`--allowed-uids` and `ALLOWED_UIDS` are comma-separated lists of uids; the +flag adds them to the image's list for that console only (the console +prints them at start). Both refuse root (0), the console's own uid (10041) +and 65534 (nobody, the kernel's overflow uid). Only whoever starts the +console sets them: the human, through `lox run`; no client can. It is the uid the kernel reports for the agent's process, as the console sees it: the agent container's uid when neither container remaps user namespaces. Every process of that uid, in any container that mounts the socket volume, may then use the console: @@ -425,11 +431,13 @@ The agent's image needs what a client host has: the socket directory is mode 2710 and the socket 0660, group `lockssh-clients`. -Start the agent's container with the socket volume and the project at the -same path as the console's, for example: +Start the agent's container with the lock's socket volume (the one +`lox run` names in `.lockfamily/up.json`, +`lockfamily-<8 hex>_-run`) and the project at the same path as +the console's, for example: ```sh -docker run … -v lockssh-run:/run/lockssh -v "$PWD:$PWD" -w "$PWD" agent-image +docker run … -v lockfamily-<8 hex>_-run:/run/lockssh:ro -v "$PWD:$PWD" -w "$PWD" agent-image ``` `lockssh init claude` then needs no change: the `lockssh mcp` it writes in @@ -454,7 +462,8 @@ user = "deploy" key = "~/.ssh/id_ed25519" ``` -and start the console on it: `LOCKSSH_DOCKER_ARGS="--network lockssh-net"`. +and name the network in the lock's `networks` in `lockfamily.yaml` +(lockhub v0.12.0 or later): `lox run`'s gateway for the lock joins it. Give the SSH account only the rights the allow list needs: a user of its own, no `sudo`, read access to the logs it must read. Never give the agent diff --git a/docs/security-model.md b/docs/security-model.md index 0e326b4..57608ce 100644 --- a/docs/security-model.md +++ b/docs/security-model.md @@ -11,7 +11,7 @@ before it leaves the console.** |---|---|---| | The human | 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) | a socket in a read-only volume | ask the console; propose a policy change | +| 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: @@ -22,9 +22,10 @@ console framework holds it; lockssh adds the SSH side. ## What lockssh enforces - **The key never reaches the agent.** It lives in the console account's - home volume (mode 0600, refused otherwise), and a passphrase or password - is asked by the console, read from the keychain or from Vault, wiped after - use. Nothing the agent can read (the socket volume, the project, a + home volume (no group or other permission bits, refused otherwise), and a + passphrase or password is asked by the console, read from the keychain or + from Vault. A key passphrase is wiped after use; an SSH password is too, + except the string copy the SSH library needs. Nothing the agent can read (the socket volume, the project, a result, an error, the audit log) carries it; errors are scrubbed. - **No shell syntax from the agent.** The agent sends an argv; the console quotes every argument in POSIX single quotes. The server's login shell @@ -33,8 +34,18 @@ console framework holds it; lockssh adds the SSH side. - **Only allowed commands run unasked.** A command runs at once only when an allow rule of the approved policy matches it (and its auto rule is `auto`). Anything else is refused, or, on a profile with `exec = true`, - waits for a human's decision on a signed ticket bound to the argv, the - agent, and the policy fingerprint; it runs once. + waits for a decision on a signed ticket bound to the argv, the agent, and + the policy fingerprint; it runs once. The decision is the human's, or + `lox run`'s 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 project's `.lockfamily/` read-only); any other is + refused (`refused-unconfined` in the audit). The report is the client's + own self-check, sent in its handshake. A non-production profile may set + `unconfined = true` to serve such an agent anyway: a loosening the human + approves, shown with a red banner and marked in every audit record and + ticket. A production profile with it does not start. - **The policy is the human's.** The approved policy is the one in force; an agent that edits `.lockssh/config.toml` loosens nothing until the human approves the diff in the console. @@ -43,11 +54,18 @@ console framework holds it; lockssh adds the SSH side. - **Masked output.** Every byte of stdout and stderr goes through lockkit's detectors before it leaves the console; values become keyed pseudonyms, secrets `⟦secret⟧`. Clear output needs the human's switch in the console - and a decided ticket, never an auto rule. + and a decided ticket, never an auto rule, except the values a PII allow + rule of the approved policy (`.lockssh/pii.toml`) names: those stay in + clear in every output. A secret is never allowed in clear. - **Host keys.** Unknown keys are trusted only by the human on the console; changed keys are refused. -- **Audit.** Every request, refusal, decision and run is in an append-only, - hash-chained log, with the command masked, never the output. +- **Audit.** Every run, refusal of a run and decision is in an append-only, + hash-chained log, never the output; a dry run (`dry_run`, `--dry-run`) + is not logged. The command is masked with a fixed detector set (secret, + email, phone, IBAN, card), not with the profile's detectors nor the + `pii.toml` mask rules: an IP address or a custom-masked value typed in + an argument is logged, and shown on the hub's screens, in clear + ([#40](https://github.com/DavidGodefroid/lockssh/issues/40)). ## What lockssh does not do @@ -58,9 +76,11 @@ console framework holds it; lockssh adds the SSH side. such programs only with literal arguments, never with `*` or `**`. [decisions.md](decisions.md#programs-that-run-code-from-their-arguments) lists them, and the policy review warns on such a rule; the list is a - safety net, not a complete one. Globs never match an option (`-`, `+`) - nor a `.`/`..` segment, so a glob cannot choose an option the human - never wrote or climb out of a directory. + safety net, not a complete one. A glob never matches an option (`-`, + `+`) unless the glob itself starts with that character (`-*`, + `--since=*`) or follows a literal `--` in the rule; the policy review + warns on both ([#41](https://github.com/DavidGodefroid/lockssh/issues/41)). A glob never matches a `.`/`..` segment, so it cannot + climb out of a directory. - **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 @@ -74,9 +94,10 @@ console framework holds it; lockssh adds the SSH side. - **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.** Whoever runs - `docker` commands as you can attach to the console or read its volume; - run the agent in a container of its own without the Docker socket (lea) - for that boundary. + `docker` commands as you can attach to the console or read its volume. + The console refuses an agent that does not report running confined + (above), but the report is the client's own: a process of your account + can lie in it. ## Why it is built this way diff --git a/docs/usage.md b/docs/usage.md index b8c7276..c0dd225 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -70,15 +70,15 @@ every lockssh client reports it in its handshake (in a container, no host container runtime socket it can reach, no Lock Family state, the project's `.lockfamily/` read-only), and an agent that does not, or that holds the group of the host's Docker socket, is refused with the reasons -(`CodeUnconfined`, audited `refused-unconfined`). Agents run by lea are +(JSON-RPC error `-32009`, audited `refused-unconfined`). Agents run by lea are confined; an agent run on the host is not. `unconfined = true` on a non-production profile serves it anyway: turning it on is a loosening the human approves, the console shows a red banner, and every audit record and hub ticket of the connection is marked unconfined. A production profile with `unconfined = true` does not start, and a managed `require_confined_agent = true` refuses an unconfined agent whatever the -profile says. The client and the console must be of the same lockssh -version. +profile says. The client and the console must speak the same console +protocol major (`protocol_major` in `lockssh version --json`). **Policy.** Every security-relevant field is part of the profile's policy. The console shows it at its first start and asks the human to approve it; @@ -155,8 +155,8 @@ most 16 KiB in all, with no control or invisible character but tab. |---|---| | an allow rule matches | runs at once (rule `run = "auto"`, the default); with `run = "ask"`, a ticket | | no rule matches, `exec = false` | refused, `E_NOT_ALLOWED`; nothing runs | -| no rule matches, `exec = true` | a ticket (risk `write`, `prod-write` on production), decided by the human | -| `unmask` (output in clear) | only once the human allowed it in the console (`:unmask` or `--allow-unmask`); then a ticket (risk `read-pii`), never decided by an auto rule | +| no rule matches, `exec = true` | a ticket (risk `write`, `prod-write` on production), decided by the human, or by `lox run` when the profile sets `auto.exec = "auto"` (refused on production) | +| `unmask` (output in clear) | only once the human allowed it in the console (`:unmask` or `--allow-unmask`); then a ticket (risk `read-pii` for an allow-listed command; a command outside the allow list keeps `write`/`prod-write`), never decided by an auto rule | On a production profile, `auto.exec = "auto"` (and `auto = "full-auto"`) is refused when the policy loads: a command outside the allow list is a @@ -237,7 +237,9 @@ the ticket `never_auto`. `lockssh profile rules --json` prints the rules `lox run` starts the console (`lox add lockssh` declares it), from lockhub v0.11.0 or later, the first with the lockssh lock type ([lockhub#133](https://github.com/DavidGodefroid/lockhub/issues/133)); an older -`lox` starts none. `lox run` launches `lockssh console --hub URL --hub-key-file FILE +`lox` starts none. lockssh v0.3.0 takes v0.12.0 or later, the first that +passes it `--runtime-gids` and shows its unconfined row, banner and ticket +flag. `lox run` launches `lockssh console --hub URL --hub-key-file FILE --instance NAME [--profile P] [--project DIR] [--allow-unmask] [--show-results] [--allowed-uids UID,...]`. It refuses to start without its hub. At its start it shows the policy for approval, asks the secret, logs @@ -253,7 +255,7 @@ output. | CLI | MCP tool | | |---|---|---| -| `lockssh status` | `lockssh_status` | the console of each profile, its allow rules, exec, the SSH account | +| `lockssh status` | `lockssh_status` | the profile's console (the MCP tool: each profile's), its allow rules, exec, the SSH account | | `lockssh run [--intent T] [--dry-run] [--ticket T] [--unmask] [--] PROGRAM [ARG]...` | `lockssh_run` (`argv`, `intent`, `dry_run`, `ticket`, `unmask`) | run a command; flags come before the program | | `lockssh pii list` | `lockssh_pii_list` | the PII mask and allow rules in force | | `lockssh pii add "REGEXP"` | `lockssh_pii_add` (`pattern`) | add a mask rule: masks more, applied at once | @@ -270,9 +272,9 @@ denied or failed, 2 no console, 3 usage or configuration error. What `lox add` calls (the lockkit verbs contract): ``` -lockssh profile add --non-interactive --json --profile NAME [--production] [--credentials none|ask|vault --vault-path P] - --host HOST [--port N] --user USER [--auth key|password] [--key FILE] [--known-hosts FILE] - [--allow "RULE"]... [--exec] +lockssh profile add [--non-interactive] [--json] [--project DIR] [--profile NAME] [--production] + [--credentials none|ask|vault [--vault-path P]] --host HOST [--port N] --user USER + [--auth key|password] [--key FILE] [--known-hosts FILE] [--allow "RULE"]... [--exec] lockssh init claude lockssh doctor --fix --yes --json ``` @@ -297,3 +299,4 @@ wiring. | `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 | +| `-32009` (handshake) | the agent does not run confined and the profile does not accept it; the reasons are in the message | run the agent confined (as lea does), or ask the user | diff --git a/site/faq/index.html b/site/faq/index.html index 92a1581..5e6d922 100644 --- a/site/faq/index.html +++ b/site/faq/index.html @@ -64,7 +64,7 @@

Which servers can it reach?

Which AI agents does it work with?

-

Any MCP client. lockssh init wires Claude Code, Codex, Cursor and Gemini CLI. An agent talks to the console through the MCP server (lockssh mcp, five tools) or the lockssh CLI; every client command takes --json.

+

Any MCP client, run confined (in a container, as lea runs agents): the console refuses an agent that does not report running confined, unless a non-production profile sets unconfined = true. lockssh init wires Claude Code, Codex, Cursor and Gemini CLI. An agent talks to the console through the MCP server (lockssh mcp, five tools) or the lockssh CLI; every client command takes --json.

Which commands run without asking me?

@@ -76,7 +76,7 @@

Can the agent approve its own commands, or widen the rules

Can the agent slip a second command into the arguments?

-

No. The agent sends an argv, and the console quotes every argument: ;, |, &&, $(...) and backquotes reach the program as plain text. Globs in allow rules never match an option or a .. segment. No shell, no climbing, no options.

+

No. The agent sends an argv, and the console quotes every argument: ;, |, &&, $(...) and backquotes reach the program as plain text. Globs in allow rules never match an option you did not write or a .. segment. No shell, no climbing, no options.

Is every allow rule safe?

@@ -88,7 +88,7 @@

What exactly does the agent see?

What is masked, and what is not?

-

Cards, emails, IBANs, public IP addresses, phone numbers and secrets become keyed pseudonyms, stable for one console run. Person names, postal addresses and free text are not: prefer commands whose output you know. What is not masked.

+

Cards, emails, IBANs, public IP addresses and phone numbers become keyed pseudonyms, stable for one console run; secrets become ⟦secret⟧. Person names, postal addresses and free text are not: prefer commands whose output you know. What is not masked.

How are host keys checked?

@@ -112,7 +112,7 @@

What is logged?

Can I install it today?

-

v0.3.0 is released, and its launcher installs with install.sh. The console runs under lox run only, which takes lockhub’s lox v0.11.0 or later. It installs with Homebrew too: brew install davidgodefroid/tap/lockfamily installs it with lox. Where things stand.

+

v0.3.0 is released, and its launcher installs with install.sh. The console runs under lox run only, which takes lockhub’s lox v0.12.0 or later. It installs with Homebrew too: brew install davidgodefroid/tap/lockfamily installs it with lox. Where things stand.

How does it relate to the other Locks?

diff --git a/site/how-it-works/index.html b/site/how-it-works/index.html index 382ab85..be2aaea 100644 --- a/site/how-it-works/index.html +++ b/site/how-it-works/index.html @@ -94,14 +94,14 @@

The life of a request

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

  • 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 session, and the first after the policy changed, also waits for a connect ticket. The first one of each console run is always yours.

    +

    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), and never covers a . or .. segment.

    +

    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.

    @@ -133,7 +133,7 @@

    What runs, what waits, what is refused

    - +
    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 yoursconnect (ask)
    the SSH session’s first usea connect ticket; the first of each console run is yours under the default askconnect (ask)
    @@ -212,7 +212,7 @@

    In the console

  • :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).

    +

    The console serves until logout, :quit, the idle timeout (20 minutes by default) or the maximum session (4 hours by default).

    diff --git a/site/index.html b/site/index.html index 764c87f..27a4e34 100644 --- a/site/index.html +++ b/site/index.html @@ -4,7 +4,7 @@ lockssh: your agent runs the command, you hold the key - + @@ -12,7 +12,7 @@ - + @@ -22,7 +22,7 @@ - + @@ -56,15 +56,15 @@
    -

    v0.2A Lock of the Lock Family · open source · Apache 2.0

    +

    v0.3A Lock of the Lock Family · open source · Apache 2.0

    Your agent runs the command. You hold the key.

    -

    Any AI agent can run commands on your servers over SSH without ever holding the key. Allow-listed commands run at once, the rest waits for you, and the output comes back masked.

    +

    Any AI agent, run confined, can run commands on your servers over SSH without ever holding the key. Allow-listed commands run at once, the rest waits for you, and the output comes back masked.

    Set it up in your project
    lox init
     lox add lockssh
     lox run
    -

    lockssh takes lockhub’s lox v0.11.0 or later: an older one does not know it. Docker on Linux or macOS; brew install davidgodefroid/tap/lockfamily installs both, or the launcher of the install guide.

    +

    lockssh v0.3 takes lockhub’s lox v0.12.0 or later: an older one does not know it or its confined agents. Docker on Linux or macOS; brew install davidgodefroid/tap/lockfamily installs both, or the launcher of the install guide.

    Install guide @@ -150,7 +150,7 @@

    Highlights

  • One key holder

    The key or password lives in the console’s account (mode 0600). A passphrase is asked at start or read from Vault. Never in the agent’s account, a result, an error or the audit.

  • Allow rules, no prompt

    systemctl status *, journalctl -u * -n * --no-pager: a command an approved rule matches runs at once. The program is always literal.

  • The rest, approved

    Anything else is refused or, with exec = true, becomes a signed ticket you decide in lox run. It runs once, for that agent, that argv, that policy.

  • -
  • No shell

    Every argument is quoted: ;, |, $(...) stay literal. Globs never match an option or climb out with ...

  • +
  • No shell

    Every argument is quoted: ;, |, $(...) stay literal. Globs never match an option you did not write or climb out with ...

  • Masked output

    stdout and stderr are capped, then masked: emails, public IPs, cards, IBANs, phones, secrets. Clear output needs your switch and a ticket.

  • Pinned host keys

    A host key the console has never seen is trusted only on your answer; a changed key is always refused.

  • Bounded runs

    One SSH session per command: no PTY, no stdin, no forwarding. A timeout (30 s by default) and an output cap per stream.

  • @@ -161,7 +161,7 @@

    Highlights

    Quick start

      -
    1. Install the lockssh launcher and lockhub’s lox v0.11.0 or later, or both with brew install davidgodefroid/tap/lockfamily (install guide). Docker must be running.

    2. +
    3. Install the lockssh launcher and lockhub’s lox v0.12.0 or later, or both with brew install davidgodefroid/tap/lockfamily (install guide). Docker must be running.

    4. In your project, write a lockfamily.yaml with the hub alone (once):

      lox init
    5. Add an SSH host: host, port, login, key file in the lock’s home, allow rules. Never a secret.

      diff --git a/site/install/index.html b/site/install/index.html index dcf3fb4..9467243 100644 --- a/site/install/index.html +++ b/site/install/index.html @@ -63,8 +63,8 @@

      Install lockssh

      Where things stand

      -

      lockssh v0.3.0 is the latest release. lox add lockssh and lox run serving it ship in lockhub v0.11.0 (lockhub#133); an older lox does not know lockssh and cannot start its console. lox add lockssh pins lockssh v0.2.0.

      -

      lockssh has a Homebrew formula, on Linux and macOS. The lockfamily meta formula installs the whole family, lockssh and lockhub’s lox v0.11.0 included; or install lockssh by name.

      +

      lockssh v0.3.0 is the latest release. lox add lockssh and lox run serving it ship in lockhub v0.11.0 (lockhub#133), and lockssh v0.3.0’s confined agents in v0.12.0; an older lox does not know lockssh and cannot start its console. lox add lockssh pins the latest signed lockssh release.

      +

      lockssh has a Homebrew formula, on Linux and macOS. The lockfamily meta formula installs the whole family, lockssh and lockhub’s lox included; or install lockssh by name.

      lockssh, with Homebrew
      @@ -101,7 +101,7 @@

      The launcher

      Set up a project

      -

      In your project, with lockhub’s lox v0.11.0 or later:

      +

      In your project, with lockhub’s lox v0.12.0 or later:

      lox init           # a lockfamily.yaml with the hub alone (once)
       lox add lockssh    # host, port, login, key file, allow rules; never a secret
       lox run            # in a terminal of its own: starts the console, serves the decisions
      @@ -143,7 +143,7 @@

      Wire your agent

      lockssh init codex          # or claude, cursor, gemini; this project
       lockssh doctor --fix        # the config, the consoles, .lockssh, the agent wiring
      -

      lockssh init writes the MCP command, lockssh mcp, which runs through the launcher in a throwaway container. Any MCP client works; init wires Claude Code, Codex, Cursor and Gemini CLI.

      +

      lockssh init writes the MCP command, lockssh mcp, which runs through the launcher in a throwaway container. Any MCP client works, run confined (as lea runs agents); init wires Claude Code, Codex, Cursor and Gemini CLI.

      Keep the client’s tool timeouts: the console waits up to 5 minutes for an approval. Start the agent at the project root, or below it.

      diff --git a/site/security/index.html b/site/security/index.html index 265ba2b..cec6a05 100644 --- a/site/security/index.html +++ b/site/security/index.html @@ -58,7 +58,7 @@

      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 in lox run, outside the agent. The console runs in an account and a container the agent cannot read or drive.

      +

      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.

      @@ -71,7 +71,7 @@

      Parties

      Youthe 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 logrun an argv on the host, mask its output - The agent (lockssh-clients, or an --allowed-uids uid)a socket in a read-only volumeask the console; propose a policy change + The agent (lockssh-clients, or an --allowed-uids uid), run confineda socket in a read-only volumeask the console; propose a policy change The serverthe SSH account’s rightsrun what it is sent @@ -86,14 +86,15 @@

      What lockssh enforces

      Guarantees and what enforces them GuaranteeEnforced by - The key never reaches the agentit lives in the console account’s home volume (mode 0600, refused otherwise); a passphrase or password is asked by the console or read from Vault, and wiped after use; 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 agentan 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 on the host’s PATH, never a builtin, keyword, alias or function; control and invisible characters refused - Only allowed commands run unaskedthe 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 + The key never reaches the agentit 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 agentan 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 unaskedthe 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 onlythe 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 yoursthe 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 runsone 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 outputevery 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 + Masked outputevery 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 keysan 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 - Auditevery request, refusal, decision and run in an append-only, hash-chained log, with the command masked, never the output + Auditevery 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
      @@ -103,7 +104,7 @@

      What lockssh enforces

      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 +, 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.

      +

      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.

      @@ -129,8 +130,8 @@

      What is not masked

      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.

      -

      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. For that boundary, run the agent in a container of its own without the Docker socket, as lea does. Details.

      +

      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.