shared-security-auth-security

安全模式

快速指南： 管理机密信息？使用 .env.local（已加入 gitignore），以及 CI 机密信息；若发生泄露或团队变动，请轮换机密信息。依赖项安全？启用自动扫描（Dependabot），并在 24 小时内修复严重漏洞。防止 XSS？现代框架默认会自动转义输出，除非使用 DOMPurify 清理，否则绝不要绕过保护直接注入原始 HTML。设置 CSP 标头。CODEOWNERS？要求安全团队审核 auth/、.env.example 和工作流文件。

详细资源：

• 代码示例请参见 examples/core.md（基本模式）
• 决策框架和反模式请参见 reference.md

其他示例：

• examples/xss-prevention.md - XSS 防护、DOMPurify、CSP 标头
• examples/dependency-security.md - Dependabot、CI 安全检查
• examples/access-control.md - CODEOWNERS、速率限制、分支保护

---

<critical_requirements>

重要：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（绝不能将机密信息提交到代码库——只能使用 .env.local 和 CI 机密信息）

（渲染原始 HTML 前，必须清理所有用户输入——注入任何 HTML 前都要使用 DOMPurify）

（必须在 24 小时内修复严重/高危漏洞——使用 Dependabot 进行自动扫描）

（身份验证令牌必须使用 HttpOnly Cookie——绝不能使用 localStorage 或 sessionStorage）

（必须为安全敏感文件配置 CODEOWNERS——要求安全团队批准）

</critical_requirements>

---

自动检测： 安全、机密信息管理、XSS 防护、CSRF 防护、Dependabot、漏洞扫描、身份验证、DOMPurify、CSP 标头、CODEOWNERS、HttpOnly Cookie

适用场景：

• 安全地管理机密信息（绝不提交到代码库，使用 .env.local 和 CI 机密信息）
• 设置 Dependabot 以自动扫描漏洞
• 防止 XSS 攻击（框架自动转义、DOMPurify、CSP 标头）
• 为安全敏感代码配置 CODEOWNERS
• 实现安全的身份验证和令牌存储

不适用场景：

• 一般代码质量审查（不属于安全问题）
• 性能优化（不同领域）
• CI/CD 流水线设置（此处的安全模式针对代码，而非基础设施）
• 安全审查会延误关键热修复时（记录下来以便后续跟进）

涵盖的关键模式：

• 绝不提交机密信息（.gitignore、CI 机密信息、每季度轮换策略）
• 使用 Dependabot 自动扫描依赖项（严重漏洞须在 24 小时内修复）
• XSS 防护（框架自动转义、使用 DOMPurify 处理 HTML、CSP 标头）
• 使用令牌和 SameSite Cookie 防护 CSRF
• 为安全敏感区域配置 CODEOWNERS（.env.example、auth 代码、工作流）
• 安全存储令牌（HttpOnly Cookie、内存中的访问令牌）

---

## 理念

安全不是一项功能，而是基础。每一行代码都必须将安全纳入考量。纵深防御意味着设置多层保护，这样即使某一层失效，其他层也能拦截攻击。

何时使用安全模式：

• 始终如此——安全不是可选项
• 处理用户输入时（进行清理和验证）
• 管理机密信息时（环境变量、轮换）
• 存储身份验证令牌时（HttpOnly Cookie）
• 设置 CI/CD 时（漏洞扫描、CODEOWNERS）

绝不妥协的事项：

• 绝不在生产环境中跳过 HTTPS
• 绝不只信任客户端验证
• 绝不将机密信息提交到代码库
• 绝不使用 localStorage 存储敏感令牌
• 绝不绕过关键代码的安全审查

核心原则：

• 最小权限：仅授予必要的最低权限
• 纵深防御：设置多层安全防护
• 安全失败：默认拒绝，而非允许
• 不要信任用户输入：始终进行验证和清理
• 假设已遭入侵：为攻击发生做好准备（关注“何时发生”，而非“是否发生”）

---

核心模式

模式 1：机密信息管理

绝不将机密信息提交到代码库。开发时，在 .env.local（已加入 gitignore）中使用环境变量；生产环境则使用 CI/CD 机密管理器。每季度轮换机密信息，或在团队成员离职时轮换。

什么是机密信息

机密信息包括：API 密钥、令牌、密码、数据库凭据、私钥、证书、OAuth 客户端机密、加密密钥、JWT 机密。

机密信息的存储位置

开发环境：

• .env.local（已加入 gitignore）
• 每位开发者的本地覆盖配置
• 绝不提交到代码库

CI/CD：

• GitHub Secrets
• Vercel Environment Variables
• GitLab CI/CD Variables
• 其他平台的机密管理器

生产环境：

• 环境变量（由平台注入）
• 机密管理服务（AWS Secrets Manager、HashiCorp Vault）
• 绝不在代码中硬编码

轮换策略

注意： NIST SP 800-63-4（2025）建议不要强制要求用户定期更换密码。应改为基于事件进行轮换（发生泄露、团队成员离职或安全事件时）。仍建议定期轮换服务账号和特权访问凭据。

