FastAPI 安全规范（Security Spec）实战指南：从安全默认代码生成到漏洞审计-平芜编程栈

FastAPI 安全规范（Security Spec）实战指南：从安全默认代码生成到漏洞审计

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文围绕本项目 Codex Skill「security-best-practices」所附的 FastAPI 后端安全参考文档（python-fastapi-web-server-security.md）展开。该文档以规范（normative）形式定义了 FastAPI 应用的安全默认代码生成与安全审查/漏洞挖掘两套能力，并给出了 30 余条带严重级别、检测模式与修复方案的审计规则。读完本文，你将掌握 FastAPI 生产环境的强制安全基线、按依赖注入强制认证的正确姿势、Cookie/CSRF/JWT 的边界判断，以及一套可直接执行的代码库漏洞扫描顺序与发现报告格式。

一、文档定位：一份可执行的 FastAPI 安全规格

在 Codex 的 Skill 体系中，这份文档不是泛泛的"最佳实践清单"，而是一份安全规格（Security Spec），它同时支撑三种用法：

安全默认的代码生成：当要求编写新的 FastAPI 代码时，生成的代码必须满足规范中全部 MUST 要求；
被动安全审查：在编辑 FastAPI 代码的过程中顺带发现附近代码中的安全违规；
主动漏洞审计：当明确要求"扫描/审计/寻找漏洞"时，系统性检索代码库并输出结构化发现报告。

文档采用 MUST / SHOULD / MAY 的规范语言组织规则，每条规则都包含：必需实践（Required）、不安全模式（Insecure Patterns）、检测提示（Detection Hints）与修复建议（Fix / Mitigation / False Positive Notes）。

由于 FastAPI 通常以 Uvicorn 等 ASGI 服务器部署，且构建于 Starlette + Pydantic 之上，该规范的安全范围也覆盖这三层对安全有影响的环节。整个 Skill 的定位可以从仓库中的两个文件交叉印证：

SKILL.md 定义了完整工作流：先识别语言与框架 → 到references/目录加载对应参考文档 → 进入三种操作模式（安全默认编码 / 被动检测 / 主动审计报告）；
openai.yaml 声明了该 Skill 的默认提示词："Review this codebase for security best practices and suggest secure-by-default improvements."

该 Skill 的references/目录按<语言>-<框架>-<栈>-security.md命名组织，除 FastAPI 外还覆盖 Django、Flask、Express、Next.js、Go 等后端，以及 React、Vue、jQuery 等前端，本文只聚焦 FastAPI 这一份。

二、第 0 节：安全边界与防滥用约束（必须先遵守）

在任何审计或生成任务开始前，以下约束具有最高优先级：

绝不请求、输出、记录或提交密钥（API Key、密码、私钥、会话 Cookie、签名密钥、含凭据的数据库 URL）；
绝不通过禁用保护机制来"修复"安全问题（例如弱化认证、放开 CORS、跳过签名校验、关闭校验、关闭 TLS 校验、allow_origins=["*"]配合凭据）；
审计时必须给出基于证据的结论：引用文件路径、代码片段和配置值来支撑论断；
对不确定性要诚实：若某项保护可能存在于基础设施层（反向代理、WAF、CDN、服务网格），应报告为"应用代码中不可见，需在运行时/配置层验证"；
正确理解浏览器侧控制：
- CORS 不是认证机制，它只影响浏览器；
- CSRF 防御适用于浏览器自动携带凭据（Cookie）的场景；对纯请求头 Token 的 API 通常不适用。

三、三种操作模式：生成 / 被动审查 / 主动审计

3.1 生成模式（默认）

当被要求编写或修改 FastAPI 代码时：

必须遵守规范中每一条 MUST 要求，应当遵守 SHOULD 要求（除非用户明确要求例外）；
优先使用安全默认的 API 和成熟库，而不是自己手写安全代码；
避免引入新的风险汇聚点（risky sinks）：shell 执行、不安全反序列化、动态 eval、不可信模板渲染、不安全文件服务、不安全重定向、任意外联请求。

3.2 被动审查模式（编辑时始终开启）

即使开发者并未要求安全扫描，在 FastAPI 仓库中工作时也必须"注意到"接触或邻近代码中违反本规范的问题，并以"简要说明 + 安全修复"的形式提出。

