security-best-practices

安全最佳实践

概述

此技能介绍如何识别当前上下文所使用的语言和框架，然后从此技能的 references 目录中加载有关这些语言和／或框架的安全最佳实践信息。

如果有这些信息，可用于编写默认安全的新代码，主动检测现有代码中的重大问题，或在用户提出要求时提供漏洞报告并建议修复方案。

工作流

此技能的第一步是识别你需要使用的，或已存在于当前项目范围内的所有语言和所有框架。重点关注主要核心框架。通常需要同时识别前端和后端的语言与框架。

然后检查此技能的 references 目录，查看是否有适用于相关语言和／或框架的文档。请确保阅读所有与特定框架或语言相关的参考文件。文件名格式为 <language>-<framework>-<stack>-security.md。还应检查是否有 <language>-general-<stack>-security.md 文件，该文件不依赖于特定框架。

如果你正在处理包含前端和后端的 Web 应用，请确保已检查前端和后端的参考文档！

如果用户要求制作同时包含前端和后端的 Web 应用，但未指定前端框架，也要查看 javascript-general-web-frontend-security.md。了解如何保护前端和后端都很重要。

如果技能的 references 目录中没有相关信息，请稍作思考，运用你对该语言、框架及其广为人知的安全最佳实践的了解。如果不确定，可以尝试在线搜索安全最佳实践文档。

接下来，可以采用以下几种方式。

1. 主要模式是从此刻起使用这些信息编写默认安全的代码。这适用于启动新项目或编写新代码。

2. 次要模式是在项目中工作并为用户编写代码时，主动检测漏洞。对于严重或非常重要的漏洞，或违背安全指导的重大问题，可以标记出来并告知用户。此主动模式应关注影响最大的漏洞和安全默认设置。

3. 用户可以要求提供安全报告或提升代码库的安全性。在这种情况下，应生成一份完整报告，说明项目未遵循安全最佳实践指导的所有方面。报告应按优先级排序，并明确列出严重程度和紧急程度。然后提出着手修复这些问题。请参阅下文的 #fixes。

工作流决策树

• 如果无法确定语言／框架，请检查代码库以确定它们，并列出依据。
• 如果 references/ 中有匹配的指导，只加载相关文件并遵循其中的说明。
• 如果没有匹配的指导，请考虑你是否了解所选语言和／或框架的常见安全最佳实践；但如果用户要求生成报告，应告知用户目前没有具体指导（仍可生成报告，或检测确定无疑的严重漏洞）。

供应链与依赖项安全

现代应用严重依赖第三方软件包。务必评估：

1. 依赖项审计：

   # Node.js
   npm audit
   npx better-npm-audit audit --level moderate
   
   # Python
   pip-audit
   safety check
   
   # Go
   govulncheck ./...
   

2. 锁定文件完整性：确保已提交 package-lock.json、yarn.lock、poetry.lock 或 go.sum，且文件可复现。

3. 仿冒包名：检查是否存在名称与热门软件包非常相似的软件包（例如，lodahs 与 lodash）。

4. CI 中固定版本：在 CI/CD 中使用精确版本或摘要，而非版本范围。

5. 生成 SBOM：对于生产应用，建议生成软件物料清单：

   # Node.js
   npx @cyclonedx/cyclonedx-npm --output-file sbom.json
   
   # Python
   cyclonedx-py environment -o sbom.json
   

密钥管理

代码中的密钥是一个严重且常见的问题。检查以下内容：

• 硬编码的 API 密钥、令牌、密码、连接字符串
• 已提交到 git 的 .env 文件（检查 .gitignore）
• 会被记录到日志中的环境变量密钥
• Docker 构建参数中的密钥（可在镜像历史记录中看到）

检测工具：

# Gitleaks — scan git history for secrets
gitleaks detect --source . --verbose

# TruffleHog — scan git history
trufflehog git file://. --since-commit HEAD~20

# Detect-secrets
detect-secrets scan --all-files

推荐模式：

• 使用密钥管理器（AWS Secrets Manager、HashiCorp Vault、GCP Secret Manager、Azure Key Vault）
• 如果密钥泄露，立即轮换；不要只从 git 中删除（历史记录中仍然保留着它们）
• 使用 git filter-repo 从历史记录中清除泄露的密钥

