Baneado98/npm-guardian

# npm-guardian 🛡️ [](https://www.npmjs.com/package/npm-guardian-mcp) [](./LICENSE) [](https://modelcontextprotocol.io) **在运行 `npm install` 之前，对 npm 包进行供应链攻击审查。** ``` npx -y npm-guardian-mcp # MCP server, ready for Claude / Cursor / any agent ``` `npm-guardian` 是一款专为 AI 编程智能体和开发者打造的安全工具。只需提供一个包名，它就会返回带有详细风险评分说明的 **SAFE（安全） / SUSPICIOUS（可疑） / DANGEROUS（危险）** 判定结果。它完成了单一工具在一次调用中无法做到的事情——将**已知漏洞查询**与**行为供应链检测**相结合： - 🛡️ **已知 CVE / GHSA 安全公告** — 将确切版本与 [OSV.dev](https://osv.dev) 数据库（Google 的开源漏洞反馈源：包含 CVE、GitHub 公告、npm 公告和恶意软件记录）进行交叉比对，并告诉您**应升级到的确切修复版本**。这是事实，而非启发式推测。 - 🎯 **Typosquatting（域名/包名抢注）** — 名称与热门包仅有一两个字符之差的包（例如 `lodahs` → `lodash`，`expres` → `express`，以及 2026 年的 `easy-day-js` → `dayjs` 攻击活动）。 - 💀 **恶意安装脚本** — 通过 `preinstall`/`postinstall` 钩子将远程下载内容通过管道传递给 shell、生成子进程、执行 `eval()` 或解码 base64 投放器。 - 🔑 **凭据与加密密钥窃取标记** — 脚本读取 `AWS_*`/`GITHUB_*`/`NPM_TOKEN`/`PRIVATE_KEY` 等环境变量，或触碰 `~/.ssh`、`~/.aws`、`.npmrc`、`id_rsa`、`wallet.dat` 等文件。 - 🆕 **刚发布、低信任度的包** — 在供应链攻击中被大量滥用，尤其是在与安装脚本结合使用时。 - 🚫 **依赖混淆 / 不在注册表中** + 缺少源代码仓库、无维护者、已被弃用等。 ### 🔬 深度 tarball 检查（差异化优势） 元数据只能告诉您作者*声明*了什么。通过 `deep` 模式，`npm-guardian` 会下载**实际发布的 `.tgz`** 文件，**在内存中**将其解压（没有 shell 调用，没有临时文件，不执行任何代码），并扫描**真实的源代码文件**，以发现 manifest 中隐藏的恶意模式——此外，它还能识别**index 与 tarball 之间的篡改**（即 `package.json` 中的安装脚本在 registry 索引和发布的 tarball 中存在差异，这是一种已知的隐蔽技术）。大多数 npm 扫描器从不深入检查 tarball 内部；而这款工具做到了。 它以**只读**方式运行：检查 npm registry 元数据、安装脚本源代码，以及（在 deep 模式下）已发布的包文件内容。它绝不执行包中的代码。 ## 作为 MCP server 使用（免费） 任何兼容 MCP 的智能体（Claude Desktop、Claude Code、Cursor 等）都可以调用它。 ``` { "mcpServers": { "npm-guardian": { "command": "npx", "args": ["-y", "npm-guardian-mcp"] } } } ``` 提供的工具： | Tool | 功能描述 | |------|--------------| | `audit_npm_package` | 审查单个包（`name`，可选 `version`，可选 `deep` 用于真实 tarball 检查）。 | | `audit_many` | 一次性审查整个依赖列表。 | 智能体提示词示例：*“在安装 `chalk` 之前，先对它运行 npm-guardian。”* ## 作为 HTTP API 使用 ``` GET /audit?name=&version= # FREE, metadata audit, rate-limited (30/h/IP) GET /audit_many?names=a,b,c # FREE, up to 10 packages GET /pro/audit?name= # PAID, DEEP tarball-source audit, no limit GET /pro/audit_many?names=... # PAID, DEEP, up to 50 packages ``` 免费响应（已知存在漏洞的版本）： ``` { "package": "lodash", "version": "4.17.20", "verdict": "SUSPICIOUS", "score": 25, "summary": "SUSPICIOUS — 5 known vulnerabilities for lodash@4.17.20. Review before installing. (fix available: upgrade to 4.17.21+)", "meta": { "knownVulns": 5, "hasInstallScripts": false, "repository": "git+https://github.com/lodash/lodash.git" }, "knownVulns": [ { "id": "CVE-2021-23337", "severity": "high", "summary": "Command Injection in lodash", "fixedIn": "4.17.21" }, { "id": "CVE-2020-8203", "severity": "high", "summary": "Prototype Pollution in lodash", "fixedIn": "4.17.19" } ] } ``` ### 💁 使用 x402 按次付费（USDC，无需账户，无需 API key） `/pro/*` 路由受 [x402](https://x402.org) 支付协议保护。 您的 AI 智能体每次调用会自动支付 **$0.02 USDC** — 无需注册，无需 API key，也无需订阅。结算通过链上方式以 **Base 网络上的 USDC**（即 x402 Bazaar 及大多数付费智能体使用的网络）进行，直接转入运营者的钱包。服务器**不持有任何私钥**；它只声明一个公开的收款地址。 在没有支付的情况下调用 `/pro/audit` 将返回标准的 `402 Payment Required` 挑战，任何支持 x402 的客户端（例如 `@x402/axios`、x402 MCP 客户端）都可以透明地满足此要求。 ## 自行运行 ``` npm install npm run build # MCP (stdio) npm run start:mcp # HTTP API PORT=8080 npm run start:http ``` HTTP server 的环境变量： | 变量 | 默认值 | 含义 | |-----|---------|---------| | `PORT` | `8080` | HTTP 端口 | | `X402_PAYTO` | operator wallet | 接收地址（公开） | | `X402_NETWORK` | `base` | x402 结算网络 | | `X402_PRICE` | `$0.02` | 每次付费调用的价格 | | `X402_FACILITATOR_URL` | – | 在您的网络上负责结算的 facilitator | | `X402_ENABLED` | `true` | 设置为 `false` 可禁用付费路由（全部免费） | ## 开发初衷 2026 年对 npm 供应链攻击而言是残酷的一年：通过 Typosquatting 伪造的 OpenSearch/Elastic 包窃取 CI/CD 密钥；`@mastra` 组织遭到入侵，通过 `easy-day-js` 抢注包对 140 多个包植入了后门；以及一波又一波隐藏在 `postinstall` 钩子中的信息窃取恶意软件。如今，智能体会自主执行 `npm install`——它们需要一种廉价、快速的预检查机制。这就是 `npm-guardian` 的用武之地。 ## 相关工具 [**import-guardian**](https://github.com/Baneado98/import-guardian) — 作用在更早一步的配套工具：它读取一段 AI 生成的代码，并标记出**幻觉/恶意抢注的 import**（即模型凭空捏造的、在 npm 上根本不存在的包）。建议在新鲜生成的代码上使用 `import-guardian`，然后再用 `npm-guardian` 审查您决定保留的包。 [**license-guardian**](https://github.com/Baneado98/license-guardian) — 第三款守护工具：在您发布软件之前，它会根据您的分发方式，审查依赖项的**许可证**（GPL/AGPL 等传染性开源协议、BUSL/SSPL 等源码可见协议、以及无许可证情况）。 [**lockfile-guardian**](https://github.com/Baneado98/lockfile-guardian) — 第四款守护工具：它将您已解析的 **`package-lock.json`** 与线上的 npm registry 进行比对，拦截完整性（sha512）不匹配的情况（即 lockfile 投毒），并标记出运行安装脚本或原生 `node-gyp` 脚本的新增依赖。 ## 许可证 MIT

标签：MCP, MITM代理, npm, Python脚本, StruQ, 云安全监控, 文档安全, 自动化攻击, 静态分析