js-security-audit

JS 安全审计

对 JS/TS 项目（npm、yarn 或 pnpm）执行涵盖 5 个方面的安全审计。按各方面生成通过/未通过报告，并提供文件:行号引用。

适用场景

• 加固新仓库——验证 .npmrc、锁文件、双因素认证和精确版本锁定
• 审查添加或升级依赖项的 PR
• 设置 CI 安全门禁（npm ci --ignore-scripts、lockfile-lint、审计门禁）
• 供应链攻击相关消息出现后（Axios 2026 年 3 月、Shai-Hulud 等）
• 生产部署前定期进行安全审查

流程

完整的 MUST/SHOULD/SHOULDN'T 清单请参阅 audit-checklist.md。 SAST ESLint 模板和规则表请参阅 eslint-security.md。 受攻击依赖项的 5 步响应流程请参阅 incident-playbook.md。 npm/yarn/pnpm 命令对照和工具说明请参阅 package-manager.md。

首先通过检查现有锁文件来识别包管理器：package-lock.json（npm）、yarn.lock（yarn）、pnpm-lock.yaml（pnpm）。使用 package-manager.md 中对应的命令。

1. 项目设置

检查 .npmrc、锁文件是否存在、版本锁定、.gitignore 和作用域包。

2. 依赖项卫生

运行审计，扫描锁文件差异以查找意外的包，检查 latest 标签和功能过于简单的依赖项。

3. CI/CD 流水线

验证是否使用 npm ci 而非 npm install，是否设置带有选择性重建允许列表的 --ignore-scripts、审计门禁、lockfile-lint、SHA 固定的操作、SBOM，以及 ESLint 安全配置。

4. Dependabot

检查 .github/dependabot.yml、告警路由、针对严重/高危问题的 P1 SLA，以及分组配置。

5. 事件响应准备情况

验证团队是否有成文的操作手册、IOC 监控和凭据轮换操作手册。

交互风格

• 根据锁文件识别包管理器，不会默认使用 npm
• 在警告之前标记严重发现（受攻击的包、缺少审计门禁、仓库中存在密钥）
• 每项发现都注明文件路径或配置项
• 每项发现都附有修复代码片段，而不只是说“修复它”
• 区分 MUST（阻止合并）、SHOULD（下个迭代处理）和 SHOULDN'T（反模式）

规则

• 严重 — 仓库中存在密钥、缺少锁文件、生产依赖项使用 latest 标签、CI 中没有 npm audit 门禁、发布者未启用双因素认证
• 警告 — 缺少 .npmrc 加固配置、没有 Dependabot 配置、没有生成 SBOM、缺少 ESLint 安全配置
• 信息 — 未使用 npq 进行安装前审查，未集成 Socket.dev/Snyk

注意事项

• AI 幻觉生成的包名。 Claude（以及其他大模型）有时会推荐 npm 上不存在的包——攻击者会注册这些名称并植入恶意软件。安装前务必在 npmjs.com 上检查该包，尤其是聊天建议中较少见的包名。
• 在 CI 中，npm install 和 npm ci 有区别。 如果锁文件与 package.json 不一致，npm install 会重写锁文件，悄悄拉取新版本。npm ci 则会直接使构建失败。CI 必须使用 ci。
• --ignore-scripts 也会阻止合法包运行脚本。 esbuild、sharp、prisma、bcrypt 需要运行 postinstall 脚本来下载二进制文件或生成客户端。使用 --ignore-scripts 后再运行 npm rebuild <allowlist>，并记录每个包被列入允许列表的原因。
• GitHub Actions 应固定到 SHA，而不是标签。 actions/checkout@v4 会跟随标签，而标签可能被重新指向恶意代码（这种情况确实发生过）。请使用完整的 40 位 SHA，并添加注释注明对应的标签。
• 锁文件差异是供应链问题的预警信号。 如果某个 PR 为了修复拼写错误而新增了 200 个传递依赖，或将现有包的解析 URL 从 registry.npmjs.org 改为其他地址，这就是危险信号——合并前请进行调查。
• min-release-age 需要 npm v11+。 在较旧版本的 npm 中，应将其列为 SHOULD，但不要因此判定审计失败。
• 认证代码中的 Math.random() 属于严重问题，而不是警告。 使用 Math.random() 生成的验证码、会话令牌和密码重置令牌都是可预测的。必须改用 crypto.randomInt()。Notion 指南指出，这是在 c0x12c 代码库中发现的真实问题。
• 不允许为了“减少噪声”而禁用 Dependabot。 正确的做法是对次要版本和补丁更新进行分组，而不是屏蔽警报。

建议的权限允许列表

此技能需要 Bash 来运行 npm audit 等命令。为避免每次审计都弹出提示，请将以下内容添加到 ~/.claude/settings.json（或项目的 .claude/settings.json）：

{
  "permissions": {
    "allow": [
      "Bash(npm audit:*)",
      "Bash(npm outdated:*)",
      "Bash(npm explain:*)",
      "Bash(npm list:*)",
      "Bash(npm view:*)",
      "Bash(yarn npm audit:*)",
      "Bash(yarn outdated:*)",
      "Bash(yarn why:*)",
      "Bash(pnpm audit:*)",
      "Bash(pnpm outdated:*)",
      "Bash(pnpm why:*)",
      "Bash(npx lockfile-lint:*)",
      "Bash(npx npq:*)"
    ]
  }
}

这样可以让审计命令静默运行，同时让其他所有操作（写入、删除等）仍需经过提示确认。

输出

生成审计报告：

## JS Security Audit: {repo}

### Overall: Pass | Fail

| Area               | Status   | Critical | Warnings | Info |
|--------------------|----------|----------|----------|------|
| Project Setup      | Pass     | 0        | 1        | 0    |
| Dependency Hygiene | Fail     | 1        | 0        | 0    |
| CI/CD Pipeline     | Pass     | 0        | 2        | 1    |
| Dependabot         | Warning  | 0        | 1        | 0    |
| Incident Response  | Info     | 0        | 0        | 1    |

### Critical Findings
- **[Dependency Hygiene]** `lodash` pinned to `latest` in package.json:24
  - Fix: Replace with exact version `"lodash": "4.17.21"`
  - Reason: `latest` resolves at install time, defeating lockfile guarantees

### Warnings
- **[Project Setup]** `.npmrc` missing `ignore-scripts=true`
  - File: `.npmrc:1`
  - Fix: Add `ignore-scripts=true` and use `npm rebuild` for allowlisted packages

### Remediation Priority
1. Fix critical findings before merging
2. Address warnings in next sprint
3. Info items as time permits