覆盖规则

虽然这些参考资料包含针对语言和框架的安全最佳实践，但客户可能会遇到需要绕过或覆盖这些实践的情况。请留意项目文档和提示词文件中的具体规则和说明，它们可能要求你覆盖某些最佳实践。覆盖最佳实践时，你可以向用户说明，但不要与他们争辩。如果出于特定项目原因需要绕过或忽略某项安全最佳实践，也可以建议在项目中添加相关文档，明确说明不遵循该最佳实践的原因，并确保今后继续遵循这一绕过做法。

报告格式

生成报告时，应将报告写入 Markdown 文件 security_best_practices_report.md，或者写入用户指定的其他位置。你可以询问用户希望将报告写在哪里。

报告顶部应有简短的执行摘要。

报告应根据漏洞严重程度清晰划分为多个部分。报告应重点列出影响最大的关键发现。所有发现都应标注数字 ID，以便于引用。

对于严重发现，请附上一句影响说明。

写好报告后，还应直接向用户汇报，但内容可以简洁一些。如果用户想进一步了解任何发现或安全最佳实践建议背后的原因，可以主动提出为其解释。

重要提示：在报告中引用代码时，务必找到并注明所引用代码的行号。

写完报告文件后，向用户总结发现。

还要告知用户最终报告的写入位置

修复

如果你生成了报告，请让用户阅读报告，并询问是否开始修复。

如果你被动发现了严重问题，请通知用户，并询问他们是否希望你修复此问题。

执行修复时，每次专注于修复一个问题。应添加简洁明了的注释，说明新代码基于哪项具体的安全最佳实践，以及不这样做可能带来的简短风险。

始终考虑计划进行的更改是否会影响用户代码的功能。考虑这些更改是否可能导致项目现有工作方式出现回归。通常，不安全代码之所以长期存在，是因为它还有其他用途。避免破坏用户的项目，否则他们将来可能不愿采用安全修复。与其仓促敷衍地更改，不如结合项目其余部分，经过充分考量后再修复。

始终遵循用户配置的常规更改或提交流程。如果要创建 git 提交，请提供清晰的提交说明，解释此更改旨在符合安全最佳实践。尽量避免在单个提交中捆绑多个无关问题。

始终遵循用户配置的常规测试流程（如果有），以确认更改不会引入回归。考虑这些更改可能带来的二阶影响；如果存在，请在进行更改前告知用户。

通用安全建议

以下是适用于几乎所有语言或框架的一些安全编码建议。

避免使用递增 ID 作为资源的公开 ID

为资源分配 ID 时，如果该资源将暴露给互联网使用，请避免使用较小的自动递增 ID。改用更长的随机 UUID4 或随机十六进制字符串。这样可以防止用户获知资源数量，并猜测资源 ID。

关于 TLS 的说明

虽然 TLS 对生产部署很重要，但大多数开发工作会禁用 TLS，或使用超出审查范围的 TLS 代理。鉴于此，请谨慎避免将缺少 TLS 报告为安全问题。此外，也要谨慎处理“安全” Cookie。只有当应用实际通过 TLS 运行时，才应设置这类 Cookie。如果应用未使用 TLS（例如部署用于本地开发或测试时）却设置了这类 Cookie，应用将无法正常工作。你可以提供环境变量或其他标志来控制是否设置安全属性，以便在部署到使用 TLS 的生产环境之前保持关闭。此外，避免建议使用 HSTS。若未充分理解其长期影响（可能导致严重服务中断并使用户无法访问），使用 HSTS 会很危险，而且通常不建议在 codex 所审查的项目范围内使用。

常见陷阱

本节记录了应用安全最佳实践时已知的失败模式和边缘情况：

1. Agent 缺少上下文的漏洞

陷阱： Agent 认为安全最佳实践适用于所有代码上下文，却不了解用户项目的具体约束、威胁模型或部署环境。

表现形式：

• 推荐与用户已记录的需求相冲突的严格安全控制
• 将安全实践标记为漏洞，而用户已通过外部控制（例如网络隔离、反向代理加固）缓解了相关风险
• 对所有项目一视同仁地强调安全紧迫性（并非所有系统都需要相同的威胁模型）

