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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
19 changes: 12 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.

Expand Down
27 changes: 17 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -139,23 +141,25 @@ Every held request is a `NeverAuto` ticket: a human answers it. Only a

**🔑 Credentials injected**<br>
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.

</td>
</tr>
<tr>
<td valign="top">

**🔁 LLM APIs checked as a relay**<br>
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.

</td>
<td valign="top">

**🧱 Fail closed**<br>
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.

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

Expand Down
25 changes: 15 additions & 10 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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 \
Expand Down
5 changes: 3 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Expand All @@ -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). |

</details>

Expand Down
Loading
Loading