sudacode/dotfiles
1
0
Fork 0
mirror of https://github.com/ksyasuda/dotfiles.git synced 2026-02-27 12:22:43 -08:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
dotfiles/.agents/skills/security-best-practices/references/python-fastapi-web-server-security.md
sudacode 70dd0779f2 update
2026-02-19 00:33:08 -08:00

44 KiB
Raw Permalink Blame History

FastAPI (Python) Web Security Spec (FastAPI 0.128.x, Python 3.x) (PyPI)

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)

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)

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)
  • 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)
  • Run under a production ASGI server configuration (workers, timeouts, resource controls). (PyPI)
  • Host header validation enabled (TrustedHostMiddleware or equivalent). (PyPI)
  • CORS disabled unless explicitly needed; if enabled, it is strict and least-privilege. (OWASP Cheat Sheet Series)
  • Auth is enforced consistently via dependencies (no “oops, forgot auth on this route”). (FastAPI)
  • If cookies/sessions are used, cookie flags are secure and CSRF is addressed. (OWASP Cheat Sheet Series)
  • 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)
  • Dependencies are patched promptly, especially Starlette/python-multipart (multiple DoS and traversal advisories exist historically). (advisories.gitlab.com)

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)

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)

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)
  • 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)
  • 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)

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)

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)
  • 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)

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)

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)

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)
  • If using Starlette SessionMiddleware, MUST set https_only=True in production and choose an appropriate same_site. (PyPI)

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:

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)

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)
  • 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)
  • IMPORTANT NOTE: If cookies are not used for auth (auth is via Authorization header), CSRF is usually not applicable. (FastAPI)

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:

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)

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:

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)

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)

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)

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)

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)

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)

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)

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)
    • 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)

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)
  • 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)

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)
  • 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)
  • 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)

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)
  • 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)

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)
  • 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)
  • 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)

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)

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:

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)

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)

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)

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)

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)

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:

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)
  • 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)

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)

Audit focus examples (historical):

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)

  • 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)
    • Tokens in query params (token=, api_key=, key=) (FastAPI)

  • Session/cookies + CSRF:

    • SessionMiddleware( and cookie flags (https_only, same_site) (PyPI)
    • POST/PUT/PATCH/DELETE handlers using cookie auth with no CSRF checks (OWASP Cheat Sheet Series)

  • Input validation & mass assignment:

  • Excessive data exposure:

    • Returning ORM objects or dicts without response_model; responses containing password/role/internal fields (FastAPI)

  • CORS:

  • Files:

  • Uploads / multipart:

    • multipart/form-data endpoints with no size/field constraints; outdated Starlette/python-multipart (advisories.gitlab.com)

  • Injection:

  • SSRF:

  • Redirect:

  • WebSockets:

    • @app.websocket handlers without auth/origin checks; use of ws:// in prod configs (FastAPI)

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)

6) Sources (accessed 2026-01-27)

Primary framework documentation:

  • FastAPI (PyPI metadata, versioning) — https://pypi.org/project/fastapi/ (PyPI)
  • FastAPI docs: Security “First Steps” (Authorization Bearer header conventions) — https://fastapi.tiangolo.com/tutorial/security/first-steps/ (FastAPI)
  • FastAPI reference: Dependencies (Depends, Security) — https://fastapi.tiangolo.com/reference/dependencies/ (FastAPI)
  • FastAPI reference: APIRouter (router-level dependencies) — https://fastapi.tiangolo.com/reference/apirouter/ (FastAPI)
  • FastAPI docs: WebSockets — https://fastapi.tiangolo.com/advanced/websockets/ (FastAPI)

ASGI/server stack documentation:

  • Starlette (PyPI, general capabilities) — https://pypi.org/project/starlette/ (PyPI)
  • Starlette docs: WebSockets — https://starlette.dev/websockets/ (Starlette)
  • Uvicorn (PyPI metadata) — https://pypi.org/project/uvicorn/ (PyPI)
  • Pydantic docs (v2.12.x) — https://docs.pydantic.dev/latest/ (Pydantic)

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)
  • OWASP Cheat Sheet Series: CSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: XSS Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: Mass Assignment — https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP API Security Top 10 (2023) — https://owasp.org/API-Security/editions/2023/en/0x11-t10/ (OWASP Foundation)
  • OWASP Cheat Sheet Series: SQL Injection Prevention — https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: OS Command Injection Defense — https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: SSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: File Upload — https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: Unvalidated Redirects and Forwards — https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: HTTP Security Response Headers — https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • OWASP Cheat Sheet Series: WebSocket Security — https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html (OWASP Cheat Sheet Series)
  • 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)
  • 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)

Template safety references:

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)
  • CVE-2024-47874 (multipart/form-data DoS; fixed 0.40.0) — https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2024-47874/ (advisories.gitlab.com)
  • CVE-2025-62727 (FileResponse Range header DoS; fixed 0.49.1) — https://advisories.gitlab.com/pkg/pypi/starlette/CVE-2025-62727/ (advisories.gitlab.com)
Reference in New Issue View Git Blame Copy Permalink