• 网络安全
• 应用安全

本文以仓库德语版清单 README-de.md 为骨架，系统梳理 API 在设计、测试与发布阶段最重要的 64 项安全对策，覆盖身份认证、访问控制、OAuth 授权、输入校验、数据处理、输出加固、CI/CD 与监控，并附上仓库英文原版 README.md 与中文版 README-zh.md 中的差异化条目作为深化佐证。读完本文，你将得到一份可直接用于工程安全评审、上线前检查与日常运维的完整对照表，并能逐条理解每项措施背后的攻击场景与落地要点。

一、清单概览：一张覆盖 API 全生命周期的安全对照表

API-Security-Checklist 是一个以"清单（Checklist）"形态组织的开源安全知识库，其德语版 README-de.md 开篇即点明主题："Checkliste für die wichtigsten Sicherheitsmaßnahmen beim Designen, Testen und Veröffentlichen deiner API"——即"面向 API 设计、测试与发布阶段最重要安全措施的核对清单"。

整份清单按安全领域划分为8 个核心板块（身份认证、访问控制、授权、输入、处理、输出、CI/CD、监控），末尾另附4 组进阶最佳实践（限流与滥用防护、GraphQL 专属安全、密钥管理、零信任架构），总计约 64 个勾选项。每个条目以- [ ]待勾选形式呈现，天然适合直接打印为评审表，或在工程立项、迭代发布、安全审计时逐项打勾确认。

该仓库在根目录维护了 30+ 种语言的翻译版本（德、中、日、法、俄、阿拉伯语等），其中英文原版 README.md、简中版 README-zh.md、繁中版 README-tw.md、日文版 README-ja.md 均在仓库根目录可见。多语言版本在核心框架一致的前提下存在细节差异——例如英文原版在 HTTPS 条目中额外注明TLS 1.2+、安全密码套件与Host头/SNI 匹配要求，中文版则补充了防爬取限速、SourceMap 暴露、数据脱敏等条目。本文以德语版为绝对主体，并在对应小节中以"仓库佐证"形式呈现这些差异，供对照取用。

二、身份认证（Authentifizierung）：放弃自研，拥抱标准

德语版清单在"Authentifizierung"板块给出 4 项硬性要求：

1. 不要使用Basic Auth，改用标准化的认证方法。Basic Auth 将用户名与密码以 Base64 明文编码放入Authorization头，几乎等于明文传输凭据，且无法提供细粒度权限与过期机制。应改用 OAuth 2.0 / OpenID Connect、SAML 或平台托管的身份服务等标准协议。
2. 不要在Authentication（认证）、Tokengenerierung（令牌生成）、Passwort speichern（密码存储）上重复造轮子，请使用现有标准。密码散列应使用经过专门设计的慢哈希算法（如 bcrypt、scrypt、Argon2），令牌生成应使用密码学安全的随机源，而不是Math.random()之类的伪随机实现。
3. 在登录流程中启用"有限次数的登录尝试 + 锁定功能"（limitierte Anzahl von Anmeldeversuche与 Aussperrfunktionen：Ban、IP-Block、Permanent）。即：允许失败重试次数有上限，超过后按账号冻结（Ban）、按 IP 封锁（IP-Block）或长期禁止（Permanent）三级递进处置。
4. 对所有敏感数据使用加密。无论是数据库中的凭据、传输中的令牌还是配置文件中的密钥，都应遵循"静态加密 + 传输加密"双重保护。

仓库佐证：中文版 README-zh.md 在身份认证板块进一步补充了三条与本板块同源但更细致的条目——"密码或账号登录失败时返回模糊的提示信息，防止暴力破解攻击""不要将 API Key、云组件 Key 等硬编码到前端页面或 APP 中""使用开源框架时禁止使用默认 Key（如 Shiro）"，可作为德语版第 3、4 条的具体落地补充。

三、访问控制（Zugriff）：在入口处挡住绝大多数攻击

本板块共 5 项措施，全部聚焦"请求到达业务代码之前"的防线：