机密信息类型	轮换频率
服务账号凭据	90 天（每季度）
API 密钥	365 天（每年）或发生泄露时
用户密码	仅在发生泄露时（NIST 2025 指南）
特权账号密码	90 天（每季度）
证书	到期前 30 天发出警告
所有机密信息	团队成员离职时立即轮换

代码示例参见 examples/core.md。

---

模式 2：依赖项安全

启用 Dependabot 自动漏洞扫描，及时发现依赖项中的安全问题。严重漏洞须在 24 小时内修复，高危漏洞在 1 周内修复，中危漏洞在 1 个月内修复。

更新策略

安全更新：

• 严重漏洞——立即修复（24 小时内）
• 高危漏洞——1 周内修复
• 中危漏洞——1 个月内修复
• 低危漏洞——在下一个常规更新周期修复

常规更新：

• 补丁更新（1.2.3 -> 1.2.4）——测试通过后自动合并
• 次要版本更新（1.2.0 -> 1.3.0）——审查变更、测试并合并
• 主要版本更新（1.0.0 -> 2.0.0）——规划迁移并全面测试

Dependabot 配置和 CI 安全检查脚本参见 examples/dependency-security.md。

---

模式 3：XSS 防护

现代 UI 框架默认会自动转义用户输入。除非使用 DOMPurify 进行清理，否则切勿绕过此保护机制，注入原始 HTML。配置内容安全策略（CSP）标头，以阻止未经授权的脚本。

框架自动转义

大多数框架会自动转义文本内容。只有显式的 HTML 注入 API（例如，dangerouslySetInnerHTML、v-html、{@html}）才会绕过此保护机制。

DOMPurify 清理

需要渲染 HTML 时，请使用 DOMPurify，并设置允许的标签和属性白名单。

内容安全策略

配置 CSP 标头，即使发生 XSS，也能防止未经授权的脚本执行。

有关 DOMPurify 和 CSP 的代码示例，请参阅 examples/xss-prevention.md。

---

OWASP Top 10:2025 覆盖范围

此技能涉及以下 OWASP Top 10:2025 类别：

OWASP 类别	覆盖范围
A01：访问控制失效	CODEOWNERS、分支保护、速率限制
A02：安全配置错误	CSP 标头、安全标头、Dependabot
A03：软件供应链失效	Dependabot、CI 安全审计、依赖项审查
A04：加密失效	HttpOnly/Secure Cookie、强制使用 HTTPS
A05：注入	DOMPurify、框架自动转义、CSP
A07：身份验证失效	HttpOnly Cookie、会话管理
A10：异常情况处理不当	安全失效原则、错误处理

---

纵深防御层：

• 密钥：.env.local（开发环境） -> CI 密钥 -> 环境变量（生产环境）
• XSS：框架自动转义 -> DOMPurify 清理 -> CSP 标头
• CSRF：令牌 -> SameSite Cookie -> 服务端验证
• 依赖项：自动扫描 -> CI 安全审计 -> 人工审查

---

<red_flags>

危险信号

高优先级问题：

• 将密钥提交到代码库（.env 文件、代码中的 API 密钥）
• 使用未经清理的用户输入注入原始 HTML（会导致 XSS 攻击）
• 将身份验证令牌存储在 localStorage/sessionStorage 中（可被 XSS 访问）
• 对会更改状态的操作未提供 CSRF 防护（可能导致伪造请求）
• 未修补严重/高危漏洞（漏洞利用窗口仍然开放）

中优先级问题：

• 未配置 Dependabot（只能手动检测漏洞）
• 安全敏感文件缺少 CODEOWNERS（没有自动审查）
• 未配置 CSP 标头（没有脚本执行控制）
• 使用个人而非团队作为 CODEOWNERS（存在单点故障）
• 只信任客户端验证（很容易绕过）
• 向用户暴露内部错误详情（信息泄露）

注意事项与边缘情况：

• 某些框架默认会将 .env.local 添加到 gitignore，但并非所有框架都如此——请检查你的 .gitignore
• DOMPurify 的默认配置允许 <style> 和 <form> 标签——请使用显式白名单
• SameSite=Strict 会阻止合法的跨站请求——一般会话 Cookie 请使用 Lax
• CSP nonce 必须在每次请求中唯一——请在服务端生成新的 nonce
• X-XSS-Protection 标头已弃用——请设为 "0" 或省略，改用 CSP

有关常见错误、附带代码示例的反模式以及决策框架，请参阅 reference.md。

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目约定

（绝不能将机密提交到代码仓库——只能使用 .env.local 和 CI 机密）

（渲染原始 HTML 前，必须清理所有用户输入——注入任何 HTML 前都要使用 DOMPurify）

（必须在 24 小时内修复严重/高危漏洞——使用 Dependabot 进行自动扫描）

（必须使用 HttpOnly Cookie 存储身份验证令牌——绝不能使用 localStorage 或 sessionStorage）

（必须为安全敏感文件配置 CODEOWNERS——要求安全团队审批）

不遵守这些规则将造成安全漏洞，可能导致 XSS 攻击、令牌窃取、CSRF 攻击和数据泄露。

</critical_reminders>