mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(proxy): allow loopback-published container hosts to access /debug/memory (#4259)
## Description A request forwarded through a loopback-published container port reaches the proxy from the container gateway, so the strict loopback peer check returned 404 even though `/debug/memory` was registered. This changes the route to the existing exact-gateway guard while retaining its loopback Host check. Fixes #4247 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Use the existing loopback-or-container-gateway dependency for `/debug/memory`. - Add regression coverage for loopback, the configured gateway, another bridge peer, and a non-loopback Host. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text LITELLM_LOCAL_MODEL_COST_MAP=true uv run --no-sync pytest tests/test_proxy_loopback_gating.py tests/test_proxy_debug_endpoints.py -q 176 passed, 6 warnings .venv/bin/ruff check headroom/proxy/server.py tests/test_proxy_loopback_gating.py All checks passed .venv/bin/ruff format --check headroom/proxy/server.py tests/test_proxy_loopback_gating.py Passed ``` ## Real Behavior Proof - Environment: Linux, Python 3.14.7, local source checkout; no external provider request. - Exact command / steps: run Uvicorn from this checkout on `127.0.0.1:18787`, then request `/openapi.json` and `/debug/memory` over loopback. - Observed result: both requests returned HTTP 200; the memory response contained the `process` statistics. - Not tested: actual Docker port publication. The configured gateway, unrelated bridge peer, and non-loopback Host cases were exercised through the ASGI test client. ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: N/A. - Stable/default behavior changed: `/debug/memory` accepts the exact container gateway peer when the Host remains loopback. - Kill switch / disable path: revert this change. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert this change. ## 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 - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A. ## Additional Notes An Issue comment links a separate `oxura/headroom` branch and says an upstream PR is queued; current checks found no upstream PR for this issue or this submission branch. This run did not test Docker port publication, the full test suite, or upstream CI. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4259" 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 --> ### Maintainer container-runtime qualification - Environment: Docker Engine 29.9.2 on a Windows host, Linux container/Python 3.12.3, mounted source from the current-main integration. The listener used `create_app(ProxyConfig(host="0.0.0.0", optimize=False, cache_enabled=False, rate_limit_enabled=False, disable_kompress=True, stateless=True))` with Uvicorn on port 8787. `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` explicitly acknowledged the tokenless container listener; `HEADROOM_REQUIRE_RUST_CORE=false` exercised Python authorization/routes without claiming a Linux native build or compression qualification. Telemetry and model warmup were disabled. - Exact command / steps: published only `127.0.0.1:18787:8787`; requested `/debug/memory` from the host using httpx with environment proxies disabled; recorded the actual ASGI TCP peer and Host with observational middleware. Restarted the same container/dependencies against unchanged main `31dcaf41`, then against the combined PR source. Requested the container bridge address from a separate container while explicitly setting a loopback Host. Finally configured `HEADROOM_PROXY_TOKEN` and repeated host and unrelated-peer requests, including a spoofed `X-Forwarded-For: 127.0.0.1`. No provider calls were made. - Observed result: ```text actual host-forwarded TCP peer: 172.17.0.1 main /debug/memory via loopback publication: 404 PR /debug/memory via loopback publication: 200, process statistics present PR gateway peer + Host attacker.example: 404 unrelated bridge container + loopback Host: 404 proxy token configured, host request without token: 401 proxy token configured, host request with token: 200 unrelated bridge container + valid token + spoofed forwarded loopback IP: 404 ``` - Not tested: Podman, other Docker network drivers/host platforms, production reverse proxies, provider traffic, or native compression inside the container. The Windows focused suite separately passed all 176 loopback/debug tests using the existing native extension; changed-file lint, formatting, and whitespace checks passed. Supported deployment boundary: tokenless access assumes a port published only on host loopback and trust in processes already running on that host. The exact gateway peer is a transport boundary, not proof of the original caller behind a host relay; Host is caller-controlled. Do not expose a tokenless host relay/public reverse proxy to this listener. Such forwarding must enforce authentication (for example the proxy token, whose rejection/acceptance was verified above, or equivalent relay authentication). This qualification clears the earlier missing published-port evidence without claiming that a loopback Host alone authenticates a remote caller. Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
@@ -5886,7 +5886,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
|
||||
)
|
||||
|
||||
# Debug endpoints
|
||||
@app.get("/debug/memory", dependencies=[Depends(_require_loopback)])
|
||||
@app.get("/debug/memory", dependencies=[Depends(_require_loopback_or_container_gateway)])
|
||||
async def debug_memory():
|
||||
"""Get detailed memory usage statistics.
|
||||
|
||||
|
||||
@@ -61,6 +61,26 @@ def _loopback_client() -> TestClient:
|
||||
return TestClient(_make_app(), base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
|
||||
|
||||
|
||||
def test_debug_memory_is_available_to_loopback_published_container_host(
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.17.0.1")
|
||||
app = create_app(ProxyConfig(optimize=False, cache_enabled=False, stateless=True))
|
||||
loopback = TestClient(app, base_url="http://127.0.0.1:8787", client=("127.0.0.1", 1))
|
||||
host = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.1", 1))
|
||||
other_container = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.5", 1))
|
||||
wrong_host = TestClient(app, base_url="http://attacker.example:8787", client=("172.17.0.1", 1))
|
||||
|
||||
assert "/debug/memory" in host.get("/openapi.json").json()["paths"]
|
||||
assert loopback.get("/debug/memory").status_code == 200
|
||||
response = host.get("/debug/memory")
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
assert "process" in response.json()
|
||||
assert other_container.get("/debug/memory").status_code == 404
|
||||
assert wrong_host.get("/debug/memory").status_code == 404
|
||||
|
||||
|
||||
def _seed_ccr_entry() -> str:
|
||||
reset_compression_store()
|
||||
store = get_compression_store(backend=InMemoryBackend())
|
||||
|
||||
Reference in New Issue
Block a user