mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 12:05:34 +08:00
## Why Four related gaps in the proxy's network gate (findings 01-F1, 01-F2, 01-F5, 01-F9): - **Open bind.** A non-loopback bind with no `HEADROOM_PROXY_TOKEN` only logged a warning, then served the `/v1/*` relay, with the operator's upstream credentials, to every peer that could reach the port. - **Missing peer address.** `is_loopback_host(None)` returned `True`. A Unix-domain socket, an ASGI adapter that leaves `scope["client"]` unset, or a hand-built request therefore turned off the token gate, the `/admin` and `/debug` guards and the WebSocket gate. - **Operator data routes.** `/stats-history` (including CSV export), `/quota`, `/subscription-window` and `/metrics` were served to any network caller. - **WebSocket loopback exemption** checked only the peer IP, not the `Host` header, so it had no DNS-rebinding defence. ## What changes - New `headroom/proxy/bind_policy.py`. A non-loopback bind (`0.0.0.0`, `::`, a LAN address or a hostname) with no token is refused at three places: `create_app` (embedders and the multi-worker factory), `run_server` (one exit with code 2 before uvicorn forks) and the `headroom proxy` CLI (a clear error before the banner, exit code 1). An absent host means uvicorn's default `127.0.0.1`. - `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` acknowledges an open bind when the runtime already restricts reachability, such as a container published on `127.0.0.1`. The `proxy_open_bind` warning is still logged on that path, and the banner says the bind is open. - `is_loopback_host(None)` now returns `False` (fail closed), matching `identity.py`. - `/stats-history`, `/quota` and `/subscription-window` answer only: a non-loopback caller that passed the token gate, a loopback caller (peer and `Host` header both loopback), a trusted dashboard client, or, under an acknowledged token-less bind, the container's own default-gateway TCP peer with a loopback `Host` (the host browser reaching a `127.0.0.1`-published container). Everyone else gets 404, as with `/admin`. Settings writes keep their stricter rule with no token short-cut. - `/metrics` answers a non-loopback caller that passed the token gate, a loopback caller, a connecting peer in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` (whatever it forwards), or a resolved client in the dashboard CIDRs. For CIDR peers a hostname `Host` is fine, so Prometheus scrapers work; a cross-origin browser request is still refused. - The token short-cut applies only to non-loopback requests. The gate exempts loopback peers without checking `Host`, so a loopback request has not proven it holds the token and must pass the loopback `Host` check. This blocks a DNS-rebound browser on the operator's machine. - The `/dashboard` shell stays ungated. It is a static template, like the already public `/dashboard/static` assets. Gating it would break the dashboard for containers published on host loopback, where the peer is the bridge gateway and `Host` is `localhost`. The data routes behind it are gated. - The WebSocket loopback exemption requires a loopback peer and a loopback `Host` header. A loopback peer with a foreign `Host` can still connect with the token. - Launchers that always publish on `127.0.0.1` set the acknowledgement themselves: `headroom install` (docker preset), `scripts/install.sh` and `scripts/install.ps1` (through one helper that adds the acknowledgement only together with the `127.0.0.1` publication), and `docker/docker-compose.native.yml`. - Docs: `proxy.mdx` documents the new variable and which routes the token also gates; `docker-install` (docs and wiki) and the `docker-compose.yml` comment show the acknowledgement in the loopback-published example. `e2e/docker-bind-security.sh` sets it and checks that the same launch without it refuses to start. ## Behaviour change (breaking) - `headroom proxy --host 0.0.0.0`, or `HEADROOM_HOST` set to any non-loopback address, without `HEADROOM_PROXY_TOKEN` now refuses to start. The error names both remedies. Set a token, bind loopback, or set `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` when the port is already confined. Anyone running the image by hand with `--host 0.0.0.0` and no token must add one of these. - Without a token, `/stats-history`, `/quota`, `/subscription-window` and `/metrics` return 404 to non-loopback callers outside a trusted CIDR. Prometheus scrapers on another host must be in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` or send the token. - Code that relied on a request with no peer address being treated as loopback now gets the non-loopback path. - The default loopback run is unchanged. ## Tests - `tests/test_proxy_bind_policy.py`: the refuse/allow matrix (non-loopback, loopback, unset host, token, acknowledgement values), the warning on the acknowledged path, `create_app`, the `run_server` exit before uvicorn, and the CLI (refusal, `HEADROOM_HOST` from env, acknowledged start, offline banner, start with a token). - `tests/test_proxy_loopback_gating.py`: each data route against non-loopback, loopback, trusted-CIDR and token callers; the dashboard shell stays reachable; the host of an acknowledged, loopback-published container reads the data routes while another bridge peer, a forwarded gateway address and a foreign `Host` do not; CSV export is not served to network callers; `/metrics` across loopback, both CIDR lists, out-of-range peers, cross-origin browsers and token callers, including a trusted gateway relaying a scraper outside its own range. A regression test shows that a token on the proxy does not exempt a loopback peer from the `Host` check; it fails without the fix. - `tests/test_proxy_hardening.py`: the HTTP gate with no peer address, WebSocket `Host` cases, `require_loopback` and `/debug` with no peer. - Installer tests: `headroom install` adds the acknowledgement, and the shell and PowerShell wrappers add it only together with the loopback publication. Launcher-level tests start the proxy with the environment and `--host` that `build_runtime_command()` and `docker-compose.native.yml` produce and check that the host browser (bridge-gateway peer) gets `/stats-history` and another container does not. - Tests that bound `0.0.0.0` for unrelated reasons now set a token or the acknowledgement. Tests that read operator routes use an explicit loopback peer. On `main`, 14 of the gating and hardening tests fail and the bind-policy module does not exist. Manual runs: token-less `--host 0.0.0.0` exits with the refusal from both the CLI and `run_server`; with the acknowledgement, the data routes are 404 to a LAN peer and to a loopback peer with a foreign `Host`; with a token, a LAN peer gets 401 without it and 200 with it; the default loopback bind starts as before. Not tested: a real Unix-domain-socket deployment and a real Prometheus scrape (both covered by tests only). ## Merge order Part of a set. Suggested order: #3852 → #3891 → #3849 → #3860 → #3862 → #3863. This PR goes first: it is the gate the others assume, and it is the release-note event. ## Not in this PR - Enforcing the token for loopback callers when one is configured. Revised 2026-10-02 after review: `/metrics` matches gateway CIDRs against the TCP peer, and the operator data routes serve the host of a loopback-published container (bridge-gateway peer under the launchers' bind acknowledgement) so the default Docker dashboard works. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3852" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
126 lines
6.0 KiB
YAML
126 lines
6.0 KiB
YAML
# =============================================================================
|
|
# Headroom — full "memory stack" compose
|
|
# =============================================================================
|
|
# Brings up the Headroom proxy together with the two datastores it needs for
|
|
# semantic memory: Qdrant (vector search) and Neo4j (relationship graph).
|
|
#
|
|
# Quick start:
|
|
# 1. cp .env.example .env # then set a real NEO4J_AUTH before any non-local use
|
|
# 2. docker compose up -d
|
|
# 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 --rm -p 127.0.0.1:8787:8787 -e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1
|
|
# ghcr.io/headroomlabs-ai/headroom --host 0.0.0.0 --port 8787`; the env var acknowledges that the
|
|
# 127.0.0.1 publication, not a token, is what keeps the port private); 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):
|
|
# 8787 proxy (OpenAI-compatible endpoint)
|
|
# 6333 Qdrant REST 6334 Qdrant gRPC
|
|
# 7474 Neo4j Browser 7687 Neo4j Bolt
|
|
#
|
|
# None of these three services authenticates inbound callers by default: the
|
|
# proxy's /v1/* data plane is open unless HEADROOM_PROXY_TOKEN is set, Qdrant
|
|
# has no API key, and Neo4j falls back to a published dev password. Publishing
|
|
# them on 0.0.0.0 therefore hands any peer on your network a relay through the
|
|
# proxy plus direct read/write on the embeddings and graph derived from your
|
|
# prompts. They are bound to loopback so that `docker compose up -d` is safe on
|
|
# a shared or untrusted network.
|
|
#
|
|
# To reach the proxy from another machine, publish it deliberately AND require
|
|
# a token — never one without the other:
|
|
# HEADROOM_PROXY_TOKEN=$(openssl rand -hex 32) # put this in .env
|
|
# ports: ["8787:8787"] # override in a compose override file
|
|
# =============================================================================
|
|
|
|
services:
|
|
# Headroom proxy — the OpenAI-compatible endpoint your client talks to.
|
|
# Built from the repo Dockerfile so it tracks your local checkout.
|
|
headroom-proxy:
|
|
build:
|
|
context: .
|
|
args:
|
|
HEADROOM_BUILD_VERSION: ${HEADROOM_BUILD_VERSION:-source-build}
|
|
# Bind to all interfaces inside the container so the published port is reachable.
|
|
command: ["--host", "0.0.0.0"]
|
|
environment:
|
|
- HEADROOM_HOST=0.0.0.0
|
|
# The proxy binds 0.0.0.0 *inside* the container (required for Docker port
|
|
# forwarding); it is confined to host loopback by the published port below.
|
|
# A proxy token is required so the data plane is never open if you widen the
|
|
# bind. Generate one with: openssl rand -hex 32
|
|
- HEADROOM_PROXY_TOKEN=${HEADROOM_PROXY_TOKEN:?set HEADROOM_PROXY_TOKEN (see .env.example; e.g. openssl rand -hex 32)}
|
|
- HOME=/home/nonroot
|
|
# Keep all Headroom read/write state on the named volume below.
|
|
- HEADROOM_WORKSPACE_DIR=/home/nonroot/.headroom
|
|
- HEADROOM_CONFIG_DIR=/home/nonroot/.headroom/config
|
|
# if you want to use a custom OpenAI-compatible API endpoint,
|
|
# uncomment and set the following line with the desired URL
|
|
# - OPENAI_TARGET_API_URL=https://api.x.ai
|
|
# Required before publishing this port beyond loopback: without it the
|
|
# /v1/* data plane accepts unauthenticated callers.
|
|
# - HEADROOM_PROXY_TOKEN=${HEADROOM_PROXY_TOKEN}
|
|
ports:
|
|
# Loopback-only. The container still listens on 0.0.0.0 (above) so the
|
|
# other compose services can reach it by name; this line controls only
|
|
# which host interfaces the port is published on.
|
|
- "127.0.0.1:8787:8787"
|
|
volumes:
|
|
- headroom_workspace:/home/nonroot/.headroom
|
|
# Readiness probe: the orchestrator polls /readyz so dependents and
|
|
# `docker compose up --wait` only see the proxy as healthy once it's serving.
|
|
healthcheck:
|
|
test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:8787/readyz"]
|
|
interval: 30s
|
|
timeout: 5s
|
|
retries: 3
|
|
start_period: 20s
|
|
# Start the datastores first. Note: this waits for the containers to start,
|
|
# not for them to be fully ready — the proxy retries its connections, so a
|
|
# brief "database not ready yet" window on first boot is expected.
|
|
depends_on:
|
|
- qdrant
|
|
- neo4j
|
|
|
|
# Vector database for semantic search.
|
|
# Stores embeddings so the proxy can retrieve semantically similar context.
|
|
qdrant:
|
|
image: qdrant/qdrant:v1.17.1
|
|
ports:
|
|
# Loopback-only: Qdrant runs unauthenticated here and holds embeddings
|
|
# derived from your prompts.
|
|
- "127.0.0.1:6333:6333" # REST API
|
|
- "127.0.0.1:6334:6334" # gRPC
|
|
# Named volume keeps the vector index across container restarts/recreates.
|
|
volumes:
|
|
- qdrant_data:/qdrant/storage
|
|
environment:
|
|
- QDRANT__SERVICE__GRPC_PORT=6334
|
|
|
|
# Graph database for relationships and multi-hop reasoning.
|
|
# Backs the memory features that traverse links between stored items.
|
|
neo4j:
|
|
image: neo4j:5.26
|
|
ports:
|
|
# Loopback-only to keep the graph store off the network.
|
|
- "127.0.0.1:7474:7474" # HTTP (Browser)
|
|
- "127.0.0.1:7687:7687" # Bolt
|
|
# Named volume persists the graph data across container restarts/recreates.
|
|
volumes:
|
|
- neo4j_data:/data
|
|
environment:
|
|
# No default credential — must be supplied (see .env.example).
|
|
- NEO4J_AUTH=${NEO4J_AUTH:?set NEO4J_AUTH, e.g. neo4j/<strong-password>}
|
|
# APOC: Neo4j's standard procedure library, needed by Headroom's queries.
|
|
- NEO4J_PLUGINS=["apoc"]
|
|
# APOC file import/export stays disabled (its Neo4j default) — it grants
|
|
# filesystem read/write via stored procedures. Do not enable unless required.
|
|
|
|
# Named volumes — managed by Docker, survive `docker compose down` (use
|
|
# `docker compose down -v` to delete the stored data as well).
|
|
volumes:
|
|
headroom_workspace: # persists dashboard savings/history, logs, config, memory state, session stats, and TOIN
|
|
qdrant_data:
|
|
neo4j_data:
|