3.3 主动审计模式（显式扫描请求）

当用户要求"扫描 / 审计 / 寻找漏洞"时，必须系统性检索代码库并按下述推荐审计顺序执行：

应用入口 / 部署脚本 / Dockerfile / Procfile / Helm / Terraform；
ASGI 服务器配置（Uvicorn/Gunicorn）、代理设置、debug/reload 设置；
FastAPI 应用配置（文档暴露、中间件、可信主机、CORS）；
认证 / 授权设计（依赖项、JWT/会话处理、密码存储）；
Cookie/会话使用与 CSRF（如果使用 Cookie）；
输入校验与输出塑形（Pydantic 模型、批量赋值、数据过度暴露）；
模板渲染与 XSS/SSTI（如果服务 HTML）；
文件处理（上传与下载）、StaticFiles、Range 支持；
注入类（SQL、命令执行、不安全反序列化）；
外联请求（SSRF）、重定向处理、WebSocket 安全。

四、核心概念：不可信输入、状态变更请求与审计报告格式

4.1 不可信输入（Untrusted Input）

除非能证明可信，以下一律视为攻击者可控：

查询参数 / 路径参数；
JSON 请求体（含嵌套字段）；
请求头（含Host、Origin、X-Forwarded-*）；
Cookie（含会话 Cookie）；
文件上传（multipart 各部件）；
WebSocket 消息、握手阶段的查询参数与请求头；
来自外部系统的任何数据（webhook、第三方 API、消息队列）；
任何源于用户的持久化内容（数据库行）。

4.2 状态变更请求（State-Changing Request）

若请求能够创建 / 更新 / 删除数据、改变认证或会话状态、触发副作用（购买、发邮件、发 webhook）或发起特权操作，即视为状态变更请求——这类请求是 CSRF、越权等风险的主要关注面。

4.3 必需审计发现格式

主动审计时，每个发现必须包含以下字段：

Rule ID（对应规则编号）；
Severity：Critical / High / Medium / Low；
Location：文件路径 + 函数/路由名 + 行号；
Evidence：精确的代码/配置片段；
Impact：可能造成的后果、谁可以利用；
Fix：安全的修改（优先最小 diff）；
Mitigation：若无法立即修复时的纵深防御措施；
False positive notes：不确定时需验证什么。

对应地，SKILL.md 要求完整审计报告写入security_best_practices_report.md（或用户指定位置），顶部为执行摘要，按严重程度分节，关键发现需附带一行影响陈述，且报告中引用代码必须包含行号。

五、生产环境最低安全基线（生产环境 MUST）

这是防止常见 FastAPI/ASGI 错误配置的最小"生产基线"：

生产环境无 debug traceback、无自动重载；
使用生产级 ASGI 服务器配置（workers、超时、资源控制）；
启用 Host 头校验（TrustedHostMiddleware或等价物）；
CORS 默认关闭，仅在明确需要时开启，且严格最小权限；
认证通过依赖项（Dependencies）统一强制，杜绝"某路由忘了加认证"；
使用 Cookie/会话时，Cookie 标志位安全且 CSRF 已处理；
请求体大小限制与 multipart 限制在边缘层存在，并在应用内按需校验（缓解内存/CPU DoS）；
依赖及时打补丁，尤其 Starlette 与 python-multipart（历史上存在多个 DoS 与路径穿越公告）。

六、规则详解：按攻击面分组的 FastAPI 安全规则

6.1 部署与运行时配置

FASTAPI-DEPLOY-001：生产环境禁止自动重载（Severity: High）

要求：生产环境不得使用 auto-reload/watch 模式（如 Uvicorn reload）；应使用生产进程模型（如多 worker）与稳定服务器配置。
不安全模式：生产入口中的uvicorn ... --reload或reload=True；Docker/Procfile/systemd 命令携带--reload。
检测提示：搜索--reload、reload=True、watchfiles、fastapi dev、"development"运行脚本；检查 Docker CMD/ENTRYPOINT、Procfile、systemd 单元与 shell 脚本。
修复：生产环境移除 reload，以稳定配置显式指定 worker 运行 Uvicorn/Gunicorn。
注意：本地开发用 reload 没问题，仅在明确作为生产入口时标记。