1. 限制所有请求（Throttling），防止 DDoS 与暴力破解。速率限制应区分"每用户/每 IP/每 API Key"维度，超出阈值的请求直接返回429 Too Many Requests，让攻击流量在网关层即被消化。
2. 服务端使用 HTTPS，防止 MITM（中间人攻击）。仓库佐证：英文原版 README.md 在此条目上写得更细——要求"HTTPS on server side with TLS 1.2+ and secure ciphers ... ensure Host header matches the SNI"，即加密协议版本至少 TLS 1.2、必须配置安全密码套件，并确保 HTTPHost头与 TLS SNI 一致，防止虚拟主机层面的会话劫持。
3. 启用 SSL 时设置HSTS（HTTP Strict Transport Security）头，防止 SSL Strip 攻击。HSTS 通过Strict-Transport-Security: max-age=<秒数>; includeSubDomains告知浏览器"本域名只能走 HTTPS"，从而阻断攻击者把 HTTPS 降级为 HTTP 的中间人手法。
4. 关闭目录列表（Deaktivieren Verzeichniseinträge）。即禁止 Web 服务器对目录返回索引页面，避免暴露项目结构、文件名与静态资源清单。
5. 私有 API 仅允许白名单中的 IP/主机访问。在网关或安全组层设置 allowlist，不面向公网开放内部服务。

仓库佐证：中文版 README-zh.md 在此板块额外强调"对 API 接口访问进行速率限制防止业务数据被批量爬取""禁止将内部组件接口、登录管理接口暴露于公网中""禁止将 SourceMap 文件暴露到公网""禁止将 API 接口描述文档暴露到公网"等条目，与德语版第 1、5 条形成互补，实际评审时可合并使用。

四、授权（Autorisierung）：OAuth 的四条红线

授权板块专门针对 OAuth 授权流程，共 4 项：

1. 始终在服务端校验redirect_uri，只允许白名单内的 URL。攻击者常通过篡改redirect_uri把授权码重定向到自己的域名，从而窃取授权码；校验必须在服务端完成，而非依赖前端。
2. 始终用授权码（Access-Code）换取访问令牌，禁止response_type=token。response_type=token会把令牌直接放在浏览器重定向 URL 的 Fragment 中，增加令牌被历史记录、Referrer 泄露的风险；应采用authorization_code模式，由服务端在受保护的后端通道兑换令牌。
3. state参数必须携带随机哈希，防止针对 OAuth 授权过程的 CSRF。state的作用是绑定"本次授权请求"与"回调响应"，随机值应在服务端生成并在回调时严格比对。
4. 为每个应用定义默认 scope，并校验所有 scope 参数。不校验 scope 可能导致权限越权——攻击者可请求超过应用应有权限的范围。

五、输入安全（Input）：从源头拒绝脏数据

输入板块共 7 项，是清单中篇幅最大的板块之一，强调"所有进入 API 的字节都必须被质疑"：

1. 按操作语义使用正确的 HTTP 方法：GET（读取）、POST（创建）、PUT/PATCH（替换/更新）、DELETE（删除记录）；若请求方法不适用于目标资源，返回405 Method Not Allowed。
2. 校验请求Accept头中的 content-type（内容协商），只允许受支持的格式（如application/xml、application/json），不匹配时返回406 Not Acceptable。
3. 校验 POST/PUT 传入数据的Content-Type，确保声明与正文一致，允许的范围示例包括application/x-www-form-urlencoded、multipart/form-data、application/json等；不匹配时应直接拒绝，防止内容解析歧义被利用。
4. 始终校验请求中所有输入与参数，以防范常见攻击面：XSS（跨站脚本）、SQL-Injection（SQL 注入）、Remote Code Execution（远程代码执行）等。校验应覆盖长度、类型、字符集、枚举范围与业务规则，且永远不做"仅前端校验"。
5. 绝不在 URL 中携带敏感数据（Anmeldedaten凭据、Passwörter密码、Security Tokens安全令牌、API-SchlüsselAPI 密钥），一律使用标准化的Authorization请求头。URL 会出现在服务器访问日志、代理日志、浏览器历史与 Referrer 中，泄露面极大。
6. 只使用服务端加密。密钥与加解密操作必须留在服务端可信环境，前端只负责展示与服务端约定的密文。
7. 使用 API Gateway 服务，统一提供缓存、限流策略（如Quota配额、Spike Arrest尖峰抑制、Concurrent Rate Limit并发限制）以及 API 资源的动态部署。将上述能力沉淀到网关层，业务代码即可专注逻辑，同时获得一致的策略实施点。

六、数据处理（Verarbeitung）：让业务代码更安全、更抗压

处理板块共 9 项，覆盖认证保护、ID 设计、XML 解析、大流量与运行环境配置：

1. 检查所有端点是否都被认证保护，避免"破坏性认证"（broken authentication）——只要有一个端点遗漏认证，整个认证体系形同虚设。仓库佐证：英文原版 README.md 明确写为"Check if all the endpoints are protected behind authentication to avoid broken authentication process"，可配合自动化扫描定期核对全量路由。
2. 避免暴露用户自有资源 ID：用/me/orders代替/user/654321/orders，从路由层面杜绝"遍历他人 ID"的越权尝试。
3. 不使用自增 ID，改用UUID。自增 ID 可被顺序枚举、泄露业务规模；UUID 提供不可预测性，降低资源被猜测命中的风险。
4. 解析 XML 时确保实体解析（Entity Parsing）处于关闭状态，防止XXE（XML External Entity，外部实体注入）攻击。未关闭时，攻击者可通过构造外部实体读取服务器本地文件或发起内网 SSRF。
5. 解析 XML 时确保实体扩展（Entity Expansion）处于关闭状态，防止Billion Laughs/XML-Bombe（十亿笑/XML 炸弹）指数实体扩展攻击。仓库佐证：英文原版 README.md 将本条扩展为"If you are parsing XML, YAML or any other language with anchors and refs ..."，即同样存在锚点/引用机制的语言（如 YAML）也需禁用实体扩展，防止资源耗尽型 DoS。
6. 文件上传使用 CDN，将存储与分发流量剥离出应用服务器，既缓解带宽压力，也避免把可执行上下文暴露在业务进程内。
7. 处理大量数据时使用 Worker 与队列（Queues），尽量将耗时计算放入后台异步处理，快速返回响应，避免 HTTP 阻塞（对应英文版"avoid HTTP Blocking"）。
8. 别忘了关闭 DEBUG 模式。生产环境开启 DEBUG 会泄露堆栈、SQL、配置与内部路径，是最常见也最容易被忽视的泄露源。
9. 尽可能使用不可执行栈（Nicht ausführbare Stacks），例如将上传目录、静态资源目录的代码执行权限关闭，防止上传即命令执行。

仓库佐证：中文版 README-zh.md 在此板块还补充了"对访问资源进行权限检查，防止横向越权"与"禁止使用类似 PHPextract函数将接口输入参数转换为变量"两条实践，可视为第 2 条（资源 ID）与第 4 条（输入解析）的姊妹条目。

七、输出安全（Output）：响应头与响应体同样需要加固

输出板块共 8 项，核心思想是"响应不泄露任何超出必要的信息"：

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：返回 JSON 时Content-Type必须为application/json，防止内容被按 HTML 解析。
6. 不要向客户端返回过于具体的错误信息（德语原文此条以英文保留："Do not return overly specific error messages to the client that could reveal implementation details, use generic messages instead, and log detailed information only on the server side"）——客户端给通用错误文案，详细信息只写入服务端日志。
7. 绝不返回敏感数据：Anmeldedaten凭据、Passwörter密码、Sicherheitsschlüssel安全密钥等一律不得出现在响应中。
8. 根据操作结果返回恰当的 HTTP 状态码：如200 OK、400 Bad Request、401 Unauthorized、405 Method Not Allowed等，让调用方与监控系统能准确判断语义。

仓库佐证：中文版 README-zh.md 在输出板块进一步补充了"返回统一的错误页面，勿将调用堆栈展示在错误页面""仅返回前端需要的业务数据，禁止返回过多类型敏感数据""数据返回时在后端进行脱敏（禁止前端脱敏）"三条，正好是第 6、7 条的落地细化，可作为输出安全评审的扩展检查项。

八、持续集成与持续交付（CI & CD）：把安全左移到流水线

CI/CD 板块共 6 项，强调"安全必须成为发布流水线的固定环节"：

1. 用单元测试与集成测试及其覆盖率（Test Coverage）来审计设计实现。
2. 建立代码评审（Code Review）流程。德语版特别强调"bleib sachlich"（保持客观），英文原版 README.md 对应表述为"disregard self-approval"（不允许自我批准合并），即评审必须独立于作者。
3. 所有组件（第三方库与全部依赖）在进入生产环境前必须经杀毒软件静态扫描，把供应链风险挡在发布之前。
4. 持续对代码执行安全测试（静态/动态分析，SAST/DAST），形成常态化的自动化安全门禁。
5. 检查依赖（软件与操作系统层面）的已知漏洞，例如维护 CVE 基线、订阅漏洞公告，并在流水线中设置阻断条件。
6. 为部署设计回滚（Rollback）方案，确保故障发生时能快速恢复上一稳定版本。

九、监控（Überwachung）：看得见，才能守得住

