mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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>
This commit is contained in:
@@ -586,14 +586,16 @@ jobs:
|
||||
needs: changes
|
||||
if: needs.changes.outputs.native == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
timeout-minutes: 60
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-python@v7
|
||||
with:
|
||||
python-version: "3.11"
|
||||
- name: Build local Headroom image
|
||||
run: docker build -t headroom-native-e2e:latest .
|
||||
- name: Run Docker bind security proof
|
||||
run: bash e2e/docker-bind-security.sh --base-image headroom-bind-base --head-image headroom-native-e2e:latest --fixture tests/fixtures/docker-bind-exposure.json --base-ref "${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}"
|
||||
- name: Run Docker-native installer e2e
|
||||
env:
|
||||
HEADROOM_DOCKER_IMAGE: headroom-native-e2e:latest
|
||||
|
||||
@@ -64,11 +64,13 @@ jobs:
|
||||
- name: Validate compose model
|
||||
env:
|
||||
ANTHROPIC_API_KEY: dummy
|
||||
HEADROOM_PROXY_TOKEN: capture-proof
|
||||
run: docker compose -f docker/differential-network-capture/docker-compose.yml --profile run config
|
||||
|
||||
- name: Build Claude Code runner image
|
||||
env:
|
||||
ANTHROPIC_API_KEY: dummy
|
||||
HEADROOM_PROXY_TOKEN: capture-proof
|
||||
run: docker compose -f docker/differential-network-capture/docker-compose.yml --profile run build claude-direct
|
||||
|
||||
- name: Smoke Claude Code runner image
|
||||
@@ -117,6 +119,8 @@ jobs:
|
||||
working-directory: docker/differential-network-capture
|
||||
run: |
|
||||
set -euo pipefail
|
||||
HEADROOM_PROXY_TOKEN="$(openssl rand -hex 32)"
|
||||
export HEADROOM_PROXY_TOKEN
|
||||
mkdir -p captures
|
||||
docker compose up -d --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-client
|
||||
trap 'docker compose --profile run down -v' EXIT
|
||||
|
||||
+4
-4
@@ -185,7 +185,7 @@ RUN mkdir -p /home/nonroot /data && \
|
||||
USER ${RUNTIME_USER}
|
||||
WORKDIR ${RUNTIME_HOME}
|
||||
|
||||
ENV HEADROOM_HOST=0.0.0.0 \
|
||||
ENV HEADROOM_HOST=127.0.0.1 \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
PYTHONDONTWRITEBYTECODE=1
|
||||
|
||||
@@ -202,7 +202,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
|
||||
CMD ["curl", "--fail", "--silent", "http://127.0.0.1:8787/readyz"]
|
||||
|
||||
ENTRYPOINT ["headroom", "proxy"]
|
||||
CMD ["--host", "0.0.0.0", "--port", "8787"]
|
||||
CMD ["--port", "8787"]
|
||||
|
||||
FROM ${DISTROLESS_IMAGE} AS runtime-slim
|
||||
|
||||
@@ -216,7 +216,7 @@ COPY --from=builder /usr/local/bin/headroom-proxy /usr/local/bin/headroom-proxy
|
||||
USER ${RUNTIME_USER}
|
||||
WORKDIR /app
|
||||
|
||||
ENV HEADROOM_HOST=0.0.0.0 \
|
||||
ENV HEADROOM_HOST=127.0.0.1 \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
PYTHONPATH=${PYTHON_SITE_PACKAGES}
|
||||
@@ -227,7 +227,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
|
||||
CMD ["python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8787/readyz', timeout=5)"]
|
||||
|
||||
ENTRYPOINT ["python3", "-m", "headroom.cli", "proxy"]
|
||||
CMD ["--host", "0.0.0.0", "--port", "8787"]
|
||||
CMD ["--port", "8787"]
|
||||
|
||||
# Default published image remains python-slim runtime
|
||||
FROM runtime-slim-base AS runtime
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@
|
||||
# 3. point your LLM client at http://localhost:8787 (proxy)
|
||||
#
|
||||
# Just want the proxy without the memory features? You can run the proxy image
|
||||
# on its own (`docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom`); the two
|
||||
# on its own (`docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom --host 0.0.0.0 --port 8787`); the two
|
||||
# database services below are only required for the memory/relevance features.
|
||||
#
|
||||
# Ports published on the host — all bound to 127.0.0.1 (this machine only):
|
||||
|
||||
@@ -25,7 +25,7 @@ services:
|
||||
- ./captures:/captures
|
||||
- mitm_direct_ca:/mitmproxy
|
||||
ports:
|
||||
- "${DIRECT_MITM_PORT:-18080}:8080"
|
||||
- "127.0.0.1:${DIRECT_MITM_PORT:-18080}:8080"
|
||||
|
||||
mitm-headroom-client:
|
||||
image: mitmproxy/mitmproxy:12
|
||||
@@ -43,12 +43,12 @@ services:
|
||||
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
|
||||
ports:
|
||||
- "${HEADROOM_CLIENT_MITM_PORT:-18082}:8080"
|
||||
depends_on:
|
||||
- headroom-proxy
|
||||
|
||||
@@ -76,7 +76,7 @@ services:
|
||||
- ./captures:/captures
|
||||
- mitm_headroom_ca:/mitmproxy
|
||||
ports:
|
||||
- "${HEADROOM_MITM_PORT:-18081}:8080"
|
||||
- "127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"
|
||||
|
||||
headroom-proxy:
|
||||
build:
|
||||
@@ -84,6 +84,7 @@ services:
|
||||
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
|
||||
|
||||
@@ -20,6 +20,12 @@ INCLUDE_HOSTS = {
|
||||
if host.strip()
|
||||
}
|
||||
BODY_BYTES = int(os.environ.get("CAPTURE_BODY_BYTES", "262144"))
|
||||
PROXY_TOKEN = os.environ.get("CAPTURE_PROXY_TOKEN") if LANE == "headroom-client" else None
|
||||
TOKEN_DESTINATION_HOSTS = {
|
||||
host.strip().lower()
|
||||
for host in os.environ.get("CAPTURE_PROXY_TOKEN_HOSTS", "").split(",")
|
||||
if host.strip()
|
||||
}
|
||||
SENSITIVE_HEADER_PARTS = ("authorization", "api-key", "apikey", "token", "secret", "cookie")
|
||||
SENSITIVE_QUERY_PARTS = ("key", "token", "secret", "signature", "code")
|
||||
_sequence = 0
|
||||
@@ -53,10 +59,26 @@ def _request_json(content: bytes) -> object | None:
|
||||
return None
|
||||
|
||||
|
||||
def _host_is_included(host: str) -> bool:
|
||||
return not INCLUDE_HOSTS or host.lower() in INCLUDE_HOSTS
|
||||
|
||||
|
||||
def _destination_is_allowed(flow: http.HTTPFlow) -> bool:
|
||||
address = getattr(getattr(flow, "server_conn", None), "address", None)
|
||||
destination = address[0] if address else ""
|
||||
return bool(destination) and destination.lower() in TOKEN_DESTINATION_HOSTS
|
||||
|
||||
|
||||
def request(flow: http.HTTPFlow) -> None:
|
||||
"""Authenticate only the internal Headroom client lane."""
|
||||
if PROXY_TOKEN and _destination_is_allowed(flow):
|
||||
flow.request.headers["X-Headroom-Proxy-Token"] = PROXY_TOKEN
|
||||
|
||||
|
||||
def response(flow: http.HTTPFlow) -> None:
|
||||
global _sequence
|
||||
host = flow.request.pretty_host.lower()
|
||||
if INCLUDE_HOSTS and host not in INCLUDE_HOSTS:
|
||||
if not _host_is_included(host):
|
||||
return
|
||||
|
||||
_sequence += 1
|
||||
|
||||
@@ -29,12 +29,13 @@ services:
|
||||
environment:
|
||||
HOME: /tmp/headroom-home
|
||||
HEADROOM_HOST: 0.0.0.0
|
||||
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
|
||||
# Canonical Headroom filesystem contract (issue #175). See `cli` service
|
||||
# above for rationale.
|
||||
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
|
||||
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
|
||||
ports:
|
||||
- "${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
|
||||
- "127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
|
||||
volumes:
|
||||
- ${HEADROOM_WORKSPACE:-.}:/workspace
|
||||
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
|
||||
|
||||
@@ -334,7 +334,7 @@ If the upstream base URL itself must vary per request, use the `x-headroom-base-
|
||||
```bash
|
||||
headroom proxy \
|
||||
--port 8787 \ # Port to listen on
|
||||
--host 0.0.0.0 \ # Host to bind to
|
||||
--host 127.0.0.1 \ # Host to bind to
|
||||
--mode cache \ # default; freezes prior turns for prefix-cache stability
|
||||
--budget 10.00 \ # Daily budget limit in USD
|
||||
--log-file headroom.jsonl # Log file path
|
||||
|
||||
@@ -59,15 +59,27 @@ headroom mcp install
|
||||
headroom memory list
|
||||
```
|
||||
|
||||
For `proxy`, the wrapper publishes the selected port back to the host:
|
||||
For `proxy`, the maintained wrapper always publishes the selected host port on
|
||||
loopback. It passes `--host 0.0.0.0` inside the container so that the loopback
|
||||
publication can reach the container, and it has no public-publication override.
|
||||
For local-only use, no token is required:
|
||||
|
||||
```bash
|
||||
docker run --rm -it \
|
||||
-p 8787:8787 \
|
||||
-p 127.0.0.1:8787:8787 \
|
||||
-v "$PWD:/workspace" \
|
||||
-w /workspace \
|
||||
ghcr.io/headroomlabs-ai/headroom:latest \
|
||||
headroom proxy --host 0.0.0.0 --port 8787
|
||||
--host 0.0.0.0 --port 8787
|
||||
```
|
||||
|
||||
For deliberate public access, publish on an explicit public address and set
|
||||
`HEADROOM_PROXY_TOKEN`:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 0.0.0.0:8787:8787 \
|
||||
-e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
|
||||
ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0 --port 8787
|
||||
```
|
||||
|
||||
### `wrap` commands
|
||||
|
||||
@@ -230,7 +230,8 @@ Pre-built images are published to GitHub Container Registry on every release.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/headroomlabs-ai/headroom:latest
|
||||
docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest
|
||||
docker run --rm -p 127.0.0.1:8787:8787 \
|
||||
ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0
|
||||
```
|
||||
|
||||
<Callout type="info" title="Running Headroom without installing Python or Node?">
|
||||
|
||||
@@ -13,8 +13,10 @@ Running a local OpenAI-compatible model? See [Local LLM prefill benchmarking](/d
|
||||
# Basic usage
|
||||
headroom proxy
|
||||
|
||||
# Custom host and port
|
||||
headroom proxy --host 0.0.0.0 --port 8080
|
||||
# Deliberate public access, with the existing token protocol
|
||||
HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
|
||||
# Send `Authorization: Bearer replace-with-a-secret` or
|
||||
# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.
|
||||
|
||||
# With logging and budget
|
||||
headroom proxy \
|
||||
@@ -927,7 +929,9 @@ Rewriting the request body invalidates the caller's **SigV4** signature (it cove
|
||||
## Environment variables
|
||||
|
||||
```bash
|
||||
# For deliberate public access, configure the existing token and send it from callers.
|
||||
export HEADROOM_HOST=0.0.0.0
|
||||
export HEADROOM_PROXY_TOKEN='replace-with-a-secret'
|
||||
export HEADROOM_PORT=8787
|
||||
export HEADROOM_BUDGET=100.0
|
||||
|
||||
@@ -954,6 +958,8 @@ gunicorn "headroom.proxy.server:create_app()" \
|
||||
--workers 4 \
|
||||
--bind 0.0.0.0:8787 \
|
||||
--worker-class uvicorn.workers.UvicornWorker
|
||||
# Callers must send `Authorization: Bearer replace-with-a-secret` or
|
||||
# `X-Headroom-Proxy-Token: replace-with-a-secret`.
|
||||
```
|
||||
|
||||
`headroom.proxy.server` has no module-level `app` object — it exposes a `create_app(config: ProxyConfig | None = None) -> FastAPI` factory, so gunicorn's import string must call it.
|
||||
@@ -967,9 +973,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends build-essential
|
||||
&& apt-get purge -y build-essential && apt-get autoremove -y \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
EXPOSE 8787
|
||||
CMD ["headroom", "proxy", "--host", "0.0.0.0"]
|
||||
CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
|
||||
```
|
||||
|
||||
Run this image with an explicit token and a deliberate publication choice:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 127.0.0.1:8787:8787 \
|
||||
-e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
|
||||
headroom-proxy
|
||||
```
|
||||
|
||||
Callers must send `Authorization: Bearer replace-with-a-secret` or
|
||||
`X-Headroom-Proxy-Token: replace-with-a-secret`. For network access, replace
|
||||
the host-side `127.0.0.1` with an intentional public address and keep the
|
||||
token configured.
|
||||
|
||||
<Callout type="info" title="Build dependencies">
|
||||
`build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension compiled from source. It is removed after installation to keep the image slim.
|
||||
</Callout>
|
||||
|
||||
@@ -0,0 +1,185 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
|
||||
|
||||
base_image=; head_image=; fixture=; base_ref="${HEADROOM_BASE_REF:-origin/main}"
|
||||
while (($#)); do
|
||||
case "$1" in
|
||||
--base-image) base_image="$2"; shift 2 ;;
|
||||
--head-image) head_image="$2"; shift 2 ;;
|
||||
--fixture) fixture="$2"; shift 2 ;;
|
||||
--base-ref) base_ref="$2"; shift 2 ;;
|
||||
*) echo "unknown argument: $1" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
[[ -n "$base_image" && -n "$head_image" && -n "$fixture" ]] || exit 2
|
||||
PYTHON_BIN="${PYTHON_BIN:-python3}"
|
||||
command -v "$PYTHON_BIN" >/dev/null 2>&1 || PYTHON_BIN=python
|
||||
command -v "$PYTHON_BIN" >/dev/null 2>&1 || { echo "python3 or python is required" >&2; exit 127; }
|
||||
|
||||
base_container="headroom-bind-base-$$"; head_container="headroom-bind-head-$$"
|
||||
local_container="headroom-bind-local-$$"; public_container="headroom-bind-public-$$"
|
||||
attacker_container="headroom-bind-attacker-$$"; mock_container="headroom-bind-upstream-$$"
|
||||
slim_container="headroom-bind-slim-$$"; network="headroom-bind-network-$$"
|
||||
tmp_dir="$(mktemp -d)"
|
||||
cleanup() {
|
||||
docker rm -f "$attacker_container" "$public_container" "$local_container" "$slim_container" "$head_container" "$base_container" "$mock_container" >/dev/null 2>&1 || true
|
||||
# The CI workflow reuses the head image for installer, compose, and wrap checks.
|
||||
docker image rm "$base_image" "${head_image}-runtime-slim" >/dev/null 2>&1 || true
|
||||
docker network rm "$network" >/dev/null 2>&1 || true
|
||||
rm -rf "$tmp_dir"
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
mapfile -t request_paths < <("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
for path in json.load(open(sys.argv[1], encoding="utf-8"))["request_paths"]:
|
||||
print(path)
|
||||
PY
|
||||
)
|
||||
upstream_path="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["path"])
|
||||
PY
|
||||
)"
|
||||
missing_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["missing"])
|
||||
PY
|
||||
)"
|
||||
wrong_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["wrong"])
|
||||
PY
|
||||
)"
|
||||
correct_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["correct"])
|
||||
PY
|
||||
)"
|
||||
ws_status_expected="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["websocket_control"]["missing"])
|
||||
PY
|
||||
)"
|
||||
upstream_path="${upstream_path//$'\r'/}"
|
||||
|
||||
fixture_description="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["description"])
|
||||
PY
|
||||
)"
|
||||
upstream_method="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["method"])
|
||||
PY
|
||||
)"
|
||||
upstream_authorization="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
value = json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["authorization"]
|
||||
print("" if value is None else value)
|
||||
PY
|
||||
)"
|
||||
network_publication="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["network"]["publication"])
|
||||
PY
|
||||
)"
|
||||
network_peer="$("$PYTHON_BIN" - "$fixture" <<'PY'
|
||||
import json, sys
|
||||
print(json.load(open(sys.argv[1], encoding="utf-8"))["network"]["peer"])
|
||||
PY
|
||||
)"
|
||||
|
||||
test "$fixture_description" = "Unauthenticated public Docker publication"
|
||||
test "$upstream_method" = POST
|
||||
test -z "$upstream_authorization"
|
||||
test "$network_publication" = "0.0.0.0:8787:8787"
|
||||
test "$network_peer" = non-loopback
|
||||
git archive "$base_ref" | tar -x -C "$tmp_dir"
|
||||
docker build -t "$base_image" "$tmp_dir" >/dev/null
|
||||
docker build -t "$head_image" . >/dev/null
|
||||
slim_image="${head_image}-runtime-slim"
|
||||
docker build --target runtime-slim -t "$slim_image" . >/dev/null
|
||||
docker network create "$network" >/dev/null
|
||||
mock_script='from http.server import BaseHTTPRequestHandler,HTTPServer
|
||||
class Handler(BaseHTTPRequestHandler):
|
||||
def _reply(self):
|
||||
print(self.command + " " + self.path + " authorization=" + str(self.headers.get("authorization")), flush=True)
|
||||
self.send_response(200); self.send_header("Content-Type", "application/json"); self.end_headers(); self.wfile.write(b"{}")
|
||||
do_GET = _reply
|
||||
do_POST = _reply
|
||||
def log_message(self, *_): pass
|
||||
HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()'
|
||||
docker run -d --rm --name "$mock_container" --network "$network" python:3.12-alpine python -c "$mock_script" >/dev/null
|
||||
docker run -d --rm --name "$base_container" --network "$network" -p "0.0.0.0:18783:8787" \
|
||||
-e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \
|
||||
"$base_image" >/dev/null
|
||||
docker run -d --rm --name "$head_container" --network "$network" -p "0.0.0.0:18784:8787" "$head_image" >/dev/null
|
||||
docker run -d --rm --name "$local_container" --network "$network" -p "127.0.0.1:18786:8787" \
|
||||
-e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \
|
||||
"$head_image" --host 0.0.0.0 --port 8787 >/dev/null
|
||||
docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$slim_image" \
|
||||
| grep -Fxq 'HEADROOM_HOST=127.0.0.1'
|
||||
docker run --rm --entrypoint python3 "$slim_image" -c 'import headroom._core; print("rust_core=loaded")'
|
||||
|
||||
host_ip="$(docker network inspect -f '{{range .IPAM.Config}}{{.Gateway}}{{end}}' "$network")"
|
||||
wait_healthy() {
|
||||
local container="$1"
|
||||
for _ in $(seq 1 60); do
|
||||
if docker inspect -f '{{.State.Health.Status}}' "$container" 2>/dev/null | grep -Fxq healthy; then
|
||||
return 0
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
docker inspect -f '{{.State.Health.Status}}' "$container"
|
||||
docker logs "$container" 2>&1 || true
|
||||
return 1
|
||||
}
|
||||
wait_healthy "$base_container"
|
||||
wait_healthy "$head_container"
|
||||
wait_healthy "$local_container"
|
||||
docker exec "$base_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
|
||||
docker exec "$head_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
|
||||
docker exec "$local_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
|
||||
request() {
|
||||
local port="$1" path="$2" token="${3:-}"; local -a args=(--silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3)
|
||||
[[ -n "$token" ]] && args+=(-H "Authorization: Bearer ${token}")
|
||||
[[ "$path" == "$upstream_path" ]] && args+=(-H 'Content-Type: application/json' --data '{"model":"fixture","messages":[]}')
|
||||
docker run --rm --name "$attacker_container" --network "$network" curlimages/curl:8.12.1 \
|
||||
"${args[@]}" "http://${host_ip}:${port}${path}"
|
||||
}
|
||||
first_path="${request_paths[0]//$'\r'/}"
|
||||
base_first_status="$(request 18783 "$first_path" || true)"
|
||||
if [[ "$base_first_status" == 200 ]]; then
|
||||
# The vulnerable base must retain the issue-shaped unauthenticated exposure.
|
||||
for path in "${request_paths[@]}"; do
|
||||
path="${path//$'\r'/}"
|
||||
test "$(request 18783 "$path")" = 200
|
||||
done
|
||||
docker logs "$mock_container" 2>&1 | grep -Fq "${upstream_method} ${upstream_path} authorization=${upstream_authorization:-None}"
|
||||
elif [[ "$base_first_status" != 000 && "$base_first_status" != 401 && "$base_first_status" != 403 ]]; then
|
||||
echo "unexpected safe-base status: $base_first_status" >&2
|
||||
exit 1
|
||||
fi
|
||||
test "$(request 18784 "$first_path")" = 000
|
||||
test "$(curl --silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3 "http://127.0.0.1:18786${first_path}")" = 200
|
||||
test "$(curl --silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3 --header 'Content-Type: application/json' --data '{"model":"fixture","messages":[]}' "http://127.0.0.1:18786${upstream_path}")" = 200
|
||||
test "$(request 18786 "$first_path" || true)" = 000
|
||||
token="$(openssl rand -hex 32)"
|
||||
docker run -d --rm --name "$public_container" --network "$network" -p 0.0.0.0:18785:8787 \
|
||||
-e "HEADROOM_PROXY_TOKEN=${token}" -e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" \
|
||||
-e OPENAI_API_KEY=upstream-secret \
|
||||
"$head_image" --host 0.0.0.0 --port 8787 >/dev/null
|
||||
for _ in $(seq 1 60); do curl -4 --fail --silent http://127.0.0.1:18785/readyz >/dev/null && break; sleep 1; done
|
||||
for path in "${request_paths[@]}"; do
|
||||
path="${path//$'\r'/}"
|
||||
test "$(request 18785 "$path")" = "$missing_status"
|
||||
test "$(request 18785 "$path" wrong-token)" = "$wrong_status"
|
||||
test "$(request 18785 "$path" "$token")" = "$correct_status"
|
||||
done
|
||||
ws_key="$(printf '%s' 'the sample nonce' | base64 | tr -d '\n')"
|
||||
ws_status="$(docker run --rm --name "$attacker_container" --network "$network" curlimages/curl:8.12.1 --silent --output /dev/null --write-out '%{http_code}' --http1.1 -H 'Connection: Upgrade' -H 'Upgrade: websocket' -H 'Sec-WebSocket-Version: 13' -H "Sec-WebSocket-Key: ${ws_key}" "http://${host_ip}:18785/v1/live")"
|
||||
test "$ws_status" = "$ws_status_expected"
|
||||
printf 'base_ref=%s base_digest=%s head_digest=%s slim_digest=%s runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=%s\n' "$base_ref" "$(docker image inspect --format='{{.Id}}' "$base_image")" "$(docker image inspect --format='{{.Id}}' "$head_image")" "$(docker image inspect --format='{{.Id}}' "$slim_image")" "$ws_status"
|
||||
echo "docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed"
|
||||
@@ -19,7 +19,7 @@ The canonical, always-current documentation index lives at the docs site below.
|
||||
|
||||
- Python: `pip install headroom-ai` (add `[all]` for every optional extra)
|
||||
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
|
||||
- Docker: `docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest`
|
||||
- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
|
||||
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
|
||||
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`)
|
||||
|
||||
|
||||
+8
-3
@@ -253,7 +253,7 @@ function Start-ProxyContainer {
|
||||
|
||||
$containerName = "headroom-proxy-$Port-$PID"
|
||||
$dockerArgs = New-Object System.Collections.Generic.List[string]
|
||||
$dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName,'-p',"$Port`:$Port"))
|
||||
$dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port"))
|
||||
$dockerArgs.AddRange((Get-SharedDockerArgs))
|
||||
$dockerArgs.Add($HeadroomImage)
|
||||
$dockerArgs.Add('--host')
|
||||
@@ -1723,7 +1723,7 @@ switch ($args[0]) {
|
||||
'proxy' {
|
||||
$port = 8787
|
||||
$forwardArgs = New-Object System.Collections.Generic.List[string]
|
||||
foreach ($arg in $args) { $forwardArgs.Add($arg) }
|
||||
for ($i = 1; $i -lt $args.Count; $i++) { $forwardArgs.Add($args[$i]) }
|
||||
for ($i = 1; $i -lt $args.Count; $i++) {
|
||||
if ($args[$i] -eq '--port' -or $args[$i] -eq '-p') {
|
||||
Require-OptionValue -Arguments $args -Index $i -Option $args[$i]
|
||||
@@ -1739,11 +1739,16 @@ switch ($args[0]) {
|
||||
$dockerArgs = New-Object System.Collections.Generic.List[string]
|
||||
$dockerArgs.AddRange([string[]]@('run','--rm'))
|
||||
Add-TtyArgs -ArgsList $dockerArgs
|
||||
$dockerArgs.AddRange([string[]]@('-p',"$port`:$port"))
|
||||
$dockerArgs.AddRange([string[]]@('-p',"127.0.0.1`:$port`:$port"))
|
||||
$dockerArgs.AddRange((Get-SharedDockerArgs))
|
||||
$dockerArgs.Add('--entrypoint')
|
||||
$dockerArgs.Add('headroom')
|
||||
$dockerArgs.Add($HeadroomImage)
|
||||
$dockerArgs.Add('proxy')
|
||||
$dockerArgs.Add('--host')
|
||||
$dockerArgs.Add('0.0.0.0')
|
||||
$dockerArgs.Add('--port')
|
||||
$dockerArgs.Add("$port")
|
||||
foreach ($arg in $forwardArgs) {
|
||||
$dockerArgs.Add($arg)
|
||||
}
|
||||
|
||||
+3
-3
@@ -186,7 +186,7 @@ start_proxy_container() {
|
||||
|
||||
local container_name="headroom-proxy-${port}-$$"
|
||||
local args=()
|
||||
args=(docker run -d --rm --name "${container_name}" -p "${port}:${port}")
|
||||
args=(docker run -d --rm --name "${container_name}" -p "127.0.0.1:${port}:${port}")
|
||||
append_common_container_args args
|
||||
args+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")
|
||||
"${args[@]}" >/dev/null
|
||||
@@ -1571,8 +1571,8 @@ EOF
|
||||
run_args=(docker run --rm)
|
||||
append_tty_args run_args
|
||||
append_common_container_args run_args
|
||||
run_args+=(-p "${port}:${port}")
|
||||
run_args+=(--entrypoint headroom "${HEADROOM_IMAGE}" "${args[@]}")
|
||||
run_args+=(-p "127.0.0.1:${port}:${port}")
|
||||
run_args+=(--entrypoint headroom "${HEADROOM_IMAGE}" proxy --host 0.0.0.0 --port "${port}" "${args[@]:1}")
|
||||
"${run_args[@]}"
|
||||
;;
|
||||
*)
|
||||
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"description":"Unauthenticated public Docker publication","request_paths":["/openapi.json","/docs","/dashboard","/v1/models","/v1/chat/completions"],"upstream":{"method":"POST","path":"/v1/chat/completions","authorization":null},"network":{"publication":"0.0.0.0:8787:8787","peer":"non-loopback"},"token_control":{"missing":401,"wrong":401,"correct":200},"websocket_control":{"missing":403}}
|
||||
@@ -63,3 +63,51 @@ def test_top_level_compose_marks_source_build_version() -> None:
|
||||
assert ".git/*" in dockerignore
|
||||
assert "!.git/HEAD" in dockerignore
|
||||
assert "!.git/refs/**" in dockerignore
|
||||
|
||||
|
||||
def test_native_compose_keeps_host_publication_loopback_and_optional_token() -> None:
|
||||
compose = yaml.safe_load(
|
||||
(ROOT / "docker" / "docker-compose.native.yml").read_text(encoding="utf-8")
|
||||
)
|
||||
proxy = compose["services"]["proxy"]
|
||||
|
||||
assert proxy["ports"] == ["127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"]
|
||||
assert proxy["environment"]["HEADROOM_HOST"] == "0.0.0.0"
|
||||
assert proxy["environment"]["HEADROOM_PROXY_TOKEN"] == "${HEADROOM_PROXY_TOKEN:-}"
|
||||
assert proxy["command"] == ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]
|
||||
|
||||
|
||||
def test_differential_capture_compose_keeps_proxy_internal_and_host_ports_loopback() -> None:
|
||||
compose = yaml.safe_load(
|
||||
(ROOT / "docker" / "differential-network-capture" / "docker-compose.yml").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
)
|
||||
services = compose["services"]
|
||||
assert (
|
||||
services["headroom-proxy"]["environment"]["HEADROOM_PROXY_TOKEN"]
|
||||
== "${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}"
|
||||
)
|
||||
assert (
|
||||
services["mitm-headroom-client"]["environment"]["CAPTURE_PROXY_TOKEN"]
|
||||
== "${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}"
|
||||
)
|
||||
assert (
|
||||
services["mitm-headroom-client"]["environment"]["CAPTURE_PROXY_TOKEN_HOSTS"]
|
||||
== "headroom-proxy"
|
||||
)
|
||||
assert services["mitm-direct"]["ports"] == ["127.0.0.1:${DIRECT_MITM_PORT:-18080}:8080"]
|
||||
assert services["mitm-headroom-upstream"]["ports"] == [
|
||||
"127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"
|
||||
]
|
||||
assert "ports" not in services["mitm-headroom-client"]
|
||||
assert "HEADROOM_CLIENT_MITM_PORT" not in compose["services"]["mitm-headroom-client"].get(
|
||||
"environment", {}
|
||||
)
|
||||
|
||||
|
||||
def test_published_dockerfile_stages_default_to_loopback() -> None:
|
||||
dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
|
||||
|
||||
assert dockerfile.count("ENV HEADROOM_HOST=127.0.0.1") == 2
|
||||
assert dockerfile.count('CMD ["--port", "8787"]') == 2
|
||||
|
||||
@@ -384,6 +384,39 @@ def _bash_supports_4_3() -> bool:
|
||||
return (major, minor) >= (4, 3)
|
||||
|
||||
|
||||
def _assert_loopback_publication(call: list[str]) -> None:
|
||||
publication = call[call.index("-p") + 1].split(":")
|
||||
assert len(publication) == 3
|
||||
assert publication[0] == "127.0.0.1"
|
||||
assert publication[1] == publication[2]
|
||||
|
||||
|
||||
def _assert_generated_proxy_argv(
|
||||
call: list[str], expected_port: int, forwarded_tail: list[str] | None = None
|
||||
) -> None:
|
||||
_assert_loopback_publication(call)
|
||||
entrypoint = call.index("--entrypoint")
|
||||
image = entrypoint + 2
|
||||
assert call[entrypoint + 1] == "headroom"
|
||||
assert call[image + 1 : image + 6] == [
|
||||
"proxy",
|
||||
"--host",
|
||||
"0.0.0.0",
|
||||
"--port",
|
||||
str(expected_port),
|
||||
]
|
||||
if forwarded_tail is not None:
|
||||
assert call[image + 6 :] == forwarded_tail
|
||||
|
||||
|
||||
def test_generated_wrappers_explicitly_override_image_host_for_container_access() -> None:
|
||||
bash_source = (REPO_ROOT / "scripts" / "install.sh").read_text(encoding="utf-8")
|
||||
powershell_source = (REPO_ROOT / "scripts" / "install.ps1").read_text(encoding="utf-8")
|
||||
|
||||
assert 'args+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")' in bash_source
|
||||
assert "dockerArgs.Add('0.0.0.0')" in powershell_source
|
||||
|
||||
|
||||
@pytest.mark.skipif(
|
||||
os.name == "nt" or shutil.which("bash") is None or not _bash_supports_4_3(),
|
||||
reason="installer requires bash >= 4.3 (macOS system bash is 3.2)",
|
||||
@@ -407,6 +440,7 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
|
||||
wrap_help = _run([str(wrapper), "wrap", "--help"], env=env)
|
||||
assert "Supported commands:" in wrap_help.stdout
|
||||
assert "copilot" not in wrap_help.stdout
|
||||
_run([str(wrapper), "proxy", "--help"], env=env)
|
||||
unsupported_wrap = _run(
|
||||
[str(wrapper), "wrap", "copilot", "--help"],
|
||||
env=env,
|
||||
@@ -517,8 +551,33 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
|
||||
if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "--help" in call
|
||||
)
|
||||
assert "-it" not in help_call
|
||||
proxy_help_call = next(
|
||||
call
|
||||
for call in docker_calls
|
||||
if call[:2] == ["run", "--rm"] and "-p" in call and "proxy" in call and "--help" in call
|
||||
)
|
||||
_assert_generated_proxy_argv(proxy_help_call, 8787)
|
||||
explicit_port = _free_port()
|
||||
_run(
|
||||
[str(wrapper), "proxy", "--port", str(explicit_port), "--host", "192.0.2.1"],
|
||||
env=env,
|
||||
)
|
||||
explicit_call = next(
|
||||
call
|
||||
for call in reversed(_read_fake_docker_log(env))
|
||||
if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "192.0.2.1" in call
|
||||
)
|
||||
_assert_generated_proxy_argv(
|
||||
explicit_call,
|
||||
explicit_port,
|
||||
["--port", str(explicit_port), "--host", "192.0.2.1"],
|
||||
)
|
||||
install_call = next(
|
||||
call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
|
||||
call
|
||||
for call in docker_calls
|
||||
if call[:2] == ["run", "-d"]
|
||||
and "--name" in call
|
||||
and call[call.index("--name") + 1] == "headroom-smoke"
|
||||
)
|
||||
assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
|
||||
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
|
||||
@@ -1040,8 +1099,40 @@ def test_powershell_native_installer_supports_persistent_docker_lifecycle(tmp_pa
|
||||
if call[:2] == ["run", "--rm"] and "-p" in call and "proxy" in call and "--help" in call
|
||||
)
|
||||
assert "-it" not in proxy_help_call
|
||||
_assert_generated_proxy_argv(proxy_help_call, 8787)
|
||||
explicit_port = _free_port()
|
||||
_run(
|
||||
[
|
||||
powershell,
|
||||
"-NoProfile",
|
||||
"-ExecutionPolicy",
|
||||
"Bypass",
|
||||
"-File",
|
||||
str(wrapper),
|
||||
"proxy",
|
||||
"--port",
|
||||
str(explicit_port),
|
||||
"--host",
|
||||
"192.0.2.1",
|
||||
],
|
||||
env=env,
|
||||
)
|
||||
explicit_call = next(
|
||||
call
|
||||
for call in reversed(_read_fake_docker_log(env))
|
||||
if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "192.0.2.1" in call
|
||||
)
|
||||
_assert_generated_proxy_argv(
|
||||
explicit_call,
|
||||
explicit_port,
|
||||
["--port", str(explicit_port), "--host", "192.0.2.1"],
|
||||
)
|
||||
install_call = next(
|
||||
call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
|
||||
call
|
||||
for call in docker_calls
|
||||
if call[:2] == ["run", "-d"]
|
||||
and "--name" in call
|
||||
and call[call.index("--name") + 1] == "headroom-smoke"
|
||||
)
|
||||
assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
|
||||
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
|
||||
|
||||
@@ -106,6 +106,56 @@ def test_build_runtime_command_for_docker_includes_deployment_env(
|
||||
assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command
|
||||
|
||||
|
||||
def test_build_runtime_command_preserves_non_ascii_ambient_token(
|
||||
monkeypatch, tmp_path: Path
|
||||
) -> None:
|
||||
monkeypatch.setattr(Path, "home", lambda: tmp_path)
|
||||
token = "tökén-安全-🔐"
|
||||
monkeypatch.setenv("HEADROOM_PROXY_TOKEN", token)
|
||||
manifest = DeploymentManifest(
|
||||
profile="default",
|
||||
preset="persistent-docker",
|
||||
runtime_kind="docker",
|
||||
supervisor_kind="none",
|
||||
scope="user",
|
||||
provider_mode="manual",
|
||||
targets=["claude"],
|
||||
port=8787,
|
||||
host="127.0.0.1",
|
||||
backend="anthropic",
|
||||
image="ghcr.io/headroomlabs-ai/headroom:latest",
|
||||
base_env={"HEADROOM_PORT": "8787"},
|
||||
proxy_args=["--host", "127.0.0.1", "--port", "8787"],
|
||||
)
|
||||
|
||||
command = build_runtime_command(manifest)
|
||||
|
||||
token_env_index = command.index("HEADROOM_PROXY_TOKEN")
|
||||
assert command[token_env_index - 1] == "--env"
|
||||
assert token not in command
|
||||
|
||||
captured: dict[str, list[str] | dict[str, str]] = {}
|
||||
|
||||
def fake_run(command: list[str], **kwargs: object) -> None:
|
||||
captured["command"] = command
|
||||
container_env: dict[str, str] = {}
|
||||
for index, arg in enumerate(command):
|
||||
if arg != "--env":
|
||||
continue
|
||||
value = command[index + 1]
|
||||
if "=" in value:
|
||||
name, resolved = value.split("=", 1)
|
||||
container_env[name] = resolved
|
||||
else:
|
||||
container_env[value] = os.environ[value]
|
||||
captured["container_env"] = container_env
|
||||
|
||||
monkeypatch.setattr("headroom.install.runtime.subprocess.run", fake_run)
|
||||
start_persistent_docker(manifest)
|
||||
assert captured["container_env"]["HEADROOM_PROXY_TOKEN"] == token
|
||||
assert token not in captured["command"]
|
||||
|
||||
|
||||
def test_build_runtime_command_for_docker_includes_gpu_passthrough(
|
||||
monkeypatch, tmp_path: Path
|
||||
) -> None:
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import importlib.util
|
||||
import json
|
||||
import sys
|
||||
import types
|
||||
from pathlib import Path
|
||||
|
||||
from click.testing import CliRunner
|
||||
@@ -22,6 +25,124 @@ def _body(payload: dict[str, object]) -> str:
|
||||
return base64.b64encode(json.dumps(payload).encode("utf-8")).decode("ascii")
|
||||
|
||||
|
||||
class _Headers(dict[str, str]):
|
||||
def items(self, multi: bool = False):
|
||||
return super().items()
|
||||
|
||||
|
||||
def _load_capture_addon(
|
||||
monkeypatch,
|
||||
tmp_path: Path,
|
||||
lane: str,
|
||||
token: str | None,
|
||||
*,
|
||||
include_hosts: str = "api.anthropic.com",
|
||||
token_hosts: str = "headroom-proxy",
|
||||
):
|
||||
fake_http = types.SimpleNamespace(HTTPFlow=object)
|
||||
fake_mitmproxy = types.ModuleType("mitmproxy")
|
||||
fake_mitmproxy.http = fake_http
|
||||
monkeypatch.setitem(sys.modules, "mitmproxy", fake_mitmproxy)
|
||||
monkeypatch.setenv("CAPTURE_LANE", lane)
|
||||
monkeypatch.setenv("CAPTURE_INCLUDE_HOSTS", include_hosts)
|
||||
monkeypatch.setenv("CAPTURE_PROXY_TOKEN_HOSTS", token_hosts)
|
||||
monkeypatch.setenv("CAPTURE_OUTPUT", str(tmp_path / f"{lane}.jsonl"))
|
||||
if token is None:
|
||||
monkeypatch.delenv("CAPTURE_PROXY_TOKEN", raising=False)
|
||||
else:
|
||||
monkeypatch.setenv("CAPTURE_PROXY_TOKEN", token)
|
||||
|
||||
path = Path(__file__).parents[1] / "docker/differential-network-capture/mitm_capture.py"
|
||||
spec = importlib.util.spec_from_file_location(f"mitm_capture_{lane}", path)
|
||||
assert spec and spec.loader
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def test_network_capture_injects_token_only_on_included_headroom_client_lane(
|
||||
monkeypatch, tmp_path: Path
|
||||
) -> None:
|
||||
token = "capture-secret"
|
||||
headroom_addon = _load_capture_addon(monkeypatch, tmp_path, "headroom-client", token)
|
||||
headroom_flow = types.SimpleNamespace(
|
||||
request=types.SimpleNamespace(
|
||||
headers=_Headers(),
|
||||
pretty_host="api.anthropic.com",
|
||||
pretty_url="https://api.anthropic.com/v1/messages",
|
||||
method="POST",
|
||||
raw_content=b"{}",
|
||||
),
|
||||
server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
|
||||
response=types.SimpleNamespace(
|
||||
headers=_Headers({"X-Headroom-Proxy-Token": token}),
|
||||
raw_content=b"{}",
|
||||
status_code=200,
|
||||
),
|
||||
)
|
||||
|
||||
headroom_addon.request(headroom_flow)
|
||||
|
||||
assert headroom_flow.request.headers == {"X-Headroom-Proxy-Token": token}
|
||||
headroom_addon.response(headroom_flow)
|
||||
record = json.loads((tmp_path / "headroom-client.jsonl").read_text(encoding="utf-8"))
|
||||
assert record["request_headers"]["X-Headroom-Proxy-Token"] == "<redacted>"
|
||||
assert record["response_headers"]["X-Headroom-Proxy-Token"] == "<redacted>"
|
||||
|
||||
outside_flow = types.SimpleNamespace(
|
||||
request=types.SimpleNamespace(
|
||||
headers=_Headers(),
|
||||
pretty_host="other.example.com",
|
||||
),
|
||||
server_conn=types.SimpleNamespace(address=("other.example.com", 443)),
|
||||
)
|
||||
|
||||
headroom_addon.request(outside_flow)
|
||||
|
||||
assert outside_flow.request.headers == {}
|
||||
|
||||
direct_addon = _load_capture_addon(monkeypatch, tmp_path, "direct", token)
|
||||
direct_flow = types.SimpleNamespace(
|
||||
request=types.SimpleNamespace(
|
||||
headers=_Headers(),
|
||||
pretty_host="api.anthropic.com",
|
||||
),
|
||||
server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
|
||||
)
|
||||
|
||||
direct_addon.request(direct_flow)
|
||||
|
||||
assert direct_flow.request.headers == {}
|
||||
|
||||
|
||||
def test_network_capture_token_destination_allowlist_is_independent_of_logging_filter(
|
||||
monkeypatch, tmp_path: Path
|
||||
) -> None:
|
||||
addon = _load_capture_addon(
|
||||
monkeypatch,
|
||||
tmp_path,
|
||||
"headroom-client",
|
||||
"capture-secret",
|
||||
include_hosts="other.example.com",
|
||||
)
|
||||
flow = types.SimpleNamespace(
|
||||
request=types.SimpleNamespace(headers=_Headers(), pretty_host="api.anthropic.com"),
|
||||
server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
|
||||
)
|
||||
addon.request(flow)
|
||||
assert flow.request.headers == {"X-Headroom-Proxy-Token": "capture-secret"}
|
||||
|
||||
empty_allowlist = _load_capture_addon(
|
||||
monkeypatch, tmp_path, "headroom-client", "capture-secret", token_hosts=""
|
||||
)
|
||||
empty_flow = types.SimpleNamespace(
|
||||
request=types.SimpleNamespace(headers=_Headers(), pretty_host="api.anthropic.com"),
|
||||
server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
|
||||
)
|
||||
empty_allowlist.request(empty_flow)
|
||||
assert empty_flow.request.headers == {}
|
||||
|
||||
|
||||
def test_network_diff_redacts_and_reports_body_json_deltas(tmp_path: Path) -> None:
|
||||
direct_path = tmp_path / "direct.jsonl"
|
||||
headroom_path = tmp_path / "headroom.jsonl"
|
||||
|
||||
@@ -37,6 +37,11 @@ def _make_app(**overrides):
|
||||
return create_app(config)
|
||||
|
||||
|
||||
def test_create_app_accepts_test_net_host_without_transport_validation() -> None:
|
||||
app = _make_app(host="203.0.113.5", proxy_token=None)
|
||||
assert app is not None
|
||||
|
||||
|
||||
# ───────────────────────────── 2.1 inbound auth token ─────────────────────
|
||||
|
||||
|
||||
|
||||
@@ -177,3 +177,24 @@ def test_check_rust_core_returns_loaded_when_extension_present(
|
||||
status, error = server._check_rust_core()
|
||||
assert status == "loaded"
|
||||
assert error is None
|
||||
|
||||
|
||||
def test_proxy_refuses_marker_mismatch(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
"""A loadable but stale extension is still a required-core failure."""
|
||||
import sys
|
||||
from types import SimpleNamespace
|
||||
|
||||
from headroom.proxy import server
|
||||
|
||||
monkeypatch.delenv("HEADROOM_REQUIRE_RUST_CORE", raising=False)
|
||||
original = sys.modules.get("headroom._core")
|
||||
sys.modules["headroom._core"] = SimpleNamespace(hello=lambda: "stale-core")
|
||||
try:
|
||||
with pytest.raises(SystemExit) as exc_info:
|
||||
server._check_rust_core()
|
||||
assert exc_info.value.code == 78
|
||||
finally:
|
||||
if original is None:
|
||||
sys.modules.pop("headroom._core", None)
|
||||
else:
|
||||
sys.modules["headroom._core"] = original
|
||||
|
||||
@@ -54,7 +54,7 @@ client = HeadroomClient(
|
||||
```bash
|
||||
headroom proxy \
|
||||
--port 8787 \ # Port to listen on
|
||||
--host 0.0.0.0 \ # Host to bind to
|
||||
--host 127.0.0.1 \ # Host to bind to
|
||||
--budget 10.00 \ # Daily budget limit in USD
|
||||
--log-file headroom.jsonl # Log file path
|
||||
```
|
||||
|
||||
+15
-3
@@ -56,15 +56,27 @@ headroom mcp install
|
||||
headroom memory list
|
||||
```
|
||||
|
||||
For `proxy`, the wrapper publishes the selected port back to the host:
|
||||
For `proxy`, the maintained wrapper always publishes the selected host port on
|
||||
loopback. It passes `--host 0.0.0.0` inside the container so that the loopback
|
||||
publication can reach the container, and it has no public-publication override.
|
||||
For local-only use, no token is required:
|
||||
|
||||
```bash
|
||||
docker run --rm -it \
|
||||
-p 8787:8787 \
|
||||
-p 127.0.0.1:8787:8787 \
|
||||
-v "$PWD:/workspace" \
|
||||
-w /workspace \
|
||||
ghcr.io/headroomlabs-ai/headroom:latest \
|
||||
headroom proxy --host 0.0.0.0 --port 8787
|
||||
--host 0.0.0.0 --port 8787
|
||||
```
|
||||
|
||||
For deliberate public access, publish on an explicit public address and set
|
||||
`HEADROOM_PROXY_TOKEN`:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 0.0.0.0:8787:8787 \
|
||||
-e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
|
||||
ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0 --port 8787
|
||||
```
|
||||
|
||||
### `wrap` commands
|
||||
|
||||
@@ -12,6 +12,7 @@ and JSON payload differences.
|
||||
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
|
||||
@@ -27,6 +28,16 @@ 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.
|
||||
|
||||
|
||||
+23
-6
@@ -10,13 +10,13 @@ The Headroom proxy server is a production-ready HTTP server that applies context
|
||||
# Basic usage
|
||||
headroom proxy
|
||||
|
||||
# Custom port
|
||||
headroom proxy --port 8080
|
||||
# Deliberate public access, with the existing token protocol
|
||||
HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
|
||||
# Send `Authorization: Bearer replace-with-a-secret` or
|
||||
# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.
|
||||
|
||||
# With all options
|
||||
# With logging and budget
|
||||
headroom proxy \
|
||||
--host 0.0.0.0 \
|
||||
--port 8787 \
|
||||
--log-file /var/log/headroom.jsonl \
|
||||
--budget 100.0
|
||||
```
|
||||
@@ -427,7 +427,9 @@ headroom_latency_ms_sum
|
||||
## Configuration via Environment
|
||||
|
||||
```bash
|
||||
# For deliberate public access, configure the existing token and send it from callers.
|
||||
export HEADROOM_HOST=0.0.0.0
|
||||
export HEADROOM_PROXY_TOKEN='replace-with-a-secret'
|
||||
export HEADROOM_PORT=8787
|
||||
export HEADROOM_BUDGET=100.0
|
||||
|
||||
@@ -455,6 +457,8 @@ gunicorn headroom.proxy.server:create_app \
|
||||
--bind 0.0.0.0:8787 \
|
||||
--worker-class uvicorn.workers.UvicornWorker \
|
||||
--factory
|
||||
# Callers must send `Authorization: Bearer replace-with-a-secret` or
|
||||
# `X-Headroom-Proxy-Token: replace-with-a-secret`.
|
||||
```
|
||||
|
||||
Or with Docker:
|
||||
@@ -466,7 +470,20 @@ RUN apt-get update && apt-get install -y --no-install-recommends build-essential
|
||||
&& apt-get purge -y build-essential && apt-get autoremove -y \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
EXPOSE 8787
|
||||
CMD ["headroom", "proxy", "--host", "0.0.0.0"]
|
||||
CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
|
||||
```
|
||||
|
||||
Run this image with an explicit token and a deliberate publication choice:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 127.0.0.1:8787:8787 \
|
||||
-e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
|
||||
headroom-proxy
|
||||
```
|
||||
|
||||
Callers must send `Authorization: Bearer replace-with-a-secret` or
|
||||
`X-Headroom-Proxy-Token: replace-with-a-secret`. For network access, replace
|
||||
the host-side `127.0.0.1` with an intentional public address and keep the
|
||||
token configured.
|
||||
|
||||
> **Note:** `build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension that must be compiled from source. It is removed after installation to keep the image slim.
|
||||
|
||||
Reference in New Issue
Block a user