DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(api): disable the ssrf category and qualify guard behaviour notes
Renn F53fa3627d9a7
diff --git a/deeptutor/api/security_guard.py b/deeptutor/api/security_guard.pyindex e37de8654..0870486fc 100644--- a/deeptutor/api/security_guard.py+++ b/deeptutor/api/security_guard.py@@ -41,6 +41,7 @@ def build_security_config(settings: dict[str, Any]) -> Any:from guard import SecurityConfigexcept ImportError as exc:raise RuntimeError(INSTALL_HINT) from exc+ from guard_core.handlers.suspatterns_handler import ALL_DETECTION_CATEGORIESreturn SecurityConfig(rate_limit=settings["rate_limit"],@@ -56,6 +57,9 @@ def build_security_config(settings: dict[str, Any]) -> Any:security_headers={"enabled": False},# Prompts, documents and chat messages are free text, not attack input.detection_scan_body=False,+ # Browsers send the page URL as Referer; guard-core 4.4.0 flags localhost and+ # LAN addresses in it as ssrf (400), so that category stays off.+ enabled_detection_categories=ALL_DETECTION_CATEGORIES - {"ssrf"},enable_agent=False,)diff --git a/docs-for-user/SECURITY_GUARD.md b/docs-for-user/SECURITY_GUARD.mdindex c713f96b4..f0bb0d2bf 100644--- a/docs-for-user/SECURITY_GUARD.md+++ b/docs-for-user/SECURITY_GUARD.md@@ -1,6 +1,6 @@# Optional request screening (fastapi-guard)-DeepTutor can screen HTTP requests inside the backend with [fastapi-guard](https://github.com/Guard-Core/fastapi-guard). It is **off by default**. When it is off, the package is never imported and the middleware stack is unchanged.+DeepTutor can screen HTTP requests inside the backend with [fastapi-guard](https://github.com/Guard-Core/fastapi-guard). It is **off by default**. When it is off, the package is never imported and the middleware stack is unchanged. Like any new setting, `system.json` gains the disabled `security_guard` block with its defaults on the next load, and a malformed block is replaced by the defaults.The guard is an application-layer control. It complements a reverse proxy, WAF or firewall at the edge, and it keeps working when the backend port is reached without one (for example a published `:8001`, `deeptutor serve` on a LAN, or a tunnel).@@ -11,7 +11,7 @@ For every HTTP request it checks, in this order of concern:- **IP lists**: an optional allowlist (only listed addresses pass) and an optional denylist.- **Rate limit**: a sliding window per client address, 300 requests per 60 seconds by default.- **Ban list**: an address that triggers repeated attack-pattern matches is blocked for a while.-- **Attack-pattern scan** of the URL path, query string and headers (XSS, SQL injection, path traversal and similar). A match returns `400`.+- **Attack-pattern scan** of the URL path, query string and headers (XSS, SQL injection, path traversal and similar). A match returns `400`. The `ssrf` category is turned off because browsers send the page address as `Referer` and guard-core 4.4.0 flags localhost and LAN addresses in it, so SSRF patterns are not screened; this is to be revisited when the engine fix ships.Rejected requests return `429` (rate limit) or `403` (IP lists, ban). The guard sits inside `CORSMiddleware`, so those responses still carry CORS headers and the browser shows the real status instead of an opaque CORS error.@@ -74,6 +74,8 @@ python -m uvicorn deeptutor.api.main:app --host 0.0.0.0 --port 8001 --no-proxy-hIf a reverse proxy sits in front of the backend, add its address to `trusted_proxies`; otherwise every client looks like the proxy. The guard warns when it bans a private address because of this.+Dual-stack binds: with guard-core 4.4.0, a peer reported in IPv4-mapped form (`::ffff:a.b.c.d`, as on a dual-stack `::` bind) is not matched against IPv4 `trusted_proxies` entries, so a reverse proxy's `X-Forwarded-For` is ignored and all its clients share the proxy's bucket. The default launch paths bind `0.0.0.0` and are not affected. If you bind `::`, also list the mapped form of each proxy, for example `["10.0.0.0/8", "::ffff:10.0.0.0/104"]` (checked with guard-core 4.4.0, and covered by a test). Later guard-core versions may not need this.+**Bundled frontend.** The Next.js proxy (`web/proxy.ts`) deletes `X-Forwarded-For` and the other forwarded headers from browser requests (`web/lib/backend-forward.ts`) and does not add the browser's address. Requests that reach the backend through it all arrive from the frontend's own address (loopback in the default layout), with no forwarded header. One shared limit would throttle every user together, so `exempt_ips` (default `127.0.0.1` and `::1`) exempts that address from the rate limit. Through the frontend, requests are therefore screened for attack patterns and the denylist, but not rate-limited. Per-client limits apply to requests that reach the backend directly, or through a reverse proxy that sets `X-Forwarded-For` and is listed in `trusted_proxies` (with `exempt_ips` containing loopback, a loopback request that carries `X-Forwarded-For` is limited as the forwarded client). `exempt_ips` skips the rate limit only: the denylist, bans and the attack-pattern scan still apply to listed addresses. The guard does not ban loopback addresses.**Allowlist with the bundled frontend.** If `whitelist` is set, frontend traffic (loopback) is refused unless loopback is listed. With the bundled frontend, add `127.0.0.1` and `::1` to `whitelist`. The allowlist and denylist then govern direct backend access only, because the frontend hides browser addresses.diff --git a/tests/api/test_security_guard.py b/tests/api/test_security_guard.pyindex 0c8f18138..aae537b3f 100644--- a/tests/api/test_security_guard.py+++ b/tests/api/test_security_guard.py@@ -395,6 +395,34 @@ async def test_attack_pattern_in_query_is_blocked_with_400() -> None:assert status == 400+@requires_guard+ "referer",+ ["http://localhost:3000/chat", "http://127.0.0.1:3000/", "http://192.168.50.199:3782/"],+)+async def test_browser_referer_with_local_address_is_allowed(referer: str) -> None:+ app = _build_app(trusted_proxies=[])++ status, _, _ = await _call(app, client=(_unique_ip(), 1), headers=[("referer", referer)])++ assert status == 200+++@requires_guard+async def test_referer_carrying_an_attack_pattern_is_still_blocked() -> None:+ app = _build_app(trusted_proxies=[])++ status, _, _ = await _call(+ app,+ client=(_unique_ip(), 1),+ headers=[("referer", "http://localhost:3000/<script>alert(1)</script>")],+ )++ assert status == 400++@requires_guard@pytest.mark.asyncioasync def test_request_body_is_not_scanned() -> None:@@ -468,6 +496,32 @@ async def test_streaming_chunks_are_delivered_incrementally() -> None:assert seen == [b"chunk0", b"chunk1", b"chunk2"]+@requires_guard+async def test_forwarded_for_works_for_ipv4_mapped_proxy_peer_when_mapped_form_is_listed() -> None:+ """Dual-stack binds report IPv4 peers as ``::ffff:a.b.c.d``; list that form too."""+ app = _build_app(+ rate_limit=3,+ rate_limit_window=60,+ trusted_proxies=["10.0.0.0/8", "::ffff:10.0.0.0/104"],+ exempt_ips=[],+ )+ proxy = ("::ffff:10.0.0.9", 1)+ same_client = _unique_ip()++ limited = [+ (await _call(app, client=proxy, headers=[("x-forwarded-for", same_client)]))[0]+ for _ in range(4)+ ]+ distinct = [+ (await _call(app, client=proxy, headers=[("x-forwarded-for", _unique_ip())]))[0]+ for _ in range(5)+ ]++ assert limited == [200, 200, 200, 429]+ assert distinct == [200] * 5++# --- uvicorn peer handling --------------------------------------------------@@ -517,17 +571,19 @@ async def test_uvicorn_default_proxy_headers_would_defeat_the_limit(monkeypatch)assert statuses == [200, 200, 200, 200]-def test_every_launch_point_keeps_proxy_headers_off() -> None:- """The guard's client identity relies on these flags; see the test above."""- for relpath in ("deeptutor/api/run_server.py", "deeptutor_cli/main.py"):- assert "proxy_headers=False" in (_REPO / relpath).read_text(encoding="utf-8")- assert '"--no-proxy-headers"' in (_REPO / "deeptutor/runtime/launcher.py").read_text(- encoding="utf-8"+@requires_guard+def test_access_log_records_guard_rejections_in_main_app(tmp_path: Path) -> None:+ probe = """+from fastapi.testclient import TestClient+import deeptutor.api.main as m+client = TestClient(m.app, client=("203.0.113.9", 5000))+print([client.get("/api/auth/status").status_code for _ in range(3)])+"""+ result = _run_python(+ probe,+ tmp_path,+ DEEPTUTOR_GUARD_ENABLED="true",+ DEEPTUTOR_GUARD_RATE_LIMIT="1",)- launches = [- line- for line in (_REPO / "Dockerfile").read_text(encoding="utf-8").splitlines()- if "-m uvicorn deeptutor.api.main:app" in line- ]- assert launches- assert all("--no-proxy-headers" in line for line in launches)++ assert '203.0.113.9 - "GET /api/auth/status HTTP/1.1" 429' in result.stdout