API-Security-Checklist 实战指南：从认证到监控的 API 全生命周期安全核对清单

API-Security-Checklist 是 Shieldfy 团队维护的开源安全清单项目，仓库以一份可勾选的 Markdown 核对表为核心，覆盖 API 设计、测试与发布全流程中最关键的安全对策，并提供 30 余种语言版本。本文以越南语版 README-vi.md 为骨架，逐条展开每项措施的威胁场景、实现要点与可落地建议，帮助你把它转化为团队设计评审、代码走查和上线前检查的实战工具。

一、清单概览：一份贯穿 API 生命周期的安全核对表

整个仓库是一个纯文档型项目，核心内容即根目录下的多语言 README 系列文件：

• 英文原版 README.md：清单的权威基准版本，其余语言均以其为翻译蓝本；
• 简体中文版 README-zh.md、繁体中文版 README-tw.md 与越南语版 README-vi.md 等 30 余种翻译；
• CONTRIBUTING.md：说明如何通过 fork + Pull Request 贡献内容与新增翻译；
• LICENSE：MIT 协议（© 2017 Shieldfy），可自由用于团队内部。

清单采用 - [ ] 可勾选格式组织，每个条目即一项安全对策。使用方式很直接：把对应章节复制进项目的安全评审文档，在需求设计、编码完成、发布前三个阶段逐项打勾复核。各版本内容以英文原版最全，例如原版在访问控制一节额外强调「HTTPS 需使用 TLS 1.2+ 与安全加密套件，并确保 Host 头与 SNI 匹配」，在处理一节补充「解析 XML、YAML 等含锚点与引用的语言时同样要关闭实体扩展」；中文版则进一步补充了登录失败返回模糊提示、防止横向越权、敏感数据后端脱敏等条目。以下按越南语版骨架逐节展开，并标注来自其他版本的补充要点。

二、身份认证（Authentication）

身份认证是 API 的第一道门，清单在此给出四条底线。

1. 不要使用 Basic Auth，改用标准认证协议。Basic Auth 把 用户名:密码 做 Base64 编码后放入请求头，Base64 可被瞬间解码，且密码随每次请求传输、极易被重放和泄露。应使用 OAuth 2.0、OpenID Connect 或标准 Token 认证方案。

2. 不要在 Authentication、token generation、password storage 上重复造轮子，使用标准方案。token 生成应使用经过审计的标准库（如各自语言生态中实现 RFC 7519 的 JWT 库、支持随机密钥的签名算法），密码存储应使用专门设计的慢哈希算法（bcrypt、scrypt、Argon2），并配合随机盐。自研加密与哈希算法是安全界反复强调的高危行为——密码存储务必使用不可逆、抗 GPU 爆破的哈希方案，而非明文或弱哈希。

3. 登录功能使用 Max Retry 与自动封禁（jail）机制。对单账号或单 IP 的连续失败登录设置最大重试次数，超过阈值即触发临时封禁或验证码挑战，这正是抵御暴力破解的直接手段。中文版 README-zh.md 在此补充：登录失败时应返回模糊提示（如统一的「用户名或密码错误」），避免暴露账号是否存在、降低枚举攻击面。

4. 加密所有敏感数据。既包括传输层加密（TLS），也包括存储层加密（数据库字段级加密、加密卷、KMS 管理的密钥）。

此外，原文档「参见」一节有一条值得记住的项目立场：并不一定需要 JWT——多数场景下直接使用随机生成的 API Key 即可；仅当确实需要非对称加密或防篡改能力时，才考虑替代 JWT 的令牌方案。这提示我们认证选型应服从实际威胁模型，而非追逐流行方案。

三、访问控制（Access）

本节回答「谁能在什么条件下到达你的 API」。

1. 限制请求量（Throttling），防御 DDoS 与暴力攻击。通过限流把单 IP、单账号的请求频率压在正常阈值内，可显著抬高暴力破解与流量洪水攻击的成本。实现层可以是反向代理（如 nginx 的 limit_req）、WAF 或 API 网关的限流策略；中文版补充：对 API 接口进行速率限制也能防止业务数据被批量爬取。

2. 服务端使用 HTTPS，避免 MITM（中间人攻击）。HTTP 明文流量可被中间人窃听与篡改；启用 TLS 后，证书链校验保证通信方身份，加密保证数据机密性。英文原版进一步要求 TLS 1.2+ 与安全加密套件，并确保 Host 头与 SNI 一致——过时协议（SSLv3、TLS 1.0/1.1）与弱套件（RC4、3DES）应显式禁用。

