Files
headroom/docker/differential-network-capture/docker-compose.yml
Rod BoevandJerrettDavis b0c19a25f0 fix(security): reject unauthenticated public proxy binds (#3316)
## 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>
2026-09-24 23:58:46 -05:00

144 lines
4.3 KiB
YAML

name: headroom-network-diff
services:
mitm-direct:
image: mitmproxy/mitmproxy:12
command:
- mitmdump
- --mode
- regular
- --listen-host
- 0.0.0.0
- --listen-port
- "8080"
- --set
- confdir=/mitmproxy
- -s
- /capture/mitm_capture.py
environment:
CAPTURE_LANE: direct
CAPTURE_OUTPUT: /captures/direct.jsonl
CAPTURE_INCLUDE_HOSTS: ${CAPTURE_INCLUDE_HOSTS:-api.anthropic.com}
CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
volumes:
- ./mitm_capture.py:/capture/mitm_capture.py:ro
- ./captures:/captures
- mitm_direct_ca:/mitmproxy
ports:
- "127.0.0.1:${DIRECT_MITM_PORT:-18080}:8080"
mitm-headroom-client:
image: mitmproxy/mitmproxy:12
command:
- mitmdump
- --mode
- reverse:http://headroom-proxy:8787
- --listen-host
- 0.0.0.0
- --listen-port
- "8080"
- -s
- /capture/mitm_capture.py
environment:
CAPTURE_LANE: headroom-client
CAPTURE_OUTPUT: /captures/headroom-client.jsonl
CAPTURE_INCLUDE_HOSTS: ${CAPTURE_CLIENT_INCLUDE_HOSTS:-mitm-headroom-client,headroom-proxy,api.anthropic.com}
CAPTURE_PROXY_TOKEN_HOSTS: headroom-proxy
CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
CAPTURE_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}
volumes:
- ./mitm_capture.py:/capture/mitm_capture.py:ro
- ./captures:/captures
depends_on:
- headroom-proxy
mitm-headroom-upstream:
image: mitmproxy/mitmproxy:12
command:
- mitmdump
- --mode
- regular
- --listen-host
- 0.0.0.0
- --listen-port
- "8080"
- --set
- confdir=/mitmproxy
- -s
- /capture/mitm_capture.py
environment:
CAPTURE_LANE: headroom-upstream
CAPTURE_OUTPUT: /captures/headroom-upstream.jsonl
CAPTURE_INCLUDE_HOSTS: ${CAPTURE_INCLUDE_HOSTS:-api.anthropic.com}
CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
volumes:
- ./mitm_capture.py:/capture/mitm_capture.py:ro
- ./captures:/captures
- mitm_headroom_ca:/mitmproxy
ports:
- "127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"
headroom-proxy:
build:
context: ../..
dockerfile: Dockerfile
command: ["--host", "0.0.0.0", "--port", "8787", "--backend", "anthropic"]
environment:
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
ANTHROPIC_TARGET_API_URL: ${ANTHROPIC_TARGET_API_URL:-https://api.anthropic.com}
HTTPS_PROXY: http://mitm-headroom-upstream:8080
HTTP_PROXY: http://mitm-headroom-upstream:8080
NO_PROXY: 127.0.0.1,localhost,headroom-proxy
REQUESTS_CA_BUNDLE: /mitmproxy/mitmproxy-ca-cert.pem
SSL_CERT_FILE: /mitmproxy/mitmproxy-ca-cert.pem
volumes:
- mitm_headroom_ca:/mitmproxy:ro
depends_on:
- mitm-headroom-upstream
claude-direct:
build:
context: .
dockerfile: Dockerfile.runner
args:
CLAUDE_CODE_PACKAGE: ${CLAUDE_CODE_PACKAGE:-@anthropic-ai/claude-code}
profiles: ["run"]
environment:
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
HTTPS_PROXY: http://mitm-direct:8080
HTTP_PROXY: http://mitm-direct:8080
NO_PROXY: 127.0.0.1,localhost
NODE_EXTRA_CA_CERTS: /mitmproxy/mitmproxy-ca-cert.pem
SSL_CERT_FILE: /mitmproxy/mitmproxy-ca-cert.pem
CLAUDE_LANE: direct
CLAUDE_PROMPT: ${CLAUDE_PROMPT:-Summarize this repository in one sentence.}
CLAUDE_ARGS: ${CLAUDE_DIRECT_ARGS:-}
volumes:
- ../..:/workspace:ro
- mitm_direct_ca:/mitmproxy:ro
depends_on:
- mitm-direct
claude-headroom:
build:
context: .
dockerfile: Dockerfile.runner
args:
CLAUDE_CODE_PACKAGE: ${CLAUDE_CODE_PACKAGE:-@anthropic-ai/claude-code}
profiles: ["run"]
environment:
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
ANTHROPIC_BASE_URL: http://mitm-headroom-client:8080
CLAUDE_LANE: headroom
CLAUDE_PROMPT: ${CLAUDE_PROMPT:-Summarize this repository in one sentence.}
CLAUDE_ARGS: ${CLAUDE_HEADROOM_ARGS:-}
volumes:
- ../..:/workspace:ro
depends_on:
- mitm-headroom-client
volumes:
mitm_direct_ca:
mitm_headroom_ca: