accelint-security-best-practices

安全最佳实践

对 JavaScript/TypeScript 应用进行系统化安全审计和漏洞检测。将审计工作流与 OWASP Top 10 安全模式相结合，打造可用于生产环境的代码。

框架无关的指导：此技能提供适用于各种框架（Express、Fastify、Nest.js、Next.js 等）的安全原则。代码示例使用常见模式说明相关概念，请根据项目的具体框架和包管理器（npm、yarn、pnpm、bun）进行调整。

实施安全措施时绝对不要做的事

**注意：**有关常规最佳实践（类型安全、代码质量、文档），请使用相应的 accelint 技能。本节仅关注安全方面的反模式。

• 绝不要硬编码机密信息——将 API 密钥、令牌、密码或凭据写入源代码，一旦推送到版本控制中就会立即泄露。即使是私有代码库，也可能因员工离职、第三方访问和 git 历史记录而泄露机密信息。2024 年的泄露事件分析显示，47% 的暴露凭据来自意外提交到 .env 文件、之后又“删除”但仍保留在 git 历史记录中的内容。攻击者会在代码推送后的几分钟内扫描公开的 GitHub 提交。请仅使用环境变量。

• 绝不要信任用户输入——使用架构（Zod、Joi）验证类型、格式、大小和内容。

• 绝不要将用户输入拼接到查询中——仅使用参数化查询、ORM 或预处理语句。在 SQL、NoSQL 或 shell 命令中拼接字符串会导致注入攻击。

• 绝不要在 localStorage 中存储敏感数据——localStorage 容易遭受 XSS 攻击，恶意脚本可能会借此窃取令牌。存储在 localStorage 中的 JWT 令牌、会话 ID 或凭据会跨会话保留，且任何 JavaScript 代码都能访问。请使用 httpOnly cookie 存储身份验证令牌。

• 绝不要跳过授权检查——身份验证用于确认身份；授权用于确认权限。攻击者会篡改 ID、绕过身份验证或猜测 URL。每个访问资源的端点都必须验证请求用户是否拥有该资源或具备相应角色。

• 绝不要向用户暴露详细错误信息——在服务器端记录日志，并返回通用消息。堆栈跟踪会泄露架构信息，便于攻击者侦察。

• 绝不要使用 Array.includes() 检查权限——角色超过 100 个的权限数组查找耗时为 O(n)，还会带来类型安全问题。请使用 Set.has()，实现 O(1) 查找，或使用带有适当类型检查的基于角色的访问控制（RBAC）。

• 绝不要跳过 API 速率限制——不受限制的 API 请求会导致暴力攻击（每秒尝试 1000 个密码）、拒绝服务（耗尽服务器资源）或数据爬取（枚举所有用户/资源）。请对所有端点设置速率限制，并对身份验证和开销较大的操作设置更严格的限制。

• 绝不要记录敏感数据——日志中的密码、令牌、信用卡号或个人信息会留存在日志聚合系统、备份和第三方服务中。能访问日志的人比能访问应用本身的人更多。记录日志前请对敏感字段进行脱敏。

• 绝不要在生产环境中使用默认配置——在生产环境中使用默认机密信息、禁用安全标头、宽松的 CORS 或开发模式会造成已知漏洞。攻击者会扫描默认配置。请针对生产环境强化所有配置。

实施安全措施前，请先询问

应用以下检查，确保全面覆盖安全问题：

威胁评估

• **攻击面有哪些？**识别用户输入进入系统的所有位置（表单、API、文件上传、URL）
• **最坏的情况是什么？**考虑数据泄露、未授权访问、服务中断或经济损失
• **攻击者是谁？**脚本小子会利用已知漏洞；高水平攻击者会将多个弱点串联起来

合规验证

• 所有受保护的路由都启用了身份验证吗？ 公共 API 可能是有意设置的，但请核实每个端点的访问策略。
• 操作前是否执行了授权检查？ 在读取、写入或删除资源前，验证所有权和权限。
• 是否验证了所有用户输入？ 在处理前，使用架构检查类型、格式、大小和内容。

纵深防御

• 是否存在单点故障？ 采用分层防御，避免一次绕过就危及整个系统。
• 是否妥善处理了错误？ 未处理的错误会泄露信息；妥善处理可维护安全态势。
• 日志是否足以支持审计追踪？ 必须记录安全事件（登录尝试、访问拒绝、可疑模式），以便响应事件。

如何使用

此技能采用渐进式披露，以尽量减少上下文用量：

1. 从工作流开始（SKILL.md）

按照下面的 4 阶段审计工作流进行系统化安全分析。

2. 参考安全规则概览（AGENTS.md）