监控板块共 5 项：

1. 所有服务与组件使用集中式日志（Zentralisierte Logins），将分散在各节点的日志统一汇聚，便于关联分析与故障定位。
2. 使用 Agent 监控全部流量、错误、请求与响应，形成完整的可观测性数据面。
3. 配置多渠道告警：SMS、Slack、Email、Telegram、Kibana、Cloudwatch 等，确保异常事件能第一时间触达值班人员。
4. 确保日志中不记录敏感数据：信用卡号、密码、PIN 等一律禁止入日志，防止日志系统成为新的数据泄露点。
5. 使用 IDS（入侵检测系统）和/或 IPS（入侵防御系统）监控 API 请求与实例，识别攻击特征并主动阻断。

仓库佐证：中文版 README-zh.md 额外补充了"使用 API 检测设备进行 API 资产梳理、日志审计"一条，属于第 1、5 条在资产可视化管理维度上的延伸。

十、进阶最佳实践（Advanced）：面向高对抗环境的四项加固

德语版 README-de.md 在基础清单之后，以英文附了 4 组进阶最佳实践（此部分与英文原版保持一致），适合高价值业务、公网暴露面大或安全合规要求高的 API：

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

• 针对每个 API Key 和 IP实现滑动窗口（sliding window）限流，比固定窗口更平滑、更难被绕过；
• 对反复失败的认证尝试采用指数退避（exponential backoff），加大暴力破解的时间成本；
• 可疑活动后引入CAPTCHA 或工作量证明（proof-of-work）挑战；
• 对异常 API 使用模式（时间、量级、端点分布）进行监控与告警。

10.2 GraphQL 专属安全（GraphQL-Specific Security）

• 生产环境关闭 introspection（内省），避免攻击者枚举完整 schema；
• 实施查询深度限制（query depth limiting），防止嵌套查询攻击耗尽资源；
• 使用查询成本分析（query cost analysis），防止复杂查询导致资源耗尽；
• 生产环境尽可能对允许执行的查询做白名单。

10.3 密钥管理（Secrets Management）

• 按固定周期轮换 API Key 与密钥；
• 签名操作使用**硬件安全模块（HSM）**承载密钥；
• 在 CI/CD 流水线中实施密钥扫描（secret scanning），拦截硬编码泄露；
• 绝不让密钥进入版本控制，改用环境变量或密钥管理服务。

10.4 零信任架构（Zero Trust Architecture）

• 服务间通信启用双向 TLS（mTLS）；
• 内部服务发来的请求同样要校验，不因来源可信而豁免；
• 使用短生命周期令牌并自动刷新，压缩令牌泄露的窗口；
• 对敏感操作实施请求签名（request signing），保证来源与完整性。

十一、延伸阅读与参与贡献

德语版清单末尾的"Siehe auch"（参见）板块附有两个外部参考资料：其一是面向 RESTful HTTP+JSON API 构建的工具集合，其二是一篇"无需 JWT，直接使用随机生成的 API Key；若确需非对称加密或防篡改，可参考 JWT 替代方案"的讨论。上述外部链接可在英文原版 README.md 末尾查看（本文按规范不输出外部地址）。

本清单面向社区开放协作：CONTRIBUTING.md 明确了贡献方式——fork 仓库、修改、提交 Pull Request，并通过邮件联系维护团队；同时规定了新增翻译的命名规范README-[Language-code].md（例如德语对应 README-de.md，日语对应 README-ja.md，中文对应 README-zh.md）。仓库其余多语言版本均可作为核对清单的团队内部分发介质。

结语：把清单变成流程，而不是墙上的纸

API-Security-Checklist 的价值不在于条目数量，而在于它把"设计、测试、发布"三个阶段的安全要求压缩成一张可执行、可评审、可自动化的对照表。落地建议如下：

• 设计期：以"身份认证—访问控制—授权—输入"四板块为架构评审红线；
• 开发与测试期：用"处理—输出"两板块指导代码实现与测试用例设计，配合 CI/CD 板块的测试覆盖率、SAST/DAST 与依赖漏洞检查形成流水线门禁；
• 发布与运行期：以"输出—监控"两板块做上线前最后检查，并持续运行限流、密钥轮换与零信任加固等进阶实践。

将本文所列 64 项逐条映射到你的工程中，指定负责人与完成状态，API 的安全性就能从"经验判断"升级为"可度量、可追溯、可复盘"的工程流程。

• 网络安全
• 应用安全