installaudit

installaudit

安装就是在运行代码。installaudit 会在你安装之前告诉你运行的是谁的代码。

npm install 不只是下载文件。锁文件条目中带有 hasInstallScript: true 的任何包都会在安装时运行代码，根包自己的 preinstall、install、postinstall 和 prepare 脚本也会运行。大多数审计会询问依赖项是否存在漏洞。installaudit 会先问一个问题：安装这棵依赖树的那一刻，究竟会执行什么？

它会读取 package.json 和 package-lock.json，盘点依赖树中的所有安装脚本，区分直接依赖和传递依赖，根据根脚本的作用对其分类，并给出结论。它绝不会安装任何内容、运行任何脚本或获取任何包。

安装

npx @reneturcios/installaudit audit

也可以全局安装，或将其添加为 MCP 服务（见下文）。

CLI

# Audit the current directory
npx @reneturcios/installaudit audit

# Audit another path
npx @reneturcios/installaudit audit ~/src/my-repo

# Machine readable output
npx @reneturcios/installaudit audit ~/src/my-repo --json

# Run as an MCP server on stdio
npx @reneturcios/installaudit mcp

# Print the version
npx @reneturcios/installaudit --version

退出代码：

• 0：结论为 CLEAN。
• 1：结论为 REVIEW。
• 2：用法错误，包括缺少 package.json 或 package-lock.json。
• 141：读取器提前关闭了输出管道。

MCP

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "installaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/installaudit", "mcp"]
    }
  }
}

工具：audit_install_scripts，接收一个 path 参数。它会以 JSON 格式返回完整报告：结论、计数和发现项。

盘点方式

依赖项来自锁文件，而不只是 package.json，因为锁文件包含实际将要安装的解析后依赖树。

• 锁文件 v2 和 v3 格式：packages 对象将诸如 node_modules/<name> 的安装路径映射到相应条目。
• 带有 hasInstallScript: true 的条目会在安装时运行代码，并成为一项发现。
• 包名取自路径中最后一个 node_modules/ 片段之后的部分。作用域包名包含两段：node_modules/@scope/name 对应 @scope/name，而 node_modules/a/node_modules/@scope/name 也对应 @scope/name。
• 当路径中恰好只有一个 node_modules 片段，且其名称列在根 package.json 的 dependencies 或 devDependencies 中时，该包属于直接依赖。其他情况都属于传递依赖，包括名称恰好与直接依赖相同的嵌套副本。
• version 和 dev 标志从锁文件条目中读取，并随发现项一并报告。

根脚本来自 package.json。只读取 preinstall、install、postinstall 和 prepare，因为这些是 npm 在安装期间运行的脚本。每个存在的脚本都会成为一项发现，并根据其命令内容进行分类。

规则

规则	严重性	含义
DEP-INSTALL-SCRIPT	中（直接依赖），低（传递依赖）	锁文件条目中 hasInstallScript: true 的依赖。证据为 name@version。
ROOT-SCRIPT-NETWORK	高	被归类为 NETWORK 的根生命周期脚本。
ROOT-SCRIPT-SHELL-OUT	中	被归类为 SHELL-OUT 的根生命周期脚本。
ROOT-SCRIPT-BUILD	低	被归类为 BUILD 的根生命周期脚本。
ROOT-SCRIPT-OTHER	信息	被归类为 OTHER 的根生命周期脚本。

根脚本分类使用简单且有文档记录的模式，并按以下优先级检查：先检查 NETWORK，然后是 SHELL-OUT、BUILD，最后是 OTHER。

类别	模式
NETWORK	curl 或 wget；或者 http:// 或 https:// URL 与获取或下载工具词（fetch、download、curl、wget）组合出现。
SHELL-OUT	Shell 解释器词（sh、bash、zsh）、node -e，或脚本解释器词（python、python3、perl、ruby）。
BUILD	tsc、npm run build（也包括 pnpm、yarn 和 bun），或构建工具名称（webpack、vite、rollup、esbuild、parcel、gulp、grunt、babel）。
OTHER	其他任何内容。

每份报告都会列出以下计数：

• totalDeps：锁文件 packages 对象中的所有依赖条目，不包括根条目。
• depsWithScripts：hasInstallScript: true 的条目。
• directWithScripts：depsWithScripts 中的直接依赖子集。
• transitiveWithScripts：depsWithScripts 中的传递依赖子集。
• rootScripts：根生命周期脚本中存在的 preinstall、install、postinstall 和 prepare。
• findings：发现项总数。

发现项按规则排序，然后按名称排序，确保结果确定。报告不含时间戳，因此相同的目录树始终会生成相同的报告。

判定

• CLEAN：没有根 NETWORK 或 SHELL-OUT 脚本，也没有依赖安装脚本。单独存在的根 BUILD 或 OTHER 脚本仍会判定为 CLEAN；它们会作为低级或信息级发现项报告，不会被隐藏。
• REVIEW：其他任何情况。此目录树中至少有一项会在安装时运行代码，值得人工检查。

限制

• 仅基于锁文件。缺少 package-lock.json 会报错（退出码 2），而不是生成空报告，因为没有锁文件就无法盘点已解析的依赖树。缺少 package.json 同样会报错。
• 锁文件中不包含依赖的脚本内容，因此不会获取这些内容。对于依赖，installaudit 会报告其是否存在安装脚本、名称、版本、dev 标志，以及它是直接依赖还是传递依赖。它不会报告脚本的具体行为，也不会判断其意图。带有安装脚本的包可能完全合理；原生构建是常见情况。
• 根脚本分类基于模式。它会读取 package.json 中的命令文本，不会追踪脚本所调用的文件、展开变量，也不会追踪下载文件会执行什么操作。
• 仅支持通过 packages 对象表示的锁文件 v2 和 v3。不读取旧版锁文件 v1 的 dependencies 对象，因此 v1 锁文件会报错，而不会生成不完整的盘点结果。
• 仅读取与安装相关的四种根脚本。其他脚本（如 test 或 start）不在范围内，即使命令看起来有风险也一样。
• 直接依赖是指列在根目录 package.json 的 dependencies 或 devDependencies 中的依赖。按照此处的定义，只能通过依赖树间接访问的依赖都属于传递依赖，无论由谁维护。