dotfiles/.agents/skills/security-best-practices/references/python-fastapi-web-server-security.md

# 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/"