DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(api): exempt loopback from the guard rate limit by default
Renn F86b3633ca21e
diff --git a/deeptutor/api/security_guard.py b/deeptutor/api/security_guard.pyindex bdfa75273..e37de8654 100644--- a/deeptutor/api/security_guard.py+++ b/deeptutor/api/security_guard.py@@ -46,6 +46,7 @@ def build_security_config(settings: dict[str, Any]) -> Any:rate_limit=settings["rate_limit"],rate_limit_window=settings["rate_limit_window"],trusted_proxies=tuple(settings["trusted_proxies"]),+ exempt_ips=tuple(settings["exempt_ips"]),whitelist=tuple(settings["whitelist"]) or None,blacklist=tuple(settings["blacklist"]),# Process-local state: each uvicorn worker keeps its own counters.@@ -75,10 +76,11 @@ def install_security_guard(app: FastAPI, settings: dict[str, Any] | None = None)app.add_middleware(PureASGISecurityMiddleware, config=config)logger.info(- "Security guard enabled: rate_limit=%s/%ss trusted_proxies=%s whitelist=%s blacklist=%s",+ "Security guard enabled: rate_limit=%s/%ss trusted_proxies=%s exempt_ips=%s whitelist=%s blacklist=%s",settings["rate_limit"],settings["rate_limit_window"],settings["trusted_proxies"],+ settings["exempt_ips"],len(settings["whitelist"]),len(settings["blacklist"]),)diff --git a/deeptutor/services/config/runtime_settings.py b/deeptutor/services/config/runtime_settings.pyindex 83131637f..283cb0cc5 100644--- a/deeptutor/services/config/runtime_settings.py+++ b/deeptutor/services/config/runtime_settings.py@@ -78,6 +78,11 @@ DEFAULT_SYSTEM_SETTINGS: dict[str, Any] = {"rate_limit": 300,"rate_limit_window": 60,"trusted_proxies": ["127.0.0.1", "::1"],+ # Skip the rate limit only. The bundled frontend hides browser+ # addresses, so its traffic arrives as loopback and would share one+ # bucket; loopback requests that carry X-Forwarded-For still resolve+ # to, and are limited as, the forwarded client.+ "exempt_ips": ["127.0.0.1", "::1"],"whitelist": [],"blacklist": [],},@@ -411,6 +416,7 @@ _SECURITY_GUARD_ENV_KEYS = (("DEEPTUTOR_GUARD_RATE_LIMIT", "rate_limit"),("DEEPTUTOR_GUARD_RATE_LIMIT_WINDOW", "rate_limit_window"),("DEEPTUTOR_GUARD_TRUSTED_PROXIES", "trusted_proxies"),+ ("DEEPTUTOR_GUARD_EXEMPT_IPS", "exempt_ips"),("DEEPTUTOR_GUARD_WHITELIST", "whitelist"),("DEEPTUTOR_GUARD_BLACKLIST", "blacklist"),)@@ -1351,6 +1357,9 @@ class RuntimeSettingsService:"trusted_proxies": _host_list(guard["trusted_proxies"])if "trusted_proxies" in guardelse list(guard_defaults["trusted_proxies"]),+ "exempt_ips": _host_list(guard["exempt_ips"])+ if "exempt_ips" in guard+ else list(guard_defaults["exempt_ips"]),"whitelist": _host_list(guard.get("whitelist")),"blacklist": _host_list(guard.get("blacklist")),},diff --git a/docs-for-user/SECURITY_GUARD.md b/docs-for-user/SECURITY_GUARD.mdindex c2a85cd90..c713f96b4 100644--- a/docs-for-user/SECURITY_GUARD.md+++ b/docs-for-user/SECURITY_GUARD.md@@ -22,7 +22,7 @@ Rejected requests return `429` (rate limit) or `403` (IP lists, ban). The guard- 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.+Two engine behaviours worth knowing, as of fastapi-guard 8.1.1 / guard-core 4.4.0 (later engine versions may change them): 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@@ -43,13 +43,14 @@ Two engine behaviours worth knowing: paths in the engine's default `exclude_path"rate_limit": 300,"rate_limit_window": 60,"trusted_proxies": ["127.0.0.1", "::1"],+ "exempt_ips": ["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`.+ 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_EXEMPT_IPS`, `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.@@ -57,7 +58,7 @@ If `enabled` is true and `fastapi-guard` is not installed, the backend refuses t### 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.+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, whereas the 10 per 60 seconds that fastapi-guard 8.1.1 uses when nothing is configured 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@@ -73,4 +74,6 @@ 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.-**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.+**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 a89d8366a..0c8f18138 100644--- a/tests/api/test_security_guard.py+++ b/tests/api/test_security_guard.py@@ -200,6 +200,7 @@ def test_settings_defaults_json_and_env_overrides(tmp_path: Path) -> None:"rate_limit": 300,"rate_limit_window": 60,"trusted_proxies": ["127.0.0.1", "::1"],+ "exempt_ips": ["127.0.0.1", "::1"],"whitelist": [],"blacklist": [],}@@ -211,6 +212,7 @@ def test_settings_defaults_json_and_env_overrides(tmp_path: Path) -> None:"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_EXEMPT_IPS": "10.1.2.3; 10.9.0.0/16","DEEPTUTOR_GUARD_WHITELIST": "203.0.113.0/24","DEEPTUTOR_GUARD_BLACKLIST": "198.51.100.9",},@@ -220,6 +222,7 @@ def test_settings_defaults_json_and_env_overrides(tmp_path: Path) -> None:"rate_limit": 50,"rate_limit_window": 10,"trusted_proxies": ["10.0.0.0/8", "192.168.1.5"],+ "exempt_ips": ["10.1.2.3", "10.9.0.0/16"],"whitelist": ["203.0.113.0/24"],"blacklist": ["198.51.100.9"],}@@ -227,11 +230,12 @@ def test_settings_defaults_json_and_env_overrides(tmp_path: Path) -> None:# 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": []}+ system["security_guard"] = {"enabled": True, "trusted_proxies": [], "exempt_ips": []}from_file.save_system(system)saved = from_file.load_system()["security_guard"]assert saved["enabled"] is Trueassert saved["trusted_proxies"] == []+ assert saved["exempt_ips"] == []assert saved["rate_limit"] == 300@@ -247,6 +251,7 @@ def test_security_config_is_stateless_and_scoped() -> None:assert config.detection_scan_body is Falseassert config.enable_agent is Falseassert config.trusted_proxies == ()+ assert config.exempt_ips == ("127.0.0.1", "::1")assert (config.rate_limit, config.rate_limit_window) == (300, 60)@@ -314,6 +319,72 @@ async def test_forwarded_for_is_honoured_from_trusted_proxy() -> None:assert b == 200 # a different forwarded client has its own window+@requires_guard+async def test_loopback_without_forwarded_for_is_not_rate_limited() -> None:+ """The bundled frontend arrives as loopback with no X-Forwarded-For."""+ app = _build_app(rate_limit=3, rate_limit_window=60)++ statuses = [(await _call(app, client=("127.0.0.1", 1)))[0] for _ in range(8)]++ assert statuses == [200] * 8+++@requires_guard+async def test_loopback_attack_query_is_still_blocked() -> None:+ app = _build_app(rate_limit=3, rate_limit_window=60)++ status, _, _ = await _call(app, client=("127.0.0.1", 1), query="q=<script>alert(1)</script>")++ assert status == 400+++@requires_guard+async def test_lan_peer_is_still_rate_limited_with_loopback_exempt() -> None:+ app = _build_app(rate_limit=3, rate_limit_window=60)+ peer = _unique_ip()++ statuses = [(await _call(app, client=(peer, 1)))[0] for _ in range(4)]++ assert statuses == [200, 200, 200, 429]+++@requires_guard+async def test_loopback_with_forwarded_for_stays_limited_per_forwarded_client() -> None:+ app = _build_app(rate_limit=3, rate_limit_window=60)+ forwarded = _unique_ip()++ statuses = [+ (await _call(app, client=("127.0.0.1", 1), headers=[("x-forwarded-for", forwarded)]))[0]+ for _ in range(4)+ ]++ assert statuses == [200, 200, 200, 429]+++@requires_guard+async def test_allowlist_without_loopback_refuses_the_bundled_frontend() -> None:+ app = _build_app(whitelist=[_unique_ip()])++ status, _, _ = await _call(app, client=("127.0.0.1", 1))++ assert status == 403+++@requires_guard+async def test_allowlist_with_loopback_admits_the_bundled_frontend() -> None:+ app = _build_app(whitelist=["127.0.0.1", "::1"])++ status, _, _ = await _call(app, client=("127.0.0.1", 1))++ assert status == 200++@requires_guard@pytest.mark.asyncioasync def test_attack_pattern_in_query_is_blocked_with_400() -> None: