Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

feat(api): add opt-in fastapi-guard request screening

Renn Fdbd270cfdbc1
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index bf2f9f481..15db9f290 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -261,6 +261,9 @@ jobs:
pip install -r requirements/partners.txt
pip install pytest pytest-asyncio
+ - name: Install optional fastapi-guard
+ run: pip install -r requirements/guard.txt
+
- name: Install optional LightRAG SDK
if: matrix.python-version == '3.12'
run: pip install "lightrag-hku==1.5.7"
diff --git a/deeptutor/api/main.py b/deeptutor/api/main.py
index 26dc3e27e..b998231fb 100644
--- a/deeptutor/api/main.py
+++ b/deeptutor/api/main.py
@@ -7,6 +7,7 @@ from fastapi import Depends, FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse, RedirectResponse
+from deeptutor.api.security_guard import install_security_guard
from deeptutor.logging import configure_logging
from deeptutor.services.config import (
ensure_runtime_settings_files,
@@ -445,6 +446,12 @@ async def json_error_boundary(request: Request, call_next):
)
+# Optional fastapi-guard screening (off unless security_guard.enabled). Added
+# before the access log and CORS middlewares below: Starlette makes the last-added
+# middleware outermost, so CORS stays outside the guard (429/403 carry CORS
+# headers) and the access log sees what the guard rejects.
+install_security_guard(app)
+
# Access logging is funneled through this one middleware. uvicorn's own
# per-request access log is disabled on every launch path (run_server.py via
# access_log=False; the launcher and Docker via `--no-access-log`), so routine
diff --git a/deeptutor/api/security_guard.py b/deeptutor/api/security_guard.py
new file mode 100644
index 000000000..bdfa75273
--- /dev/null
+++ b/deeptutor/api/security_guard.py
@@ -0,0 +1,85 @@
+"""Opt-in request screening with fastapi-guard.
+
+Disabled by default. When ``system.json`` -> ``security_guard.enabled`` is false
+(or ``DEEPTUTOR_GUARD_ENABLED`` is unset), nothing here imports ``guard`` and the
+middleware stack is unchanged. See ``docs-for-user/SECURITY_GUARD.md``.
+
+The guard runs inside the application, in front of the routers. It screens HTTP
+requests by client address (rate limit, IP allow/deny lists, ban list) and scans
+the URL path, query string and headers for attack patterns. It does not read
+request bodies (prompts, documents and chat are free text), does not touch
+WebSocket handshakes, and does not use Redis, CORS or security headers.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+
+from deeptutor.services.config import load_system_settings
+
+logger = logging.getLogger(__name__)
+
+INSTALL_HINT = (
+ "security_guard is enabled but the 'fastapi-guard' package is not installed. "
+ "Install it with `pip install 'deeptutor[guard]'` (Docker: set "
+ "DEEPTUTOR_EXTRAS=guard), or disable it with security_guard.enabled=false in "
+ "system.json / DEEPTUTOR_GUARD_ENABLED=false."
+)
+
+
+def load_guard_settings() -> dict[str, Any]:
+ """Effective ``security_guard`` settings (file plus deployment overrides)."""
+ return dict(load_system_settings()["security_guard"])
+
+
+def build_security_config(settings: dict[str, Any]) -> Any:
+ """Translate DeepTutor settings into a ``guard.SecurityConfig``."""
+ try:
+ from guard import SecurityConfig
+ except ImportError as exc:
+ raise RuntimeError(INSTALL_HINT) from exc
+
+ return SecurityConfig(
+ rate_limit=settings["rate_limit"],
+ rate_limit_window=settings["rate_limit_window"],
+ trusted_proxies=tuple(settings["trusted_proxies"]),
+ whitelist=tuple(settings["whitelist"]) or None,
+ blacklist=tuple(settings["blacklist"]),
+ # Process-local state: each uvicorn worker keeps its own counters.
+ enable_redis=False,
+ # DeepTutor sets CORS itself (CORSMiddleware) and owns its response headers.
+ enable_cors=False,
+ security_headers={"enabled": False},
+ # Prompts, documents and chat messages are free text, not attack input.
+ detection_scan_body=False,
+ enable_agent=False,
+ )
+
+
+def install_security_guard(app: FastAPI, settings: dict[str, Any] | None = None) -> bool:
+ """Add the guard middleware to ``app`` when enabled; return whether it was added.
+
+ Call this before ``CORSMiddleware`` is added: Starlette puts the last-added
+ middleware outermost, so CORS stays outside the guard and 429/403 responses
+ still carry CORS headers.
+ """
+ settings = load_guard_settings() if settings is None else settings
+ if not settings["enabled"]:
+ return False
+
+ config = build_security_config(settings)
+ from guard import PureASGISecurityMiddleware
+
+ app.add_middleware(PureASGISecurityMiddleware, config=config)
+ logger.info(
+ "Security guard enabled: rate_limit=%s/%ss trusted_proxies=%s whitelist=%s blacklist=%s",
+ settings["rate_limit"],
+ settings["rate_limit_window"],
+ settings["trusted_proxies"],
+ len(settings["whitelist"]),
+ len(settings["blacklist"]),
+ )
+ return True
diff --git a/deeptutor/services/config/runtime_settings.py b/deeptutor/services/config/runtime_settings.py
index 4e001bac6..83131637f 100644
--- a/deeptutor/services/config/runtime_settings.py
+++ b/deeptutor/services/config/runtime_settings.py
@@ -66,6 +66,21 @@ DEFAULT_SYSTEM_SETTINGS: dict[str, Any] = {
# earlier images ride along on every later turn — a re-sent payload, so
# it is a policy like the caps above, not an LLM budget.
"chat_prior_image_reinject_max": 4,
+ # Opt-in fastapi-guard request screening (deeptutor/api/security_guard.py).
+ # Off by default: when disabled, the package is never imported and the
+ # middleware stack is unchanged. ``trusted_proxies`` are the only peers
+ # whose X-Forwarded-For is believed; an empty list means the socket peer is
+ # always the client. The rate limit counts every HTTP request from one
+ # client address, so it is sized for the frontend's polling, not for one
+ # call per page view.
+ "security_guard": {
+ "enabled": False,
+ "rate_limit": 300,
+ "rate_limit_window": 60,
+ "trusted_proxies": ["127.0.0.1", "::1"],
+ "whitelist": [],
+ "blacklist": [],
+ },
}
# Clamp bounds for the chat attachment knobs. The MB ceilings are deliberately
@@ -390,6 +405,15 @@ IGNORE_PROCESS_OVERRIDES_ENV = "DEEPTUTOR_IGNORE_PROCESS_ENV_OVERRIDES"
# can never win again: toggling "check for updates" wrote system.json while the
# live API kept answering with the value captured at startup (#1536).
SETTINGS_DERIVED_ENV_KEYS = "DEEPTUTOR_SETTINGS_DERIVED_ENV_KEYS"
+# (process env name, security_guard key) deployment overrides.
+_SECURITY_GUARD_ENV_KEYS = (
+ ("DEEPTUTOR_GUARD_ENABLED", "enabled"),
+ ("DEEPTUTOR_GUARD_RATE_LIMIT", "rate_limit"),
+ ("DEEPTUTOR_GUARD_RATE_LIMIT_WINDOW", "rate_limit_window"),
+ ("DEEPTUTOR_GUARD_TRUSTED_PROXIES", "trusted_proxies"),
+ ("DEEPTUTOR_GUARD_WHITELIST", "whitelist"),
+ ("DEEPTUTOR_GUARD_BLACKLIST", "blacklist"),
+)
TRUTHY = {"1", "true", "yes", "on"}
FALSY = {"0", "false", "no", "off"}
@@ -878,6 +902,11 @@ class RuntimeSettingsService:
payload["chat_attachment_max_chars_total"] = value
if value := self._process_env_value("CHAT_PRIOR_IMAGE_REINJECT_MAX"):
payload["chat_prior_image_reinject_max"] = value
+ guard = dict(payload.get("security_guard") or {})
+ for env_name, key in _SECURITY_GUARD_ENV_KEYS:
+ if value := self._process_env_value(env_name):
+ guard[key] = value
+ payload["security_guard"] = guard
return self._normalize_system(payload)
def _apply_auth_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
@@ -1261,6 +1290,9 @@ class RuntimeSettingsService:
)
# A per-message total below the per-file cap is contradictory; lift it.
max_total_mb = max(max_total_mb, max_file_mb)
+ raw_guard = settings.get("security_guard")
+ guard = raw_guard if isinstance(raw_guard, dict) else {}
+ guard_defaults = DEFAULT_SYSTEM_SETTINGS["security_guard"]
return {
"version": 1,
"version_check_enabled": _coerce_bool(settings.get("version_check_enabled"), True),
@@ -1306,6 +1338,22 @@ class RuntimeSettingsService:
DEFAULT_SYSTEM_SETTINGS["chat_attachment_max_chars_total"],
*CHAT_ATTACHMENT_CHARS_RANGE,
),
+ "security_guard": {
+ "enabled": _coerce_bool(guard.get("enabled"), False),
+ "rate_limit": _coerce_clamped_int(
+ guard.get("rate_limit"), guard_defaults["rate_limit"], 1, 1_000_000
+ ),
+ "rate_limit_window": _coerce_clamped_int(
+ guard.get("rate_limit_window"), guard_defaults["rate_limit_window"], 1, 86_400
+ ),
+ # An absent key keeps the loopback default; an explicit empty
+ # list means "trust no proxy".
+ "trusted_proxies": _host_list(guard["trusted_proxies"])
+ if "trusted_proxies" in guard
+ else list(guard_defaults["trusted_proxies"]),
+ "whitelist": _host_list(guard.get("whitelist")),
+ "blacklist": _host_list(guard.get("blacklist")),
+ },
}
def _normalize_auth(self, settings: dict[str, Any]) -> dict[str, Any]:
diff --git a/docs-for-user/CONTAINERIZATION.md b/docs-for-user/CONTAINERIZATION.md
index 113d08441..b7ab1d504 100644
--- a/docs-for-user/CONTAINERIZATION.md
+++ b/docs-for-user/CONTAINERIZATION.md
@@ -535,3 +535,7 @@ renormalized on save.
- CORS uses frontend **origins**, not API URLs. With auth enabled, set
`cors_origins` in `system.json` to the exact frontend origins the
deployment serves.
+- Optional request screening (rate limit, IP allow/deny lists, attack-pattern
+ scan) is available through `security_guard` in `system.json` and the
+ `guard` extra (`DEEPTUTOR_EXTRAS: "guard"`). It is off by default; see
+ [SECURITY_GUARD.md](SECURITY_GUARD.md).
diff --git a/docs-for-user/SECURITY_GUARD.md b/docs-for-user/SECURITY_GUARD.md
new file mode 100644
index 000000000..c2a85cd90
--- /dev/null
+++ b/docs-for-user/SECURITY_GUARD.md
@@ -0,0 +1,76 @@
+# 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.
+
+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).
+
+## What it does
+
+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`.
+
+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.
+
+## What it does not do
+
+- It never reads request bodies. Prompts, documents and chat messages are free text, so body scanning is turned off (`detection_scan_body=False`).
+- It does not screen WebSocket handshakes (`/ws`), only HTTP requests.
+- It does not use Redis. Counters live in each backend process, so with `backend_workers` greater than 1 the effective limit is up to `rate_limit` times the worker count.
+- It does not add security headers, handle CORS or send telemetry (`security_headers`, `enable_cors` and `enable_agent` are all off).
+
+Two engine behaviours worth knowing: paths in the engine's default `exclude_paths` (`/docs`, `/redoc`, `/openapi.json`, `/openapi.yaml`, `/favicon.ico`, `/static`) skip the attack-pattern scan only, the rate limit and IP lists still apply to them; and an allowlisted address skips both the attack-pattern scan and the rate limit.
+
+## Enable it
+
+1. Install the extra (it adds `fastapi-guard`; `redis` is already a DeepTutor dependency, `maxminddb` and `cachetools` are new):
+
+ ```bash
+ pip install "deeptutor[guard]" # or: pip install -r requirements/guard.txt
+ ```
+
+ In Docker set `DEEPTUTOR_EXTRAS: "guard"` on the service, the same way as other extras (see [CONTAINERIZATION.md](CONTAINERIZATION.md)).
+
+2. Enable it in `data/user/settings/system.json`:
+
+ ```json
+ {
+ "security_guard": {
+ "enabled": true,
+ "rate_limit": 300,
+ "rate_limit_window": 60,
+ "trusted_proxies": ["127.0.0.1", "::1"],
+ "whitelist": [],
+ "blacklist": []
+ }
+ }
+ ```
+
+ Outside Docker the same keys can be set as process environment overrides: `DEEPTUTOR_GUARD_ENABLED`, `DEEPTUTOR_GUARD_RATE_LIMIT`, `DEEPTUTOR_GUARD_RATE_LIMIT_WINDOW`, `DEEPTUTOR_GUARD_TRUSTED_PROXIES`, `DEEPTUTOR_GUARD_WHITELIST` and `DEEPTUTOR_GUARD_BLACKLIST` (comma-separated IPs or CIDR ranges). The Docker entrypoint ignores process environment overrides, so in a container use `system.json`.
+
+3. Restart the backend.
+
+If `enabled` is true and `fastapi-guard` is not installed, the backend refuses to start and prints how to install it. Invalid IP or CIDR entries also fail at startup.
+
+### Sizing the rate limit
+
+The limit counts **every** HTTP request from one client address, including the frontend's background polling (several panels poll every 1 to 5 seconds). 300 per 60 seconds leaves room for a few open panels; the engine's own default of 10 per 60 seconds would trip on normal use. The Next.js frontend serves its static assets itself, so those requests do not reach the backend and are not counted.
+
+## Client address and proxies
+
+The guard identifies a client by the socket peer of the request. It believes `X-Forwarded-For` only when the peer is listed in `trusted_proxies` (default: loopback only). A request from any other peer has its `X-Forwarded-For` ignored.
+
+Uvicorn can also rewrite the peer from `X-Forwarded-For` (and from `FORWARDED_ALLOW_IPS`) before the application sees it, which would let a client choose its own identity. Every DeepTutor launch path already passes `proxy_headers=False` / `--no-proxy-headers` (`deeptutor/api/run_server.py`, `deeptutor_cli/main.py`, `deeptutor/runtime/launcher.py`, both `Dockerfile` launch lines), so the guard sees the real peer. `tests/api/test_security_guard.py` checks this through `uvicorn.Config(...).load()`.
+
+If you start the backend yourself, keep the flag:
+
+```bash
+python -m uvicorn deeptutor.api.main:app --host 0.0.0.0 --port 8001 --no-proxy-headers
+```
+
+If 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.
+
+**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). The rate limit and IP lists then apply to the frontend as a whole, not per browser, and the guard does not ban loopback. Per-client limits and lists apply to requests that reach the backend directly.
diff --git a/pyproject.toml b/pyproject.toml
index 0f5bc7c5e..abc0e1657 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -271,6 +271,12 @@ rag-lightrag = ["lightrag-hku==1.5.7"]
# package or configured model is unavailable.
rag-rerank = ["sentence-transformers>=3.0.0,<6.0.0; python_version < '3.14'"]
+# Optional request screening (rate limit, IP allow/deny lists, attack-pattern
+# scan of path, query and headers). Off unless system.json `security_guard`
+# is enabled; see docs-for-user/SECURITY_GUARD.md. Mirrors
+# requirements/guard.txt. Docker: DEEPTUTOR_EXTRAS=guard.
+guard = ["fastapi-guard>=8.1.1,<9.0.0"]
+
# Dev/test tooling. Mirrors requirements/dev.txt.
dev = [
"deeptutor[server]",
diff --git a/requirements/guard.txt b/requirements/guard.txt
new file mode 100644
index 000000000..97f740a38
--- /dev/null
+++ b/requirements/guard.txt
@@ -0,0 +1,3 @@
+# Mirrors pyproject.toml `[project.optional-dependencies].guard`.
+# Optional request screening; off unless system.json `security_guard` is enabled.
+fastapi-guard>=8.1.1,<9.0.0
diff --git a/tests/api/test_security_guard.py b/tests/api/test_security_guard.py
new file mode 100644
index 000000000..a89d8366a
--- /dev/null
+++ b/tests/api/test_security_guard.py
@@ -0,0 +1,462 @@
+"""Tests for the opt-in fastapi-guard integration (deeptutor/api/security_guard.py).
+
+Guard state (rate-limit windows, ban lists) is process-wide, so every test uses
+its own client address from ``_unique_ip``. The requests are driven straight
+through the ASGI interface so the peer address (``scope["client"]``) is under the
+test's control and streaming responses are observed chunk by chunk.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable
+from copy import deepcopy
+import importlib.util
+import itertools
+import json
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+import pytest
+
+from deeptutor.api.security_guard import INSTALL_HINT, install_security_guard
+from deeptutor.services.config.runtime_settings import (
+ DEFAULT_SYSTEM_SETTINGS,
+ RuntimeSettingsService,
+)
+
+requires_guard = pytest.mark.skipif(
+ importlib.util.find_spec("guard") is None,
+ reason="fastapi-guard is an optional extra (deeptutor[guard])",
+)
+
+_REPO = Path(__file__).resolve().parents[2]
+_ORIGIN = "http://localhost:3000"
+_ip_counter = itertools.count(1)
+
+
+def _unique_ip() -> str:
+ n = next(_ip_counter)
+ return f"198.18.{n // 250}.{n % 250 + 1}"
+
+
+def _guard_settings(**overrides: Any) -> dict[str, Any]:
+ settings = deepcopy(DEFAULT_SYSTEM_SETTINGS["security_guard"])
+ settings["enabled"] = True
+ settings.update(overrides)
+ return settings
+
+
+def _build_app(**overrides: Any) -> FastAPI:
+ app = FastAPI()
+ assert install_security_guard(app, _guard_settings(**overrides)) is True
+ # Same order as deeptutor/api/main.py: the guard first, CORS added last.
+ app.add_middleware(
+ CORSMiddleware,
+ allow_origins=[_ORIGIN],
+ allow_methods=["*"],
+ allow_headers=["*"],
+ )
+
+ @app.get("/ping")
+ async def ping() -> dict[str, bool]:
+ return {"ok": True}
+
+ @app.post("/echo")
+ async def echo(request: Request) -> dict[str, Any]:
+ return {"body": (await request.body()).decode()}
+
+ return app
+
+
+async def _call(
+ app: Any,
+ path: str = "/ping",
+ *,
+ method: str = "GET",
+ query: str = "",
+ headers: Iterable[tuple[str, str]] = (),
+ client: tuple[str, int] | None = ("127.0.0.1", 50000),
+ body: bytes = b"",
+) -> tuple[int, dict[str, str], bytes]:
+ scope = {
+ "type": "http",
+ "asgi": {"version": "3.0"},
+ "http_version": "1.1",
+ "method": method,
+ "scheme": "http",
+ "path": path,
+ "raw_path": path.encode(),
+ "query_string": query.encode(),
+ "headers": [(k.lower().encode(), v.encode()) for k, v in headers],
+ "client": client,
+ "server": ("testserver", 80),
+ }
+ sent_body = False
+
+ async def receive() -> dict[str, Any]:
+ nonlocal sent_body
+ if not sent_body:
+ sent_body = True
+ return {"type": "http.request", "body": body, "more_body": False}
+ await asyncio.sleep(3600)
+ return {"type": "http.disconnect"}
+
+ status = 0
+ response_headers: dict[str, str] = {}
+ chunks: list[bytes] = []
+
+ async def send(message: dict[str, Any]) -> None:
+ nonlocal status
+ if message["type"] == "http.response.start":
+ status = message["status"]
+ response_headers.update({k.decode().lower(): v.decode() for k, v in message["headers"]})
+ elif message["type"] == "http.response.body":
+ chunks.append(message.get("body", b""))
+
+ await app(scope, receive, send)
+ return status, response_headers, b"".join(chunks)
+
+
+def _run_python(code: str, tmp_path: Path, **env: str) -> subprocess.CompletedProcess[str]:
+ import os
+
+ child_env = {**os.environ, "DEEPTUTOR_HOME": str(tmp_path), **env}
+ for key in ("DEEPTUTOR_GUARD_ENABLED", "DEEPTUTOR_IGNORE_PROCESS_ENV_OVERRIDES"):
+ if key not in env:
+ child_env.pop(key, None)
+ return subprocess.run(
+ [sys.executable, "-c", code],
+ cwd=_REPO,
+ env=child_env,
+ capture_output=True,
+ check=True,
+ text=True,
+ )
+
+
+_STACK_PROBE = """
+import json, sys
+import deeptutor.api.main as m
+print(json.dumps({
+ "stack": [layer.cls.__name__ for layer in m.app.user_middleware],
+ "guard_imported": "guard" in sys.modules or "guard_core" in sys.modules,
+}))
+"""
+
+
+# --- opt-in behaviour -------------------------------------------------------
+
+
+def test_disabled_by_default_never_imports_guard(tmp_path: Path) -> None:
+ result = _run_python(_STACK_PROBE, tmp_path)
+ probe = json.loads(result.stdout.strip().splitlines()[-1])
+
+ assert probe["guard_imported"] is False
+ assert "PureASGISecurityMiddleware" not in probe["stack"]
+ assert probe["stack"][0] == "CORSMiddleware"
+
+
+def test_disabled_settings_add_nothing() -> None:
+ app = FastAPI()
+ settings = _guard_settings(enabled=False)
+
+ assert install_security_guard(app, settings) is False
+ assert app.user_middleware == []
+
+
+def test_enabled_without_package_fails_with_install_hint(monkeypatch) -> None:
+ monkeypatch.setitem(sys.modules, "guard", None) # `import guard` raises ImportError
+
+ with pytest.raises(RuntimeError, match=r"deeptutor\[guard\]") as excinfo:
+ install_security_guard(FastAPI(), _guard_settings())
+
+ assert str(excinfo.value) == INSTALL_HINT
+
+
+@requires_guard
+def test_enabled_main_app_keeps_cors_outermost(tmp_path: Path) -> None:
+ result = _run_python(_STACK_PROBE, tmp_path, DEEPTUTOR_GUARD_ENABLED="true")
+ probe = json.loads(result.stdout.strip().splitlines()[-1])
+
+ # user_middleware is outermost first.
+ assert probe["stack"][0] == "CORSMiddleware"
+ assert probe["stack"].count("PureASGISecurityMiddleware") == 1
+ assert probe["stack"].index("PureASGISecurityMiddleware") > 0
+ assert probe["guard_imported"] is True
+
+
+def test_settings_defaults_json_and_env_overrides(tmp_path: Path) -> None:
+ defaults = RuntimeSettingsService(tmp_path / "a", process_env={}).load_system()[
+ "security_guard"
+ ]
+ assert defaults == {
+ "enabled": False,
+ "rate_limit": 300,
+ "rate_limit_window": 60,
+ "trusted_proxies": ["127.0.0.1", "::1"],
+ "whitelist": [],
+ "blacklist": [],
+ }
+
+ overridden = RuntimeSettingsService(
+ tmp_path / "b",
+ process_env={
+ "DEEPTUTOR_GUARD_ENABLED": "1",
+ "DEEPTUTOR_GUARD_RATE_LIMIT": "50",
+ "DEEPTUTOR_GUARD_RATE_LIMIT_WINDOW": "10",
+ "DEEPTUTOR_GUARD_TRUSTED_PROXIES": "10.0.0.0/8, 192.168.1.5",
+ "DEEPTUTOR_GUARD_WHITELIST": "203.0.113.0/24",
+ "DEEPTUTOR_GUARD_BLACKLIST": "198.51.100.9",
+ },
+ ).load_system()["security_guard"]
+ assert overridden == {
+ "enabled": True,
+ "rate_limit": 50,
+ "rate_limit_window": 10,
+ "trusted_proxies": ["10.0.0.0/8", "192.168.1.5"],
+ "whitelist": ["203.0.113.0/24"],
+ "blacklist": ["198.51.100.9"],
+ }
+
+ # system.json: an explicit empty list means "trust no proxy" (not the default).
+ from_file = RuntimeSettingsService(tmp_path / "c", process_env={})
+ system = from_file.load_system(include_process_overrides=False)
+ system["security_guard"] = {"enabled": True, "trusted_proxies": []}
+ from_file.save_system(system)
+ saved = from_file.load_system()["security_guard"]
+ assert saved["enabled"] is True
+ assert saved["trusted_proxies"] == []
+ assert saved["rate_limit"] == 300
+
+
+@requires_guard
+def test_security_config_is_stateless_and_scoped() -> None:
+ from deeptutor.api.security_guard import build_security_config
+
+ config = build_security_config(_guard_settings(trusted_proxies=[]))
+
+ assert config.enable_redis is False
+ assert config.enable_cors is False
+ assert config.security_headers == {"enabled": False}
+ assert config.detection_scan_body is False
+ assert config.enable_agent is False
+ assert config.trusted_proxies == ()
+ assert (config.rate_limit, config.rate_limit_window) == (300, 60)
+
+
+# --- request screening ------------------------------------------------------
+
+
+@requires_guard
+async def test_rate_limit_burst_returns_429_with_cors_header() -> None:
+ app = _build_app(rate_limit=3, rate_limit_window=60, trusted_proxies=[])
+ ip = _unique_ip()
+ headers = [("origin", _ORIGIN)]
+
+ statuses = [(await _call(app, client=(ip, 1), headers=headers))[0] for _ in range(3)]
+ status, response_headers, _ = await _call(app, client=(ip, 1), headers=headers)
+
+ assert statuses == [200, 200, 200]
+ assert status == 429
+ assert response_headers["access-control-allow-origin"] == _ORIGIN
+
+
+@requires_guard
+async def test_allowlist_rejects_other_addresses_with_403() -> None:
+ allowed = _unique_ip()
+ app = _build_app(whitelist=[allowed], trusted_proxies=[])
+
+ status_other, headers_other, _ = await _call(
+ app, client=(_unique_ip(), 1), headers=[("origin", _ORIGIN)]
+ )
+ status_allowed, _, _ = await _call(app, client=(allowed, 1))
+
+ assert status_other == 403
+ assert headers_other["access-control-allow-origin"] == _ORIGIN
+ assert status_allowed == 200
+
+
+@requires_guard
+async def test_spoofed_forwarded_for_is_ignored_from_untrusted_peer() -> None:
+ app = _build_app(rate_limit=3, rate_limit_window=60) # trusts loopback only
+ peer = _unique_ip()
+
+ statuses = [
+ (await _call(app, client=(peer, 1), headers=[("x-forwarded-for", _unique_ip())]))[0]
+ for _ in range(4)
+ ]
+
+ assert statuses == [200, 200, 200, 429]
+
+
+@requires_guard
+async def test_forwarded_for_is_honoured_from_trusted_proxy() -> None:
+ app = _build_app(rate_limit=2, rate_limit_window=60) # trusts loopback
+ client_a, client_b = _unique_ip(), _unique_ip()
+
+ def via_proxy(client_ip: str):
+ return _call(app, client=("127.0.0.1", 1), headers=[("x-forwarded-for", client_ip)])
+
+ a = [(await via_proxy(client_a))[0] for _ in range(3)]
+ b = (await via_proxy(client_b))[0]
+
+ assert a == [200, 200, 429]
+ assert b == 200 # a different forwarded client has its own window
+
+
+@requires_guard
+async def test_attack_pattern_in_query_is_blocked_with_400() -> None:
+ app = _build_app(trusted_proxies=[])
+
+ status, _, _ = await _call(app, client=(_unique_ip(), 1), query="q=<script>alert(1)</script>")
+
+ assert status == 400
+
+
+@requires_guard
+async def test_request_body_is_not_scanned() -> None:
+ app = _build_app(trusted_proxies=[])
+ payload = b"explain <script>alert(1)</script> and ' OR 1=1 -- in my homework"
+
+ status, _, body = await _call(
+ app,
+ "/echo",
+ method="POST",
+ client=(_unique_ip(), 1),
+ headers=[("content-type", "text/plain")],
+ body=payload,
+ )
+
+ assert status == 200
+ assert json.loads(body)["body"] == payload.decode()
+
+
+@requires_guard
+async def test_streaming_chunks_are_delivered_incrementally() -> None:
+ app = _build_app(trusted_proxies=[])
+ release: list[asyncio.Event] = [asyncio.Event() for _ in range(3)]
+
+ @app.get("/stream")
+ async def stream() -> StreamingResponse:
+ async def gen():
+ for index, gate in enumerate(release):
+ yield f"chunk{index}".encode()
+ await gate.wait() # the next chunk exists only after the client saw this one
+
+ return StreamingResponse(gen(), media_type="text/event-stream")
+
+ seen: list[bytes] = []
+ first_chunk = asyncio.Event()
+
+ async def drive() -> None:
+ scope = {
+ "type": "http",
+ "asgi": {"version": "3.0"},
+ "http_version": "1.1",
+ "method": "GET",
+ "scheme": "http",
+ "path": "/stream",
+ "raw_path": b"/stream",
+ "query_string": b"",
+ "headers": [],
+ "client": (_unique_ip(), 1),
+ "server": ("testserver", 80),
+ }
+
+ async def receive() -> dict[str, Any]:
+ await asyncio.sleep(3600)
+ return {"type": "http.disconnect"}
+
+ async def send(message: dict[str, Any]) -> None:
+ if message["type"] == "http.response.body" and message.get("body"):
+ seen.append(message["body"])
+ release[len(seen) - 1].set()
+ first_chunk.set()
+
+ await app(scope, receive, send)
+
+ # A buffering middleware would never emit chunk0 (the generator is parked on
+ # its gate), so the wait below would time out instead of completing.
+ task = asyncio.create_task(drive())
+ await asyncio.wait_for(first_chunk.wait(), timeout=10)
+ await asyncio.wait_for(task, timeout=10)
+
+ assert seen == [b"chunk0", b"chunk1", b"chunk2"]
+
+
+# --- uvicorn peer handling --------------------------------------------------
+
+
+def _loaded_uvicorn_app(app: FastAPI, **kwargs: Any) -> Any:
+ import uvicorn
+
+ config = uvicorn.Config(app, log_config=None, **kwargs)
+ config.load()
+ return config.loaded_app
+
+
+@requires_guard
+async def test_uvicorn_with_no_proxy_headers_keeps_guard_identity(monkeypatch) -> None:
+ """The launch flag DeepTutor already passes keeps the socket peer as identity.
+
+ With ``FORWARDED_ALLOW_IPS=*`` and the flag in place, rotating X-Forwarded-For
+ values from one peer must not give the attacker a fresh rate-limit window.
+ """
+ monkeypatch.setenv("FORWARDED_ALLOW_IPS", "*")
+ app = _build_app(rate_limit=3, rate_limit_window=60) # guard trusts loopback only
+ served = _loaded_uvicorn_app(app, proxy_headers=False)
+ peer = _unique_ip()
+
+ statuses = [
+ (await _call(served, client=(peer, 1), headers=[("x-forwarded-for", _unique_ip())]))[0]
+ for _ in range(4)
+ ]
+
+ assert statuses == [200, 200, 200, 429]
+
+
+@requires_guard
+async def test_uvicorn_default_proxy_headers_would_defeat_the_limit(monkeypatch) -> None:
+ """Control for the test above: without the flag the same attack succeeds."""
+ monkeypatch.setenv("FORWARDED_ALLOW_IPS", "*")
+ app = _build_app(rate_limit=3, rate_limit_window=60)
+ served = _loaded_uvicorn_app(app, proxy_headers=True)
+ peer = _unique_ip()
+
+ statuses = [
+ (await _call(served, client=(peer, 1), headers=[("x-forwarded-for", _unique_ip())]))[0]
+ for _ in range(4)
+ ]
+
+ 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"
+ )
+ 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)