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>
144 lines
4.3 KiB
YAML
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:
|