3. 配合 SSL 使用 HSTS 头，防御 SSL Strip 攻击。攻击者可通过把 https:// 改写为 http:// 诱导降级，HSTS 让浏览器强制使用 HTTPS 访问该域名。建议配置：

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

注意 HSTS 只在用户首次通过 HTTPS 访问后生效，因此生产环境应尽早配置并考虑加入预加载列表。

4. 关闭目录列表。Web 服务器默认开启的目录索引（Apache Options -Indexes、nginx autoindex off）可能把源码、备份、配置文件暴露给扫描器。部署时逐一关闭静态资源目录的索引，并确保敏感文件不落在可公开访问的路径下。

5. 私有 API 仅允许白名单 IP/主机访问。对面向内部或合作方的私有接口，在网络层（防火墙、安全组）或应用层（API 网关 IP 白名单）收紧来源，只放行已知可信的 IP 段或主机。中文版补充的「禁止将内部组件接口、登录管理接口暴露于公网」与此同理。

四、授权（Authorization）：OAuth 实践

授权决定「已认证的用户能做什么」。清单聚焦 OAuth 流程中的四个高频漏洞点。

1. 始终在服务端校验 redirect_uri，只允许白名单 URL。攻击者常通过篡改重定向地址，把授权码或令牌回传给自己的服务器（授权码拦截攻击）。服务端必须把回调地址与注册时备案的白名单逐项比对，而不是信任客户端传入的值。

2. 优先使用 response_type=code，而非 response_type=token。授权码模式（Authorization Code Flow）中，浏览器只短暂持有有效期很短的 code，真正的 access_token 在服务端经「code + client_secret」换取，令牌不会出现在 URL 或浏览器历史里；而隐式授权（response_type=token）直接把令牌放回地址栏，泄露面显著更大，应禁止使用。

3. 使用携带随机哈希值的 state 参数，防御认证过程中的 CSRF。发起授权时生成随机 state 并绑定用户会话，回调时校验其一致性，防止攻击者诱导用户完成非预期的授权。示意如下：

https://provider.com/oauth/authorize?response_type=code&client_id=your-app&redirect_uri=https://yourapp.com/callback&scope=read&state=9f8a7b6c5d4e3f2a

4. 为每个应用定义默认 scope，并校验 scope 参数。不同应用应只被授予其业务所需的最小权限范围；对客户端请求的 scope 逐一验证，拒绝未登记或超范围的授权申请，避免「一次授权、全局放行」。

五、输入安全（Input）

输入是攻击面最大的入口，本节是清单中条目最多、最需要落到代码层的一节。

1. 按操作使用恰当的 HTTP 方法：GET（读取）、POST（创建）、PUT/PATCH（替换/更新）、DELETE（删除记录）。若请求方法不适用于目标资源，应返回 405 Method Not Allowed，而不是静默处理或返回 200。这能避免语义混乱带来的越权与缓存污染。

2. 校验请求 Accept 头（内容协商），只允许受支持的格式，如 application/xml、application/json 等；不匹配时返回 406 Not Acceptable。

3. 校验提交数据的 content-type 与正文一致，例如 application/x-www-form-urlencoded、multipart/form-data、application/json。声明的类型与解析方式不一致，常被用来绕过过滤规则。

4. 校验用户输入，规避常见漏洞：XSS（输出转义与 CSP 结合）、SQL-Injection（一律使用参数化查询/预编译语句，杜绝字符串拼接）、Remote Code Execution（禁用 eval 类动态执行、反序列化严格白名单）等。中文版额外提醒：避免使用类似 PHP extract 的函数把接口输入直接转成变量。

5. 不要在 URL 中携带敏感数据（credentials、密码、security tokens、API keys），统一放入标准的 Authorization 请求头。URL 会出现在访问日志、浏览器历史、代理日志与 Referer 头中，敏感信息一旦入 URL 便等于四处扩散。

6. 只使用服务端加密。密钥与加密运算留在服务端，避免把加解密能力与密钥材料下发到不可信的前端环境。

7. 使用 API Gateway 服务：统一启用缓存、限流策略（如 Quota 配额、Spike Arrest 尖峰抑制、Concurrent Rate Limit 并发限流），并能动态部署 API 资源。网关把认证、限流、审计等横切关注点从业务代码中剥离，是输入侧防御的重要基础设施。

六、处理层安全（Processing）

