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:
lorenzozane
2026-11-04 22:40:37 -06:00
committed by GitHub
co-authored by JD Davis
parent 662a7f6fd8
commit e546e71aeb
2 changed files with 21 additions and 1 deletions
+1 -1
View File
@@ -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.
+20
View File
@@ -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())