FASTAPI-DEPLOY-002：生产环境必须关闭 Debug 模式（Severity: Critical）

要求：生产环境不得开启 debug traceback（FastAPI/Starlette debug 模式会暴露内部敏感信息，并使某些利用链更容易）；任何向客户端返回详细堆栈的配置都应视为敏感。
不安全模式：app = FastAPI(debug=True)或等价的环境开关在生产中启用 debug；服务器/日志配置向终端用户暴露 traceback。
检测提示：搜索debug=True、DEBUG = True、映射到 debug 的环境标志；审查异常中间件与错误处理器。
修复：确保 debug 仅在本地开发/测试开启；对客户端返回通用错误响应，细节记入内部日志。

FASTAPI-OPENAPI-001：OpenAPI 与交互式文档生产环境必须禁用或保护（Severity: Medium，内部/敏感应用可为 High）

要求：公开服务生产环境应当禁用/docs、/redoc、/openapi.json，除非有明确的业务需求；若保留则必须保护（认证、网络白名单或仅内网路由）；不得抱有"隐藏即安全"的幻想——文档暴露是信息泄露放大器。
不安全模式：内部/管理 API 的/docs与/openapi.json公网可达；生产同域名下文档无访问控制。
检测提示：查找FastAPI(docs_url=..., redoc_url=..., openapi_url=...)或默认值；检查反向代理路由与白名单。
修复：生产环境禁用文档端点（docs_url=None, redoc_url=None, openapi_url=None），或在边缘限制访问。

6.2 认证（Authentication）

FASTAPI-AUTH-001：认证必须显式且通过依赖项统一强制（Severity: High）

要求：认证必须实现为依赖项（或路由级依赖），使受保护端点不可能"忘记"认证；特权路由/端点默认"拒绝"，真实公开路由显式标记；应当把认证集中在路由器边界（如为已认证端点单设受保护的APIRouter）。
不安全模式：各处理器内散落临时认证检查（易遗漏）；受保护与不受保护端点混杂、策略不清。
检测提示：识别路由与端点，检查受保护端点是否包含Depends(...)/Security(...)；搜索处理器内部的if user is None: raise ...这类模式。
修复：把认证移入依赖项，通过Depends()/Security()一致地挂到路由器/端点上。

FASTAPI-AUTH-002：使用标准认证传输，避免把密钥放进 URL（Severity: High）

要求：Token 认证应当使用Authorization: Bearer <token>请求头而非查询参数；在可避免时，绝不把密钥（Token、含长期密钥的密码重置链接、API Key）放进查询字符串。
不安全模式：?token=...、?api_key=...、?auth=...用作主认证；长期有效的访问令牌嵌入 URL（会通过日志、Referrer、缓存泄露）。
检测提示：搜索token、api_key、key、secret、password等参数名；寻找无正当理由的查询 API Key 安全方案。
修复：把 Token 移到 Authorization 头；轮换/缩短有效期；敏感值用 POST 请求体传输。

FASTAPI-AUTH-003：密码必须强哈希存储，绝不存明文（Severity: Critical）

要求：必须使用强且慢的密码哈希方案（如 Argon2id、bcrypt）存储密码；不得以明文或可逆加密作为主要保护；应当使用成熟库完成哈希与校验（不要自己造轮子）。
不安全模式：数据库存明文密码；用快速哈希（如 SHA256）而不用正规密码哈希 KDF；API 响应返回密码哈希。
检测提示：搜索持久化的password=字段，检查对密码使用hashlib.md5/sha1/sha256；检查响应模型中是否含密码/哈希字段。
修复：迁移到正规密码哈希库；增加"登录时重新哈希"的升级路径。

FASTAPI-AUTH-004：JWT 校验必须严格，JWT 不得携带密钥（Severity: High）

要求：必须校验 JWT 签名并强制算法白名单；必须按系统需要校验标准声明（至少exp，多服务/多租户通常还需iss/aud）；必须明白 JWT 内容客户端可读，不要把密钥放进 payload。
不安全模式：jwt.decode(..., options={"verify_signature": False})或等价写法；接受alg=none/ 算法混淆；用 JWT payload 存敏感密钥（API Key、密码）。
检测提示：搜索jwt.decode、python-jose、PyJWT、verify_signature；检查是否缺少 exp 校验或有效期过长。
修复：强制严格校验（签名、允许算法、exp 及必需的 issuer/audience 约束）；payload 只放你愿意暴露给客户端的标识符与声明。

