diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 7a9d764..f20963b 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -26,10 +26,10 @@ jobs:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- - uses: actions/checkout@v7
- - uses: actions/configure-pages@v6
- - uses: actions/upload-pages-artifact@v5
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+ - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site
- id: deployment
- uses: actions/deploy-pages@v5
+ uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a864d6..3396e24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,19 @@ uses [Semantic Versioning](https://semver.org/).
## [Unreleased]
+### Fixed
+
+- The README, `docs/`, `SECURITY.md`, `CONTRIBUTING.md` and the site say
+ what the code does (#73): approvals are hub tickets and the console only
+ reviews policy loosenings; the gate resolves names before the decision
+ when it has the hub's networks (a T2 residual); the Claude API allowlist
+ yields to a rule naming a Claude host and to shadow mode; `Cookie` is
+ scanned; credential injection and the secret check need decryption (or
+ plain HTTP to an internal host); managed rules in the evaluation order;
+ lea's CA, trust store, audit volume and proxy address; the supported
+ versions table up to v0.12.0. `pages.yml` pins its actions by commit
+ SHA, as `SECURITY.md` says.
+
## [0.12.0] - 2026-11-14
Built on lockkit v0.20.0.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b6c8997..55a664a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,6 +51,7 @@ that makes it pass.
```sh
go vet ./...
go test ./...
+go test -tags lockfamily_managed_test ./... # the managed-configuration tests, as CI runs them
```
The module also builds for Windows, where lockhttp refuses to run, and CI
@@ -68,10 +69,11 @@ GOOS=windows go test -exec /bin/true ./...
Integration tests start the gate, the console, lockkit's test hub and test
upstream servers in-process, on `127.0.0.1`; they need no Docker and no
-network access.
+network access. They run on Linux only, and `managed_test.go` also needs
+the `lockfamily_managed_test` tag. CI runs:
```sh
-go test -tags integration ./test/integration/...
+go test -tags integration,lockfamily_managed_test -count=1 -timeout 15m ./test/integration/...
```
Never point a test at a real remote service.
@@ -130,8 +132,9 @@ on a machine with a lockhttp setup you want to keep. CI runs it in the
Pull requests target `main`, which is protected:
-- the CI checks (`test` on Linux, macOS and Windows, `lint`, `integration`,
- `docker`)
+- the CI checks (`test` on Linux and Windows, `lint`, `integration`,
+ `docker`; `test` on macOS runs on `main`, nightly and by hand, not on
+ pull requests)
must pass and the branch must be up to date with `main`;
- a review from a code owner is required, and every review thread must be
resolved;
@@ -181,9 +184,11 @@ The release chain is pinned end to end:
repos/OWNER/REPO/commits/vX.Y.Z --jq .sha`) and keep the comment exact;
- `release.yml` pins the GoReleaser, cosign and syft versions and does not
use `check-latest`;
-- the cosign identity is the release workflow run for a version tag, the
- same in `scripts/lockhttp`, `SECURITY.md` and
- `.goreleaser.yaml`;
+- the cosign identity is the release workflow run for a version tag:
+ `scripts/lockhttp` names the exact run for the tag it installs
+ (`--certificate-identity`), while `SECURITY.md` and `.goreleaser.yaml`
+ use a regular expression that accepts any version tag
+ (`--certificate-identity-regexp`, checked by `cmd/lockhttp/release_test.go`);
- the `Dockerfile` pins its base images by digest: update the tag and the
digest together.
diff --git a/README.md b/README.md
index 392a347..69caf39 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ goes through. Reads of hosts you trust pass; anything else waits for
> gate: lockhttp sees none of its requests and protects nothing there.
> [!NOTE]
-> **0.x**: the policy format may still change between minor versions. Built on [lockkit](https://github.com/DavidGodefroid/lockkit) v0.14.1.
+> **0.x**: the policy format may still change between minor versions. Built on [lockkit](https://github.com/DavidGodefroid/lockkit) v0.20.0.
> Command names are fixed; flags may still move. Design decisions: [docs/decisions.md](docs/decisions.md).
## Why lockhttp
@@ -55,8 +55,10 @@ goes through. Reads of hosts you trust pass; anything else waits for
- **Approval outside the agent.** Each held request becomes a `NeverAuto`
ticket on lockhub, answered by a human in `lox run`. Nothing in the agent's
process can switch it off.
-- **Credentials the agent never holds.** The gate can inject an API token
- for one host and port; a credential sent to the wrong host is refused.
+- **Credentials the agent never holds.** With TLS decryption (or plain HTTP
+ to an internal host), the gate can inject an API token for one host and
+ port; a known credential format sent to the wrong host is refused once
+ the gate sees the request (decrypted or plain HTTP).
- **Traced.** Every decision is tied to the container, the agent and the
session that asked.
@@ -139,7 +141,8 @@ Every held request is a `NeverAuto` ticket: a human answers it. Only a
**π Credentials injected**
A policy `inject` entry has the gate add an `Authorization` header from its
-own secrets file. The agent never holds the token.
+own secrets file, on a decrypted request or plain HTTP to an internal host.
+The agent never holds the token.
@@ -147,15 +150,16 @@ own secrets file. The agent never holds the token.
**π LLM APIs checked as a relay**
-With TLS decryption, the Claude API's `mcp_servers`, server tools and Files
-API wait for a human; plain messages pass.
+With TLS decryption, the Claude API's `mcp_servers`, code execution
+`container`, server tools other than `web_search`, and Files API wait for a
+human; plain messages, OAuth and body-less reads pass.
**π§± Fail closed**
-No console: asks are refused at once. Unknown source, undecodable policy, an
-error while deciding: deny.
+No console, or a policy that does not decode: asks are refused at once.
+Unknown source, an error while deciding: deny.
@@ -207,8 +211,11 @@ limits: [docs/how-it-works.md](docs/how-it-works.md).
`unconfined = true` ([docs/policy.md](docs/policy.md#confined-agents)).
- **The AI tightens, the human loosens.** Any change that widens what passes
without a human waits for your `:review` in the console.
-- **Audit.** The gate's JSONL log and the console's audit share a
- `request_id`, never a body, a query string or a header value.
+- **Audit.** The gate audits every decision and every hub ticket's outcome
+ in its JSONL log, with a `request_id`; never a body, a query string or a
+ header value (a decision's warnings may name a `/v1/messages` body's
+ `mcp_servers`). The console approves no request: it audits policy
+ reviews.
- **Known limits.** Without decryption a `CONNECT` opens reads and writes,
and whoever can run `docker` can reach the console's container.
diff --git a/SECURITY.md b/SECURITY.md
index 097a4c3..c55497a 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,9 +1,9 @@
# Security policy
LockHTTP is the proxy every outbound HTTP(S) request of an AI agent goes
-through. It runs in Docker: its approval console runs in a container of its
-own, under a separate account, which the agent cannot reach. A flaw in
-either is a security issue.
+through. It runs in Docker: its policy console runs in a container of its
+own, under a separate account, which the agent cannot reach, and the human
+approves held requests on lockhub. A flaw in either is a security issue.
## Reporting a vulnerability
@@ -41,8 +41,9 @@ Issues of interest include, among others:
or to reach the console or its socket;
- a secret reaching argv, the environment, a file, a log, the socket or an
error message;
-- agent- or server-controlled text that can spoof the console's approval
- screen;
+- agent- or server-controlled text that can spoof the approval screen of a
+ hub ticket (the request the gate shows on a lockhub facade) or the
+ console's policy review;
- a decision that is not traced, or traced to the wrong container, agent or
session.
@@ -72,16 +73,20 @@ cosign verify-blob --bundle checksums.txt.sigstore.json \
sha256sum -c --ignore-missing checksums.txt
```
-The launcher's `lockhttp update` runs the same check and refuses to update
-without cosign (`LOCKHTTP_SKIP_COSIGN=1` is its explicit way past it).
+The launcher's `lockhttp update` runs a stricter check, with
+`--certificate-identity` naming the workflow run for the very tag it
+installs, and refuses to update without cosign (`LOCKHTTP_SKIP_COSIGN=1`
+is its explicit way past it when cosign is not installed).
## Verifying the image
The release image, `ghcr.io/davidgodefroid/lockhttp:X.Y.Z` (amd64 and
arm64, one manifest), is signed with cosign, keylessly and by digest, by the
-same workflow run for the release's tag. The installers and `lockhttp update`
-verify it and write its digest into the launcher (`image_digest=`), which
-runs the image by that digest, never by its tag. By hand:
+same workflow run for the release's tag. Lock Family's installer and
+`lockhttp update` verify it and write its digest into the launcher
+(`image_digest=`); the brew formula writes the digest the tap verified with
+cosign when it was bumped. The launcher runs the image by that digest,
+never by its tag. By hand:
```sh
cosign verify ghcr.io/davidgodefroid/lockhttp:X.Y.Z \
diff --git a/docs/configuration.md b/docs/configuration.md
index 12e593e..92641dd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -30,7 +30,7 @@ deny = [] # always refused
| Key | Default | Notes |
|---|---|---|
-| `production` | `false` | No rule may be `auto` (an `auto` rule only asks), and the console treats the profile as production. |
+| `production` | `false` | No rule may be `auto`: such a rule is a parse error, and the file does not load. The console treats the profile as production. |
| `unconfined` | `false` | `true` lets in an agent that does not run confined (a loosening; never with `production = true`, which then does not start). See [Confined agents](policy.md#confined-agents). |
| `mode` | `enforce` | `shadow`: what would ask or be denied passes and is logged as such. |
| `heuristics` | `shadow` | Exfiltration score: `off` (not computed), `shadow` (logged), `enforce` (a score β₯ 3 asks, `NeverAuto`, red). |
@@ -39,12 +39,13 @@ deny = [] # always refused
| `connect_grant` | `10m` | At least `1s`. |
| `idle_timeout` | `24h` | Console session limit. |
| `max_session` | `24h` | Console session limit. |
-| `trusted` | `[]` (`init` writes a docs set) | Reads (`GET`, `HEAD`, `OPTIONS` without body) are free. |
+| `trusted` | `[]` (`profile add` writes a docs set) | Reads (`GET`, `HEAD`, `OPTIONS` without body) are free. |
| `splice` | `[]` | Never decrypted: decided at the domain. |
| `deny` | `[]` | Always refused (`E_RULE`). |
| `redirect_cdn` | `[]` | `"origin>cdn"`: a 3xx from origin to cdn lets the same container `GET` that exact URL once within 60 s. Eight GitHub, Docker, Go and PyPI pairs are built in. |
| `[[profiles.P.internal_hosts]]` | none | `host`, `ports` (required), `read` (`false`). May resolve to a private address. |
| `[[profiles.P.rules]]` | none | `id`, `container`, `host`, `methods`, `path`, `verdict`, `max_body`, `expires`, `note`. |
+| `[[profiles.P.inject]]` | none | `id`, `host`, `port`, `header`, `credential` (required), `scheme`, `container`, `methods`, `paths`, `note`. See [Credential injection](policy.md#credential-injection). |
diff --git a/docs/decisions.md b/docs/decisions.md
index 8e54700..13a966c 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -10,41 +10,42 @@ first are not.
| Requirement | Where it lives |
|---|---|
-| The console runs **apart from the agent**, in its own account (`lockhttp`): since the Docker-only change (after v0.1.0) that account and its socket live in the image, the console in its own container (`lockhttp-console`), the agent's containers never get its socket or its home volume. lockkit's isolation checks run against the image's root-owned `system.toml`. | `Dockerfile`, `scripts/lockhttp`, `lockhttp console` (lockkit `console.Run`) |
-| **NeverAuto.** Every hub ticket is `NeverAuto`; an `auto` rule asks like `ask`. At parse time such a rule is valid only for a container (or all containers), never for an agent, and never for a forbidden class (uploads, messaging, registry publishing, `git-receive-pack`, a spliced host, a heuristic hit, a secret, a production profile). No auto mode answers a held request. | `internal/policy` (validation), `internal/gate` (hub tickets) |
-| **A human decision is shared only by requests of identical fingerprint** (container, method, URL, significant headers, normalised body). Requests under the same key but with another fingerprint are separate items, each approved on its own. | `internal/gate` (ask queue) |
-| **Claude API path and body allowlist** once TLS is decrypted: `POST /v1/messages` and `/v1/messages/count_tokens` are free only without `mcp_servers` and with no server tool other than `web_search`; `/v1/files*` asks; a credential that is not one of the container's is denied; any other host or path under the Anthropic domains asks (`NeverAuto`). | `internal/decide/claude.go` |
-| **Fail closed.** No console: an ASK is refused at once (`E_NO_CONSOLE`). An error while deciding, an unknown source, an unreadable source map, a policy that does not decode: deny. The gate never reads a policy file; it only uses what the console serves. | `internal/gate` |
+| The console runs **apart from the agent**, in its own account (`lockhttp`): since the Docker-only change (after v0.1.0) that account and its socket live in the image, the console in its own container (`lox run`'s service `lock-`, or `lockhttp-console` with the standalone launcher), the agent's containers never get its socket or its home volume. lockkit's isolation checks run against the image's root-owned `system.toml`. | `Dockerfile`, `scripts/lockhttp`, `lockhttp console` (lockkit `console.Run`) |
+| **NeverAuto.** Every hub ticket is `NeverAuto`; an `auto` rule asks like `ask`. At parse time such a rule is valid only for a container (or all containers), never for an agent, and never in a production profile, for every host (`*`), for a spliced host, for messaging, for registry publishing, for `git-receive-pack` or for a write to any path of a git forge. Uploads, heuristic hits and secrets are checked per request. No auto mode answers a held request. | `internal/policy` (validation), `internal/gate` (hub tickets) |
+| **A human decision is shared only by requests of identical fingerprint** (container, method, URL, every end-to-end header, normalised body). Requests under the same key but with another fingerprint are separate hub tickets, each approved on its own. | `internal/gate` (ask queue) |
+| **Claude API path and body allowlist** once TLS is decrypted: `POST /v1/messages` and `/v1/messages/count_tokens` are free only when the body is one unambiguous JSON object without `mcp_servers` or `container` and with no server tool other than `web_search`; `/v1/files*` asks; OAuth paths and other body-less reads on the four Claude hosts are free; a credential that is not one of the container's is denied; any other write on the Claude hosts, and any other host under the Anthropic domains, asks (`NeverAuto`), unless the human lists that host as trusted (`docs.anthropic.com` is in the default set): then it is an ordinary trusted host. A policy rule naming a Claude host applies before the allowlist, and shadow mode lets its asks through. | `internal/decide/claude.go` |
+| **Fail closed.** No console: an ASK is refused at once (`E_NO_CONSOLE`). An error while deciding, an unknown source, an unreadable source map: deny. A policy that does not decode counts as no console: FREE continues on the last policy, an ASK gets `E_NO_CONSOLE`; a policy whose fingerprint does not match is not installed and the previous one stays. The gate never reads a policy file; it only uses what the console serves. | `internal/gate` |
## Open decisions, recommended option taken
| ID | Question | Decision for v0.1.0 | Rationale |
|---|---|---|---|
-| **D-optin** | Opt-in, and migration of `LEA_EGRESS_ALLOW`? | **Opt-in** (`LEA_LOCKHTTP=1` on the lea side). With LockHTTP on, `LEA_EGRESS_ALLOW` entries become trusted read-only domains and squid's hard allowlist is switched off; squid's floor (DoH, IP literals, private ranges, ports) stays. Default after the shadow period. | A new egress path must earn trust before it becomes the default; the floor keeps the old guarantees. |
+| **D-optin** | Opt-in, and migration of `LEA_EGRESS_ALLOW`? | **Opt-in** (`LEA_LOCKHTTP=1` on the lea side). With LockHTTP on, squid's hard allowlist is switched off; `LEA_EGRESS_ALLOW` entries are migrated by hand, as trusted read-only hosts, with `lockhttp profile add --trusted`; squid's floor (DoH, IP literals, private ranges, ports) stays. Default after the shadow period. | A new egress path must earn trust before it becomes the default; the floor keeps the old guarantees. |
| **D-console** | Behaviour without a console | **FREE continues** on the last approved policy the gate holds in memory (or the built-in floor and Claude hosts when it never had one); **ASK is refused at once** with `E_NO_CONSOLE` and a page naming the command to run. | Availability of trusted reads without weakening anything that needs a human. |
-| **D-ih** | Internal hosts | **Before** the private-range floor, as in squid today; decided at the domain (spliced); FREE only when marked `read`, ASK otherwise; only on the ports their line declares. | Keeps lea's internal hosts working without making them a free channel. |
+| **D-ih** | Internal hosts | **Before** the private-range floor, as in squid today; decided at the domain (spliced); FREE only when marked `read`, ASK otherwise; on ports 80 and 443 and the ports their line declares. | Keeps lea's internal hosts working without making them a free channel. |
| **D-connect** | claude.ai connectors and `mcp_servers` | **No connector exception**; `mcp_servers` (and server tools other than `web_search`) on the API is **ASK, `NeverAuto`**. Connectors are switched off at the source by lea's managed settings. | The Claude API is a generic relay; every relay use needs a human. |
| **D-body** | Body preview on the screen | **Masked preview** (PII detectors + terminal sanitising, first 1 KiB) by default; never the clear body. | lockkit refuses clear results at level 1; the agent's account may read the window. |
| **D2** | Podman rootless without isolated gateway | **Accepted if the isolation test passes** (blocking test on the lea side, #115 option A). | Rootless Podman refuses the isolated gateway option. |
| **D3** | CA key in the gate or in a signer | **Separate signer** (`lockhttp signer`): it holds the CA key and issues leaf certificates over a Unix socket; the gate never sees the CA key. | A compromised gate cannot mint certificates beyond what it asks the signer for, and the key never sits in the data plane. |
| **D5** | Hold time and body limit | **60 s** hold, **10 MiB** buffer limit (`buffer_limit`), both in the policy. | Fits common client timeouts (git, npm, pip). |
-| **D6** | lea deck notification | **Counter + sound on the first ASK** (lea side; the gate publishes pending counts in its status file). | Draws the human to the console without a card that could be mistaken for an approval channel. |
-| **D7** | Serial lockkit approvals | **Accepted for v1**: the gate keeps its own queue and sends one approval at a time; concurrent approvals will be asked of lockkit later. | No lockkit fork, no shared decisions. |
-| **D8** | Initial trusted list | lea's `EGRESS_DEFAULT` + Claude hosts (exact) + the docs set (`go.dev`, `pkg.go.dev`, `docs.python.org`, `developer.mozilla.org`, `docs.docker.com`, `kubernetes.io`, `man7.org`, `docs.anthropic.com`); **OpenAI only if a provider uses it**. | Small, read-only, human-reviewed at first start. |
+| **D6** | lea deck notification | **A counter** of pending asks (lea side; the gate publishes pending counts in its status file); the first ASK plays no sound. | Draws the human to the hub without a card that could be mistaken for an approval channel. |
+| **D7** | Concurrent approvals | **Side by side on the hub**: each held request is its own hub ticket, sent as it comes; identical requests share one. (Until the gate became hub-attached, it kept its own queue and sent one console approval at a time.) | No lockkit fork, no shared decisions. |
+| **D8** | Initial trusted list | The set `lockhttp profile add` writes into `trusted` (`DocsTrusted`: Go, Python, npm, Rust, Debian, Ubuntu and Alpine package hosts, GitHub's read hosts, `developer.mozilla.org`, `docs.docker.com`, `kubernetes.io`, `man7.org`, `docs.anthropic.com`), plus the hosts given with `--trusted`. The four Claude hosts are built in, not in the list. Nothing adds OpenAI: trust it by hand if a provider uses it. | Small, read-only, human-reviewed at first start. |
| **D10** | WebFetch | **WebSearch allowed; WebFetch allowed** (its requests go through the gate and ask for unknown hosts); revisit after the shadow period. | WebSearch is server-side; WebFetch is visible to the gate. |
## Product choices made while building v0.1.0
-- **One approval answer, three meanings.** lockkit's screen takes `y` or
- `n `. For a CONNECT (phase 1, or a spliced host) `y` opens
+- **One approval, three meanings.** An approval on the hub is a ticket the
+ human approves or denies (with a reason). For a CONNECT (phase 1, or a spliced host) `y` opens
container Γ host Γ port for `connect_grant` (10 min by default, a policy
field); for a decrypted request `y` approves that request, and creates a
- single-use authorisation (container, method, URL, significant headers,
- normalised body; 10 min) if the client already left. Durable openings are
+ single-use authorisation (container, method, URL, every end-to-end
+ header, normalised body; 10 min) if the client already left. Durable openings are
policy rules, written by the human and confirmed in `:review`.
- **Shadow mode** (`mode = "shadow"`) logs what would have asked or been
denied, and lets it pass; the floor (IP literals, DoH, private ranges,
- ports, SNI mismatch, h2c, nested CONNECT) and secret matches stay enforced.
+ ports, SNI mismatch, h2c, nested CONNECT), secret matches, the deny list
+ and the company's managed rules stay enforced.
`heuristics = "shadow"` (the default) does the same for the exfiltration
score only.
- **Source map.** The container is read from the local address the
@@ -52,7 +53,7 @@ first are not.
file lea writes; an address missing from the map is refused
(`E_SOURCE_UNKNOWN`). `Proxy-Authorization` names the agent, for the
audit only.
-- **No MCP server in v0.1.0.** Agents never talk to the console: they meet
+- **No MCP server.** Agents never talk to the console: they meet
LockHTTP as a proxy, and its 403 pages say what to ask of the human.
## Hub-attached only (lockkit#110)
diff --git a/docs/docker.md b/docs/docker.md
index 0c2de9d..9ae62f9 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -49,7 +49,7 @@ credentials, as on a host: the gate is accepted because uid 10003 is in
| Volume | Mounted at | Shared by | Holds |
|---|---|---|---|
| `lockhttp-run` | `/run/lockhttp` | the console and the gate | the console's socket, `user-.sock` |
-| `lockhttp-home` | `/home/lockhttp` | the console account's commands only (`console`, `policy`) | the policy `~/.config/lockhttp/config.toml`, the approved policy and the console's audit (`~/.local/state/lockhttp/`) |
+| `lockhttp-home` | `/home/lockhttp` | the console account's commands only (`console`, `policy`) | the policy `~/.config/lockhttp/config.toml`, the approved policy and the console's log of policy reviews (`~/.local/state/lockhttp/`) |
A named volume takes the owner and mode of the image's directory on first
use, so `lockhttp-run` is `2710 lockhttp:lockhttp-clients` and
@@ -58,9 +58,11 @@ use, so `lockhttp-run` is `2710 lockhttp:lockhttp-clients` and
## Subcommand β `docker run`
Every run is `docker run --rm $LOCKHTTP_DOCKER_ARGS ... IMAGE ...`, with
-`-it` when stdin and stdout are terminals, else `-i`.
+`-it` when stdin and stdout are terminals, else `-i` (`version` runs
+without either).
`LOCKHTTP_DOCKER_ARGS` is split on spaces and never globbed. Every container
-the launcher starts (but `version` and `help`) is confined: `--cap-drop ALL
+the launcher starts is confined, except `version` and the catch-all row
+below (`help`, `hub-key` and any unknown command): `--cap-drop ALL
--security-opt no-new-privileges --read-only --tmpfs
/tmp:rw,nosuid,nodev,noexec,size=64m --pids-limit 256 --memory 1g`; the
volumes stay writable. A path holding `:` (which `docker -v` cannot mount) is
@@ -68,15 +70,15 @@ refused.
| Subcommand | Account | `docker run` arguments | Why |
|---|---|---|---|
-| `console` | `lockhttp` (10021) | `--name lockhttp-console --log-driver none --user lockhttp -v lockhttp-run:/run/lockhttp -v lockhttp-home:/home/lockhttp` | the only container with `lockhttp-home`; no log driver, so `docker logs` keeps no approval screen; a stopped container named `lockhttp-console` is removed first |
-| `policy` | `lockhttp` | `--user lockhttp -v lockhttp-home:/home/lockhttp` | it reads or edits the policy in the console account's home |
+| `console` | `lockhttp` (10021) | `--name lockhttp-console --log-driver none --user lockhttp -v lockhttp-run:/run/lockhttp -v lockhttp-home:/home/lockhttp` | the only container with `lockhttp-home`; no log driver, so `docker logs` keeps no policy review screen; a stopped container named `lockhttp-console` is removed first |
+| `policy`, `managed` | `lockhttp` | `--user lockhttp -v lockhttp-home:/home/lockhttp` | it reads or edits the policy in the console account's home; `managed` reads the company's managed configuration as the console does |
| `profile`, `init`, `doctor` | you (`id -u`:`id -g`) | `--user UID:GID -v ROOT:ROOT -w CWD`: ROOT is the project of the current directory (the nearest directory holding `.lockhttp/config.toml`, else `.git`, else the current directory), or `profile add`'s `--project DIR`, made absolute; under rootless Podman also `--userns keep-id`; no lockhttp volume | the launcher verbs `lox add` runs: they write and check the project's `.lockhttp/config.toml`, which is yours |
| `gate` | `gate` (10003) | `--name lockhttp-gate --user gate -v lockhttp-run:/run/lockhttp -p ${LOCKHTTP_PUBLISH:-127.0.0.1:3130}:3130`, and `--listen 0.0.0.0:3130` unless you pass `--listen` | it needs the hub flags, and refuses to start without them; lea starts its own gate ([lea.md](lea.md)) |
| `signer` | `signer` (10004) | `--user signer -v lockhttp-signer:/run/lockhttp-signer` | the socket directory (`signer:lockhttp-clients`, 2750, from the image) the gate shares; lea runs its own signer ([lea.md](lea.md#3-mitm-phase-2-optional)) |
| `ca` | you (`id -u`:`id -g`) | `--user UID:GID -v DIR:DIR`, with `--dir DIR` made absolute (created 0700) and `--name $(uname -n)` unless you pass `--name`; under rootless Podman also `--userns keep-id`, so that the files are yours on the host | the CA files are yours; lea reads `ca.pem` and gives `ca-key.pem` to the signer alone |
| `version` | `gate` | | prints `lockhttp launcher X (image I)`, then runs `I version` |
| `update [vX.Y.Z]` | (host) | | [below](#install-and-update) |
-| anything else (`help`, ...) | `gate` (image default) | | |
+| anything else (`help`, `hub-key`, ...) | `gate` (image default) | not confined | |
Invariants: the Docker socket is never mounted; only the console's
container gets `lockhttp-home`; the gate shares only `lockhttp-run` with
@@ -122,11 +124,15 @@ The digest comes from `cosign verify` of the image against the release
workflow run **for that very tag**
(`https://github.com/DavidGodefroid/lockhttp/.github/workflows/release.yml@refs/tags/vX.Y.Z`,
`--certificate-identity`, never a regular expression: a tag moved onto an
-older release's signed files does not verify), the same check as for `checksums.txt` (
-[SECURITY.md](../SECURITY.md#verifying-the-image)), so the launcher runs
+older release's signed files does not verify), the same check the launcher
+makes on `checksums.txt`, so the launcher runs
`ghcr.io/davidgodefroid/lockhttp@sha256:...`, never a tag that could move.
-With `LOCKHTTP_SKIP_COSIGN=1` nothing is verified: `image_digest` stays
-empty and the launcher runs `ghcr.io/davidgodefroid/lockhttp:X.Y.Z`. A
+The manual check in [SECURITY.md](../SECURITY.md#verifying-the-image) uses
+`--certificate-identity-regexp` on the release workflow's tags instead,
+which accepts any release tag. Without cosign installed and with
+`LOCKHTTP_SKIP_COSIGN=1`, nothing is verified: `image_digest` stays empty
+and the launcher runs `ghcr.io/davidgodefroid/lockhttp:X.Y.Z`. With cosign
+installed, `LOCKHTTP_SKIP_COSIGN` has no effect. A
launcher run from a clone (`launcher_version=dev`) runs the local image
`lockhttp`.
@@ -164,9 +170,11 @@ installed launcher with a release's:
6. run `docker pull` of the pinned image.
Any failed check stops before the launcher is replaced. cosign is required;
-`LOCKHTTP_SKIP_COSIGN=1` is the explicit way past it, and then neither the
-signature nor the image is verified. Without a version, `update` takes the
-newest entry of the releases feed. A launcher installed by brew is updated
+when it is not installed, `LOCKHTTP_SKIP_COSIGN=1` is the explicit way past
+it, and then neither the signature nor the image is verified (the new
+launcher runs the image by its tag). With cosign installed the variable has
+no effect. Without a version, `update` takes the newest entry of the
+releases feed, pre-releases included. A launcher installed by brew is updated
by `brew upgrade` instead.
## Platforms
@@ -282,8 +290,8 @@ The gate's container reaches the console only through the socket in
gets that volume, nor the Docker socket.
Your own account is another matter. Whoever can run `docker` on the host
-can `docker attach` to `lockhttp-console` and type an approval, `docker
-exec` into it, or open `lockhttp-home` in another container and edit the
+can `docker attach` to `lockhttp-console` and confirm a policy loosening,
+`docker exec` into it, or open `lockhttp-home` in another container and edit the
approved policy. An agent that runs shell commands in an account allowed to
use Docker can do the same. Keep the agent in a container without the
Docker socket, as lea does: it then reaches the network only through the
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index bf9bb04..678254a 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -97,7 +97,7 @@ the same URL with another body is a separate screen.
A refusal is a `403 Forbidden` with a plain-text body that says why and
what to ask of the human, and two headers: `X-LockHTTP-Code` and
-`X-LockHTTP-Request` (the id to find in the console and the audit). For a
+`X-LockHTTP-Request` (the id to find in the gate's audit). For a
`CONNECT` it is the `CONNECT`'s own response, which clients show as a proxy
error. In hub mode an `E_PENDING` also names the hub ticket the request
waits on (`X-LockHTTP-Ticket`). A forwarded response carries `X-LockHTTP-Request` too (decrypted or
@@ -116,19 +116,24 @@ plain HTTP); a target the gate cannot reach is a `502`.
| `E_SOURCE_UNKNOWN` | The gate cannot tell which container sent the request. | Use the proxy address lea gave. |
| `E_UNCONFINED` | The sender is not known to run confined (a gate without lea's `sources.json`), and the profile does not set `unconfined = true` ([Confined agents](policy.md#confined-agents)). | Run the agent inside lea, or ask the user to set `unconfined = true` on a non-production profile. |
| `E_INJECT` | The policy injects a credential for this host, and the gate's secrets file lacks it or does not load. | Ask the user to check the gate's secrets file; never send the credential yourself. |
+| `E_METHOD` | `TRACE` or `TRACK` to a host and port where the gate injects a credential. | Use another method. |
-`E_HOST_UNKNOWN`, `E_CLAUDE_API_PARAM`, `E_EXFIL_SUSPECT`, `E_METHOD` and
-`E_PINNED` are registered codes too; in v0.1.0 a refused ASK reaches the
-agent as `E_DENIED`, `E_TIMEOUT`, `E_PENDING` or `E_NO_CONSOLE`, and
-`E_PINNED` appears in the gate's audit only (a client that rejects the
-gate's certificate closes the connection before any response).
+`E_HOST_UNKNOWN`,
+`E_CLAUDE_API_PARAM`, `E_EXFIL_SUSPECT` and `E_PINNED` are registered codes
+too; a refused ASK reaches the agent as `E_DENIED`, `E_TIMEOUT`,
+`E_PENDING` or `E_NO_CONSOLE`, and `E_PINNED` appears in the gate's audit
+only (a client that rejects the gate's certificate closes the connection
+before any response).
## Claude API allowlist
The four hosts Claude Code reaches (`api.anthropic.com`, `claude.ai`,
`console.anthropic.com`, `statsig.anthropic.com`) are free at the domain.
Any other host under `anthropic.com`, `claude.ai` or `claude.com` asks
-(`NeverAuto`), unless a rule says otherwise.
+(`NeverAuto`), unless a rule says otherwise or the host is in `trusted`
+(the default set has `docs.anthropic.com`): then it is an ordinary trusted
+host. A policy rule naming one of the four Claude hosts applies before the
+allowlist below, and shadow mode lets the allowlist's asks through.
Once TLS is decrypted, the Claude API is a generic relay and is checked per
request:
@@ -140,7 +145,7 @@ request:
| `/v1/files*` | ASK, `NeverAuto` |
| Other reads on the four hosts | FREE |
| Other writes | ASK, `NeverAuto` |
-| A credential (`Authorization`, `x-api-key`) not in the caller's list, or two credentials | DENY `E_SECRET_EGRESS` (with lea's `credentials.json`) |
+| A credential (`Authorization`, `x-api-key`) not in the caller's list (with lea's `credentials.json`), or two credentials (always) | DENY `E_SECRET_EGRESS` |
Duplicate keys, and keys that differ from `mcp_servers`, `tools` or
`container` only by case, make the body ambiguous: it asks.
@@ -155,7 +160,8 @@ Duplicate keys, and keys that differ from `mcp_servers`, `tools` or
- **HTTP/1.1 only to clients when decrypting.** The gate offers ALPN
`http/1.1`; it does not speak HTTP/2 to clients, and refuses `Upgrade: h2c`.
- **A WebSocket session is one approval.** The upgrade request is decided;
- the frames that follow are not.
+ the frames that follow are not. With injected secrets, the client's
+ frames are scanned for their values.
- **Heuristics run in shadow by default.** The exfiltration score is logged,
not enforced, until you set `heuristics = "enforce"`.
- **Asks wait side by side.** Each held request is its own hub ticket;
@@ -164,5 +170,5 @@ Duplicate keys, and keys that differ from `mcp_servers`, `tools` or
the connection arrived on; the agent name comes from `Proxy-Authorization`
and is for the audit only. Agents of one container share a uid, so rules
scope to containers, never to agents.
-- No MCP server in v0.1.0: agents meet LockHTTP as a proxy, and its `403`
+- No MCP server: agents meet LockHTTP as a proxy, and its `403`
pages tell them what to ask of the human.
diff --git a/docs/install.md b/docs/install.md
index 3aad7fa..278879f 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -21,9 +21,11 @@ the Lock Family's installer puts the same launcher in `~/.local/bin`
curl -fsSL https://lockfamily.dev/install.sh | sh
```
-Both verify the keyless cosign signature of the release against this
-repository's release workflow and write the verified image digest into the
-launcher, which runs the image by that digest. lea's `LEA_LOCKHTTP=1` uses
+The installer verifies the keyless cosign signature of the release and of
+its image against this repository's release workflow, and writes the
+verified image digest into the launcher. The brew formula checks the
+archive's SHA-256 and writes the image digest the tap verified with cosign
+when it was bumped. Either way the launcher runs the image by that digest. lea's `LEA_LOCKHTTP=1` uses
this launcher from lea v0.16.0 on (it checks the digest against its pin or
with cosign); older lea accept only a root-owned `/usr/local/bin/lockhttp`,
which lockhttp no longer installs (`scripts/install.sh` is gone since
diff --git a/docs/lea.md b/docs/lea.md
index 3e157ef..66c4618 100644
--- a/docs/lea.md
+++ b/docs/lea.md
@@ -21,15 +21,15 @@ against. Contract version: **1** (the `version` field of every file below).
> ([docker.md](docker.md)). There is no host install any more: no
> `sudo lockhttp install`, no `lockhttp` account or `lockhttp-clients` group
> on the host, no `allowed_uids`, no subuid mapping, no `--group-add`, no
-> host `/run/lockhttp` bind mount, no `LOCKHTTP_RUNTIME_DIR`. The human runs
-> the console in a container through the launcher; lea runs the gate (and
+> host `/run/lockhttp` bind mount, no `LOCKHTTP_RUNTIME_DIR`. `lox run` runs
+> the console in a container of its own; lea runs the gate (and
> the signer) as sidecar containers from the same image, by digest. The file
> formats (`sources.json`, `credentials.json`, the status file) are
> unchanged: contract version 1.
```
agent container (-internal-, --internal)
- HTTP(S)_PROXY=http://:@lea-proxy:3130
+ HTTP(S)_PROXY=http://:@$LEA_PROXY_IP:3130
LockHTTP CA in the trust stores (when MITM is on)
β
-proxy container (network namespace shared with the gate)
@@ -50,7 +50,7 @@ against. Contract version: **1** (the `version` field of every file below).
| Step | Command | Notes |
|---|---|---|
-| Install the launcher | `brew install davidgodefroid/tap/lockfamily`, or lockfamily's `install.sh` ([install.md](install.md#install)) | In brew's `bin` or `~/.local/bin`, with the verified image digest written into it (`image_digest=` line). lea v0.16.0 or later: lea runs that image as the gate only if the digest matches its pin in `config/locks.lock` or `cosign verify` proves the release signed it (keep `cosign` installed). |
+| Install the launcher | `brew install davidgodefroid/tap/lockfamily`, or lockfamily's `install.sh` ([install.md](install.md#install)) | In brew's `bin` or `~/.local/bin`, with the verified image digest written into it (`image_digest=` line). lea v0.16.0 or later: lea runs that image as the gate only if the digest matches its pin in `config/locks.lock` or `cosign verify` proves the release signed it (keep `cosign` installed). A root-owned `/usr/local/bin/lockhttp` (owned and writable by root only) is trusted without either check. |
| The lock and its policy | `lox add lockhttp `, the policy in `/.lockhttp/config.toml` | lockhub's `lox`. lea never writes the policy. |
| Start the hub and the console | `lox run` | In a terminal of its own, outside lea and any agent. Runs the hub and the lockhttp console (uid 10021, no log driver) in compose services, makes the gate's instance key in the gate's own volume (`_-gate`) and registers it with the hub, writes `up.json`, and serves the decisions in its terminal. `lox attach ` attaches the console's terminal (its first policy review). |
@@ -79,13 +79,13 @@ docker run -d --name -lockhttp-gate \
-v _-gate:/lockhttp-home \
-v /lockhttp/gate/hub:/run/lockfamily:ro \
-v /lockhttp/gate:/etc/lockhttp-gate:ro \
- -v /lockhttp/audit:/var/log/lockhttp \
+ -v -lockhttp-audit:/var/log/lockhttp \
-v /lockhttp/status:/run/lockhttp-gate \
ghcr.io/davidgodefroid/lockhttp@sha256: \
gate \
--listen 0.0.0.0:3130 \
--upstream http://127.0.0.1:3128 \
- --profile default \
+ --profile \
--sources /etc/lockhttp-gate/sources.json \
[--credentials /etc/lockhttp-gate/credentials.json] \
--audit-dir /var/log/lockhttp \
@@ -108,8 +108,8 @@ start without them.
| uid | `--user gate` (10003, **never 0**) | In the image, uid 10003 is in `lockhttp-clients`, the group the console accepts. Nothing to configure on the host: no `allowed_uids`, no subuid, no `--group-add`. The gate refuses to run as root. |
| Socket | volume `_-run` (`up.json`'s `socket_volume`) β `/run/lockhttp` (**the gate's container only**, never an agent container) | The console's socket. The image's `/etc/lockhttp/system.toml` names `/run/lockhttp`; the console checks the gate's uid with `SO_PEERCRED`. The volume belongs to the Docker engine `lox run` uses: lea must start the gate on that same engine. |
| Hub | volume `_-gate` β `--home`; lea's copies of the hub key, facade keys and devices, read-only | The gate's instance key, plans and hub state. Only the proxy container joins the hub's network; the gate refuses its addresses as targets. |
-| Files (read-only, written by lea on the host) | `/lockhttp/gate/` β `/etc/lockhttp-gate`: `sources.json`, `credentials.json`, `ca.pem` | Readable by uid 10003. Reloaded when they change (2 s poll). An unreadable or invalid file is fail-closed (see Β§2.3). |
-| Writable | `--audit-dir` (`/var/log/lockhttp`, persisted on the host), the `--status-file` directory | Writable by uid 10003. JSONL audit of every decision (FREE, DENY, ask outcomes), daily files, 30 days kept. |
+| Files (read-only, written by lea on the host) | `/lockhttp/gate/` β `/etc/lockhttp-gate`: `sources.json`, `credentials.json`, `ca.pem` | Readable by uid 10003. `sources.json`, `credentials.json` and the secrets file are reloaded when they change (2 s poll); `ca.pem` is read once at start, and lea restarts the gate on a new CA. An unreadable or invalid file is fail-closed (see Β§2.3). |
+| Writable | `--audit-dir` (`/var/log/lockhttp`, the named volume `-lockhttp-audit`), the `--status-file` directory | Writable by uid 10003. JSONL audit of every decision (FREE, DENY, ask outcomes), daily files, 30 days kept. |
| Liveness | `docker exec -lockhttp-gate lockhttp gate --check --listen 127.0.0.1:3130` | Exits 0 when the gate answers. For lea's doctor. |
The `/...` paths are lea's choice; only the in-container paths
@@ -120,8 +120,8 @@ above are the ones the flags name.
1. **squid listens on `127.0.0.1:3128` only** (`render-squid-conf.sh`), so the gate is the only HTTP way out. Its floor (DoH, IP literals, private ranges, ports) stays; its hard allowlist is switched off when `LEA_LOCKHTTP=1` (the gate decides).
2. **keyproxy goes through the gate**: `-via http://keyproxy:@127.0.0.1:3130`, with `X-Lea-Source: ` and the same `Proxy-Authorization` set on the CONNECT (`http.Transport.ProxyConnectHeader`). keyproxy strips any `X-Lea-Source` and `Proxy-Authorization` an agent sends. The gate honours `X-Lea-Source` only from 127.0.0.1 with the keyproxy token; elsewhere it is ignored and logged.
3. **SSH git forwarders are off**: lea refuses to start the proxy with a non-empty `LEA_GIT_SSH` when `LEA_LOCKHTTP=1`.
-4. **Nested Podman** (`image/containers.conf.tmpl`): `HTTPS_PROXY=http://nested:@lea-proxy:3130`.
-5. Agent env: `HTTP_PROXY`/`HTTPS_PROXY=http://:@lea-proxy:3130`. `NO_PROXY` may keep `lea-proxy` (keyproxy on 4400 is reached directly; squid is no longer reachable).
+4. **Nested Podman** (`image/containers.conf.tmpl`): `HTTPS_PROXY=http://nested:@$LEA_PROXY_IP:3130` (the proxy container's IP).
+5. Agent env: `HTTP_PROXY`/`HTTPS_PROXY=http://:@$LEA_PROXY_IP:3130`. `NO_PROXY` may keep `lea-proxy` (keyproxy on 4400 is reached directly; squid is no longer reachable).
6. The gate serves only the local addresses listed in `sources.json` (one per internal network) and loopback with the keyproxy token: a connection arriving on any other address, the egress side included, is refused (`E_SOURCE_UNKNOWN`), fail-closed. Bind the gate where agents can reach it, never expose it on the egress bridge.
### 2.3 `sources.json`: who is calling
@@ -176,12 +176,12 @@ no file (no `--credentials`), the check is off.
| Step | Who | What |
|---|---|---|
-| CA | lea, on the host, through the launcher | `lockhttp ca init --dir ~/.local/state/lea/lockhttp/ca --name ` β `ca.pem` (public) and `ca-key.pem` (0600). The launcher runs it as the invoking user, with the directory mounted at its own path: both files belong to that user. P-256, `pathlen:0`, 90 days; `--force` rotates. Without `--name`, the launcher passes the machine's name (`uname -n`). The key stays readable by the user who ran it, so keep `--dir` out of any directory an agent container mounts (lea's state dir, not a project), and once the key is copied to the signer's volume (below), the host copy can be removed or kept 0600 for rotation. |
-| CA key to the signer | lea | `ca-key.pem` must be owned by uid 10004 (`signer`), mode 0600, mounted read-only in the signer's container only. For example, copy it into a volume with a one-off root container of the same image: `docker run --rm --user 0 --entrypoint sh -v ~/.local/state/lea/lockhttp/ca:/src:ro -v -lockhttp-ca:/ca IMAGE@sha256: -c 'install -m 0600 -o signer /src/ca-key.pem /ca/ca-key.pem && install -m 0644 /src/ca.pem /ca/ca.pem'`. |
+| CA | lea, on the host, in the verified image | lea runs `ca init` itself (not through the launcher), in the image it verified, with `--network none`, as the invoking user (the directory mounted at its own path, so both files belong to that user) and always with `--name `: `lockhttp ca init --dir ~/.local/share/lea/lockhttp/ca --name ` (lea's data dir) β `ca.pem` (public) and `ca-key.pem` (0600). P-256, `pathlen:0`, 90 days; `--force` rotates. The key stays readable by the user who ran it, so keep `--dir` out of any directory an agent container mounts (lea's data dir, not a project); lea keeps the host copy (0600) and copies it to the signer's volume (below). |
+| CA key to the signer | lea | `ca-key.pem` must be owned by uid 10004 (`signer`), mode 0600, mounted read-only in the signer's container only. lea copies it into a volume with a one-off root container of the same image: `docker run --rm --user 0 --entrypoint sh --network none -v ~/.local/share/lea/lockhttp/ca:/src:ro -v -lockhttp-ca:/ca IMAGE@sha256: -c 'install -m 0600 -o signer /src/ca-key.pem /ca/ca-key.pem && install -m 0644 /src/ca.pem /ca/ca.pem'`. |
| Signer socket directory | image | A named volume on `/run/lockhttp-signer`, shared by the signer and the gate. The image's directory is `signer:lockhttp-clients`, mode `2750`, and a new named volume takes it on first use: the socket (mode 0660) gets group `lockhttp-clients`, so the gate can connect and nothing else in the proxy namespace can. |
| Signer | its own container, uid 10004 | `docker run -d --name -lockhttp-signer --network none --user signer -v -lockhttp-ca:/etc/lockhttp-ca:ro -v -lockhttp-signer:/run/lockhttp-signer IMAGE@sha256: signer --ca-cert /etc/lockhttp-ca/ca.pem --ca-key /etc/lockhttp-ca/ca-key.pem --listen /run/lockhttp-signer/signer.sock --allow-uid 10003`. The signer refuses a key readable by group or others. |
| Gate | the gate's container | Add `-v -lockhttp-signer:/run/lockhttp-signer` and `--ca-cert /etc/lockhttp-gate/ca.pem --signer /run/lockhttp-signer/signer.sock` (lea copies `ca.pem` into `/lockhttp/gate/`). The gate never holds the CA key. |
-| Trust stores | `image/entrypoint` (root phase, before `setpriv`) | `ca.pem` into `/usr/local/share/ca-certificates/lockhttp.crt` + `update-ca-certificates`; `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `PIP_CERT`, `SSL_CERT_FILE`; nested Podman: mount the PEM in `/etc/containers/certs.d/`. Never the key. |
+| Trust stores | `image/entrypoint` (root phase, before `setpriv`) | lea mounts `ca.pem` read-only at `/etc/lea/lockhttp-ca.pem`; the entrypoint installs it as `/etc/pki/ca-trust/source/anchors/lea-lockhttp.pem` and runs `update-ca-trust extract` (the system store, which curl, git, Go, OpenSSL and the nested Podman read); `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `PIP_CERT`, `SSL_CERT_FILE`. Never the key. |
| keyproxy | | trusts `ca.pem` (`RootCAs`). |
Hosts in the policy's `splice` list (and internal hosts) are not decrypted:
@@ -203,14 +203,18 @@ proxy error).
- **Status file** (`--status-file`, JSON, rewritten on change):
`{"version":1, "console": "up|down", "pending": 2, "pending_by_container": {"lea-ab12cd34ef": 2}, "policy_fp": "sha256:β¦", "updated": "β¦"}`.
- The deck shows the counter and plays a sound on the first ASK (D6). It is
+ The deck shows the counter (D6), without a sound. It is
a notification only: approvals happen on the hub's facades.
- **Audit**: gate JSONL in `--audit-dir` (`gate-YYYY-MM-DD.jsonl`), console
audit in the console account's `~/.local/state/lockhttp/audit.log`, in
the console's home volume, which lea does not mount; the hub's audit; both carry
`request_id`, `container`, `agent`, `attribution`, `via`.
-## 6. Doctor checks for lea
+## 6. Checks for lea
+
+`lea doctor` checks that the gate answers, the CA's validity (more than 7
+days) and the console's state from the gate's status file; the others
+below are checks to make by hand.
- gate answers (`docker exec -lockhttp-gate lockhttp gate --check --listen 127.0.0.1:3130`),
squid listens on loopback only;
diff --git a/docs/policy.md b/docs/policy.md
index 400d54b..90a2341 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -9,7 +9,7 @@ the approved policy to the gate (`policy.get`) with its sha256 fingerprint.
checks the fingerprint, and keeps the previous policy when they do not
match.
-This page documents v0.1.0 as the code implements it
+This page documents the current release as the code implements it
(`internal/policy`, `internal/decide`, `internal/gate`).
## File format
@@ -193,14 +193,15 @@ For each connection, then each request, the first step that decides wins.
goes through steps 6 onwards. The gate offers HTTP/1.1 only.
5. Any other `CONNECT` is decided at the domain: a live connect grant for
container Γ host Γ port is FREE; otherwise steps 7 onwards decide, with
- no method, path or body known. Once open, the client's first bytes must
- be a complete TLS ClientHello naming the host on port 443 (a ClientHello
- on other ports must name it too), or the tunnel is closed.
+ no method, path or body known. Once open, for a host that is not an
+ internal host, the client's first bytes must be a complete TLS
+ ClientHello naming the host on port 443 (a ClientHello on other ports
+ must name it too), or the tunnel is closed.
### Grants (decrypted or plain HTTP requests)
-6. First the deny list and the secret check (steps 7 and 8) apply: no
- grant lifts them. Then a single-use authorisation for this exact request fingerprint (created
+6. First the deny list, a managed deny rule and the secret check (steps 7,
+ 7a and 8) apply: no grant lifts them. Then a single-use authorisation for this exact request fingerprint (created
when you approved a request whose client had left) is FREE and consumed.
A `GET` without body of an exact URL a listed CDN redirect opened for
this container within 60 s is FREE and consumed.
@@ -208,9 +209,13 @@ For each connection, then each request, the first step that decides wins.
### The policy (`internal/decide`)
7. **Deny list.** A host on `deny`: DENY `E_RULE`.
+7a. **Managed deny.** A `deny` rule of the company's managed configuration
+ (`[[lockhttp.bounds.rules]]`) matching the request: DENY `E_RULE` (rule
+ `managed:`). At the domain, a managed rule with methods or a path
+ counts as an ask (step 15a).
8. **Secrets** (requests only, not a `CONNECT`). A known credential format
- in the path, query (raw and unescaped), header values (except `Cookie`)
- or held body, sent to a host it does not belong to: DENY
+ in the path, query (raw and unescaped), any header value (`Cookie`
+ included) or held body, sent to a host it does not belong to: DENY
`E_SECRET_EGRESS`. Formats: GitHub tokens (GitHub hosts), Anthropic API
keys (`api.anthropic.com`, `console.anthropic.com`), AWS access keys
(`*.amazonaws.com`), Slack tokens (Slack), OpenAI keys
@@ -268,7 +273,7 @@ For each connection, then each request, the first step that decides wins.
| `read` | `GET`, `HEAD`, `OPTIONS` with an empty body | FREE on a trusted host; else ASK (unknown host) |
| `messaging` | a messaging host | ASK, red |
| `publish` | a registry host and `PUT`, `PATCH`, `DELETE` (any write on an upload host) | ASK, red |
- | `upload` | body over 64 KiB or of unknown length, or a multipart, octet-stream, image, video, audio, zip or tar type | ASK |
+ | `upload` | body over 64 KiB, or a multipart, octet-stream, image, video, audio, zip or tar type | ASK |
| `write` | anything else | ASK |
Every default ASK is `NeverAuto`. A non-read body larger than
@@ -276,6 +281,9 @@ For each connection, then each request, the first step that decides wins.
15. **Heuristics.** With `heuristics = "enforce"`, a score of 3 or more
turns any verdict but DENY into ASK, `NeverAuto`, red, with the reasons
as warnings. With `"shadow"`, the reasons are only logged.
+15a. **Managed ask.** An `ask` rule of the company's managed configuration
+ matching the request turns a FREE (or `auto`) verdict into ASK,
+ `NeverAuto`, under the rule `managed:`.
16. **Shadow mode.** With `mode = "shadow"`, see below.
### After the decision
@@ -289,13 +297,15 @@ For each connection, then each request, the first step that decides wins.
sent upstream is the host decided, never the client's. A FREE or
approved request first gets the headers of its
[credential injections](#credential-injection).
-19. An ASK request waits in the gate's queue. No console: `E_NO_CONSOLE` at
- once. Past `hold`: `E_PENDING` (the item stays on the console). The
- human's `n` or the console's timeout: `E_DENIED` or `E_TIMEOUT`.
+19. An ASK request becomes a hub ticket. No console: `E_NO_CONSOLE` at
+ once. Past `hold`: `E_PENDING` (the ticket is kept on the hub; its id is
+ in `X-LockHTTP-Ticket`). The human's denial on the hub: `E_DENIED`;
+ the ticket expiring unanswered: `E_TIMEOUT`.
With no policy received yet (the console never answered since the gate
-started), step 7 to 9 and 11 do nothing, nothing is trusted, and only the
-four Claude hosts and their allowlist are free.
+started), steps 7, 7a, 9, 11 and 15a do nothing, nothing is trusted, and
+only the four Claude hosts and their allowlist are free. Step 8 still
+applies, and so does the check for the gate's injected secrets.
## Confined agents
@@ -361,7 +371,7 @@ note = "Home Assistant long-lived token"
| `credential` | yes | The name of the secret in the gate's secrets file: lower-case letters, digits, `_`, `-`, `.`, at most 32 characters, no run of more than 16 letters and digits (a name, not a pasted token). Never the value. |
| `container` | no | The container it applies to. A container's injection wins over an all-containers one of the same header. |
| `methods` | no | The methods that get the header (upper-cased); empty: every one. `TRACE`, `TRACK` and `CONNECT` are refused: they never get it, in any case of the method (`trace` too). |
-| `paths` | no | The paths that get the header, each exact or a prefix when it ends with `*` (as a rule's `path`); empty: every one. A request outside them goes out without it (audited `inject skipped`). So does any path that is not canonical, whatever the list (an allowlist): only RFC 3986 unreserved characters (`A-Z a-z 0-9 - . _ ~`) and `/` as is, escapes only of reserved characters other than `/` (`%3A`, `%3B`, `%40`, ...), and escaped bytes >= 0x80 only as valid shortest-form UTF-8 letters, marks or digits (`caf%C3%A9`); no segment made only of dots, even with a reserved suffix (`..`, `...`, `..;x`, `..%3f`). Everything else goes out without the header: `/api/../admin`, `%2e`, `%2F`, `%5c`, `%25`, `%20`, `%00` (`..%20`, `..%00`), an escaped unreserved character (`%41`), overlong or invalid UTF-8 (`%c0%ae`), a fullwidth dot or slash, a literal `;`, `,` or `@`, an invalid escape. |
+| `paths` | no | The paths that get the header, each exact or a prefix when it ends with `*` (as a rule's `path`); empty: every one. A request outside them goes out without it (audited `inject skipped`). When `paths` is set, so does any path that is not canonical, whatever the list (an allowlist): only RFC 3986 unreserved characters (`A-Z a-z 0-9 - . _ ~`) and `/` as is, escapes only of reserved characters other than `/` (`%3A`, `%3B`, `%40`, ...), and escaped bytes >= 0x80 only as valid shortest-form UTF-8 letters, marks or digits (`caf%C3%A9`); no segment made only of dots, even with a reserved suffix (`..`, `...`, `..;x`, `..%3f`). Everything else goes out without the header: `/api/../admin`, `%2e`, `%2F`, `%5c`, `%25`, `%20`, `%00` (`..%20`, `..%00`), an escaped unreserved character (`%41`), overlong or invalid UTF-8 (`%c0%ae`), a fullwidth dot or slash, a literal `;`, `,` or `@`, an invalid escape. |
| `note` | no | Free text for you. |
Two injections of the same header, host, port and container are refused.
@@ -535,7 +545,8 @@ enforced:
- the floor (step 3) and the gate's own checks (steps 1, 2, 5, 17);
- secret matches and Claude credential mismatches (`E_SECRET_EGRESS`);
-- the deny list (`E_RULE`), at the domain and inside a decrypted tunnel.
+- the deny list (`E_RULE`), at the domain and inside a decrypted tunnel;
+- the company's managed rules (steps 7a and 15a), deny and ask.
Everything else passes, including the Claude API allowlist, messaging,
publishing and git pushes. Use it to measure what a policy would ask before
diff --git a/docs/safety.md b/docs/safety.md
index 8b3b203..6d17a91 100644
--- a/docs/safety.md
+++ b/docs/safety.md
@@ -25,8 +25,8 @@ console the only place a loosening of the policy is. In short:
like `ask`), so
nothing answers a held request but a human. Secrets are denied.
- **A decision is shared only by identical requests.** Same container,
- method, URL, significant headers and normalised body; anything else is
- its own screen.
+ method, URL, media type, every end-to-end header and normalised body;
+ anything else is its own hub ticket.
- **Hub-attached only.** The gate does not start without its hub flags,
and nothing falls back to another approver when the hub is unreachable:
the ticket stays pending until the hub answers.
@@ -43,8 +43,11 @@ console the only place a loosening of the policy is. In short:
- **The AI tightens, the human loosens.** Any change that widens what passes
without a human (a trusted host, a `free` rule, shadow mode, a
longer grant, a removed deny...) waits for your `:review`.
-- **Traced.** The gate's JSONL audit and the console's audit carry
+- **Traced.** The gate audits every decision and every hub ticket's outcome
+ in its own JSONL (and lockhub keeps its tickets); each line carries
`request_id`, `container`, `agent`, `attribution`, `via`, never a body, a
- query string or a header value.
+ query string or a header value, except a decision's warnings, which can
+ name the `mcp_servers` (names and URLs) of a `/v1/messages` body. The
+ console approves no request: it reviews policy loosenings only.
Threats, parades and residual risks: [docs/security-model.md](security-model.md).
diff --git a/docs/security-model.md b/docs/security-model.md
index ad8e054..ab33586 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -3,17 +3,21 @@
LockHTTP puts every outbound HTTP(S) request of an AI agent running in
[lea](https://github.com/DavidGodefroid/lea) through a gate
that decides it with a policy only a human loosens, and holds what needs a
-human until that human answers in a console the agent cannot reach. This
-document says what it protects, how, and where it stops. It describes
-the Docker-only setup ([docker.md](docker.md)): every command runs in the
-image, through the launcher.
+human until that human answers a ticket on lockhub, which the agent cannot
+reach. This document says what it protects, how, and where it stops. It
+describes the setup `lox run` starts (the hub and the lockhttp console) with
+the gate lea runs ([how-it-works.md](how-it-works.md)); every command runs in
+the image. The standalone launcher ([docker.md](docker.md)) names its
+containers and volumes differently: `lockhttp-console`, `lockhttp-run`,
+`lockhttp-home`.
## Principles
1. **Two planes.** The gate (data plane) carries the traffic and applies the
- policy; the console (control plane) holds the policy and the human's
- answers. The gate has no authority of its own: it never reads a policy
- file and cannot approve anything.
+ policy; the console (control plane) holds the policy and asks the human
+ about every loosening; the human answers held requests on lockhub. The
+ gate has no authority of its own: it never reads a policy file and
+ cannot approve anything; the console approves no request.
2. **The network is the boundary.** In lea the agent's container has no
route out except the proxy container; proxy variables are a convenience.
3. **NeverAuto.** A human answers every ASK: every hub ticket of the gate is
@@ -22,9 +26,10 @@ image, through the launcher.
passes without a human waits for the human's `:review`.
5. **Fail closed.** No console, an unknown source, an unreadable source map,
an unparsable policy: nothing that needs a human goes through.
-6. **Traced, without content.** Every decision is audited with its
+6. **Traced, without content.** The gate audits every decision with its
container, agent, task and session; never a body, a query string or a
- header value.
+ header value. One exception: a decision's warnings, which can name the
+ `mcp_servers` (names and URLs) found in a `/v1/messages` body.
## Assets, attackers, scope
@@ -46,10 +51,11 @@ image, through the launcher.
|---|---|
| Agent β network | lea: the agent's container is on an `--internal` network whose only peer is the proxy container; squid listens on 127.0.0.1 only, so the gate is the only HTTP way out ([lea.md](lea.md) Β§2.2). |
| Agent β gate | the gate reads the container from the local address the connection arrived on (one per internal network, `sources.json`); an unknown address is refused. The agent name (`Proxy-Authorization`) is recorded, not trusted. |
-| Gate β console | lockkit's Unix socket in `/run/lockhttp` (`2710 lockhttp:lockhttp-clients`), the volume `lockhttp-run`, mounted only in the console's and the gate's containers; the console checks the peer's uid (`SO_PEERCRED`) against the image's clients group (the `gate` account, uid 10003) and `allowed_uids` (empty unless the image is built with `ALLOWED_UIDS`); the gate refuses to run as root. |
-| Console β human | the console runs as `lockhttp` (uid 10021, not in the clients group) in the container `lockhttp-console`, started by the human through the launcher, with no log driver (no approval screen in `docker logs`); it is the only container with the volume `lockhttp-home` (policy, approved policy, audit); approval screens in its own terminal, sanitised; 5 minutes without an answer is a denial. |
+| Gate β console | lockkit's Unix socket in `/run/lockhttp` (`2710 lockhttp:lockhttp-clients`), the socket volume (`_-run` under `lox run`, `lockhttp-run` with the standalone launcher), mounted only in the console's and the gate's containers; the console checks the peer's uid (`SO_PEERCRED`) against the image's clients group (the `gate` account, uid 10003) and `allowed_uids` (empty unless the image is built with `ALLOWED_UIDS`); the gate refuses to run as root. |
+| Console β human | the console runs as `lockhttp` (uid 10021, not in the clients group) in `lox run`'s service `lock-` (`lockhttp-console` with the standalone launcher), with no log driver (no screen in `docker logs`); it is the only container with its home volume (`_-home` under `lox run`, `lockhttp-home` standalone: the approved policy, the console's own log) and the profile's copy; its terminal shows only policy reviews, sanitised. |
+| Gate β human | each held request is a signed, `NeverAuto` hub ticket; the human approves or denies it on a lockhub facade (`lox approve`, lea's deck, a phone); the gate audits the outcome in its own JSONL. |
| Image's accounts | `lockhttp` (console, 10021), `gate` (10003, in `lockhttp-clients`, gid 10020), `signer` (10004); `/etc/lockhttp/system.toml` and the binary owned by root; the launcher on the host root-owned, running the image by the digest verified with cosign at install. |
-| Gate β CA key | `lockhttp signer`, under its own uid, alone reads the key (refused if group- or world-readable) and issues 24-hour leaves over a Unix socket to allowed uids. |
+| Gate β CA key | at run time `lockhttp signer`, under its own uid, alone reads the key (refused if group- or world-readable) and issues 24-hour leaves over a Unix socket to allowed uids. Under lea the key is created and kept on the host in lea's data dir, then copied into the signer's volume. |
| Policy | the console account's file, read by the console only, approved by fingerprint; the gate checks the fingerprint of what it receives. |
## Threats and parades
@@ -57,23 +63,23 @@ image, through the launcher.
| # | Threat | Parade | Residual |
|---|---|---|---|
| T1 | The agent goes out directly, around the gate. | lea's `--internal` networks; squid on loopback only; keyproxy chained through the gate; SSH git forwarders refused with LockHTTP on (lea side). Direct mode refuses non-public addresses except internal hosts. | Depends on lea's network setup (rootless Podman without an isolated gateway: lea's isolation test, decision D2). |
-| T2 | Exfiltration through DNS (`.evil.com`). | The gate resolves a name only after the decision (direct mode), squid resolves after the gate; heuristics score long, deep and high-entropy labels. | The container's resolver is lea's (non-forwarding DNS is a lea requirement). Heuristics run in shadow by default. |
-| T3 | DNS over HTTPS, IP literals, metadata endpoints, odd ports, `h2c`, nested `CONNECT`, SNI and Host spoofing. | The floor, which no policy loosens and shadow mode does not lift; a full ClientHello naming the `CONNECT` host is required on 443; the `Host` sent upstream is the decided host. | DoH hosts not on the list and not named `doh.*`/`dns.*` are decided like any host (unknown: ASK). |
+| T2 | Exfiltration through DNS (`.evil.com`). | Squid resolves after the gate; on decrypted or plain HTTP requests, heuristics score long, deep and high-entropy labels. | **With the hub's networks given (`--hub-net`, which lea always passes), the gate resolves every name that passes the floor before the decision**, to refuse the hub's addresses: a lookup of `.evil.com` leaves even when the request is then denied. The container's resolver is lea's (non-forwarding DNS is a lea requirement). A `CONNECT` decided at the domain is not scored. Heuristics run in shadow by default. |
+| T3 | DNS over HTTPS, IP literals, metadata endpoints, odd ports, `h2c`, nested `CONNECT`, SNI and Host spoofing. | The floor, which no policy loosens (except `internal_hosts`, for their declared ports and single-label names) and shadow mode does not lift; a full ClientHello naming the `CONNECT` host is required on 443 for a non-internal host; the `Host` sent upstream is the decided host. | DoH hosts not on the list and not named `doh.*`/`dns.*` are decided like any host (unknown: ASK). |
| T4 | Exfiltration in reads to a trusted host (data in the URL or headers). | Decryption lets the gate see URLs and headers; secret formats are denied outside their hosts; the exfiltration score asks in `enforce`. | Without decryption the gate sees only the host. Low-bandwidth channels stay under the threshold. Heuristics are shadow by default. Spliced hosts are opaque. |
-| T5 | A write to a trusted host (a webhook, an issue, a push). | Trusted means reads only: with decryption every non-read asks (`NeverAuto`, red for messaging, publishing, pushes), and a git push shows its refs. | **Without decryption, a trusted host is free at the domain, reads and writes**, and an approved `CONNECT` opens its host for `connect_grant`; the screen and the doctor say so. |
-| T6 | The Claude API as a relay: `mcp_servers`, server tools, code execution containers, Files, a third-party key. | With decryption: the `/v1/messages` parameter allowlist, `/v1/files` asks, any other path or Anthropic host asks, credentials checked against the caller's list. | Without decryption the four Claude hosts are free at the domain. Prompt content sent to Anthropic is intended traffic. With no `credentials.json` the key check is off. |
-| T7 | A secret leaving with a request. | Known formats (GitHub, Anthropic, AWS, Slack, OpenAI, Google, npm, GitLab, private keys) in the URL, headers or held body are denied outside their hosts, in shadow mode too. | Unknown formats, encoded or split secrets, and bodies over `buffer_limit` streamed by a `free` rule are not matched. Cookies are not scanned. |
+| T5 | A write to a trusted host (a webhook, an issue, a push). | Trusted means reads only: decryption covers `CONNECT` to port 443, where every non-read asks (`NeverAuto`, red for messaging, publishing, pushes), and a git push shows its refs. | **Without decryption, a trusted host is free at the domain, reads and writes**, and an approved `CONNECT` opens its host for `connect_grant`; the screen and the doctor say so. A `CONNECT` to port 80 of a trusted or Claude host is free at the domain and the plain HTTP inside is not decided: lea's squid refuses `CONNECT` to any port but 443, the gate alone does not. |
+| T6 | The Claude API as a relay: `mcp_servers`, server tools, code execution containers, Files, a third-party key. | With decryption: the `/v1/messages` parameter allowlist, `/v1/files` asks, any other write or Anthropic host asks, credentials checked against the caller's list. | Without decryption the four Claude hosts are free at the domain. A policy rule naming a Claude host is applied before the allowlist, and shadow mode turns the allowlist's asks into FREE. Prompt content sent to Anthropic is intended traffic. With no `credentials.json` the key check is off. |
+| T7 | A secret leaving with a request. | Known formats (GitHub, Anthropic, AWS, Slack, OpenAI, Google, npm, GitLab, private keys) in the URL, headers or held body are denied outside their hosts, in shadow mode too. | Unknown formats, encoded or split secrets, and bodies over `buffer_limit` streamed by a `free` rule are not matched. |
| T8 | Approval fatigue. | Container-scoped `free` rules for routine calls (confirmed with `:review`); identical requests share one screen; the pending count per container, method, host and path; a single-use authorisation after `E_PENDING` instead of a second screen. | The human factor. Requests with another body are separate screens, by design. |
| T9 | The agent manipulates the policy. | The policy lives in the console account's home; the gate only receives it; every loosening waits for `:review`; `auto` is refused on forbidden classes at parse time, and an `auto` rule only asks. | A human who approves a bad `:review`. |
| T10 | A compromised gate. | Dedicated non-root uid; no decision authority (every hub ticket it makes is `NeverAuto`; only a human approves on lockhub); no CA key. | It sees and can alter FREE traffic and decrypted content; it can ask the signer for leaves for any valid host name while it runs; it can lie to the human about a request's content within the screen's bounds. |
-| T11 | Theft of the CA key. | Only the signer reads it (`0600`, its own uid); CA `pathlen:0`, 90 days, trusted only in lea's containers; `lockhttp ca init --force` rotates. | Whoever holds the key can intercept traffic of containers that trust the CA until it expires or is rotated. |
+| T11 | Theft of the CA key. | At run time only the signer reads it (`0600`, its own uid); the host copy in lea's data dir stays on the host; CA `pathlen:0`, 90 days, trusted only in lea's containers; `lockhttp ca init --force` rotates. | Whoever holds the key can intercept traffic of containers that trust the CA until it expires or is rotated. |
| T12 | One agent impersonates another. | Rules apply to containers, never to agents; an agent token from another container is marked `ambiguous`. | Agents in one container share a uid: attribution within a container is declarative. |
| T13 | Replay or forgery of an approval. | A decision covers one fingerprint (container, method, URL, media type, every end-to-end header value hashed, normalised body); a single-use authorisation is consumed once and lives 10 minutes; a connect grant is per container Γ host Γ port. | During `connect_grant`, a `CONNECT` grant opens the host for any traffic of that container. |
| T14 | Prompt injection through the approval screen. | Every field the gate sends is bounded (512 B per field, 1 KiB preview, 16 warnings, 32 refs) and sanitised by lockkit; the preview is masked (personal data, credentials); the agent name is labelled "declared". | Text the human reads is still chosen in part by the agent (paths, body preview). |
-| T15 | The console is absent or killed. | Every ASK is refused at once (`E_NO_CONSOLE`); FREE continues on the last approved policy. | Reduced availability, by design. |
-| T16 | The console socket reachable by agents. | Besides the console, the volume `lockhttp-run` is mounted in the gate's container only, never in an agent's; the clients group exists only in the image, where it holds the `gate` account; the agent gets neither the socket nor the Docker socket. | Any account that may run `docker` on the host can mount `lockhttp-run`, and more ([below](#what-docker-does-and-does-not-separate)). |
+| T15 | The console is absent or killed. | Every ASK is refused at once (`E_NO_CONSOLE`); FREE continues on the last approved policy. A policy that does not decode counts as no console; one whose fingerprint does not match is not installed, and the previous one stays. | Reduced availability, by design. |
+| T16 | The console socket reachable by agents. | Besides the console, the socket volume is mounted in the gate's container only, never in an agent's; the clients group exists only in the image, where it holds the `gate` account; the agent gets neither the socket nor the Docker socket. | Any account that may run `docker` on the host can mount the socket volume, and more ([below](#what-docker-does-and-does-not-separate)). |
| T18 | In hub mode, a forged, replayed or misdirected decision; the agent reaching the hub. | A decision verifies under the pinned hub key only, must name this instance, the instance key and the ticket's plan hash (the request fingerprint), under the policy fingerprint in force; its nonce is consumed once and its pass once. The instance key lives in the gate's volume only. The gate refuses the hub's host name and its networks as targets, even with `internal_hosts`. A ticket's clear screen stays in the gate's volume and leaves only sealed: to a facade key pinned with `--facade-keys-file` (a reveal), or, with `--seal-clear`, to every device pinned with `--devices-file`; the hub relays ciphertext. A renewal of an expired ticket is re-checked against the policy in force, and a changed policy is a new ticket. | With `--upstream`, squid resolves names again after the gate: a name re-pointed into the hub's network between the gate's check and squid's lookup is not seen by the gate (squid's own rules and lea's networks still apply). |
-| T17 | The agent edits the policy or the approved policy. | Both live in `lockhttp-home`, mounted only by the console account's commands (`console`, `policy`), never by the gate or an agent; the project's `.lockhttp/config.toml`, which `profile add` writes and `lox run` copies, is only a proposal: any loosening in it still waits for `:review`. | An account that may run `docker` can open `lockhttp-home` in a container of its own and change the approved policy. |
+| T17 | The agent edits the policy or the approved policy. | Both live in the console's volumes (its home and the profile's read-only copy under `lox run`, `lockhttp-home` with the standalone launcher), mounted only in the console account's containers, never by the gate or an agent; the project's `.lockhttp/config.toml`, which `profile add` writes and `lox run` copies, is only a proposal: any loosening in it still waits for `:review`. | An account that may run `docker` can open the console's home volume in a container of its own and change the approved policy. |
| T19 | A credential the agent holds leaks (its commands, logs, files, a request to another host). | Credential injection: the secret lives in the gate's secrets file (`0600`, the gate's container only), the policy names it only, and the gate adds the header after the verdict to one host and port, on a decrypted request or plain HTTP to an internal host; a request of the agent carrying the value (as is, URL-escaped, hex, base64 at any alignment), in its URL, headers, body, host (absolute URL, `Host`, `CONNECT` authority) or header names, is `E_SECRET_EGRESS` for every host (a value in a host or header name is refused before the floor, the hub's DNS check and the hub), with streamed and `gzip`/`deflate` bodies, WebSocket frames and plain tunnels scanned too (an encoding the gate cannot decode is refused); every response from a host and port with an injection (any path, any container) has the values redacted from its status, headers and body, with `Range`/`If-Range` removed and a partial response refused; TRACE to such a host is refused and no request to it upgrades; injections may be limited to methods and paths; the audit and the hub get the injection's name, never the value. | A compromised gate holds the values (T10). A value split across requests, frames or reads, or otherwise encoded by the agent, is not matched; a tunnel the gate does not decrypt is ciphertext; a target that transforms the credential before echoing it, or serves parts of it in separate responses through its own API, is not redacted; a value split over host names or written in punycode is not matched in the host ([policy.md](policy.md#credential-injection)). |
## Security requirements
@@ -86,11 +92,14 @@ These do not change with the policy ([decisions.md](decisions.md)):
- Every screen is `NeverAuto`: the gate runs hub-attached only, every hub
ticket it makes is `NeverAuto`, and an `auto` rule asks like `ask`.
- A human decision is shared only by requests of identical fingerprint.
-- The Claude API is checked per path and parameter once decrypted.
-- Fail closed: no console means every ASK is refused; an unknown source, an
- unreadable source map or an unreadable credentials file refuses; a policy
- whose fingerprint does not match is not installed.
-- The gate never reads a policy; the signer alone holds the CA key.
+- The Claude API is checked per path and parameter once decrypted, unless
+ a policy rule names the Claude host or the profile is in shadow mode.
+- Fail closed: no console means every ASK is refused; an unknown source or
+ an unreadable source map refuses; an unreadable credentials file denies
+ every Claude credential; a policy whose fingerprint does not match is not
+ installed.
+- The gate never reads a policy; at run time the signer alone reads the CA
+ key.
## Residual risks and limits
@@ -104,9 +113,10 @@ These do not change with the policy ([decisions.md](decisions.md)):
- **HTTP/1.1 only to clients when decrypting.** Clients that require HTTP/2
fail rather than bypass.
- **A WebSocket session is one approval.** Frames after the upgrade are not
- inspected.
+ decided; with injected secrets, the client's frames are scanned for them.
- **Heuristics are in shadow by default**, and shadow mode lets everything
- but the floor, secrets and the deny list through.
+ but the floor, secrets, the deny list and the company's managed rules
+ through.
- **Grants skip the rules.** A single-use authorisation or a CDN redirect
exemption is FREE without the rule and heuristic checks (the floor, the
deny list and the secret check still apply); both are bound to one exact
@@ -120,20 +130,24 @@ These do not change with the policy ([decisions.md](decisions.md)):
## What Docker does and does not separate
-The gate's container reaches the console only through the socket in
-`lockhttp-run`, as uid 10003; it holds no policy file and cannot approve.
-lea's agent containers get neither `lockhttp-run`, nor `lockhttp-home`, nor
-the Docker socket, and reach the network only through the gate.
+The gate's container reaches the console only through the socket in the
+socket volume, as uid 10003; it holds no policy file and cannot approve.
+lea's agent containers get neither the console's socket volume, nor its
+home volume, nor the Docker socket, and reach the network only through the
+gate. Under `lox run` these are `_-run` and
+`_-home`, and the console is the service `lock-`; the
+standalone launcher's are `lockhttp-run`, `lockhttp-home` and
+`lockhttp-console`.
The Docker daemon is the residual boundary. Whoever can run `docker`
commands on the host (root, members of the `docker` group, the owner of a
rootless daemon) can:
-- `docker attach lockhttp-console` and type an approval;
+- attach to the console's container and confirm a policy loosening;
- `docker exec` into the console's container, or read its memory;
-- mount `lockhttp-home` in another container and read or change the policy,
- the approved policy and the console's audit;
-- mount `lockhttp-run` and talk to the console as `gate`;
+- mount the console's home volume in another container and read or change
+ the approved policy and the console's log;
+- mount the socket volume and talk to the console as `gate`;
- run the gate's or the signer's container differently, or read the CA key
given to the signer.
diff --git a/docs/usage.md b/docs/usage.md
index 81e7306..b8f0981 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -27,11 +27,16 @@ image, as the account it needs ([docker.md](docker.md#subcommand--docker-run)).
lea does not use the launcher for the gate and the signer: it runs them
from the same image beside its proxy container ([lea.md](lea.md)). A path
given to a command is a path inside its container: only `ca init` and the
-launcher verbs (the project) mount a host directory; `LOCKHTTP_DOCKER_ARGS`
-adds mounts for the others.
+launcher verbs (the project) mount a host directory of yours;
+`LOCKHTTP_DOCKER_ARGS` adds mounts for the others. Every container also gets
+the company's managed directory (`/etc/lockfamily`, or
+`/Library/Application Support/lockfamily` on macOS), read-only at
+`/etc/lockfamily`, when it exists.
Flags use Go's syntax: `-flag value`, `--flag value` or `--flag=value`.
-Positional arguments are refused.
+Positional arguments are refused, except `init ` and
+`update [vX.Y.Z]`, which take one. `hub-key` takes `--home` only with two
+dashes (`--home DIR` or `--home=DIR`).
## Exit codes
@@ -279,7 +284,7 @@ files are yours.
| Flag | Default | Meaning |
|---|---|---|
| `--dir DIR` | required | Directory (created `0700`) for `ca.pem` (`0644`) and `ca-key.pem` (`0600`). |
-| `--name NAME` | the host name | Installation name in the CA's subject. Through the launcher the host name is the container's: pass `--name`. |
+| `--name NAME` | the host name | Installation name in the CA's subject. Through the launcher it defaults to the host's name (the launcher passes `--name "$(uname -n)"`). |
| `--force` | off | Replace an existing CA (rotation). Without it, an existing `ca-key.pem` is refused. |
The CA is ECDSA P-256, `pathlen:0`, valid 90 days. Trust `ca.pem` in the
@@ -302,8 +307,8 @@ The HTTP(S) proxy. It runs hub-attached only: without `--hub`,
`--hub-key-file` and `--instance` it exits with a usage error (exit 3,
"launched by `lox run` only"); lea passes them from `lox run`'s `up.json`.
It refuses to run as root; in the image it runs as `gate` (uid 10003).
-Each flag but `--check` has an environment variable, read when the flag is
-not given.
+Each flag but `--check` and `--hub-net` has an environment variable, read
+when the flag is not given.
Through the launcher, `lockhttp gate` runs in the container `lockhttp-gate`
with the socket volume, publishes its port on `LOCKHTTP_PUBLISH`
@@ -315,7 +320,7 @@ with the socket volume, publishes its port on `LOCKHTTP_PUBLISH`
| `--listen ADDR` | `LOCKHTTP_LISTEN` | `127.0.0.1:3130` | Address to listen on. |
| `--upstream URL` | `LOCKHTTP_UPSTREAM` | none | Proxy to send through, `http://host:port` (lea: squid, `http://127.0.0.1:3128`). Empty: the gate dials targets itself and refuses non-public addresses (except internal hosts). |
| `--profile P` | `LOCKHTTP_PROFILE` | `default` | Console profile to dial. |
-| `--sources FILE` | `LOCKHTTP_SOURCES` | none | `sources.json` written by lea. Empty: every connection is container `local`. An unreadable or invalid file at start is a configuration error; later, it refuses every connection until fixed. |
+| `--sources FILE` | `LOCKHTTP_SOURCES` | none | `sources.json` written by lea. Empty: every connection is container `local`, not known to run confined (`no_lea_sources`): its requests are refused with `E_UNCONFINED` unless the profile sets `unconfined = true` ([Confined agents](policy.md#confined-agents)). An unreadable or invalid file at start is a configuration error; later, it refuses every connection until fixed. |
| `--credentials FILE` | `LOCKHTTP_CREDENTIALS` | none | `credentials.json` written by lea: hashes of each container's Claude credentials. Empty: the check is off. Unreadable or invalid: every credential is unknown (denied). |
| `--secrets FILE` | `LOCKHTTP_SECRETS` | none | The gate's secrets file: the values the policy's `inject` entries name ([policy.md](policy.md#credential-injection)). JSON `{"version": 1, "secrets": {"name": "value"}}`, mode `0600` (refused if group- or world-readable), in the gate's container only, never an agent's. Reloaded when it changes. Invalid at start: a configuration error; later, every injection is refused (`E_INJECT`). |
| `--audit-dir DIR` | `LOCKHTTP_AUDIT_DIR` | none (stderr) | Directory (created `0700`) of the JSONL audit: `gate-YYYY-MM-DD.jsonl` (UTC), files `0600`, kept 30 days. |
@@ -376,7 +381,7 @@ by the hub are audited (`reveal`/`renew`, `approval` `hub-claimed`).
releases each lockhttp release works with. Under `lox run`, lea runs the gate in hub mode
(lockhub's `docs/lox-run.md`), and only from an `up.json` that says what the gate pins
(`"lockhttp_gate": 1`): that needs lockhub v0.2.2 or later and lea v0.3.0 or later, for every
-lockhttp release below. A gate run by hand works with the hub image of the last column.
+lockhttp release from v0.3.0 to v0.10.0; v0.11.0 and later need lea v0.16.0 or later. A gate run by hand works with the hub image of the last column.
From v0.6.0 the gate is hub-attached only (there is no standalone gate): run it under `lox run`,
with a trusted `up.json` naming one lockhttp lock. lea after v0.3.5 (lea#232) then refuses to
start a gate without one and says to run `lox run`; lea v0.3.0 to v0.3.5 instead falls back to a
@@ -384,6 +389,11 @@ standalone gate, which v0.6.0 and later refuse: that gate container exits and re
| lockhttp | lockkit | Under `lox run` (lea's gate) | Hub image, gate run by hand |
|---|---|---|---|
+| v0.12.0 | v0.20.0 | as v0.11.0; `lox run` passes the console `--runtime-gids` only from a lockhub that pins `"lockhttp": "v0.12.0"` (v0.12.1 or later) | v0.2.0 or later |
+| v0.11.0 | v0.20.0 | as v0.10.0, with lea v0.16.0 or later (the brew or lockfamily launcher) | v0.2.0 or later |
+| v0.10.0 | v0.20.0 | as v0.6.0; the gate and the console must be the same lockhttp release | v0.2.0 or later |
+| v0.9.1 | v0.18.0 | as v0.6.0 | v0.2.0 or later |
+| v0.9.0 | v0.18.0 | as v0.6.0 | v0.2.0 or later |
| v0.8.1 | v0.14.1 | as v0.6.0 | v0.2.0 or later |
| v0.8.0 | v0.13.0 | as v0.6.0 | v0.2.0 or later |
| v0.7.1 | v0.10.0 | as v0.6.0 | v0.2.0 or later |
@@ -427,8 +437,9 @@ lockhttp signer --ca-cert FILE --ca-key FILE --listen SOCKET [--allow-uid N ...]
The only process that reads the CA key. It issues 24-hour leaf certificates
(capped at the CA's expiry) to the gate over a Unix socket. In the image it
-runs as `signer` (uid 10004). The launcher mounts nothing for it: lea runs
-it with the key and a socket directory shared with the gate
+runs as `signer` (uid 10004). The launcher mounts only its socket volume
+(`lockhttp-signer`), not the CA key: lea runs it with the key and a socket
+directory shared with the gate
([lea.md](lea.md#3-mitm-phase-2-optional)).
| Flag | Default | Meaning |
@@ -456,7 +467,7 @@ home directory.
`lockhttp version` (or `--version`) prints the launcher's version and the
image it runs (`lockhttp launcher X (image I)`), then the image's
-`lockhttp vX`; `lockhttp help` (`-h`, `--help`) prints the usage. `lockhttp`
+`lockhttp X.Y.Z` (no `v`); `lockhttp help` (`-h`, `--help`) prints the usage. `lockhttp`
without a command prints the usage on stderr and exits 3.
## `lockhttp update`
@@ -466,9 +477,13 @@ lockhttp update [vX.Y.Z]
```
A launcher command, run on the host: replaces the launcher with a release's
-(latest by default) after checking the cosign signature of `checksums.txt`,
-the archive's checksum and the image's signature, then `docker pull`s the
-pinned image ([docker.md](docker.md#install-and-update)).
+(by default the newest of the release feed, pre-releases included) after
+checking the cosign signature of `checksums.txt`, the archive's checksum
+and the image's signature, then `docker pull`s the pinned image
+([docker.md](docker.md#install-and-update)). Without cosign it stops,
+unless `LOCKHTTP_SKIP_COSIGN=1`: then neither signature is checked (only
+the checksum) and the new launcher runs the image by its tag. With cosign
+installed, `LOCKHTTP_SKIP_COSIGN` has no effect.
## Files
@@ -479,7 +494,7 @@ pinned image ([docker.md](docker.md#install-and-update)).
| `/etc/lockhttp/system.toml` | image | root, `0644` | separated setup: console account, clients group, socket directory, `allowed_uids` (build arg `ALLOWED_UIDS`) |
| `/run/lockhttp/` | volume `lockhttp-run` | `lockhttp:lockhttp-clients`, `2710` | the console's sockets, `user-.sock` |
| `~/.config/lockhttp/config.toml` | volume `lockhttp-home` | `lockhttp`, `0600` | the policy |
-| `~/.local/state/lockhttp/audit.log` | volume `lockhttp-home` | `lockhttp` | the console's audit (approvals, policy reviews) |
+| `~/.local/state/lockhttp/audit.log` | volume `lockhttp-home` | `lockhttp` | the console's audit (policy reviews; it approves no request) |
| `--audit-dir/gate-YYYY-MM-DD.jsonl` | the gate's container (lea: a host directory) | the gate's uid | the gate's audit |
| `ca.pem`, `ca-key.pem` | the `ca init --dir` directory | you; lea gives the key to the signer's uid | the local CA |
@@ -495,5 +510,7 @@ Both audits write one JSON object per line with lockkit's base fields
`resp_bytes`, `duration_ms`, `policy_fp`. Never a body, a query string or a
header value.
-`decision` is `free`, `approved`, `refused`, or `shadow-ask` /
-`shadow-deny` for what shadow mode let through.
+`decision` is `free`, `approved`, `refused`, `refused-unconfined` (a
+sender not known to run confined), `denied` (the human denied the hub
+ticket), `timeout` (the ticket expired), `renew` (a renewal the hub asked
+for), or `shadow-ask` / `shadow-deny` for what shadow mode let through.
diff --git a/site/404.html b/site/404.html
index e8fb54e..0f9b9ad 100644
--- a/site/404.html
+++ b/site/404.html
@@ -102,7 +102,7 @@
Only if you turn it on. Without it, lockhttp decides HTTPS on the host name and port (CONNECT and SNI).
-
With a CA made per installation (lockhttp ca init), trusted only inside leaβs containers, and the signer that holds its key, the gate decrypts and decides each request. Hosts that pin their certificates go in a splice list and stay decided at the domain.
+
With a CA made per installation (lockhttp ca init --dir DIR), trusted only inside leaβs containers, and the signer that holds its key, the gate decrypts and decides each request. Hosts that pin their certificates go in a splice list and stay decided at the domain.
Can the agent approve its own request?
@@ -99,7 +99,7 @@
Can I let some requests through without asking?
Can the agent call an API without holding its token?
-
Yes, since v0.8.0. A policy inject entry has the gate add the credential header for one exact host and port, from its own secrets file. How it works.
+
Yes, since v0.8.0, with TLS decryption (or plain HTTP to an internal host). A policy inject entry has the gate add the credential header for one exact host and port, from its own secrets file; on a tunnel it does not decrypt, it adds nothing. How it works.
agent container (internal network, no other route)
+
agent container (internal network, no other route)
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β your agent Β· curl Β· git Β· npm Β· chromium β
β HTTP(S)_PROXY=http://<agent>:<token>@lea-proxy:3130 β
ββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ
β the only way out
- lea proxy network namespace βΌ (gate + signer sidecars)
+ lea proxy network namespace βΌ (the gate sidecar)
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β lockhttp gate :3130 (own uid, never 0) β
β source β container Β· policy β FREE / ASK / DENY β
- β lockhttp signer (optional: holds the CA key) β
β squid 127.0.0.1:3128 (network floor) βββΆ Internet β
ββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ
- β Unix socket, volume lockhttp-run:
+ β Unix socket, volume <project>_<lock>-run:
β the gate and the console only
console container (lox run)βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- β lockhttp console --profile default β
- β account lockhttp, volume lockhttp-home (policy) β
- β serves the policy Β· policy review Β· audit β
+ β lockhttp console --profile <profile> β
+ β account lockhttp, home volume (approved policy) β
+ β serves the policy Β· policy review Β· its own log β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+ signer container (optional, --network none, own uid)
+ lockhttp signer: holds the CA key, signs the gate's leaves
gate βββΆ lockhub (hub network: lea's proxy only)
held request β signed ticket β you, on a facade
@@ -146,7 +147,8 @@
LLM APIs as a relay
POST /v1/messages and /v1/messages/count_tokens pass only without mcp_servers or container, and with no server tool other than web_search;
/v1/files* asks;
a credential that is not one of the containerβs own is denied (E_SECRET_EGRESS);
-
any other path or host under the Anthropic domains asks, never answered without a human.
+
OAuth paths and other body-less reads on the four Claude hosts pass; any other write there, and any other host under the Anthropic domains, asks, never answered without a human, unless you list that host as trusted (the default set has docs.anthropic.com);
+
a policy rule naming a Claude host applies before these checks, and shadow mode lets their asks through.
A policy inject entry has the gate add a header, such as Authorization: Bearer β¦, for one exact host and port. The secret comes from the gateβs own secrets file.
+
A policy inject entry has the gate add a header, such as Authorization: Bearer β¦, for one exact host and port, on a decrypted request or plain HTTP to an internal host. The secret comes from the gateβs own secrets file.
The agent sends its request without the credential. A request that carries the injected secret itself is refused with E_SECRET_EGRESS; a missing secret, with E_INJECT.
-
[[profiles.default.inject]]
+
[[profiles.default.internal_hosts]]
+host = "homeassistant" # a single-label host needs this entry
+ports = [8123]
+read = true
+
+[[profiles.default.inject]]
id = "home-assistant"
host = "homeassistant"
port = 8123
@@ -190,7 +197,7 @@
Rules
max_body = "256KiB"
Any loosening (a new host, a wider method or path, ask to free, a wider scope) waits for your confirmation in the consoleβs :review.
-
An auto rule stays valid but asks like ask: every held request is a NeverAuto ticket. Uploads, messaging, registry publishing, git-receive-pack, spliced hosts, heuristic hits, secrets and production profiles can never be auto.
+
An auto rule stays valid but asks like ask: every held request is a NeverAuto ticket. A rule for every host, a spliced host, messaging, registry publishing, git-receive-pack, a write to any path of a git forge and any rule of a production profile can never be auto; uploads, heuristic hits and secrets are checked per request.
@@ -211,10 +218,12 @@
Refusal codes
E_BODY_TOO_LARGE
the body is over the buffer limit
send less, or ask for a rule
E_SOURCE_UNKNOWN
the gate cannot tell which container sent the request
use the proxy address lea gave
E_INJECT
the policy injects a credential for this host, and the gate lacks it
ask the user; never send the credential itself
+
E_UNCONFINED
the sender is not known to run confined (a gate without leaβs source map), and the profile does not set unconfined = true
run inside lea, or ask the user
+
E_METHOD
TRACE or TRACK to a host where the gate injects a credential
use another method
-
Also registered: E_HOST_UNKNOWN, E_METHOD, E_EXFIL_SUSPECT, E_CLAUDE_API_PARAM and E_PINNED (in the gateβs audit only).
+
Also registered: E_HOST_UNKNOWN, E_EXFIL_SUSPECT, E_CLAUDE_API_PARAM and E_PINNED (in the gateβs audit only).
v0.9A Lock of the Lock Family Β· open source Β· Apache 2.0
+
v0.12A Lock of the Lock Family Β· open source Β· Apache 2.0
Your agent browses. You hold the key.
Every outbound HTTP(S) request of your AI agent running in lea goes through lockhttp. Reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you.
@@ -117,8 +117,8 @@
Why lockhttp?
Writes to a trusted host still need a human
No
With decryption
Approval runs outside the agent, in another account
No
Yes
LLM APIs checked as a relay (the Claude API today)
No
With decryption
-
Credential sent outside its own host is denied
No
Yes
-
Credentials injected by the proxy, never held by the agent
No
Yes
+
A known credential format sent outside its own host is denied
No
With decryption
+
Credentials injected by the proxy, never held by the agent
No
With decryption (or plain HTTP to an internal host)
Policy loosening needs a human confirmation
No
Yes
Every request traced to container, agent and session
No
Yes
@@ -150,12 +150,12 @@
Highlights
π€
Never answered automatically
Every held request is a NeverAuto ticket: lox runβs auto mode never answers it, a human does. Only a free rule you confirmed lets a request pass unasked.
π
Credentials injected
The gate can add an Authorization header for one host and port, from its own secrets file. The agent calls the API without ever holding the token.
π§±
Fail closed
No console: an ask is refused at once (E_NO_CONSOLE). An unknown source, a policy that does not decode, an error while deciding: deny.
A decision is shared only by requests of identical fingerprint: container, method, URL, every end-to-end header and normalised body.
πΆοΈ
Masked previews
The approval screen shows a masked preview of the body (PII detectors, terminal sanitising, first 1 KiB), never the clear body.
π
CA key out of the data plane
For TLS decryption, a separate lockhttp signer holds the CA key and issues leaf certificates. The gate never sees the key.
-
π
Shadow mode
mode = "shadow" logs what would have asked or been denied and lets it pass, so you can tune the policy first. The floor and secret checks stay on.
+
π
Shadow mode
mode = "shadow" logs what would have asked or been denied and lets it pass, so you can tune the policy first. The floor, the secret checks, the deny list and the companyβs managed rules stay on.
π·οΈ
Refusals the agent can act on
Every refusal carries a stable code (X-LockHTTP-Code), a request id and a retry rule: retry, ask the user, or stop.
-
π
Full audit
Free and denied requests go to the gateβs daily JSONL log, asks to the consoleβs audit, joined by request_id. Never a body or a secret.
+
π
Full audit
Every decision and every hub ticketβs outcome goes to the gateβs daily JSONL log, by request_id; lockhub keeps its tickets. Never a body or a secret.
lockhttp runs in Docker, beside lea. On your machine you need Docker, lea, lox and the lockhttp launcher, a shell script that runs every command in the signed lockhttp image.
@@ -101,7 +101,7 @@
Without Homebrew
Requirements
-
Docker, and cosign for the install script.
+
Docker, and cosign for the Lock Family installer.
lea: it runs the agents in containers on internal networks, and runs the gate beside its proxy (Docker, or rootless Podman).
lockhubβs lox: the gate runs hub-attached only, and you answer held requests on the hub.
Under its own account (lockhttp), the only container with the policy volume. The agent gets neither its socket nor the Docker socket.
NeverAuto, always
Every hub ticket the gate makes is NeverAuto. Neither lox runβs auto mode nor an auto rule answers a held request: a human does.
-
Identical fingerprint
One human decision covers only requests with the same container, method, URL, significant headers and normalised body.
+
Identical fingerprint
One human decision covers only requests with the same container, method, URL, every end-to-end header and normalised body.
LLM API relay checks
Once TLS is decrypted, the Claude APIβs mcp_servers, server tools other than web_search, files and foreign credentials never pass without a human.
Hub-attached only
The gate does not start without its hub flags. When the hub is unreachable, nothing else approves: the ticket stays pending.
-
Fail closed
No console, an unknown source, an unreadable source map, a policy that does not decode: asks are refused, errors deny.
+
Fail closed
No console or a policy that does not decode: asks are refused. An unknown source, an unreadable source map, an error while deciding: deny.
@@ -108,8 +108,8 @@
Threats and answers
Audit
-
The gate writes free and denied requests to a daily JSONL file, kept 30 days. The console writes every ask to its audit log.
-
Both carry the same request_id, the container, the declared agent and how it was attributed. The audit never holds a body or a secret.
+
The gate writes every decision, and the outcome of every hub ticket, to a daily JSONL file, kept 30 days; lockhub keeps its tickets. The console approves no request: it logs policy reviews only.
+
Each line carries the request_id, the container, the declared agent and how it was attributed. The audit never holds a body or a secret; a decisionβs warnings may name the mcp_servers of a Claude API request.
The container is known for sure: one internal network per container. The agent is an attribution, not an authentication, because agents of one container share a uid.
@@ -119,7 +119,7 @@
Known limits
Without decryption, a CONNECT opens reads and writes. An approved host stays open for connect_grant (10 minutes by default), content unseen.
HTTP/1.1 only to clients when decrypting. The gate refuses Upgrade: h2c.
-
A WebSocket session is one approval. The upgrade is decided; the frames that follow are not.
+
A WebSocket session is one approval. The upgrade is decided; the frames that follow are not (with injected secrets, the clientβs frames are scanned for them).
Heuristics run in shadow by default, until you set heuristics = "enforce".
No MCP server. Agents meet lockhttp as a proxy; its 403 pages tell them what to ask of you.