这一节关注请求进入业务逻辑之后的安全边界。

1. 确认所有端点都在认证保护之后，避免出现「被绕过的认证」——即某些内部端点、管理端点或遗留接口未挂接认证中间件。可通过路由扫描与自动化测试逐端点验证。

2. 避免在 URL 中使用资源 ID，用 /me/orders 替代 /user/654321/orders。前者由会话推导当前用户，天然避免把他人 ID 塞进请求；后者若缺权限校验，就是典型 IDOR（不安全的直接对象引用）。中文版补充：对访问的资源必须做权限检查，防止横向越权。

3. 不用自增 ID，改用 UUID。自增 ID 会泄露业务规模并允许遍历枚举；UUID（如 550e8400-e29b-41d4-a716-446655440000）不可枚举，且便于在分布式环境下无冲突生成。

4. 解析 XML 时确保实体解析（entity parsing）关闭，防范 XXE（XML 外部实体攻击）。攻击者通过 <!ENTITY xxe SYSTEM "file:///etc/passwd"> 读取服务器文件或发起 SSRF。多数解析器可显式禁用 DTD 与外部实体。

5. 解析 XML 时确保实体扩展（entity expansion）关闭，防范 Billion Laughs/XML bomb（十亿笑攻击）。嵌套实体引用会导致内存指数级膨胀，仅几十 KB 的文档即可耗尽服务器内存。英文原版补充：解析 YAML 等含锚点与引用的格式时同样要关闭实体扩展。

6. 文件上传使用 CDN。把上传流量与存储分发交给 CDN，业务服务器不直接落盘可执行内容，降低恶意文件上传与存储型攻击风险。

7. 面对大数据量处理，尽量用 Workers 与 Queues 在后台异步执行，快速返回响应，避免 HTTP 阻塞。长时间同步处理会导致连接超时与线程耗尽，应把重任务拆分为后台作业（消息队列 + 工作进程），接口仅返回任务受理状态。

8. 不要忘记关闭 DEBUG 模式。DEBUG 会输出堆栈、SQL、配置与内部路径等敏感信息，生产环境必须关闭。

9. 尽可能使用不可执行堆栈（non-executable stacks）。对上传目录、缓存目录等设置不可执行权限或 noexec 挂载，即使文件被上传也无法以代码形式执行，是纵深防御的重要一环。

七、输出安全（Output）

输出侧的核心是「给客户端最少的信息、最明确的状态」。

1. 发送 X-Content-Type-Options: nosniff 头，禁止浏览器对响应做 MIME 嗅探，防止内容类型混淆攻击。

2. 发送 X-Frame-Options: deny 头，禁止页面被 <iframe> 嵌入，抵御点击劫持（Clickjacking）。

3. 发送 Content-Security-Policy: default-src 'none' 头，默认拒绝一切内容加载来源，再按需放行，从根源上收缩 XSS 载荷的投递渠道。

4. 移除指纹头：X-Powered-By、Server、X-AspNet-Version 等会暴露技术栈与框架版本，为攻击者提供定向利用线索，应剥离或替换为通用值。

5. 强制响应 content-type：返回 application/json 时，响应头 content-type 必须是 application/json，避免「JSON 却标成 HTML」引发 MIME 混淆。

6. 不要把过于具体的错误信息返回给客户端——这类信息可能暴露实现细节（内部类名、SQL、文件路径）；应返回通用消息，详细日志只保留在服务端。例如用统一的 {"error": "Invalid credentials"} 替代底层异常原文，并在服务端日志记录完整上下文。

7. 不要返回敏感数据：credentials、密码、security tokens 等在任何响应中都不应出现。中文版补充：只返回前端业务需要的最小字段，敏感业务数据应在后端完成脱敏后再下发。

8. 按操作结果返回正确的状态码，如 200 OK、400 Bad Request、401 Unauthorized、405 Method Not Allowed 等。状态码语义混乱会让客户端与监控系统误判，也会掩盖攻击行为。

八、CI/CD 持续集成与持续部署

安全防线必须前移进流水线。

1. 用单元测试与集成测试的覆盖率审计设计与实现。安全回归测试（认证失效、越权、输入校验）应作为测试集的一等公民。

2. 引入代码审查流程，禁止自我批准（self-approval）。强制至少一名其他成员评审变更，防止单人绕过检查与后门提交。

3. 推送生产前，对所有服务组件做静态反病毒扫描，包括第三方库与依赖。供应链中的恶意或带毒组件需要独立扫描环节把关。