加载 AGENTS.md，查看按类别整理的精简安全规则摘要。

3. 按需加载具体安全模式

发现具体安全问题时，加载相应的参考文件，查看详细的 ❌/✅ 示例。

4. 使用报告模板

调用此技能时，使用标准化报告格式：

模板： assets/output-report-template.md

安全审计工作流

两种运行模式：

1. 审计模式 - 直接调用技能（/accelint-security-best-practices <path>）或用户明确请求安全审计

   • 使用模板生成结构化审计报告（仅阶段 1-2）
   • 将发现的问题报告给用户，以便审核后再实施
   • 由用户决定应用哪些安全修复

2. 实施模式 - 在功能开发期间自动触发技能

   • 直接识别并应用安全修复（全部 4 个阶段）
   • 无需正式报告
   • 重点是在代码中直接修复漏洞

复制此检查清单以跟踪进度：

- [ ] Phase 1: Discover - Identify security vulnerabilities through systematic code analysis
- [ ] Phase 2: Categorize - Classify issues by OWASP category and severity
- [ ] Phase 3: Remediate - Apply security patterns from references/
- [ ] Phase 4: Verify - Validate fixes and confirm vulnerability closure

阶段 1：发现安全漏洞

重要：审计所有代码中的安全漏洞。 不要基于对暴露范围的假设跳过代码。即使内部工具、辅助函数和数据转换的实现看似独立，也经常会通过 API、文件上传或用户交互暴露。

系统地执行静态代码分析，找出所有安全反模式：

• 硬编码的机密（API 密钥、密码、令牌）
• 缺少输入验证（用户数据、文件上传、API 响应）
• 注入漏洞（SQL、NoSQL、命令、XSS）
• 访问控制失效（缺少身份验证、未检查所有权、IDOR）
• 身份验证不安全（令牌存储在 localStorage、会话管理薄弱）
• 缺少速率限制（身份验证端点、高开销操作）
• 敏感数据泄露（日志、错误消息、客户端响应）
• 安全配置错误（默认配置、缺少标头、CORS 权限过宽）
• 易受攻击的依赖项（过时的软件包、已知 CVE）
• 缺少 CSRF 防护（会改变状态的操作）
• SSRF 漏洞（未验证 URL 即进行获取）

输出：列出所有已发现漏洞的完整清单，包括其位置、严重程度和 OWASP 类别。不要按“可能性”筛选——发现的所有问题都应报告。

阶段 2：分类并评估风险

对于阶段 1 中发现的每项漏洞，按 OWASP 类别和严重性进行分类：

按 OWASP Top 10 类别对所有漏洞进行分类：

OWASP 类别	常见问题	严重性范围
A01：访问控制失效	缺少身份验证、未检查所有权、IDOR	严重-高
A02：加密失效	硬编码密钥、弱哈希、不安全存储	严重-中
A03：注入	SQL、NoSQL、命令、XSS 漏洞	严重-高
A04：不安全设计	缺少速率限制、未验证输入	高-中
A05：安全配置错误	默认配置、缺少标头、生产环境使用开发模式	高-低
A06：易受攻击的组件	过时的依赖项、已知 CVE	严重-低
A07：身份验证失效	弱会话管理、未启用 MFA、凭据填充攻击	严重-高
A08：数据完整性失效	缺少 CSRF 防护、更新未签名	高-中
A09：日志记录和监控失效	缺少安全日志、监控不足	中-低
A10：SSRF	未验证 URL 获取、访问内部网络	高-中

严重性级别：

• 严重：可直接导致数据泄露、远程代码执行或系统完全失陷

  • 示例：SQL 注入、硬编码的生产密钥、管理端点未启用身份验证

• 高：很可能导致未授权访问、数据窃取或服务中断

  • 示例：缺少授权检查、XSS 漏洞、不安全的会话管理

• 中：在特定条件下可能被利用，或与其他漏洞组合利用

  • 示例：缺少速率限制、CORS 策略薄弱、日志记录不足

• 低：纵深防御改进、最佳实践或边缘情况防护

  • 示例：缺少安全标头、错误消息过于详细

漏洞映射快速参考：

加载 references/quick-reference.md，了解详细的漏洞到类别映射及反模式检测。

**输出：**列出所有漏洞及其 OWASP 类别和严重性级别。不要筛选或排序优先级——列出阶段 1 中发现的所有问题。

第 3 阶段：使用安全模式进行修复

步骤 1： 根据第 2 阶段的分析确定漏洞类别。

步骤 2： 加载该类别的必需参考文件。完整阅读每个文件，不要限制范围。

类别	必需文件	可选文件	不要加载
密钥管理	secrets-management.md	—	所有其他文件
输入验证	input-validation.md	file-uploads.md（针对文件上传功能）	secrets、auth
注入防护	injection-prevention.md	—	input validation、XSS
身份验证	authentication.md	mfa.md（针对多重身份验证功能）	authorization、secrets
授权	authorization.md	—	authentication
XSS 防护	xss-prevention.md	—	injection、CSRF
CSRF 防护	csrf-protection.md	—	XSS、auth
速率限制	rate-limiting.md	—	auth、injection
敏感数据	sensitive-data.md	—	secrets、logging
依赖项安全	dependency-security.md	—	所有其他文件
安全标头	security-headers.md	—	XSS、CSRF
SSRF 防护	ssrf-prevention.md	—	injection、input validation

注意：

• 如果漏洞涉及多个类别，请加载所有相关类别的参考文件
• 安全模式具有累积性——通过处理所有类别来实施深度防御
• 实施特定功能（如文件上传、MFA 等）时，请加载可选文件

---

步骤 3：修复期间查阅快速参考

加载 AGENTS.md，查看按类别整理的精简安全规则摘要。在实施上述详细参考文件中的模式时，可将其用作快速查阅资料。

系统地应用安全模式：

1. 加载参考文件，对应已确定的漏洞类别
2. 查看 ❌/✅ 示例，找到匹配的模式
3. 应用安全修复，确保实现深度防御
4. 添加注释，说明安全考量并引用相应模式

修复示例：

// ❌ Before: SQL Injection vulnerability
const query = `SELECT * FROM users WHERE email = '${email}'`;
const user = await db.query(query);

// ✅ After: Parameterized query prevents injection
// Security: injection-prevention.md - parameterized queries
const user = await db.query(
  'SELECT * FROM users WHERE email = $1',
  [email]
);

第 4 阶段：验证安全修复

验证漏洞是否已修复：

1. 检查代码，确认漏洞已得到彻底处理
2. 验证修复没有引入新的漏洞
3. 检查深度防御——是否有多个防护层保护关键资源？

安全测试：

1. 运行现有测试套件——所有测试都必须通过
2. 针对该漏洞添加安全专项测试
3. 对于关键漏洞，可考虑进行渗透测试

记录安全修复：

// Security fix applied: 2026-02-01
// Vulnerability: SQL injection via email parameter (Critical)
// OWASP Category: A03 - Injection
// Pattern: injection-prevention.md - parameterized queries
// Verified: All tests pass, manual SQL injection attempts blocked

决定是否部署修复：

• 严重漏洞： 立即部署，必要时采用紧急流程
• 高危漏洞： 在下一个发布周期内部署（以天计，而非周）
• 中危漏洞： 随下一次计划发布部署
• 低危漏洞： 在方便时部署，或与其他安全改进一并发布

如果测试失败： 修复安全实现或寻找替代方案。安全修复不应破坏功能。

常见实现陷阱

安全修复有时会与现有功能冲突。以下是常见场景的专家解决方案：

问题	❌ 错误做法	✅ 正确做法
参数化查询导致动态列排序失效	添加 try-catch，回退到字符串拼接	使用列名白名单：const allowed = ['name', 'email', 'created_at']; if (!allowed.includes(column)) throw Error;，然后安全地拼接
速率限制导致负载测试失效	在测试环境中禁用速率限制	根据环境检测，为测试使用单独的速率限制配置
CSRF 令牌导致 API 集成测试失效	在测试中跳过 CSRF 验证	在测试设置中使用 CSRF 库的令牌生成函数生成有效的 CSRF 令牌
输入验证拒绝了合理的边缘情况	放宽验证规则	调查该边缘情况——它是否合理？如果合理，则更新架构；如果不合理，则拒绝。真实用户不应遇到验证错误。
授权检查导致管理员模拟用户功能失效	跳过对管理员用户的身份验证检查	正确实现模拟功能：为管理员签发拥有目标用户权限的临时令牌，并记录日志以供审计
HTTPOnly Cookie 导致移动应用身份验证失效	在移动端将令牌存储在 localStorage 中	使用安全的令牌存储：iOS Keychain、Android Keystore 或平台专用的安全存储 API

安全与功能发生冲突时

优先级顺序：

1. 绝不妥协于严重漏洞（SQL 注入、硬编码密钥、缺少身份验证）——寻找替代架构
2. 高危漏洞可以接受轻微权衡，但必须做好文档记录，并通过其他控制措施进行补偿
3. 中低危漏洞可在业务理由充分且风险已获接受的情况下延期处理

权衡的文档要求：

// SECURITY TRADE-OFF DOCUMENTED: 2026-02-01
// Issue: Rate limiting breaks webhook ingestion from trusted partner
// Decision: Exempt partner IP range from rate limiting
// Compensating controls:
//   - IP whitelist strictly maintained (only 2 partner IPs)
//   - Separate monitoring for partner traffic
//   - Manual review of partner traffic daily
//   - 30-day review scheduled to implement alternative solution
// Risk accepted by: [Name], [Title]

自由度校准

根据漏洞严重程度调整指导的具体程度：

漏洞严重程度	自由度	指导形式	示例
严重（数据泄露、RCE）	低自由度	严格遵循参考模式，不得偏离	“使用参数化查询：db.query('SELECT * FROM users WHERE id = $1', [id])”
高危（未授权访问）	中自由度	提供带示例的模式，并验证覆盖情况	“在访问资源前实施 RBAC 或所有权检查”
中危（纵深防御）	中自由度	提供多种有效方法，根据架构选择	“使用 express-rate-limit 实施速率限制，或实现自定义中间件”
低危（最佳实践）	高自由度	提供一般性指导，具体实现可有所不同	“考虑添加安全标头以实现纵深防御”

判断标准：“严重程度和影响范围有多大？”

• 严重／高危 → 低自由度，提供精确模式以防止出错
• 中危 → 中自由度，提供经过验证的方法
• 低危 → 高自由度，提供一般性最佳实践

重要说明

• 全面审计原则 - 审计所有代码，查找安全漏洞。内部实用工具、辅助函数和数据转换，即使看似相互隔离，也经常会通过 API 或用户交互暴露出来。不要假设存在安全边界。
• 报告所有发现 - 进行系统化静态分析，识别并报告所有漏洞及其严重性和 OWASP 类别。不要根据漏洞被利用的“可能性”进行筛选。
• 参考文件具有权威性 - references/ 中的模式遵循 OWASP 最佳实践。除非安全要求另有规定，否则请严格遵循。
• 深度防御 - 通过多层安全控制，避免单个漏洞危及整个系统。身份验证 + 授权 + 输入验证 + 速率限制。
• 安全测试 - 修复安全问题时，必须使用恶意输入和边界情况进行测试。部署前为攻击场景添加测试。
• 事件响应 - 安全日志记录和监控有助于检测并响应攻击。记录所有安全事件，并提供足够的调查细节。

快速决策树

使用此表快速识别适用的安全类别和相应的严重性。

全面审计：无论当前是否暴露，都要识别代码中的所有安全漏洞。报告所有发现，并注明严重性和 OWASP 类别。

如果发现……	漏洞类型	OWASP 类别	典型严重性
源代码中包含 API 密钥、密码或令牌	硬编码密钥	A02: Cryptographic Failures	严重
用户输入直接用于 SQL/NoSQL 查询	注入漏洞	A03: Injection	严重
受保护路由上没有 authenticate 中间件	缺少身份验证	A01: Broken Access Control	严重
访问资源前没有检查所有权/权限	缺少授权	A01: Broken Access Control	高
在 localStorage.setItem() 中存储 JWT 令牌	令牌存储不安全	A07: Auth Failures	高
用户输入未经过架构验证	缺少输入验证	A04: Insecure Design	高
/api/login 或 /api/register 未设置速率限制	缺少速率限制	A04: Insecure Design	高
dangerouslySetInnerHTML 未进行净化	XSS 漏洞	A03: Injection	高
更改状态的操作未使用 CSRF 令牌	缺少 CSRF 防护	A08: Data Integrity Failures	高
console.log() 中包含密码、令牌或 PII	日志中包含敏感数据	A09: Logging Failures	中
向用户发送堆栈跟踪或数据库错误	信息泄露	A05: Security Misconfiguration	中
npm audit 显示存在漏洞	易受攻击的依赖项	A06: Vulnerable Components	严重至低（视情况而定）
fetch(userProvidedUrl) 未进行验证	SSRF 漏洞	A10: SSRF	高
缺少安全标头（CSP、HSTS）	缺少安全标头	A05: Security Misconfiguration	中
用户 ID 按顺序递增且未检查所有权	IDOR 漏洞	A01: Broken Access Control	高
生产环境中使用 CORS: *	CORS 过于宽松	A05: Security Misconfiguration	中
缺少 process.env.NODE_ENV !== 'production' 检查	在生产环境中启用开发模式	A05: Security Misconfiguration	中至低

如何使用此表：

1. 在代码审查中识别对应模式
2. 在“如果发现……”列中查找匹配的行
3. 记录对应的 OWASP 类别和典型严重性
4. 跳转到第 3 阶段中对应的安全类别
5. 加载该类别的强制参考文件