mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description Headroom's published image and maintained Docker launchers could expose the proxy on every host interface without a proxy token. This change moves the security boundary to the deployment artifacts: published images default to a container-loopback listener, supported local launchers publish only on host loopback, and deliberate public deployments retain explicit token protection. The application factory remains transport-neutral. Closes #3283 ## Type of Change - [x] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Set both published image stages to a container-loopback default while keeping explicit host overrides available. - Changed native Compose and the maintained Bash and PowerShell launchers to use an internal `0.0.0.0` listener with host-loopback publication. - Preserved the top-level Compose token requirement and the existing HTTP and WebSocket credential behavior for deliberate public binds. - Scoped differential-capture token injection to the internal `headroom-proxy` destination and kept sensitive headers redacted in captured records. - Added focused launch-contract, native-core, capture, and Docker publication checks, plus a base/head harness that tolerates a base already containing the fix. - Updated Docker, installer, capture, and mirrored documentation, including an unauthenticated local loopback quickstart and an authenticated deliberate-public example. ## Testing - [x] Focused unit and integration tests pass - [x] Linting and formatting checks pass - [ ] Type checking passes - [x] New tests added for the changed deployment and capture behavior - [ ] Manual testing performed ### Test Output ```text uv run python -m pytest tests/test_proxy_hardening.py tests/test_install/test_native_installers.py tests/test_docker_compose_persistence.py tests/test_network_diff_capture.py tests/test_rust_core_smoke.py -q 76 passed, 1 skipped, 1 warning in 23.45s uv run ruff check tests/test_install/test_native_installers.py tests/test_install/test_runtime.py All checks passed! bash -n e2e/docker-bind-security.sh passed bash e2e/docker-bind-security.sh --base-image headroom-t3283-base --head-image headroom-t3283-head --fixture tests/fixtures/docker-bind-exposure.json --base-ref origin/main base_ref=origin/main ... runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=403 docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed ``` ## Real Behavior Proof - Environment: Windows, Docker Desktop 29.6.2, current `origin/main` base, head image, and a real Docker bridge peer. - Exact command / steps: run the focused security/runtime tests, Compose configuration checks, then `bash e2e/docker-bind-security.sh` against the current base and head image definitions. - Observed result: `76 passed, 1 skipped`; the built-image harness passed base/head health, local completion, non-loopback isolation, authenticated public HTTP/WebSocket controls, loopback runtime-slim configuration, and direct Rust-core loading. - Not tested: runtime-slim proxy service health on this host, because its unrelated ONNXRuntime import path exits with code 139; the full hosted matrix and a future published GHCR image remain CI-owned. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Unsafe override required: no - Minimum rollout channel: next release containing the Docker and launcher changes - Stable/default behavior changed: published images and maintained local Docker launchers now use loopback-safe publication defaults - Kill switch / disable path: revert the deployment-artifact changes before release; deliberate public deployments remain explicitly operator-controlled - Qualification impact: Docker users relying on all-interface default publication must opt into public publication and configure the existing proxy token - Deliberate public deployment: use an explicit public host publication, set `HEADROOM_PROXY_TOKEN`, and send the matching bearer or `X-Headroom-Proxy-Token` credential - Local deployment: use the maintained loopback publication and no mandatory token - Rollback path: revert the deployment-artifact and documentation changes together ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [x] I have added tests that prove the behavior is effective - [x] Focused tests pass locally with these changes - [x] I did **not** edit `CHANGELOG.md`; release-please generates release notes from the conventional PR title ## Additional Notes The issue fixture remains provenance for the unauthenticated publication. Native `headroom proxy` defaults and the application-level authentication owners are unchanged. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# Differential Network Capture
|
|
|
|
Headroom includes a containerized harness for comparing Claude Code traffic sent
|
|
directly to Anthropic with traffic sent through a Headroom proxy. The harness
|
|
uses mitmproxy in two isolated lanes, writes sanitized JSONL captures, and then
|
|
generates Markdown/JSON reports with request route, header, body size, body hash,
|
|
and JSON payload differences.
|
|
|
|
## Run The Harness
|
|
|
|
```bash
|
|
cd docker/differential-network-capture
|
|
mkdir -p captures
|
|
export ANTHROPIC_API_KEY=...
|
|
export HEADROOM_PROXY_TOKEN='capture-secret'
|
|
export CLAUDE_PROMPT="Summarize this repository in one sentence."
|
|
docker compose up --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-client
|
|
docker compose --profile run run --rm claude-direct
|
|
docker compose --profile run run --rm claude-headroom
|
|
```
|
|
|
|
The primary captures are written to:
|
|
|
|
- `docker/differential-network-capture/captures/direct.jsonl`
|
|
- `docker/differential-network-capture/captures/headroom-client.jsonl`
|
|
|
|
The Headroom lane also writes
|
|
`docker/differential-network-capture/captures/headroom-upstream.jsonl`, which is
|
|
the request Headroom forwards to Anthropic after proxy processing.
|
|
|
|
`HEADROOM_PROXY_TOKEN` is required for the Headroom lane. The capture addon
|
|
adds it only to requests from `mitm-headroom-client`; direct and upstream
|
|
captures never receive it. Keep this value private and use the same value when
|
|
calling a deliberately public Headroom proxy.
|
|
|
|
The direct and upstream mitmproxy ports are published on loopback for local
|
|
inspection. The client capture stays on the internal Compose network because
|
|
it is an internal hop, so `HEADROOM_CLIENT_MITM_PORT` is intentionally not a
|
|
supported setting.
|
|
|
|
By default only `api.anthropic.com` is logged. Override
|
|
`CAPTURE_INCLUDE_HOSTS` with a comma-separated list to include other hosts.
|
|
|
|
## Generate A Report
|
|
|
|
```bash
|
|
headroom capture network-diff \
|
|
--direct docker/differential-network-capture/captures/direct.jsonl \
|
|
--headroom docker/differential-network-capture/captures/headroom-client.jsonl \
|
|
--output docker/differential-network-capture/captures/report.md \
|
|
--json-output docker/differential-network-capture/captures/report.json
|
|
```
|
|
|
|
The report redacts sensitive header values and sensitive query values before
|
|
comparison. Request bodies are captured so structural payload differences can be
|
|
identified; keep the generated `captures/` directory out of commits because it
|
|
may contain prompts, tool outputs, and repository context.
|
|
|
|
For Claude Code deferred-tool investigations, the paired exchange table includes
|
|
top-level Anthropic `tools` counts and serialized tool bytes. A jump from
|
|
`tools=0->N` in the Headroom client lane is evidence that Claude Code eagerly
|
|
materialized tool schemas before the request reached Headroom.
|
|
|
|
## Custom Claude Invocation
|
|
|
|
Set `CLAUDE_COMMAND` to run the exact command under test in both lanes:
|
|
|
|
```bash
|
|
CLAUDE_COMMAND='claude -p "read README.md and summarize the proxy setup"' \
|
|
docker compose --profile run run --rm claude-direct
|
|
CLAUDE_COMMAND='claude -p "read README.md and summarize the proxy setup"' \
|
|
docker compose --profile run run --rm claude-headroom
|
|
```
|
|
|
|
Use `CLAUDE_DIRECT_ARGS` and `CLAUDE_HEADROOM_ARGS` when each lane needs
|
|
different flags.
|