Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 14 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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):
Expand All @@ -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`.
Expand Down Expand Up @@ -154,8 +156,8 @@ the agent's account, the socket, a result, an error or the audit log.

**✅ Allow rules, no prompt**<br>
`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.

</td>
</tr>
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
12 changes: 8 additions & 4 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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 \
Expand Down
21 changes: 15 additions & 6 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading