fastapi-guard 7.2.2__tar.gz → 7.3.1__tar.gz

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/.mike.yml

@@ -2,6 +2,8 @@ version_selector: true
 title_switch: true
 versions_file: docs/versions/versions.json
 versions:
+  - 7.3.1
+  - 7.3.0
   - 7.2.2
   - 7.2.1
   - 7.2.0
@@ -48,4 +50,4 @@ versions:
   - 0.3.2
   - latest
 aliases:
-  latest: 7.2.2
+  latest: 7.3.1

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/CHANGELOG.md

@@ -3,6 +3,34 @@ Release Notes
 
 ___
 
+v7.3.1 (2026-07-29)
+-------------------
+
+Per-route checks now resolve through unbounded mount and router nesting (v7.3.1)
+--------------------------------------------------------------------------------
+
+- **Security** — Fixes [GHSA-f2vm-w8gq-h378](https://github.com/rennf93/fastapi-guard/security/advisories/GHSA-f2vm-w8gq-h378) (CWE-287, per-route authentication bypass, CVSS 7.4). `SecurityMiddleware._match_route()` capped its recursive walk of the route tree at a hardcoded depth of 8 and silently gave up beyond it, so an endpoint mounted 9 or more `Mount` levels deep never resolved, `request.state.guard_route_id` was never set, and guard-core's route-config resolver returned `None` — which every per-route check reads as "no policy to enforce". An endpoint protected by `@require_auth` was served to any unauthenticated client, and by the same path so were `@rate_limit`, `@require_headers`, `@require_referrer`, `@custom_validation`, `@time_window`, per-route IP restrictions, and request size / content-type limits. The arbitrary depth cap is replaced by cycle detection over the descent chain — the condition it was approximating — so nesting is now unbounded while a self-nesting router still terminates.
+- **Security** — The same bypass reached a second, more common topology: routers nested two or more levels deep via `include_router`, previously recorded in 7.2.2 as "deeply-nested prefixed routers remain a known limitation". FastAPI's `_IncludedRouter` keeps its sub-routes un-prefixed and applies the combined include prefix only in `effective_candidates()`, so descending into `original_router.routes` compared a request path like `/r0/r1/secret` against a route registered as `/r1/secret` and matched nothing. Resolution now descends through `effective_candidates()` where available — falling back to the previous attribute walk on FastAPI versions without it — and unwraps the `_EffectiveRouteContext` proxies it yields. Per-route decorators consequently fire at any include depth, and also on `Mount`s and plain Starlette `Route`s registered on an included router, which `include_router(router, prefix=...)` over `router.mount(...)` had likewise left unresolved.
+- **Added** — `SecurityMiddleware` now reports a failed route match by setting `request.state.guard_route_unresolved`, which is the fail-open half of the advisory: `get_route_config()` returns `None` both when a route carries no per-route config and when resolution failed, and every per-route check collapses those two states into "nothing to enforce". Skipping checks on an undecorated route is correct and unchanged; skipping them because resolution failed is not. With guard-core >= 3.7.0 and `SecurityConfig.route_resolution_strict=True`, an unresolved request is logged, emits a `route_unresolved` event, and is blocked with `500` instead of running the pipeline with no per-route config. It defaults to `False` because a failed match is indistinguishable from a request the app does not route, so enabling it also turns unserved paths into `500`s rather than `404`s. Older guard-core ignores the new state attribute.
+- **Performance** — Traversal is bounded by marking each route and sub-route collection as visited per request scope rather than by a fixed depth, so a graph reaching the same collection along many paths is walked once instead of exponentially often. An app with two overlapping sibling mounts per level resolves a non-matching 24-level path in 0.2 ms, against 99 s for a depth-capped walk without the marking. The one graph shape that still recurses without bound manufactures fresh sub-route objects on every access, which is not constructible through public FastAPI or Starlette APIs; it raises `RecursionError` and surfaces as `500` rather than as a silently unchecked route.
+- **Fixed** — `SecurityConfig.global_behavior_rules` never ran. `_process_response()` passed `process_behavioral_rules` to guard-core's response factory but never `process_global_behavioral_rules`, and the factory only evaluates global rules when that callback is supplied, so the branch was unreachable on every request. A rule such as `return_pattern` with `threshold=2` and `action="ban"` served six matching requests without ever banning. The callback is now wired to `BehavioralProcessor.process_global_return_rules`. Global rules additionally need guard-core >= 3.7.0, which fixes the companion defect that left the behavioural tracker unresolved on decorator-only setups and made `usage_monitor` and `return_monitor` inert too.
+- **Tests** — Route resolution and end-to-end `@require_auth` enforcement are now covered at 12 nested `Mount` levels and at 12 nested prefixed routers, plus a `Mount` inside a prefixed included router, alongside the existing self-nesting-router termination test. The global-rule callback is asserted at the call site; the end-to-end banning behaviour it enables is covered in guard-core, since it cannot fire until 3.7.0 ships.
+
+___
+
+v7.3.0 (2026-07-15)
+-------------------
+
+Security pipeline assembly delegated to guard-core's check factory (v7.3.0)
+---------------------------------------------------------------------------------
+
+- **Changed** — The security pipeline is now assembled by guard-core's `build_default_pipeline()`. New guard-core checks are picked up automatically; the middleware no longer hand-lists check classes.
+- **Compatibility (behavior change from guard-core 3.5.0)** — Global IP whitelist/blacklist and country rules now apply on routes carrying per-route decorator config; previously any decorated route silently bypassed every global IP and country rule. A client outside a configured global `whitelist` now receives `403` on decorated routes that previously served it. A route-level `@ip_whitelist` now grants access only, not trust: the matched request is still rate-limited, user-agent-filtered, cloud-provider-checked, attack-scanned, and country-checked, while global `whitelist` membership still confers full trust. The IP and country aspects are evaluated independently — a route `@ip_whitelist` match does not bypass country rules; only a route `@whitelist_countries` match overrides the global country gate. See the guard-core 3.5.0 changelog for the full description and migration guidance.
+- **Tests** — The decorator test suite now exercises the rate-limiting, user-agent, and suspicious-activity decorators through the enforced security pipeline using a non-whitelisted client, with explicit coverage for the new decorated-route `403` behavior and for a route `@ip_whitelist` client still being rate-limited. Previously these tests sent requests from a globally-whitelisted address, so the security pipeline short-circuited and the decorator logic was never exercised.
+- **Requires** — `guard-core>=3.5.0` (declared as unconstrained `guard-core` in pyproject; documented here for upgrade guidance). The pipeline factory (`build_default_pipeline`) and the decorated-route IP/country enforcement this release relies on ship in guard-core 3.5.0; installing against an older guard-core fails at middleware initialization with an `ImportError`.
+
+___
+
 v7.2.2 (2026-07-01)
 -------------------
 

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi_guard
-Version: 7.2.2
+Version: 7.3.1
 Summary: Production-ready security middleware for FastAPI — IP filtering, rate limiting, penetration detection, and 20+ per-route security decorators.
 Project-URL: Homepage, https://guard-core.com
 Project-URL: Documentation, https://rennf93.github.io/fastapi-guard/latest/
@@ -271,6 +271,21 @@ Published on crates.io. **🚧 Placeholder crates — implementation in progress
 | [rocket-guard-rs](https://github.com/rennf93/rocket-guard-rs) | Rocket adapter | [![crates.io](https://img.shields.io/crates/v/rocket-guard-rs)](https://crates.io/crates/rocket-guard-rs) |
 | [tower-guard-rs](https://github.com/rennf93/tower-guard-rs) | Tower adapter | [![crates.io](https://img.shields.io/crates/v/tower-guard-rs)](https://crates.io/crates/tower-guard-rs) |
 
+### AI Coding Agents
+
+| Package | Role | PyPI |
+|---|---|---|
+| [guard-core-mcp](https://github.com/rennf93/guard-core-mcp) | MCP server — config validation, docs search, detection sandbox | [![PyPI](https://img.shields.io/pypi/v/guard-core-mcp)](https://pypi.org/project/guard-core-mcp/) |
+
+An MCP server that answers questions about FastAPI Guard from the version **installed in your project**, rather than from a model's memory of it. It validates a config against the real `SecurityConfig` model — catching silently-ignored typos like `redis_failopen` — looks up any field's type, default and description, searches the bundled docs, and runs a payload through the real detection engine to show whether it would be blocked and by which pattern.
+
+```bash
+uv add --dev guard-core-mcp
+claude mcp add guard-core -- uv run guard-core-mcp
+```
+
+Install it into the same environment as FastAPI Guard — it introspects what is actually installed there, so an isolated run (`uvx`) has nothing to read.
+
 ---
 
 ## Documentation

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/README.md

@@ -206,6 +206,21 @@ Published on crates.io. **🚧 Placeholder crates — implementation in progress
 | [rocket-guard-rs](https://github.com/rennf93/rocket-guard-rs) | Rocket adapter | [![crates.io](https://img.shields.io/crates/v/rocket-guard-rs)](https://crates.io/crates/rocket-guard-rs) |
 | [tower-guard-rs](https://github.com/rennf93/tower-guard-rs) | Tower adapter | [![crates.io](https://img.shields.io/crates/v/tower-guard-rs)](https://crates.io/crates/tower-guard-rs) |
 
+### AI Coding Agents
+
+| Package | Role | PyPI |
+|---|---|---|
+| [guard-core-mcp](https://github.com/rennf93/guard-core-mcp) | MCP server — config validation, docs search, detection sandbox | [![PyPI](https://img.shields.io/pypi/v/guard-core-mcp)](https://pypi.org/project/guard-core-mcp/) |
+
+An MCP server that answers questions about FastAPI Guard from the version **installed in your project**, rather than from a model's memory of it. It validates a config against the real `SecurityConfig` model — catching silently-ignored typos like `redis_failopen` — looks up any field's type, default and description, searches the bundled docs, and runs a payload through the real detection engine to show whether it would be blocked and by which pattern.
+
+```bash
+uv add --dev guard-core-mcp
+claude mcp add guard-core -- uv run guard-core-mcp
+```
+
+Install it into the same environment as FastAPI Guard — it introspects what is actually installed there, so an isolated run (`uvx`) has nothing to read.
+
 ---
 
 ## Documentation

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/guard/middleware.py

@@ -242,51 +242,13 @@ class SecurityMiddleware(BaseHTTPMiddleware):
         return {"enabled": True, "degraded": self.agent_degraded, **handler_stats}
 
     def _build_security_pipeline(self) -> None:
-        from guard_core.core.checks import (
-            AuthenticationCheck,
-            CloudIpRefreshCheck,
-            CloudProviderCheck,
-            CustomRequestCheck,
-            CustomValidatorsCheck,
-            EmergencyModeCheck,
-            HttpsEnforcementCheck,
-            IpSecurityCheck,
-            RateLimitCheck,
-            ReferrerCheck,
-            RequestLoggingCheck,
-            RequestSizeContentCheck,
-            RequiredHeadersCheck,
-            RouteConfigCheck,
-            SecurityCheckPipeline,
-            SuspiciousActivityCheck,
-            TimeWindowCheck,
-            UserAgentCheck,
-        )
+        from guard_core.core.checks import build_default_pipeline
 
-        checks = [
-            RouteConfigCheck(self),
-            EmergencyModeCheck(self),
-            HttpsEnforcementCheck(self),
-            RequestLoggingCheck(self),
-            RequestSizeContentCheck(self),
-            RequiredHeadersCheck(self),
-            AuthenticationCheck(self),
-            ReferrerCheck(self),
-            CustomValidatorsCheck(self),
-            TimeWindowCheck(self),
-            CloudIpRefreshCheck(self),
-            IpSecurityCheck(self),
-            CloudProviderCheck(self),
-            UserAgentCheck(self),
-            RateLimitCheck(self),
-            SuspiciousActivityCheck(self),
-            CustomRequestCheck(self),
-        ]
-
-        self.security_pipeline = SecurityCheckPipeline(checks)
+        pipeline = build_default_pipeline(self)
+        self.security_pipeline = pipeline
         self.logger.info(
-            f"Security pipeline initialized with {len(checks)} checks: "
-            f"{self.security_pipeline.get_check_names()}"
+            f"Security pipeline initialized with {len(pipeline)} "
+            f"checks: {pipeline.get_check_names()}"
         )
 
     def _configure_security_headers(self, config: SecurityConfig) -> None:
@@ -366,6 +328,9 @@ class SecurityMiddleware(BaseHTTPMiddleware):
             response_time,
             route_config,
             process_behavioral_rules=self.behavioral_processor.process_return_rules,
+            process_global_behavioral_rules=(
+                self.behavioral_processor.process_global_return_rules
+            ),
         )
         return unwrap_response(result)
 
@@ -377,30 +342,58 @@ class SecurityMiddleware(BaseHTTPMiddleware):
         routes = getattr(app, "routes", None)
         if not routes:
             return None
-        return self._match_route(routes, request.scope, 0)
+        return self._match_route(routes, request.scope, set())
 
-    def _match_route(self, routes: Any, scope: Any, depth: int) -> Any:
+    def _match_route(self, routes: Any, scope: Any, seen: set[Any]) -> Any:
         # This middleware is a BaseHTTPMiddleware, so it runs before the router
         # and scope["route"] is unset. Replicate Starlette's matching, descending
         # into sub-routers / mounts (FastAPI's include_router inserts a wrapper
         # route whose real routes are nested inside), so per-route decorator
         # config resolves for path-parameter and include_router routes, not only
         # routes flattened directly onto the app.
+        if not self._first_visit(seen, routes, scope):
+            return None
         for r in routes:
             matched, child = self._route_full_match(r, scope)
             if not matched:
                 continue
-            if hasattr(r, "endpoint"):
+            r = self._unwrap_candidate(r)
+            if getattr(r, "endpoint", None) is not None:
                 return r
-            if depth >= 8:
+            child_scope = {**scope, **child}
+            if not self._first_visit(seen, r, child_scope):
                 continue
-            found = self._match_route(
-                self._sub_routes(r), {**scope, **child}, depth + 1
-            )
+            sub_routes = self._sub_routes(r)
+            if not sub_routes:
+                return r
+            found = self._match_route(sub_routes, child_scope, seen)
             if found is not None:
                 return found
         return None
 
+    def _first_visit(self, seen: set[Any], node: Any, scope: Any) -> bool:
+        # Replaces a fixed depth cap, which silently abandoned the walk and left
+        # deeply nested routes unresolved. Marking the route and its sub-route
+        # collection stops mount cycles and keeps a graph that reaches the same
+        # collection by many paths linear rather than exponential. Ids are safe as
+        # keys: every collection walked is owned by a live app, router or route
+        # held on the call stack, so none can be freed and recycled mid-walk.
+        key = (id(node), scope.get("path"), scope.get("root_path"))
+        if key in seen:
+            return False
+        seen.add(key)
+        return True
+
+    def _unwrap_candidate(self, route: Any) -> Any:
+        # FastAPI's include machinery matches through _EffectiveRouteContext proxies
+        # that hold the prefix-corrected route; that inner route is what carries the
+        # endpoint and the sub-routes, and its child scope is already applied here.
+        return (
+            getattr(route, "starlette_route", None)
+            or getattr(route, "original_route", None)
+            or route
+        )
+
     def _route_full_match(self, route: Any, scope: Any) -> tuple[bool, Any]:
         matches = getattr(route, "matches", None)
         if matches is None:
@@ -412,6 +405,12 @@ class SecurityMiddleware(BaseHTTPMiddleware):
         return match == Match.FULL, child
 
     def _sub_routes(self, route: Any) -> Any:
+        # FastAPI's _IncludedRouter keeps sub-routes un-prefixed and only applies the
+        # combined include prefix in effective_candidates(); descending into
+        # original_router.routes instead resolves nothing past one nesting level.
+        candidates = getattr(route, "effective_candidates", None)
+        if callable(candidates):
+            return candidates()
         included = getattr(route, "original_router", None)
         mounted = getattr(route, "app", None)
         return (
@@ -431,10 +430,14 @@ class SecurityMiddleware(BaseHTTPMiddleware):
                 guard_request.state.guard_decorator = app_decorator
 
         route = self._resolve_route(request)
-        if not route or not hasattr(route, "endpoint"):
+        if not route:
+            guard_request.state.guard_route_unresolved = True
+            return
+
+        ep = getattr(route, "endpoint", None)
+        if ep is None:
             return
 
-        ep = route.endpoint
         if hasattr(ep, "_guard_route_id"):
             guard_request.state.guard_route_id = ep._guard_route_id
         if hasattr(ep, "__module__") and hasattr(ep, "__qualname__"):

{fastapi_guard-7.2.2 → fastapi_guard-7.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi_guard"
-version = "7.2.2"
+version = "7.3.1"
 description = "Production-ready security middleware for FastAPI — IP filtering, rate limiting, penetration detection, and 20+ per-route security decorators."
 authors = [
     {name = "Renzo Franceschini", email = "rennf93@users.noreply.github.com"}