package-security-check

软件包安全检查

工作流

1. 首先将其视为基础 JS 供应链检查。不要围绕某个 CVE、供应商、软件包系列或事件来强行得出结论。
2. 在运行安装、软件包管理器变更命令或编辑文件之前，只执行只读检查，并呈现红黄绿问题分析：
   • 🔴 阻断项：存在入侵迹象、不安全的安装路径、机密泄露，或允许未经审查的代码执行的策略。
   • 🟡 风险：加固缺失、软件包管理器主版本过旧、规范范围过宽、需要审查的生命周期脚本，或 CI 弱点。
   • 🟢 正常：已验证的控制措施或未发现问题。
3. 完成红黄绿分析后，在更改文件或执行可能安装、更新、发布或重写锁文件的软件包管理器操作之前，先征求批准。
4. 在此技能目录中，针对仓库或工作区根目录运行基线扫描器：

python3 scripts/check_js_supply_chain.py --root <repo-or-workspace-root>

当检查应在发现加固缺失时失败，请使用 --strict。当其他工具需要机器可读输出时，请使用 --json。仅当 node_modules 存在且需要检查已安装软件包的生命周期元数据时，才使用 --include-installed。

5. 对于特定的活跃事件，添加一个或多个 IOC 配置文件：

python3 scripts/check_js_supply_chain.py \
  --root <repo-or-workspace-root> \
  --ioc data/iocs/npm-supply-chain-2026-05.json \
  --since 2026-05-11T19:20:00Z

依赖配置文件之前，请从当前公告来源刷新事件信息。IOC 配置文件是检测数据，而非基础策略。

6. 按以下顺序检查报告：
   • package_manager_policy
   • repo_config_findings 和 effective_config_findings
   • risky_direct_specs
   • package_lifecycle_scripts，然后在需要时检查 installed_lifecycle_scripts
   • ci_install_findings，包括 GitHub Actions 权限/缓存警告
   • ioc_hits
   • recent_package_manager_files
7. 如果出现任何 IOC 命中，请停止常规软件包操作。不要运行安装或生命周期脚本。报告确切的文件/软件包，并建议隔离、轮换凭据，以及使用已知良好的锁文件重新安装。
8. 如果未发现入侵迹象，但策略较弱且用户批准了更改，请朝规范的 pnpm 11 策略进行修补。保持仅使用一个软件包管理器、一个锁文件和一个仓库本地策略源。

规范策略

使用 pnpm 11 或更高版本作为唯一的软件包管理器，因为它目前具有最佳的 pnpm 安全模型：发布时长限制、生命周期脚本审批、阻止特殊子依赖项，以及信任策略控制。

写入 packageManager 之前，请确认当前 pnpm 版本：

npm view pnpm dist-tags --json

要求使用 pnpm 11 或更高版本。截至 2026-05-12，npm 报告的 latest 为 pnpm 11.1.1。未经重新确认，不要硬编码该版本。如果仓库的 Node 运行时无法运行 pnpm 11，请将其报告为兼容性阻断项，而不是悄悄回退到 pnpm 10。

使用 devEngines.packageManager 声明所需主版本：

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": ">=11.0.0",
      "onFail": "download"
    }
  }
}

同时在 packageManager 中固定已验证的当前稳定版本，以确保可复现性：

{
  "packageManager": "[email protected]"
}

将 pnpm 10 或更早版本视为 legacy-pnpm-major，除非用户明确批准临时例外。

包管理器策略

• pnpm >=11：标准基线。新的安全加固工作优先使用它。
• bun：仅当代码仓库有意使用 Bun，且具备同等的本地安全加固时才接受。
• npm：仅作后备方案。建议迁移到 pnpm 11，除非代码仓库有明确记录的理由继续使用 npm。
• yarn：不接受作为此技能的基线。建议改用 pnpm 11 或已加固的 Bun。

不要将 npm 描述为与 pnpm 11 等同。可以接受 Bun 作为项目级选择，但仍需根据 Bun 特有的安全加固要求进行检查。

对于使用 npm 作为后备方案的代码仓库，要求精确保存依赖项并确保 CI 可复现，同时建议迁移到 pnpm：

save-exact=true

除非已根据当前 npm 文档和本地 npm config ls -l 验证，否则不要声称 npm 支持发布版本等待门槛。

对于使用 Bun 作为后备方案的代码仓库，要求在代码仓库本地提供 bunfig.toml：

[install]
minimumReleaseAge = 604800
exact = true
frozenLockfile = true
saveTextLockfile = true

除非有经过审核的、针对特定软件包的理由，否则不要设置 minimumReleaseAgeExcludes。

添加或更新根目录中的 pnpm-workspace.yaml：

minimumReleaseAge: 10080
minimumReleaseAgeStrict: true
minimumReleaseAgeIgnoreMissingTime: false
blockExoticSubdeps: true
trustPolicy: no-downgrade
trustPolicyIgnoreAfter: 43200
dangerouslyAllowAllBuilds: false
savePrefix: ""
allowBuilds: {}

普通代码仓库使用 7 天（10080）。只有在代码仓库确实有依赖项新鲜度要求时才使用 3 天。除非有经过审核的、针对特定软件包的理由，否则不要设置 minimumReleaseAgeExclude 或 trustPolicyExclude。

仅在审核后允许依赖项构建脚本：

allowBuilds:
  esbuild: true
  core-js: false

CI 规则

要求使用冻结模式安装 pnpm 依赖项：

pnpm install --frozen-lockfile

除非代码仓库有书面说明的理由，否则以下情况均视为问题：

• pnpm 代码仓库中存在非 pnpm 锁文件
• CI 使用 npm install、yarn install、未冻结模式的 bun install 或未冻结模式的 pnpm install
• 迁移待完成期间，npm 代码仓库未使用 npm ci 和已提交的锁文件
• Bun 代码仓库缺少 bunfig.toml 发布版本等待、精确版本、冻结锁文件或文本锁文件策略
• pull_request_target 工作流；仅在有经过审核的理由时才允许使用，且不得检出或运行不受信任的 PR 代码
• 发布流水线中使用共享缓存，包括 GitHub Actions 缓存、Turborepo 和 Nx 缓存
• PR 控制的缓存内容可能流入特权发布工作流的任何路径
• 在 CI／部署期间重写锁文件
• latest、*、宽泛版本范围、Git／GitHub 简写、HTTP tarball 或外部 file: 规格
• 未经明确批准的依赖项生命周期脚本
• dangerouslyAllowAllBuilds: true
• 工作流使用 toJSON(secrets)，或在范围过大的构建任务中使用发布凭据

脚本

scripts/check_js_supply_chain.py 会执行确定性的本地检查：

• 检测包管理器和锁文件策略
• 检查代码仓库本地及生效中的 pnpm 安全加固设置
• 报告 npm 后备方案和 Bun 后备方案的安全加固缺口
• 报告存在风险的直接依赖项规格
• 报告工作区清单中的生命周期脚本，以及可选的已安装软件包中的生命周期脚本
• 报告存在风险的 GitHub Actions 安装／发布／密钥模式
• 对可能演变为供应链权限提升路径的 pull_request_target 和共享缓存模式发出警告
• 报告 --since 之后包管理器文件的修改时间
• 应用可选的 IOC JSON 配置文件，以检查特定事件的指纹、负载文件、持久化路径、工作流标记和已知恶意软件包版本

将事件配置文件保存在 data/iocs/ 下。除非某些常量适用于各类 npm 供应链攻击，否则不要将事件专用常量添加到扫描器中。