marcoazeem/claude-code-npm-osv-hook

# claude-code-npm-osv-hook 一个[Claude Code](https://claude.com/claude-code)的 `PreToolUse` 钩子，可在 Claude Code 运行 `npm` 命令之前，使用[osv-scanner](https://google.github.io/osv-scanner/)扫描 `package-lock.json` 文件。如果 OSV 报告锁定文件中存在已知恶意软件、供应链攻击或存在漏洞的软件包版本，则 npm 命令将被**阻止**，相关发现会以内联方式显示。如果所需工具缺失，命令也会被阻止，并附带安装说明。 ## 为什么 近期 npm 供应链攻击通过广泛使用软件包的已维护者账户被入侵来传播恶意代码。当你注意到“异常”的安装输出时，postinstall 脚本很可能已经运行。在 `npm install`、`npm ci` 或任何 `npm run …` 之前对锁定文件运行 OSV，可以在代码执行前捕获已锁定文件中存在的已知问题版本。 OSV 数据来自 GitHub Advisory Database，该数据库接收 npm 的恶意软件披露信息。 ## 安装 ``` # 1. 安装 osv-scanner brew install osv-scanner # （其他平台请参见 https://google.github.io/osv-scanner/installation/） # 2. 确保已安装 jq brew install jq # 3. 将 .claude/ 文件夹放入项目根目录 cd /path/to/your/project curl -fsSL https://raw.githubusercontent.com/marcoazeem/claude-code-npm-osv-hook/main/.claude/hooks/npm-osv-check.sh \ -o .claude/hooks/npm-osv-check.sh chmod +x .claude/hooks/npm-osv-check.sh # 4. 将钩子配置项合并至 .claude/settings.local.json # （若需团队共享则使用 .claude/settings.json）。 # 详见 settings.example.json 中的代码片段。 ``` 或者直接克隆并复制： ``` git clone https://github.com/marcoazeem/claude-code-npm-osv-hook cp -r claude-code-npm-osv-hook/.claude/hooks /path/to/your/project/.claude/ # 随后将 .claude/settings.example.json 合并至您的配置文件。 ``` 安装后，在 Claude Code 中打开一次 `/hooks`（或重启会话），以便设置监视器能识别到新文件。之后，Claude 尝试运行的每个 `npm …` 命令都会先触发扫描。 ## 文件 ``` .claude/ ├── hooks/ │ └── npm-osv-check.sh # the scanner script └── settings.example.json # the hook entry — merge into your settings.json ``` ## 行为 | 情况 | 结果 | |---|---| | `osv-scanner` 未安装 | npm 被阻止并显示安装消息 | | 无 `package-lock.json`（首次安装） | npm 被允许 — 暂无可扫描内容 | | osv-scanner 未发现问题 | npm 被允许（静默） | | osv-scanner 发现问题 | npm 被阻止，发现的问题在拒绝原因中显示 | 此设置示例为 Bash 工具调用运行钩子，且脚本仅在找到以 `npm` 开头的命令段时立即退出（包括 `cd app && npm ci` 这样的简单形式）。`git`、`ls`、`node` 和 `echo npm install` 不受影响。 ## 手动覆盖 如果你已审核了某个发现但仍想继续，请注释掉 `.claude/settings.local.json` 中的 `hooks.PreToolUse` 块（或删除该文件）。完成后请撤销更改。或者，由于钩子仅在 Claude Code 内部阻止命令，你也可以在终端中自行运行 npm 命令。 ## 注意事项 - 扫描会为每次 npm 调用增加一到两秒的延迟。如果这太慢，你可以添加更精确的匹配器，但这样做可能会遗漏像 `cd app && npm ci` 这样的命令。 - `npx`、`pnpm`、`yarn` 未被涵盖 — 仅限 `npm`。如果你使用这些工具，请扩展匹配器。 - OSV 仅能捕获**已知**问题。真正的零日供应链攻击可能尚未在数据库中。这是一个安全网，而非绝对保证。 - 首次安装时若不存在 `package-lock.json` 则被允许，因为此时尚无锁定文件可供扫描。 - 安装全新软件包可能会引入命令开始前锁定文件中不存在的版本。此钩子对于 `npm ci`、重复安装以及针对现有锁定文件运行的命令最为有效。 - 该钩子能处理简单的 `cd app && npm ...` 命令，并扫描该目录的锁定文件。更复杂的 shell 流程将回退到当前工作目录。 ## 测试 ``` chmod +x test/run-tests.sh test/run-tests.sh ``` ## 项目设置与本地设置 - `.claude/settings.local.json` — 已添加到 gitignore，属于个人文件。 - `.claude/settings.json` — 提交到仓库，适用于团队中的所有人。 如果你希望整个团队都进行扫描（并让他们安装 osv-scanner），请将 `hooks` 块移至 `.claude/settings.json`。 ## 许可证 MIT — 详情参见[LICENSE](./LICENSE)。

标签：Claude Code, GitHub Advisory Database, GNU通用公共许可证, MITM代理, Node.js, npm, npm命令安全, osv-scanner, PreToolUse, SOC Prime, TLS抓取, 代码安全, 供应链攻击防护, 依赖管理, 包锁文件, 安全检查, 应用安全, 开发工具, 恶意软件防护, 漏洞枚举, 结构化查询, 自动化安全, 软件安全, 钩子