cli-jaw 0.1.6 → 0.1.8

package/skills_ref/security-best-practices/references/python-fastapi-web-server-security.md

@@ -1,1036 +0,0 @@
-# FastAPI (Python) Web Security Spec (FastAPI 0.128.x, Python 3.x) ([PyPI][1])
-
-This document is designed as a **security spec** that supports:
-
-1. **Secure-by-default code generation** for new FastAPI code.
-2. **Security review / vulnerability hunting** in existing FastAPI code (passive “notice issues while working” and active “scan the repo and report findings”).
-
-It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
-
-FastAPI is commonly deployed with an ASGI server (e.g., Uvicorn) and is built on Starlette + Pydantic, so this spec covers those layers where they affect security. ([PyPI][1])
-
----
-
-## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
-
-* MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session cookies, signing keys, database URLs with credentials).
-* MUST NOT “fix” security by disabling protections (e.g., weakening auth, making CORS permissive, skipping signature checks, disabling validation, turning off TLS verification, adding `allow_origins=["*"]` with credentials).
-* MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and configuration values that justify the claim.
-* MUST treat uncertainty honestly: if a protection might exist in infrastructure (reverse proxy, WAF, CDN, service mesh), report it as “not visible in app code; verify at runtime/config”.
-* MUST treat browser controls correctly:
-
-  * CORS is **not** an auth mechanism; it only affects browsers.
-  * CSRF defenses apply when the browser automatically attaches credentials (cookies); they are usually not relevant for purely header-token APIs. ([OWASP Cheat Sheet Series][2])
-
----
-
-## 1) Operating modes
-
-### 1.1 Generation mode (default)
-
-When asked to write new FastAPI code or modify existing code:
-
-* MUST follow every **MUST** requirement in this spec.
-* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
-* MUST prefer safe-by-default APIs and proven libraries over custom security code.
-* MUST avoid introducing new risky sinks (shell execution, unsafe deserialization, dynamic eval, untrusted template rendering, unsafe file serving, unsafe redirects, arbitrary outbound fetching).
-
-### 1.2 Passive review mode (always on while editing)
-
-While working anywhere in a FastAPI repo (even if the user did not ask for a security scan):
-
-* MUST “notice” violations of this spec in touched/nearby code.
-* SHOULD mention issues as they come up, with a brief explanation + safe fix.
-
-### 1.3 Active audit mode (explicit scan request)
-
-When the user asks to “scan”, “audit”, or “hunt for vulns”:
-
-* MUST systematically search the codebase for violations of this spec.
-* MUST output findings in a structured format (see §2.3).
-
-Recommended audit order:
-
-1. App entrypoints / deployment scripts / Dockerfiles / Procfiles / Helm/terraform.
-2. ASGI server configuration (Uvicorn/Gunicorn), proxy settings, debug/reload settings.
-3. FastAPI app configuration (docs exposure, middleware, trusted hosts, CORS).
-4. Authn/Authz design (dependencies, JWT/session handling, password storage).
-5. Cookie/session usage + CSRF (if cookies are used).
-6. Input validation and output shaping (Pydantic models, mass assignment, excessive data exposure).
-7. Template rendering and XSS/SSTI (if HTML is served).
-8. File handling (uploads + downloads), StaticFiles, Range support.
-9. Injection classes (SQL, command execution, unsafe deserialization).
-10. Outbound requests (SSRF), redirect handling, WebSockets security.
-
----
-
-## 2) Definitions and review guidance
-
-### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
-
-Examples include:
-
-* Query parameters / path parameters
-* JSON bodies (including nested fields)
-* Headers (including `Host`, `Origin`, `X-Forwarded-*`)
-* Cookies (including session cookies)
-* File uploads (multipart parts)
-* WebSocket messages, query params, and headers during handshake ([Starlette][3])
-* Any data from external systems (webhooks, third-party APIs, message queues)
-* Any persisted user content (DB rows) that originated from users
-
-### 2.2 State-changing request
-
-A request is state-changing if it can create/update/delete data, change auth/session state, trigger side effects (purchase, email send, webhook send), or initiate privileged actions.
-
-### 2.3 Required audit finding format
-
-For each issue found, output:
-
-* Rule ID:
-* Severity: Critical / High / Medium / Low
-* Location: file path + function/route name + line(s)
-* Evidence: the exact code/config snippet
-* Impact: what could go wrong, who can exploit it
-* Fix: safe change (prefer minimal diff)
-* Mitigation: defense-in-depth if immediate fix is hard
-* False positive notes: what to verify if uncertain
-
----
-
-## 3) Secure baseline: minimum production configuration (MUST in production)
-
-This is the smallest “production baseline” that prevents common FastAPI/ASGI misconfigurations.
-
-Baseline goals:
-
-* No debug tracebacks or auto-reload in production. ([PyPI][4])
-* Run under a production ASGI server configuration (workers, timeouts, resource controls). ([PyPI][4])
-* Host header validation enabled (TrustedHostMiddleware or equivalent). ([PyPI][5])
-* CORS disabled unless explicitly needed; if enabled, it is strict and least-privilege. ([OWASP Cheat Sheet Series][6])
-* Auth is enforced consistently via dependencies (no “oops, forgot auth on this route”). ([FastAPI][7])
-* If cookies/sessions are used, cookie flags are secure and CSRF is addressed. ([OWASP Cheat Sheet Series][8])
-* Request size limits and multipart limits exist at the edge and are validated in app as needed (to mitigate memory/CPU DoS). ([advisories.gitlab.com][9])
-* Dependencies are patched promptly, especially Starlette/python-multipart (multiple DoS and traversal advisories exist historically). ([advisories.gitlab.com][10])
-
----
-
-## 4) Rules (generation + audit)
-
-Each rule contains: required practice, insecure patterns, detection hints, and remediation.
-
-### FASTAPI-DEPLOY-001: Do not use auto-reload / dev-only server modes in production
-
-Severity: High (if production)
-
-Required:
-
-* MUST NOT run production using auto-reload/watch mode (e.g., Uvicorn reload).
-* MUST run with a production process model (e.g., multiple workers where appropriate) and stable server settings. ([PyPI][4])
-
-Insecure patterns:
-
-* `uvicorn ... --reload` (or equivalent “reload=True” configs) in production entrypoints.
-* Docker/Procfile/systemd commands that run with `--reload` in production.
-
-Detection hints:
-
-* Search for `--reload`, `reload=True`, `watchfiles`, `fastapi dev`, “development” run scripts.
-* Check Docker CMD/ENTRYPOINT, Procfile, systemd units, shell scripts.
-
-Fix:
-
-* Remove reload in production; run Uvicorn/Gunicorn with stable settings and explicit worker configuration. ([PyPI][4])
-
-Note:
-
-* Reload is fine for local development. Only flag when it is clearly used as a production entrypoint.
-
----
-
-### FASTAPI-DEPLOY-002: Debug mode MUST be disabled in production
-
-Severity: Critical
-
-Required:
-
-* MUST NOT enable debug tracebacks in production (FastAPI/Starlette debug mode can expose sensitive internals and make some exploit chains easier). ([PyPI][5])
-* MUST treat any configuration that returns detailed stack traces to clients as sensitive.
-
-Insecure patterns:
-
-* `app = FastAPI(debug=True)` (or Starlette `debug=True`), or equivalent environment toggles enabling debug in production. ([PyPI][5])
-* Server/log config that exposes tracebacks to end users.
-
-Detection hints:
-
-* Search for `debug=True`, `DEBUG = True`, environment flags mapped to debug.
-* Review exception middleware and error handler setup.
-
-Fix:
-
-* Ensure debug is only enabled in local dev/test.
-* Return generic error responses to clients; log details internally.
-
----
-
-### FASTAPI-OPENAPI-001: OpenAPI and interactive docs MUST be disabled or protected in production
-
-Severity: Medium (can be High in sensitive/internal apps)
-
-Required:
-
-* SHOULD disable `/docs`, `/redoc`, and `/openapi.json` in production for public-facing services unless there is an explicit business need.
-* If enabled, MUST protect them (e.g., auth, network allowlists, or internal-only routing).
-* MUST NOT assume “security through obscurity”; treat docs exposure as an information disclosure amplifier.
-
-Insecure patterns:
-
-* Publicly reachable `/docs` and `/openapi.json` for internal/admin APIs.
-* Docs enabled on the same hostname as production without access control.
-
-Detection hints:
-
-* Look for `FastAPI(docs_url=..., redoc_url=..., openapi_url=...)` or defaults.
-* Check reverse proxy routing and allowlists.
-
-Fix:
-
-* Disable docs endpoints in prod (`docs_url=None`, `redoc_url=None`, `openapi_url=None`) or restrict access at the edge.
-
----
-
-### FASTAPI-AUTH-001: Authentication MUST be explicit and consistently enforced via dependencies
-
-Severity: High
-
-Required:
-
-* MUST implement authentication as a dependency (or router-level dependency) so that protected endpoints cannot “forget” auth.
-* MUST default to “deny” for privileged routers/endpoints; explicitly mark truly public routes.
-* SHOULD centralize auth enforcement at router boundaries (e.g., protected `APIRouter` for authenticated endpoints). ([FastAPI][7])
-
-Insecure patterns:
-
-* Per-route ad-hoc auth checks scattered through handlers (easy to miss).
-* A mix of protected/unprotected endpoints with no clear policy.
-
-Detection hints:
-
-* Identify routers and endpoints; check whether protected ones include `Depends(...)`/`Security(...)`.
-* Search for patterns like `if user is None: raise ...` inside handlers (instead of dependencies).
-
-Fix:
-
-* Move authentication into a dependency and attach it to the router/endpoint consistently using `Depends()`/`Security()`. ([FastAPI][7])
-
----
-
-### FASTAPI-AUTH-002: Use standard auth transports; avoid secrets in URLs
-
-Severity: High
-
-Required:
-
-* SHOULD use the `Authorization: Bearer <token>` header for token auth, not query parameters. ([FastAPI][11])
-* MUST NOT place secrets (tokens, reset links containing long-lived secrets, API keys) in query strings when avoidable.
-
-Insecure patterns:
-
-* `?token=...`, `?api_key=...`, `?auth=...` used for primary auth.
-* Long-lived access tokens embedded in URLs (leak via logs, referrers, caches).
-
-Detection hints:
-
-* Search for parameter names like `token`, `api_key`, `key`, `secret`, `password`.
-* Look for security schemes that use query API keys without justification.
-
-Fix:
-
-* Move tokens to Authorization headers; rotate/shorten lifetimes; use POST bodies for sensitive values.
-
----
-
-### FASTAPI-AUTH-003: Password storage MUST be strongly hashed; never store plaintext passwords
-
-Severity: Critical
-
-Required:
-
-* MUST store passwords using a strong, slow password hashing scheme (e.g., Argon2id, bcrypt).
-* MUST NOT store plaintext passwords, or reversible encryption as the primary protection.
-* SHOULD use established libraries for hashing and verification (do not roll your own).
-
-Insecure patterns:
-
-* Storing plaintext passwords in DB.
-* Using fast hashes (e.g., SHA256) without a proper password hashing KDF.
-* Returning password hashes in API responses.
-
-Detection hints:
-
-* Search for `password=` persisted fields, and look for `hashlib.md5/sha1/sha256` usage on passwords.
-* Inspect response models for password/hash fields.
-
-Fix:
-
-* Migrate to a proper password hashing library; add a re-hash-on-login upgrade path.
-
----
-
-### FASTAPI-AUTH-004: JWT validation MUST be strict; JWTs MUST NOT carry secrets
-
-Severity: High
-
-Required:
-
-* MUST validate JWT signature and enforce an algorithm allowlist.
-* MUST validate standard claims appropriate to your system (at least `exp`; typically also `iss`/`aud` if multi-service or multi-tenant).
-* MUST treat JWT contents as readable by the client; do not put secrets in JWT payloads. ([FastAPI][12])
-
-Insecure patterns:
-
-* `jwt.decode(..., options={"verify_signature": False})` or equivalent.
-* Accepting `alg=none` / algorithm confusion.
-* Using JWT payload to store sensitive secrets (API keys, passwords).
-
-Detection hints:
-
-* Search for `jwt.decode`, `python-jose`, `PyJWT`, `verify_signature`.
-* Check for missing exp validation or long expirations.
-
-Fix:
-
-* Enforce strict validation (signature, allowed algorithms, exp, and any required issuer/audience constraints).
-* Store only identifiers/claims you are comfortable exposing to the client. ([FastAPI][12])
-
----
-
-### FASTAPI-AUTHZ-001: Authorization MUST be enforced per-object and per-property
-
-Severity: High
-
-Required:
-
-* MUST perform object-level authorization whenever accessing a resource by user-controlled identifier (ID in path/query/body).
-* MUST perform property-level authorization and response shaping to prevent “excessive data exposure” (e.g., admin-only fields). ([OWASP Foundation][13])
-
-Insecure patterns:
-
-* `GET /users/{id}` returns user record without verifying caller can access that `id`.
-* Response models include internal fields (roles, permissions, billing data, password hashes).
-
-Detection hints:
-
-* Enumerate endpoints that accept IDs; trace whether an authz check is performed.
-* Compare response models for public vs internal fields.
-
-Fix:
-
-* Add object-level checks (ownership, ACLs, tenant boundaries).
-* Use dedicated response models that include only allowed fields.
-
----
-
-### FASTAPI-SESS-001: If using cookie-based sessions and TLS, cookie attributes MUST be secure in production
-
-Severity: High (only if TLS is enabled)
-
-Required (production, HTTPS):
-
-* MUST set session cookies to be sent only over HTTPS (secure). IMPORTANT NOTE: Only set `Secure` in production environment when TLS is configured. When running in a local dev environment over HTTP, do not set `Secure` property on cookies. You should do this conditionally based on if the app is running in production mode. You should also include a property like `SESSION_COOKIE_SECURE` which can be used to disable `Secure` cookies when testing over HTTP.
-* MUST set HttpOnly for session cookies (not accessible to JS).
-* SHOULD use `SameSite=Lax` (or `Strict` if UX allows); if you require cross-site cookies, document the CSRF implications and add compensating controls. ([OWASP Cheat Sheet Series][8])
-* If using Starlette `SessionMiddleware`, MUST set `https_only=True` in production and choose an appropriate `same_site`. ([PyPI][5])
-
-Insecure patterns:
-
-* Session cookies without Secure/HttpOnly.
-* `SameSite=None` cookies used for authenticated state-changing endpoints without CSRF protections.
-
-Detection hints:
-
-* Search for `SessionMiddleware(` and inspect parameters like `https_only`, `same_site`.
-* Search for `set_cookie(` usage and cookie flags.
-
-Fix:
-
-* Set secure cookie attributes; prefer short lifetimes for high-privilege sessions. ([OWASP Cheat Sheet Series][8])
-
----
-
-### FASTAPI-SESS-002: Do not store sensitive secrets in signed session cookies
-
-Severity: High
-
-Required:
-
-* MUST assume cookie-based session data is readable by the client (signed ≠ encrypted); do not store secrets/PII unless encrypted server-side.
-* Store only opaque identifiers (e.g., session ID) or non-sensitive state in the cookie; store sensitive session state server-side. ([OWASP Cheat Sheet Series][8])
-
-Insecure patterns:
-
-* Storing access tokens, refresh tokens, or PII directly in cookie session payloads.
-* Treating “signed cookies” as confidential storage.
-
-Detection hints:
-
-* Search for `request.session[...] =` or `session[...] =`-equivalent patterns; identify what is stored.
-* Identify use of `SessionMiddleware` or other cookie session mechanisms.
-
-Fix:
-
-* Move sensitive values to server-side storage; keep cookie minimal.
-
----
-
-### FASTAPI-CSRF-001: Cookie-authenticated state-changing requests MUST be CSRF-protected
-
-Severity: High
-
-Note: This only applies if using cookie based auth. If the application uses header or token based auth such as Authorization header, then CSRF is not an issue.
-
-Required:
-
-* MUST protect all state-changing endpoints (POST/PUT/PATCH/DELETE) that rely on cookies for authentication.
-* SHOULD use a proven CSRF approach (synchronizer token pattern, or well-reviewed middleware) rather than rolling your own. ([OWASP Cheat Sheet Series][2])
-* MAY add defense-in-depth (Origin/Referer checks, SameSite cookies, Fetch Metadata), but tokens are the primary defense for cookie-authenticated apps. ([OWASP Cheat Sheet Series][2])
-* IMPORTANT NOTE: If cookies are not used for auth (auth is via `Authorization` header), CSRF is usually not applicable. ([FastAPI][11])
-
-Insecure patterns:
-
-* Cookie-authenticated endpoints that change state with no CSRF validation.
-* Using GET for state-changing actions (amplifies CSRF risk).
-
-Detection hints:
-
-* Enumerate routes with methods other than GET; identify whether cookies are used for auth.
-* Look for CSRF token generation/verification or middleware.
-
-Fix:
-
-* Add CSRF tokens (and validate them) on state-changing actions when cookie auth is in use. ([OWASP Cheat Sheet Series][2])
-
----
-
-### FASTAPI-VALID-001: Request parsing and validation MUST be schema-driven; prevent mass assignment
-
-Severity: Medium (especially for APIs that write to DB)
-
-Required:
-
-* SHOULD use Pydantic models for request bodies instead of accepting arbitrary `dict`/`Any`.
-* SHOULD configure models to reject unexpected fields where appropriate (prevents “mass assignment” style bugs).
-* MUST validate and normalize identifiers (IDs, email, URLs) before using them for access control or side effects. ([OWASP Cheat Sheet Series][14])
-
-Insecure patterns:
-
-* `payload = await request.json()` followed by `Model(**payload)` or direct DB writes with `payload` (no allowlist).
-* Models that silently accept unknown fields for write endpoints.
-
-Detection hints:
-
-* Search for `await request.json()`, `request.body()`, `dict`-typed bodies, `Any`-typed bodies.
-* Look for endpoints that do `db.update(**payload)` or `Model(**payload)` with unfiltered input.
-
-Fix:
-
-* Use explicit Pydantic models with allowlisted fields; reject extras for write endpoints. ([OWASP Cheat Sheet Series][14])
-
----
-
-### FASTAPI-RESP-001: Prevent excessive data exposure via response models and explicit serialization
-
-Severity: Medium
-
-Required:
-
-* MUST define response models that include only intended fields (especially for user objects, auth-related objects, billing objects).
-* SHOULD use separate models for “create input”, “db/internal”, and “public output” to avoid leaking sensitive fields. ([FastAPI][15])
-
-Insecure patterns:
-
-* Returning ORM objects or dicts that include internal columns.
-* Reusing “DB model” as the response model (includes `password_hash`, `is_admin`, etc).
-
-Detection hints:
-
-* Look for endpoints that `return user` where `user` is an ORM instance.
-* Check for `response_model` omissions on endpoints that return sensitive resources.
-
-Fix:
-
-* Add explicit response models; create “public” schemas that exclude sensitive fields. ([FastAPI][15])
-
----
-
-### FASTAPI-XSS-001: Prevent reflected/stored XSS in HTML responses and templates
-
-Severity: High (if the service serves HTML)
-
-Required:
-
-* MUST use templating with auto-escaping enabled for HTML.
-* MUST NOT mark untrusted content as safe (no unsafe “raw HTML” rendering of user-controlled data).
-* SHOULD deploy a CSP when serving HTML that includes any user content. ([OWASP Cheat Sheet Series][16])
-
-Insecure patterns:
-
-* Rendering user content directly into HTML without escaping/sanitization.
-* Disabling auto-escaping or using “raw HTML” features without sanitization.
-
-Detection hints:
-
-* Search for template rendering and string concatenation that builds HTML.
-* Review templates for “unsafe” filters/constructs and unquoted attributes.
-
-Fix:
-
-* Keep auto-escaping on; sanitize user HTML only if absolutely required using a trusted sanitizer; add CSP. ([OWASP Cheat Sheet Series][16])
-
-Note:
-
-* If the app is a pure JSON API, XSS is usually a client/app concern, but error pages/docs pages might still render HTML.
-
----
-
-### FASTAPI-SSTI-001: Never render untrusted templates (Server-Side Template Injection)
-
-Severity: Critical
-
-Required:
-
-* MUST NOT render templates that contain user-controlled template syntax.
-* MUST treat “template-from-string” rendering as dangerous if influenced by untrusted input.
-* If untrusted templates are absolutely required (rare, high-risk):
-
-  * MUST use a sandboxed templating approach and restrict capabilities.
-  * MUST assume sandbox escapes are possible; add isolation and strict allowlists. ([OWASP Foundation][17])
-
-Insecure patterns:
-
-* Rendering templates loaded from user input or DB via a normal Jinja environment.
-* Building templates dynamically using user-controlled strings.
-
-Detection hints:
-
-* Grep for Jinja `Environment.from_string`, `Template(...)`, or similar.
-* Trace origin of template string (request, DB, uploads, admin panels).
-
-Fix:
-
-* Replace with non-executable templating (simple string substitution).
-* If truly needed, use Jinja’s sandbox environment plus strong isolation. ([jinja.palletsprojects.com][18])
-
----
-
-### FASTAPI-HEADERS-001: Set essential security headers (in app or at the edge)
-
-Severity: Medium
-
-Required (typical API/web app):
-
-* SHOULD set:
-
-  * `X-Content-Type-Options: nosniff`
-  * Clickjacking protection (`X-Frame-Options` and/or CSP `frame-ancestors`) if HTML is served
-  * `Referrer-Policy` and `Permissions-Policy` as appropriate
-
-NOTE:
-
-* Headers may be set by a proxy/CDN. If not visible in app code, flag as “verify at edge”. ([OWASP Cheat Sheet Series][6])
-
-Insecure patterns:
-
-* No security headers anywhere (app or edge) for apps serving HTML or sensitive APIs.
-
-Detection hints:
-
-* Search for middleware that sets headers; check reverse proxy config.
-
-Fix:
-
-* Set headers centrally (middleware) or via reverse proxy/CDN.
-
----
-
-### FASTAPI-CORS-001: CORS MUST be explicit and least-privilege
-
-Severity: Medium (High if misconfigured with credentials)
-
-Required:
-
-* If CORS is not needed, MUST keep it disabled.
-* If CORS is needed:
-
-  * MUST allowlist trusted origins (do not reflect arbitrary origins).
-  * MUST NOT combine credentialed requests with wildcard origins (this is unsafe and commonly rejected by compliant middleware). ([OWASP Cheat Sheet Series][6])
-  * SHOULD restrict allowed methods and headers.
-
-Insecure patterns:
-
-* `allow_origins=["*"]` together with `allow_credentials=True`.
-* Reflecting `Origin` without validation.
-* `allow_origin_regex=".*"` used broadly.
-
-Detection hints:
-
-* Search for `CORSMiddleware` configuration.
-* Look for `allow_origins=["*"]`, `allow_credentials=True`, `allow_origin_regex`.
-
-Fix:
-
-* Use an explicit origin allowlist and minimal methods/headers; keep credentials off unless required. ([OWASP Cheat Sheet Series][6])
-
----
-
-### FASTAPI-HOST-001: Host header MUST be validated in production
-
-Severity: Low
-
-Required:
-
-* SHOULD use `TrustedHostMiddleware` (or equivalent at edge) to restrict accepted Host values. ([PyPI][5])
-* MUST NOT trust the `Host` header for security-sensitive decisions without validation.
-
-Insecure patterns:
-
-* No Host validation while generating external URLs (password reset links, callback URLs) from request host.
-* Allowing arbitrary Host headers in apps behind permissive proxies.
-
-Detection hints:
-
-* Search for `TrustedHostMiddleware` usage.
-* Search for logic that uses `request.url`, `request.base_url`, or host-derived values to build external URLs.
-
-Fix:
-
-* Configure a strict allowed-hosts list in production; enforce at edge too if possible.
-
----
-
-### FASTAPI-PROXY-001: Reverse proxy trust MUST be configured correctly
-
-Severity: High (when behind a proxy)
-
-Required:
-
-* If behind a reverse proxy, MUST configure forwarded-header trust correctly.
-* MUST NOT blindly trust `X-Forwarded-*` headers from the open internet.
-* If using Uvicorn proxy header support, MUST restrict which IPs are allowed to provide forwarded headers. ([PyPI][4])
-
-Insecure patterns:
-
-* Enabling proxy headers broadly without restricting trusted proxy IPs.
-* Using forwarded headers to decide “is secure” / “is internal” / “client IP” without proper trust boundaries.
-
-Detection hints:
-
-* Search for `--proxy-headers`, `--forwarded-allow-ips`, or equivalent config.
-* Search for security-sensitive use of `request.client.host`, `request.url.scheme`, `request.headers["x-forwarded-for"]`.
-
-Fix:
-
-* Configure Uvicorn with proxy headers only when behind a known proxy, and restrict `forwarded_allow_ips` to that proxy. ([PyPI][4])
-* Keep Host allowlisting in place even behind proxies.
-
----
-
-### FASTAPI-LIMITS-001: Request and multipart limits MUST be enforced to prevent DoS
-
-Severity: Low
-
-Required:
-
-* MUST enforce request size limits at the edge (reverse proxy/load balancer) and validate in app where needed.
-* MUST apply special scrutiny to multipart/form-data handling; historical vulnerabilities include unbounded buffering and DoS vectors. ([advisories.gitlab.com][9])
-* SHOULD rate limit and/or add per-IP/per-user throttles for expensive endpoints.
-
-Insecure patterns:
-
-* Accepting arbitrarily large JSON bodies or multipart forms.
-* Parsing multipart forms without size/field-count controls.
-
-Detection hints:
-
-* Identify file upload endpoints and `multipart/form-data` usage.
-* Look for missing proxy-level limits (nginx `client_max_body_size`, ALB limits, etc.) and missing app-level checks.
-
-Fix:
-
-* Enforce strict body limits and multipart constraints; keep Starlette and python-multipart updated to patched versions. ([advisories.gitlab.com][9])
-
----
-
-### FASTAPI-FILES-001: Prevent path traversal and unsafe static file exposure
-
-Severity: High
-
-Required:
-
-* MUST NOT pass user-controlled file paths to `FileResponse`/filesystem calls without strict validation and safe base directories.
-* If using `StaticFiles`, MUST keep Starlette updated and understand the security history (path traversal advisory exists for older versions). ([advisories.gitlab.com][10])
-* MUST NOT serve user uploads as executable/active content (especially HTML/JS) from a static root without safe handling.
-
-Insecure patterns:
-
-* `FileResponse(request.query_params["path"])`
-* Mounting `StaticFiles(directory="uploads")` where uploads include HTML/JS/SVG and are served inline.
-
-Detection hints:
-
-* Search for `FileResponse(`, `StaticFiles(`, `open(` in routes.
-* Trace whether the path originates from untrusted input.
-
-Fix:
-
-* Use opaque IDs for files; map IDs to server-side stored paths.
-* Serve untrusted content as attachment downloads where appropriate.
-
----
-
-### FASTAPI-FILES-002: Mitigate Range-header DoS on file-serving endpoints
-
-Severity: Low (if affected versions and file serving is enabled)
-
-Required:
-
-* MUST keep Starlette patched against known file-serving DoS issues if using `FileResponse`/`StaticFiles`.
-* MUST treat unusual `Range` header handling and file serving as a DoS surface. ([advisories.gitlab.com][19])
-
-Insecure patterns:
-
-* Serving large files with vulnerable Starlette versions.
-* No rate limiting / CDN shielding for file endpoints.
-
-Detection hints:
-
-* Identify Starlette version; if in affected range, flag.
-* Find uses of `FileResponse` and `StaticFiles`.
-
-Fix:
-
-* Upgrade Starlette to a fixed version per advisory guidance. ([advisories.gitlab.com][19])
-* Add edge caching/rate limiting for file endpoints where appropriate.
-
----
-
-### FASTAPI-UPLOAD-001: File uploads MUST be validated, stored safely, and served safely
-
-Severity: Medium
-
-Required:
-
-* MUST enforce upload size limits (app + edge).
-* MUST validate file type using allowlists and content checks (not only extension). ([OWASP Cheat Sheet Series][20])
-* SHOULD generate server-side filenames (random IDs) and avoid trusting original names.
-* MUST serve potentially active formats safely (download attachment) unless explicitly intended.
-
-Insecure patterns:
-
-* Accepting arbitrary file types and serving them back inline.
-* Using user-supplied filename as storage path.
-
-Detection hints:
-
-* Look for upload handlers and where/how files are written.
-* Look for direct exposure of upload directories.
-
-Fix:
-
-* Implement allowlist validation + safe storage + safe serving; add scanning/quarantine if applicable. ([OWASP Cheat Sheet Series][20])
-
----
-
-### FASTAPI-INJECT-001: Prevent SQL injection (use parameterized queries / ORM)
-
-Severity: High
-
-Required:
-
-* MUST use parameterized queries or an ORM that parameterizes under the hood.
-* MUST NOT build SQL by string concatenation / f-strings with untrusted input. ([OWASP Cheat Sheet Series][21])
-
-Insecure patterns:
-
-* `f"SELECT ... WHERE id={user_id}"`
-* `"... WHERE name = '%s'" % user_input`
-
-Detection hints:
-
-* Grep for SQL keywords in Python strings near `.execute(...)`.
-* Trace untrusted data into DB calls.
-
-Fix:
-
-* Replace with parameterized queries / ORM query APIs; validate types before querying. ([OWASP Cheat Sheet Series][21])
-
----
-
-### FASTAPI-INJECT-002: Prevent OS command injection
-
-Severity: Critical to High (depends on exposure)
-
-Required:
-
-* MUST avoid executing shell commands with untrusted input.
-* If subprocess is necessary:
-
-  * MUST pass args as a list (not a string)
-  * MUST NOT use `shell=True` with attacker-influenced strings
-  * SHOULD use strict allowlists for any variable component ([OWASP Cheat Sheet Series][22])
-
-Insecure patterns:
-
-* `os.system(user_input)`
-* `subprocess.run(f"cmd {user}", shell=True)`
-* Passing user strings into `bash -c`, `sh -c`, PowerShell, etc.
-
-Detection hints:
-
-* Search for `os.system`, `subprocess`, `Popen`, `shell=True`.
-* Trace data from request/DB into these calls.
-
-Fix:
-
-* Use library APIs instead of shell commands.
-* If unavoidable, hard-code the command and allowlist validated parameters; use `--` separator where supported. ([OWASP Cheat Sheet Series][22])
-
----
-
-### FASTAPI-SSRF-001: Prevent server-side request forgery (SSRF) in outbound HTTP
-
-Severity: Medium (can be High in cloud/VPC environments)
-
-- Note: For small stand alone projects this is less important. It is most important when deploying into an LAN or with other services listening on the same server.
-
-Required:
-
-* MUST treat outbound requests to user-provided URLs as high risk.
-* SHOULD validate and restrict destinations (allowlist hosts/domains) for any user-influenced URL fetch.
-* SHOULD block access to localhost/private IP ranges/link-local and cloud metadata endpoints.
-* MUST restrict protocols to http/https.
-* SHOULD set timeouts and carefully control redirects. ([OWASP Cheat Sheet Series][23])
-
-Insecure patterns:
-
-* `httpx.get(request.query_params["url"])`
-* “URL preview/import/webhook tester” features that accept arbitrary URLs.
-
-Detection hints:
-
-* Search for `requests`, `httpx`, `urllib`, `aiohttp` calls with URLs derived from requests/DB.
-* Identify endpoints named `fetch`, `preview`, `proxy`, `webhook`, `import`.
-
-Fix:
-
-* Implement strict URL parsing + allowlists; add egress controls; set short timeouts; disable redirects if not required. ([OWASP Cheat Sheet Series][23])
-
----
-
-### FASTAPI-REDIRECT-001: Prevent open redirects
-
-Severity: Low
-
-Required:
-
-* MUST validate redirect targets derived from untrusted input (`next`, `redirect`, `return_to`).
-* SHOULD prefer redirecting only to same-site relative paths or an allowlist of domains. ([OWASP Cheat Sheet Series][24])
-
-Insecure patterns:
-
-* Returning `RedirectResponse(next)` where `next` is user-controlled with no validation.
-
-Detection hints:
-
-* Search for `RedirectResponse(` or redirect logic and examine the source of the target.
-
-Fix:
-
-* Allow only relative paths or allowlisted domains; fall back to a safe default. ([OWASP Cheat Sheet Series][24])
-
----
-
-### FASTAPI-WS-001: WebSocket endpoints MUST be authenticated and protected against cross-site abuse
-
-Severity: Medium to High (depends on data/privilege)
-
-Required:
-
-* MUST authenticate WebSocket connections for any non-public channel (WebSockets don’t inherently provide auth). ([OWASP Cheat Sheet Series][25])
-* SHOULD enforce origin/CSRF-like protections appropriate for browser-based WebSocket clients (Origin validation is a common control).
-* SHOULD rate limit message frequency and connection attempts; close idle/abusive connections.
-
-Insecure patterns:
-
-* `@app.websocket(...)` accepts and trusts the connection with no auth check.
-* Using query-string tokens for auth without considering leakage/rotation.
-
-Detection hints:
-
-* Search for `@app.websocket` / `websocket_endpoint` and inspect whether auth is performed before accepting sensitive operations.
-* Review origin checks, token parsing, and per-connection authorization.
-
-Fix:
-
-* Require authentication during handshake (e.g., a token or session) and enforce authorization for actions/messages.
-* Validate Origin for browser-based clients where appropriate; apply rate limits and timeouts. ([OWASP Cheat Sheet Series][25])
-
----
-
-### FASTAPI-SUPPLY-001: Dependency and patch hygiene (focus on security-relevant deps)
-
-Severity: Low
-
-Required:
-
-* SHOULD pin and regularly update security-critical dependencies (FastAPI, Starlette, Uvicorn, Pydantic, python-multipart, auth/JWT libs).
-* MUST respond to known security advisories promptly.
-* MUST treat file serving and multipart parsing dependencies as security-sensitive due to historical CVEs. ([advisories.gitlab.com][10])
-
-Audit focus examples (historical):
-
-* Starlette StaticFiles path traversal (fixed in 0.27.0). ([advisories.gitlab.com][10])
-* Starlette multipart/form-data DoS (fixed in 0.40.0). ([advisories.gitlab.com][9])
-* Starlette FileResponse Range header DoS (fixed in 0.49.1). ([advisories.gitlab.com][19])
-
-Detection hints:
-
-* Check `requirements.txt`, lockfiles, container images, and runtime environments for actual installed versions.
-* Map file upload/file serving features to dependency versions.
-
-Fix:
-
-* Upgrade to patched versions per advisories; add regression tests around affected behavior.
-
----
-
-## 5) Practical scanning heuristics (how to “hunt”)
-
-When actively scanning, use these high-signal patterns:
-
-* Dev server / debug:
-
-  * `--reload`, `reload=True`, `debug=True`, `FastAPI(debug=True)` ([PyPI][4])
-* OpenAPI/docs exposure:
-
-  * `/docs`, `/redoc`, `/openapi.json`, `docs_url=`, `openapi_url=`
-* Auth enforcement gaps:
-
-  * Endpoints missing `Depends()`/`Security()` where expected; routers without a consistent dependency boundary ([FastAPI][7])
-  * Tokens in query params (`token=`, `api_key=`, `key=`) ([FastAPI][11])
-* Session/cookies + CSRF:
-
-  * `SessionMiddleware(` and cookie flags (`https_only`, `same_site`) ([PyPI][5])
-  * POST/PUT/PATCH/DELETE handlers using cookie auth with no CSRF checks ([OWASP Cheat Sheet Series][2])
-* Input validation & mass assignment:
-
-  * `await request.json()` and direct DB writes from dicts; models accepting extra fields ([OWASP Cheat Sheet Series][14])
-* Excessive data exposure:
-
-  * Returning ORM objects or dicts without `response_model`; responses containing password/role/internal fields ([FastAPI][15])
-* CORS:
-
-  * `CORSMiddleware` with `allow_origins=["*"]`, `allow_origin_regex=".*"`, `allow_credentials=True` ([OWASP Cheat Sheet Series][6])
-* Files:
-
-  * `FileResponse(` with user-controlled paths; `StaticFiles(` exposing uploads ([advisories.gitlab.com][10])
-* Uploads / multipart:
-
-  * `multipart/form-data` endpoints with no size/field constraints; outdated Starlette/python-multipart ([advisories.gitlab.com][9])
-* Injection:
-
-  * SQL strings with f-strings/concatenation into `.execute(...)` ([OWASP Cheat Sheet Series][21])
-  * `subprocess.*`, `shell=True`, `os.system` ([OWASP Cheat Sheet Series][22])
-* SSRF:
-
-  * `httpx.get/post` or `requests.*` with URL from request/DB, no allowlist/timeouts ([OWASP Cheat Sheet Series][23])
-* Redirect:
-
-  * `RedirectResponse(next)` with no validation ([OWASP Cheat Sheet Series][24])
-* WebSockets:
-
-  * `@app.websocket` handlers without auth/origin checks; use of `ws://` in prod configs ([FastAPI][27])
-
-Always try to confirm:
-
-* data origin (untrusted vs trusted)
-* sink type (SQL/subprocess/files/template/http/redirect/ws)
-* protective controls present (validation, allowlists, middleware, edge controls)
-* installed dependency versions vs vulnerable ranges ([advisories.gitlab.com][10])
-
----
-
-## 6) Sources (accessed 2026-01-27)
-
-Primary framework documentation:
-
-* FastAPI (PyPI metadata, versioning) — `https://pypi.org/project/fastapi/` ([PyPI][1])
-* FastAPI docs: Security “First Steps” (Authorization Bearer header conventions) — `https://fastapi.tiangolo.com/tutorial/security/first-steps/` ([FastAPI][11])
-* FastAPI reference: Dependencies (`Depends`, `Security`) — `https://fastapi.tiangolo.com/reference/dependencies/` ([FastAPI][7])
-* FastAPI reference: APIRouter (router-level dependencies) — `https://fastapi.tiangolo.com/reference/apirouter/` ([FastAPI][28])
-* FastAPI docs: WebSockets — `https://fastapi.tiangolo.com/advanced/websockets/` ([FastAPI][27])
-
-ASGI/server stack documentation:
-
-* Starlette (PyPI, general capabilities) — `https://pypi.org/project/starlette/` ([PyPI][5])
-* Starlette docs: WebSockets — `https://starlette.dev/websockets/` ([Starlette][3])
-* Uvicorn (PyPI metadata) — `https://pypi.org/project/uvicorn/` ([PyPI][4])
-* Pydantic docs (v2.12.x) — `https://docs.pydantic.dev/latest/` ([Pydantic][29])
-
-Security standards and cheat sheets:
-
-* OWASP Cheat Sheet Series: Session Management — `https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][8])
-* OWASP Cheat Sheet Series: CSRF Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][2])
-* OWASP Cheat Sheet Series: XSS Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][16])
-* OWASP Cheat Sheet Series: Mass Assignment — `https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][14])
-* OWASP API Security Top 10 (2023) — `https://owasp.org/API-Security/editions/2023/en/0x11-t10/` ([OWASP Foundation][13])
-* OWASP Cheat Sheet Series: SQL Injection Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][21])
-* OWASP Cheat Sheet Series: OS Command Injection Defense — `https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][22])
-* OWASP Cheat Sheet Series: SSRF Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][23])
-* OWASP Cheat Sheet Series: File Upload — `https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][20])
-* OWASP Cheat Sheet Series: Unvalidated Redirects and Forwards — `https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][24])
-* OWASP Cheat Sheet Series: HTTP Security Response Headers — `https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][6])
-* OWASP Cheat Sheet Series: WebSocket Security — `https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][25])
-* OWASP WSTG: Testing for Server-Side Template Injection — `https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/07-Input_Validation_Testing/18-Testing_for_Server_Side_Template_Injection` ([OWASP Foundation][17])
-* OWASP WSTG: Testing WebSockets — `https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/11-Client-side_Testing/10-Testing_WebSockets` ([OWASP Foundation][26])
-
-Template safety references:
-
-* Jinja: Sandbox — `https://jinja.palletsprojects.com/en/stable/sandbox/` ([jinja.palletsprojects.com][18])
-
-Selected supply-chain/advisory references (Starlette examples):
-
-* CVE-2023-29159 (StaticFiles path traversal; fixed 0.27.0) — `https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2023-29159/` ([advisories.gitlab.com][10])
-* CVE-2024-47874 (multipart/form-data DoS; fixed 0.40.0) — `https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2024-47874/` ([advisories.gitlab.com][9])
-* CVE-2025-62727 (FileResponse Range header DoS; fixed 0.49.1) — `https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2025-62727/` ([advisories.gitlab.com][19])
-
-[1]: https://pypi.org/project/fastapi/ "https://pypi.org/project/fastapi/"
-[2]: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html"
-[3]: https://starlette.dev/websockets/?utm_source=chatgpt.com "Websockets"
-[4]: https://pypi.org/project/uvicorn/ "https://pypi.org/project/uvicorn/"
-[5]: https://pypi.org/project/starlette/ "https://pypi.org/project/starlette/"
-[6]: https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html?utm_source=chatgpt.com "HTTP Security Response Headers Cheat Sheet"
-[7]: https://fastapi.tiangolo.com/reference/dependencies/?utm_source=chatgpt.com "Dependencies - Depends() and Security() - FastAPI"
-[8]: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html"
-[9]: https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2024-47874/ "Starlette Denial of service (DoS) via multipart/form-data | GitLab Advisory Database"
-[10]: https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2023-29159/ "Starlette has Path Traversal vulnerability in StaticFiles | GitLab Advisory Database"
-[11]: https://fastapi.tiangolo.com/tutorial/security/first-steps/?utm_source=chatgpt.com "Security - First Steps - FastAPI"
-[12]: https://fastapi.tiangolo.com/tutorial/response-model/ "https://fastapi.tiangolo.com/tutorial/response-model/"
-[13]: https://owasp.org/API-Security/editions/2023/en/0x11-t10/ "https://owasp.org/API-Security/editions/2023/en/0x11-t10/"
-[14]: https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html"
-[15]: https://fastapi.tiangolo.com/tutorial/extra-models/ "https://fastapi.tiangolo.com/tutorial/extra-models/"
-[16]: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html"
-[17]: https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/07-Input_Validation_Testing/18-Testing_for_Server_Side_Template_Injection?utm_source=chatgpt.com "Testing for Server Side Template Injection"
-[18]: https://jinja.palletsprojects.com/en/stable/sandbox/?utm_source=chatgpt.com "Sandbox — Jinja Documentation (3.1.x)"
-[19]: https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2025-62727/ "Starlette vulnerable to O(n^2) DoS via Range header merging in ``starlette.responses.FileResponse`` | GitLab Advisory Database"
-[20]: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html"
-[21]: https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html"
-[22]: https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html"
-[23]: https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html"
-[24]: https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html?utm_source=chatgpt.com "Unvalidated Redirects and Forwards Cheat Sheet"
-[25]: https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html?utm_source=chatgpt.com "WebSocket Security - OWASP Cheat Sheet Series"
-[26]: https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/11-Client-side_Testing/10-Testing_WebSockets?utm_source=chatgpt.com "WSTG - Latest | OWASP Foundation"
-[27]: https://fastapi.tiangolo.com/advanced/websockets/?utm_source=chatgpt.com "WebSockets - FastAPI"
-[28]: https://fastapi.tiangolo.com/reference/apirouter/?utm_source=chatgpt.com "APIRouter class - FastAPI"
-[29]: https://docs.pydantic.dev/latest/ "https://docs.pydantic.dev/latest/"