4. 持续运行安全测试（静态/动态分析）。SAST 扫描源码缺陷，DAST 对运行中的 API 做黑盒探测，两者结合覆盖开发期与运行期。

5. 检查依赖（软件与操作系统）的已知漏洞。利用依赖漏洞数据库（如 OSV、各语言的漏洞扫描工具）定期审计，并对中高危漏洞设修复时限。

6. 为部署设计回滚方案。发布异常时能快速回退到上一稳定版本，避免故障长时间在线。

九、监控（Monitoring）

发布只是开始，运行期监控负责发现「正在进行中的攻击」。

1. 所有服务与组件使用集中式日志。日志统一汇聚（如 ELK/Kibana 栈）才能跨服务关联请求链路，定位攻击入口。

2. 使用代理/采集器监控全部流量、错误、请求与响应。对状态码分布、异常请求体、超时率做基线化分析，偏离基线即可能是扫描或攻击。

3. 配置多渠道告警：SMS、Slack、Email、Telegram、Kibana、Cloudwatch 等。告警应分级，避免告警疲劳导致真正威胁被淹没。

4. 确保日志中不记录敏感数据：信用卡号、密码、PIN 等严禁入日志。日志脱敏（掩码、截断）与采集侧过滤应同步实施。

5. 使用 IDS 和/或 IPS 系统监控 API 请求与实例。入侵检测（IDS）发现异常特征，入侵防御（IPS）在检测到攻击时实时阻断，形成主动防御闭环。

十、进阶最佳实践（Advanced）

原文档在基础清单之后，额外收录了四组面向高安全要求的进阶实践（该部分在各语言版本中以英文保留），适合对安全等级有更高要求的团队直接套用。

10.1 限流与滥用防御（Rate Limiting & Abuse Prevention）

• 针对每个 API Key 与 IP 实施滑动窗口限流，比固定窗口更能抵御突发流量绕过；
• 对连续失败的认证尝试使用指数退避（exponential backoff），逐步拉大重试间隔；
• 检测到可疑行为后引入 CAPTCHA 或工作量证明（proof-of-work） 挑战；
• 监控并对异常 API 使用模式告警（时间、流量、端点维度），如凌晨高频调用、单端点突增等。

10.2 GraphQL 专属安全

• 生产环境关闭 introspection（内省查询），避免 schema 被完整枚举；
• 实现查询深度限制，防止深层嵌套查询拖垮后端；
• 使用查询成本分析，按字段与复杂度计费式限流，防止资源耗尽；
• 条件允许时在生产环境白名单化允许执行的查询，从源头消除任意查询风险。

10.3 密钥管理（Secrets Management）

• 按固定周期轮换 API Key 与密钥，压缩泄露后的暴露窗口；
• 签名操作使用硬件安全模块（HSM），密钥不出硬件；
• 在 CI/CD 流水线中集成密钥扫描，阻止密钥进入制品；
• 绝不在版本控制中提交密钥，一律使用环境变量或专用密钥管理服务（如 Vault、云 KMS）。

10.4 零信任架构（Zero Trust Architecture）

• 服务间通信启用双向 TLS（mTLS），双方互验证书；
• 即使来自内部服务的请求也一律校验，默认不信任内网；
• 使用短期令牌并自动刷新，缩短令牌被窃后的有效期；
• 对敏感操作实施请求签名，确保请求内容未被篡改且来源可信。

十一、多语言版本与参与贡献

由于清单覆盖面广且表述精炼，多语言版本让各国团队都能直接使用。当前仓库收录了简中、繁中、越南语、日语、韩语、俄语等 30 余种翻译，其中 README-zh.md 相比英文原版补充了若干实战条目（登录失败模糊提示、禁止默认 Key、防止横向越权、后端脱敏、API 资产梳理等），可作为中文团队的进阶参考；而越南语版与英文版内容几乎一一对应，适合对照学习。

如需补充或修正条目，可参考 CONTRIBUTING.md 的流程：fork 仓库 → 基于 README.md 翻译或修改 → 按 README-[语言代码].md 命名新增文件 → 提交 Pull Request。项目以 MIT 协议（见 LICENSE）开放，清单内容可自由引入团队流程。建议的做法是把本文逐节内容整理为团队内部的可勾选模板，在设计评审、发布前检查与安全巡检三个节点固定执行，让这份「设计、测试、发布全生命周期安全清单」真正落地。