缓解方法：

• 生成安全报告或准备修复方案时，先询问项目的威胁模型、部署环境和现有安全控制，再提出建议
• 阅读用户提供的任何安全文档、架构决策或威胁分析
• 应用修复时，确认不会破坏项目特定需求或现有缓解措施
• 允许用户在记录了理由的情况下覆盖最佳实践（并建议将相关说明添加到项目文档中）

2. 在本地开发中误报 TLS/HTTPS 问题

陷阱： 在尚未部署 TLS 的本地开发、测试或 CI 环境中，将缺少 HTTPS 或 TLS 标记为安全漏洞。

表现形式：

• 建议为 localhost 开发服务器强制启用 HTTPS/TLS
• 在不需要时建议设置自签名证书
• 未考虑 TLS 由范围之外的反向代理或基础设施层处理
• 未能区分开发环境与生产部署环境

缓解方法：

• 始终询问部署环境：这是开发、测试、预发布还是生产环境？
• 假设大多数开发工作会禁用 TLS，或由外部代理提供 TLS
• 除非明确属于生产部署，否则不要将缺少 TLS 报告为安全问题
• 考虑提供环境标志，仅在生产环境中启用 TLS 专属保护

另请参阅上文的 关于 TLS 的说明，了解相关指导

3. 过度应用“安全”Cookie 标志

陷阱： 建议在开发环境中设置 Secure、HttpOnly 和 SameSite Cookie 标志，导致应用在非 TLS 连接（localhost、仅支持 HTTP 的开发服务器）上运行时出错。

表现形式：

• Cookie 被标记为 Secure，但开发服务器使用 HTTP，导致 Cookie 被静默丢弃
• 本地测试中的应用登录莫名失败
• 测试因缺少身份验证 Cookie 而失败
• 开发体验受到破坏，但代码看起来像是“修复”了

缓解方法：

• 建议设置安全 Cookie 标志前，始终检查当前部署环境
• 建议按环境配置：仅在生产环境中设置 Secure，而非开发环境
• 在任何修复中清楚记录此模式（例如，secure: process.env.NODE_ENV === 'production'）
• 应用更改后测试依赖 Cookie 的流程（登录、会话管理）
• 更改前警告用户：“这会导致非 TLS 环境中的 Cookie 处理失效”

另请参阅上文的 关于 TLS 的说明，了解相关指导

4. 未说明何时可以忽略最佳实践

陷阱： 将所有安全最佳实践都视为绝对规则，却没有承认偏离、覆盖或推迟这些做法的合理原因。

表现：

• 对可以逐步采用的做法，建议进行破坏性变更
• 将变通方案标记为漏洞，却不说明技术债务方面的权衡
• 未建议如何逐步弃用不安全的模式
• 将架构决策视为简单的最佳实践违规

缓解措施：

• 说明最佳实践与其他要求（性能、兼容性、时间安排）冲突的情况
• 建议分阶段实施方案：“这确实值得关注。我们可以现在处理［选项 A］、采取［缓解措施 B］后推迟处理，或接受风险［并记录在案］”
• 始终提供后续方案，即使不是理想的“立即修复”方案
• 记录偏离做法的原因，以便日后重新审视
• 未经用户明确同意，绝不强行实施会破坏功能或用户体验的“安全”修复

5. 缺乏上下文的被动检测

陷阱： Agent 工作期间被动地指出安全问题，却没有了解用户是希望主动监控安全，还是专注于交付功能。

表现：

• 在功能实现过程中，因用户已知的模式而打断工作并发出安全警告
• 将继承的代码（旧系统、第三方依赖项）标记为漏洞，即使无法修改这些代码
• 在快速原型开发或概念验证过程中，将所有代码都视为可投入生产的代码，从而造成阻碍

缓解措施：

• 仅被动指出严重或极高严重性的漏洞
• 询问具体情况：这是原型、旧系统，还是生产代码？
• 聚焦影响最大的漏洞，而非轻微偏离最佳实践的问题
• 如果指出问题，应主动提出解释原因，并说明是否需要立即修复
• 尊重用户的优先事项：他们可能有充分理由权衡安全性