6.3 授权（Authorization）

FASTAPI-AUTHZ-001：对象级与属性级授权必须强制（Severity: High）

要求：凡是通过用户可控标识符（路径/查询/请求体中的 ID）访问资源，必须做对象级授权；必须做属性级授权与响应塑形，防止"数据过度暴露"（如仅管理员可见的字段）。
不安全模式：GET /users/{id}不验证调用者能否访问该id就返回用户记录；响应模型包含内部字段（角色、权限、计费数据、密码哈希）。
检测提示：枚举接受 ID 的端点，追踪是否执行了授权检查；对比公开与内部响应模型字段。
修复：增加对象级检查（所有权、ACL、租户边界）；使用仅包含允许字段的专用响应模型。

6.4 会话与 CSRF

FASTAPI-SESS-001：基于 Cookie 的会话在 TLS 下必须设置安全属性（Severity: High，仅当启用 TLS）

要求（生产、HTTPS）：会话 Cookie 必须仅在 HTTPS 下发送（Secure）；重要提示：只有在生产且 TLS 已配置时才设置Secure，本地 HTTP 开发环境不要设置，应基于是否生产模式条件设置，并提供一个类似SESSION_COOKIE_SECURE的开关用于 HTTP 测试时关闭 Secure；会话 Cookie 必须设置 HttpOnly（JS 不可访问）；应当使用SameSite=Lax（UX 允许时可用Strict）；若确需跨站 Cookie，必须记录 CSRF 影响并添加补偿控制；使用 StarletteSessionMiddleware时生产环境必须设https_only=True并选择合适same_site。
不安全模式：会话 Cookie 缺 Secure/HttpOnly；SameSite=None的 Cookie 用于已认证的状态变更端点而无 CSRF 防护。
检测提示：搜索SessionMiddleware(并检查https_only、same_site参数；搜索set_cookie(与 Cookie 标志。
修复：设置安全 Cookie 属性；高特权会话优先使用短有效期。

FASTAPI-SESS-002：签名会话 Cookie 不得存放敏感密钥（Severity: High）

要求：必须假设 Cookie 中的会话数据客户端可读（签名 ≠ 加密）；不要存密钥/PII，除非服务端加密；Cookie 只放不透明标识符（如会话 ID）或非敏感状态，敏感会话状态放服务端。
不安全模式：在 Cookie 会话 payload 中直接存访问令牌、刷新令牌或 PII；把"签名 Cookie"当作机密存储。
检测提示：搜索request.session[...] =或等价模式，识别存入内容；识别SessionMiddleware或其他 Cookie 会话机制的使用。
修复：敏感值移到服务端存储，保持 Cookie 最小化。

FASTAPI-CSRF-001：Cookie 认证的状态变更请求必须防 CSRF（Severity: High）

注意：仅适用于基于 Cookie 的认证；若应用使用请求头或 Token 认证（如 Authorization 头），CSRF 不是问题。
要求：所有依赖 Cookie 认证的状态变更端点（POST/PUT/PATCH/DELETE）必须受 CSRF 保护；应当使用成熟的 CSRF 方案（同步器 Token 模式或经过充分审查的中间件）而非自研；可以增加纵深防御（Origin/Referer 检查、SameSite Cookie、Fetch Metadata），但对 Cookie 认证应用而言 Token 是主要防线；若认证不依赖 Cookie，CSRF 通常不适用。
不安全模式：Cookie 认证且改变状态但无 CSRF 校验的端点；用 GET 做状态变更（放大 CSRF 风险）。
检测提示：枚举非 GET 路由；确认是否用 Cookie 认证；查找 CSRF Token 的生成/校验或中间件。
修复：使用 Cookie 认证时，为状态变更动作添加并校验 CSRF Token。

6.5 输入校验、批量赋值与数据暴露

FASTAPI-VALID-001：请求解析与校验必须 Schema 驱动，防止批量赋值（Severity: Medium，尤其写库 API）

要求：请求体应当使用 Pydantic 模型而非任意dict/Any；写端点应当配置模型拒绝意外字段（防"批量赋值"式 bug）；用于访问控制或副作用的标识符（ID、邮箱、URL）必须校验与规范化。
不安全模式：payload = await request.json()后接Model(**payload)或直接用payload写库（无白名单）；写端点模型静默接受未知字段。
检测提示：搜索await request.json()、request.body()、dict类型请求体、Any类型请求体；查找db.update(**payload)或Model(**payload)且输入未过滤的端点。
修复：使用字段白名单化的显式 Pydantic 模型；写端点拒绝多余字段。

FASTAPI-RESP-001：通过响应模型与显式序列化防止数据过度暴露（Severity: Medium）

要求：响应模型必须只含预期字段（尤其用户对象、认证相关对象、计费对象）；应当区分"创建输入 / 数据库内部 / 公开输出"三套模型，避免泄露敏感字段。
不安全模式：返回含内部列的 ORM 对象或 dict；把"DB 模型"直接当响应模型（含password_hash、is_admin等）。
检测提示：查找return user且user为 ORM 实例的端点；检查返回敏感资源的端点是否缺response_model。
修复：添加显式响应模型；创建排除敏感字段的"公开" Schema。

6.6 XSS 与 SSTI

FASTAPI-XSS-001：HTML 响应与模板中防止反射型/存储型 XSS（Severity: High，若服务 HTML）

要求：HTML 模板必须开启自动转义；不得把不可信内容标记为安全（不渲染用户可控数据的"raw HTML"）；服务含用户内容的 HTML 时应部署 CSP。
不安全模式：用户内容未经转义/净化直接渲染进 HTML；关闭自动转义或未净化使用"raw HTML"特性。
检测提示：搜索模板渲染与字符串拼接构建 HTML；审查模板中的"unsafe"过滤器/构造与未加引号的属性。
修复：保持自动转义开启；确需渲染用户 HTML 时用可信净化器；添加 CSP。
注意：纯 JSON API 的 XSS 通常属于客户端/应用问题，但错误页/文档页仍可能渲染 HTML。

FASTAPI-SSTI-001：绝不渲染不可信模板（服务端模板注入，Severity: Critical）

要求：不得渲染含用户可控模板语法的模板；"字符串转模板"渲染若受不可信输入影响即视为危险；若确需不可信模板（罕见且高风险）：必须使用沙箱化模板方案并限制能力，必须假设沙箱可被逃逸，增加隔离与严格白名单。
不安全模式：用普通 Jinja 环境渲染从用户输入或数据库加载的模板；用用户可控字符串动态构造模板。
检测提示：grep JinjaEnvironment.from_string、Template(...)等；追溯模板字符串来源（请求、DB、上传、管理后台）。
修复：改用不可执行模板（简单字符串替换）；确需时用 Jinja 沙箱环境并加强隔离。

6.7 安全头、CORS、Host 与代理

FASTAPI-HEADERS-001：设置关键安全响应头（应用内或边缘，Severity: Medium）

要求（典型 API/Web 应用）：应当设置X-Content-Type-Options: nosniff；若服务 HTML 设置点击劫持防护（X-Frame-Options和/或 CSPframe-ancestors）；按需设置Referrer-Policy与Permissions-Policy。
注意：响应头可能由代理/CDN 设置；应用代码中不可见时标记为"边缘验证"。
不安全模式：服务 HTML 或敏感 API 的应用（含边缘）完全没有安全头。
检测提示：搜索设置响应头的中间件；检查反向代理配置。
修复：集中（中间件）或通过反向代理/CDN 设置响应头。

FASTAPI-CORS-001：CORS 必须显式且最小权限（Severity: Medium，误配凭据时为 High）

要求：不需要 CORS 时必须保持禁用；需要时：必须白名单受信来源（不反射任意 Origin）；不得把携带凭据的请求与通配符来源组合（不安全且合规中间件通常拒绝）；应当限制允许的方法与请求头。
不安全模式：allow_origins=["*"]与allow_credentials=True组合；未校验就反射Origin；广泛使用allow_origin_regex=".*"。
检测提示：搜索CORSMiddleware配置；查找allow_origins=["*"]、allow_credentials=True、allow_origin_regex。
修复：使用显式来源白名单与最小方法/请求头；除非必要保持凭据关闭。

FASTAPI-HOST-001：生产环境必须校验 Host 头（Severity: Low）

要求：应当使用TrustedHostMiddleware（或边缘等价物）限制可接受的 Host 值；在未校验的情况下，不得信任Host头用于安全敏感决策。
不安全模式：无 Host 校验，却用请求 Host 生成外部 URL（密码重置链接、回调 URL）；宽松代理后的应用允许任意 Host 头。
检测提示：搜索TrustedHostMiddleware的使用；搜索用request.url、request.base_url或 Host 派生值构建外部 URL 的逻辑。
修复：生产环境配置严格 allowed-hosts 列表；可能时在边缘也强制。

FASTAPI-PROXY-001：反向代理信任必须正确配置（Severity: High，位于代理之后时）

要求：位于反向代理之后时，必须正确配置转发头信任；不得盲目信任来自公网的X-Forwarded-*头；若使用 Uvicorn 的代理头支持，必须限制允许提供转发头的 IP。
不安全模式：未限制可信代理 IP 就广泛启用代理头；用转发头判断"是否安全 / 是否内网 / 客户端 IP"而无正确信任边界。
检测提示：搜索--proxy-headers、--forwarded-allow-ips或等价配置；搜索对request.client.host、request.url.scheme、request.headers["x-forwarded-for"]的安全敏感使用。
修复：仅在已知代理后配置 Uvicorn 代理头，并将forwarded_allow_ips限制为该代理；即使位于代理后也要保持 Host 白名单。

6.8 资源限制与 DoS

FASTAPI-LIMITS-001：请求与 multipart 限制必须执行以防 DoS（Severity: Low）

要求：必须在边缘（反向代理/负载均衡）强制请求体大小限制，并按需在应用内校验；对multipart/form-data处理必须特别关注（历史上存在无界缓冲与 DoS 向量）；应当对昂贵端点做速率限制和/或每 IP/每用户节流。
不安全模式：接受任意大的 JSON 请求体或 multipart 表单；解析 multipart 表单而无大小/字段数控制。
检测提示：识别文件上传端点与multipart/form-data使用；查找缺失的代理层限制（nginxclient_max_body_size、ALB 限制等）与缺失的应用层检查。
修复：强制严格请求体限制与 multipart 约束；保持 Starlette 与 python-multipart 更新到已修复版本。

6.9 文件处理、静态文件与上传

FASTAPI-FILES-001：防止路径穿越与不安全的静态文件暴露（Severity: High）

要求：不得在未严格校验与安全基目录的情况下，把用户可控文件路径传给FileResponse/文件系统调用；使用StaticFiles时必须保持 Starlette 更新并了解其安全历史（旧版本存在路径穿越公告）；不得把用户上传内容（尤其 HTML/JS）作为可执行/活动内容从静态根目录内联服务。
不安全模式：FileResponse(request.query_params["path"])；挂载StaticFiles(directory="uploads")且上传目录含 HTML/JS/SVG 并内联服务。
检测提示：在路由中搜索FileResponse(、StaticFiles(、open(；追踪路径是否源于不可信输入。
修复：文件使用不透明 ID，ID 映射到服务端存储路径；合适时以附件下载方式服务不可信内容。

FASTAPI-FILES-002：缓解文件服务端点上的 Range 头 DoS（Severity: Low，受影响版本且启用文件服务时）

要求：使用FileResponse/StaticFiles时必须保持 Starlette 已修补已知的文件服务 DoS 问题；必须把异常的Range头处理与文件服务视为 DoS 攻击面。
不安全模式：用存在漏洞的 Starlette 版本服务大文件；文件端点无速率限制/CDN 屏蔽。
检测提示：识别 Starlette 版本，若在受影响范围则标记；查找FileResponse与StaticFiles的使用。
修复：按公告指导升级 Starlette 至已修复版本；适当为文件端点添加边缘缓存/速率限制。

FASTAPI-UPLOAD-001：文件上传必须校验、安全存储并安全服务（Severity: Medium）

要求：必须强制上传大小限制（应用 + 边缘）；必须用白名单与内容检查（而非仅扩展名）校验文件类型；应当生成服务端文件名（随机 ID），不信任原始文件名；必须安全服务潜在活动格式（下载附件），除非明确有意内联。
不安全模式：接受任意文件类型并内联返回；用用户提供的文件名作为存储路径。
检测提示：查找上传处理器及文件的写入方式；查找上传目录的直接暴露。
修复：实施白名单校验 + 安全存储 + 安全服务；适用时增加扫描/隔离。

6.10 注入防护

FASTAPI-INJECT-001：防止 SQL 注入（使用参数化查询/ORM，Severity: High）

要求：必须使用参数化查询或底层参数化的 ORM；不得用字符串拼接 / f-string 拼接不可信输入构建 SQL。
不安全模式：f"SELECT ... WHERE id={user_id}"；"... WHERE name = '%s'" % user_input。
检测提示：grep Python 字符串中.execute(...)附近的 SQL 关键字；追踪不可信数据进入数据库调用。
修复：替换为参数化查询/ORM 查询 API；查询前校验类型。

FASTAPI-INJECT-002：防止操作系统命令注入（Severity: Critical ~ High，取决于暴露面）

要求：必须避免用不可信输入执行 shell 命令；确需 subprocess 时：参数必须以列表形式传递（而非字符串）、不得对攻击者影响的字符串使用shell=True、任何可变部分应当使用严格白名单。
不安全模式：os.system(user_input)；subprocess.run(f"cmd {user}", shell=True)；把用户字符串传入bash -c、sh -c、PowerShell 等。
检测提示：搜索os.system、subprocess、Popen、shell=True；追踪请求/DB 数据进入这些调用。
修复：用库 API 替代 shell 命令；无法避免时硬编码命令并白名单化校验参数，支持处使用--分隔符。

6.11 SSRF、开放重定向与 WebSocket

FASTAPI-SSRF-001：防止外联 HTTP 中的服务端请求伪造（Severity: Medium，云/VPC 环境可为 High）

注意：小型独立项目此风险较低，最需要注意的场景是部署到局域网或与其他服务共用同一台服务器。
要求：必须把对用户提供 URL 的外联请求视为高风险；对任何用户影响的 URL 抓取应当校验并限制目的地（白名单主机/域名）；应当阻止访问 localhost/私网 IP 段/链路本地与云元数据端点；必须把协议限制为 http/https；应当设置超时并谨慎控制重定向。
不安全模式：httpx.get(request.query_params["url"])；接受任意 URL 的"URL 预览/导入/webhook 测试器"功能。
检测提示：搜索requests、httpx、urllib、aiohttp中 URL 来自请求/DB 的调用；识别fetch、preview、proxy、webhook、import类端点。
修复：实施严格 URL 解析 + 白名单；增加出口控制；设置短超时；不需要时禁用重定向。

FASTAPI-REDIRECT-001：防止开放重定向（Severity: Low）

要求：必须校验源自不可信输入的跳转目标（next、redirect、return_to）；应当只跳转到同站相对路径或域名白名单。
不安全模式：RedirectResponse(next)且next用户可控、无校验。
检测提示：搜索RedirectResponse(或跳转逻辑，检查目标来源。
修复：只允许相对路径或白名单域名；失败时回退到安全默认目标。

FASTAPI-WS-001：WebSocket 端点必须认证并防跨站滥用（Severity: Medium ~ High，取决于数据/权限）

要求：任何非公开频道必须对 WebSocket 连接做认证（WebSocket 本身不提供认证）；应当为基于浏览器的客户端实施 Origin/类 CSRF 防护（Origin 校验是常见控制）；应当对消息频率与连接尝试做速率限制，关闭空闲/滥用连接。
不安全模式：@app.websocket(...)接受并信任连接而无认证检查；用查询字符串 Token 认证而不考虑泄露/轮换。
检测提示：搜索@app.websocket/websocket_endpoint，检查敏感操作前是否执行认证；审查 Origin 检查、Token 解析与每连接授权。
修复：握手期间要求认证（如 Token 或会话），并对动作/消息强制授权；对浏览器客户端在适当时校验 Origin；应用速率限制与超时。

6.12 供应链与补丁卫生

FASTAPI-SUPPLY-001：依赖与补丁卫生（聚焦安全相关依赖，Severity: Low）

要求：应当固定并定期更新安全关键依赖（FastAPI、Starlette、Uvicorn、Pydantic、python-multipart、认证/JWT 库）；必须及时响应已知安全公告；必须把文件服务与 multipart 解析依赖视为安全敏感（有历史 CVE）。
历史审计焦点示例：
- StarletteStaticFiles路径穿越——0.27.0 修复（CVE-2023-29159）；
- Starlettemultipart/form-dataDoS——0.40.0 修复（CVE-2024-47874）；
- StarletteFileResponseRange 头 DoS——0.49.1 修复（CVE-2025-62727）。
检测提示：检查requirements.txt、锁定文件、容器镜像与运行时环境的实际安装版本；把文件上传/文件服务功能映射到依赖版本。
修复：按公告升级到已修补版本；围绕受影响行为增加回归测试。

七、实战扫描启发式：如何在代码库中"打猎"

主动扫描时使用这些高信号模式：

攻击面	高信号模式
开发服务器 / Debug	`--reload`、`reload=True`、`debug=True`、`FastAPI(debug=True)`
OpenAPI/文档暴露	`/docs`、`/redoc`、`/openapi.json`、`docs_url=`、`openapi_url=`
认证执行缺口	期望有`Depends()`/`Security()`的端点缺失；路由器无一致依赖边界；查询参数中的 Token（`token=`、`api_key=`、`key=`）
会话/Cookie + CSRF	`SessionMiddleware(`及 Cookie 标志（`https_only`、`same_site`）；用 Cookie 认证的 POST/PUT/PATCH/DELETE 处理器无 CSRF 检查
输入校验与批量赋值	`await request.json()`与从 dict 直接写库；模型接受多余字段
数据过度暴露	无`response_model`返回 ORM 对象或 dict；响应含密码/角色/内部字段
CORS	`CORSMiddleware`配`allow_origins=[""]`、`allow_origin_regex="."`、`allow_credentials=True`
文件	用户可控路径的`FileResponse(`；暴露上传目录的`StaticFiles(`
上传 / multipart	无大小/字段约束的`multipart/form-data`端点；过期的 Starlette/python-multipart
注入	SQL 字符串用 f-string/拼接进入`.execute(...)`；`subprocess.*`、`shell=True`、`os.system`
SSRF	`httpx.get/post`或`requests.*`的 URL 来自请求/DB，无白名单/超时
重定向	无校验的`RedirectResponse(next)`
WebSocket	无认证/Origin 检查的`@app.websocket`处理器；生产配置使用`ws://`

每次确认时都要回答四个问题：

数据来源：不可信还是可信？
汇聚点类型：SQL / 子进程 / 文件 / 模板 / HTTP / 重定向 / WebSocket？
防护措施：是否已有校验、白名单、中间件、边缘控制？
依赖版本：实际安装版本是否落在受影响范围？

八、仓库佐证与延伸阅读

本文依据的规范原文：python-fastapi-web-server-security.md（FastAPI 0.128.x / Python 3.x 安全规格，含完整来源清单，2026-01-27 访问）；
Skill 总览与三模式工作流、审计报告格式、修复流程：SKILL.md；
同一 Skill 的其余语言/框架参考：Django、Flask、Express、Next.js、Go 后端及 React/Vue/jQuery 前端规范均位于 references/ 目录，文件命名遵循<语言>-<框架>-<栈>-security.md；
该 Skill 在 Codex 中的注册信息：openai.yaml；
许可信息见 LICENSE.txt。

此外，SKILL.md 中的通用建议值得在生产实践中共用：公开资源 ID 应使用随机 UUID4 或随机十六进制串而非小步长自增 ID（防止资源枚举与 ID 猜测）；关于 TLS，多数开发工作在 TLS 关闭或由 TLS 代理提供的情况下进行，不要将"缺 TLS"当作漏洞上报，"Secure" Cookie 也只在真实运行于 TLS 时设置（可用环境变量开关控制，避免本地 HTTP 开发被破坏），同时避免贸然推荐 HSTS——它可能造成重大故障与用户锁定。

一句话收束：把这份安全规格当作 FastAPI 代码的"编译期检查"——生成代码时以 MUST 为底线、审计时按第 3.3 节的顺序配合第 7 节的高信号模式逐层扫描，最终以第 4.3 节的结构化格式输出证据充分的发现报告，即可把 FastAPI 服务的安全水平稳定维持在 OWASP 与官方框架文档所要求的生产基线之上。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考