dependency-auditor

@guardbee/mcp-dependency-auditor

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

一个 MCP 服务，可针对 OSV 数据库审计 npm 和 pip 清单，查找已知 CVE。单个软件包查询还支持 PyPI、crates.io、Maven、Go 和 RubyGems。

默认情况下，遥测功能处于关闭状态。设置 GUARDBEE_TELEMETRY=1 后，会发送服务、工具、成功状态、耗时以及文件路径等较短的参数值；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

---

功能

• OSV API 集成 — Google 的开源漏洞数据库（免费，无需身份验证）
• npm 支持 — 从 package-lock.json / npm-shrinkwrap.json（v1/v2/v3）、pnpm-lock.yaml（v5/v6/v9）、yarn.lock（v1 和 Berry）和 bun.lock 读取确切版本；如果不存在，则使用 package.json 中的版本范围。包含传递依赖项；即使锁文件未标记，也会区分仅用于开发的依赖项（pnpm v9、yarn、bun）
• Rust、Go、Ruby、PHP — Cargo.lock（从 Cargo.toml 获取开发依赖项）、go.mod（识别 // indirect 和 replace）、Gemfile.lock（合并不同平台的构建版本，从 Gemfile 获取开发分组）和 composer.lock（packages-dev），由 audit 和 audit_directory 工具审计
• pip 支持 — 从 uv.lock、poetry.lock 和 Pipfile.lock 读取确切版本（区分开发分组）；如果不存在，则使用 requirements.txt、requirements/base.txt、requirements/prod.txt 和 pyproject.toml
• 恶意包检测 — 已知恶意版本（OpenSSF MAL-* 条目以及归类为 CWE-506 的公告，例如 2025 年 9 月遭劫持的 [email protected] / [email protected]）会优先作为严重问题报告，并给出移除包和轮换凭据的操作建议；任何 --fail-on 阈值都会因此失败
• 漏洞利用优先级排序 — 使用 CISA KEV（已在实际环境中遭利用、被用于勒索软件）和 FIRST EPSS（30 天内遭利用的概率）丰富发现结果，并按恶意软件 → KEV → 严重性 → EPSS 排序。使用 --fail-on-kev / --fail-on-epss=<0-1> 将其设为 CI 门禁（--fail-on=none 会关闭严重性门禁）。仅发送 CVE ID；使用 --no-exploit-data 或在 guardbee.yml 中设置 exploit-data: false 可关闭此功能
• 严重性评分 — 根据 CVSS 评分或文本启发式规则划分为严重 / 高 / 中 / 低
• 修复计划 — 每个包给出一个升级版本：列出的能修复所有公告的最小版本（例如 log4j-core 2.14.1 → 2.25.4 (fixes 7/7)），并指出仍未解决的公告和跨越主版本的升级。每项发现的修复版本会遵循已安装版本所属的发布系列（next-auth 5.0.0-beta.31 → 5.0.0-beta.32，而不是 4.24.15），并使用 SemVer、PEP 440 或 Maven 风格的版本排序
• CVE 链接 — 提供指向 NVD 或 osv.dev 的直接链接
• 依赖路径 — 每项发现都会显示包的安装路径（[email protected] › [email protected]），修复计划会指出需要升级的直接依赖项（← via [email protected]）。适用于 package-lock.json v2/v3、pnpm、yarn、bun 和 uv 锁文件
• 去重后的发现 — 互为别名的公告（GHSA + PYSEC、GHSA + MAL）会合并为一项发现；忽略列表中的任意 ID 均可匹配
• 测试 — 使用真实包管理器生成的锁文件和模拟 OSV API 进行单元测试

---

快速开始

npm install -g @guardbee/mcp-dependency-auditor

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "guardbee-dependency-auditor": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-dependency-auditor"]
    }
  }
}

---

MCP 工具

工具	描述
audit_npm	审计 npm 依赖项（package-lock、pnpm、yarn、bun 锁文件或 package.json）
audit_pip	审计 Python 依赖项（uv、Poetry、Pipenv 锁文件或 requirements.txt / pyproject.toml）
audit_package	根据名称、版本和生态系统审计单个包
audit_directory	自动检测并审计所有受支持的清单文件

使用示例

你可以向 Claude 提问：

“审计我项目的 npm 依赖项：/Users/me/my-app”

“lodash 4.17.20 是否存在 CVE？”

“扫描我的 Python 项目：/Users/me/django-app”

输出示例

⚠️  Found 3 vulnerabilities in 2/142 npm packages (1243ms)
   Critical: 1  High: 1  Medium: 1  Low: 0  Unknown: 0

[CRITICAL] [email protected]
  ID      : GHSA-35jh-r3h4-6jhm (CVE-2021-23337)
  Summary : Command injection via template
  Fix     : upgrade to [email protected]
  Details : https://nvd.nist.gov/vuln/detail/CVE-2021-23337

---

支持的生态系统

audit_package 工具可直接查询以下生态系统：

生态系统	参数
npm	npm
Python	PyPI
Rust	crates.io
Java	Maven
Go	Go
Ruby	RubyGems

---

CLI — CI/CD 集成

除了 MCP 服务模式外，也可以直接将其用作 CLI：

# Audit all dependencies in a directory (npm + pip auto-detected)
npx @guardbee/mcp-dependency-auditor audit ./my-project

# npm only
npx @guardbee/mcp-dependency-auditor audit-npm . --fail-on=critical

# pip only
npx @guardbee/mcp-dependency-auditor audit-pip . --fail-on=high

# Single package
npx @guardbee/mcp-dependency-auditor audit-pkg lodash 4.17.20 npm

# JSON output
npx @guardbee/mcp-dependency-auditor audit . --format=json

# Fail only on what attackers actually use: CISA KEV, or EPSS ≥ 10%
npx @guardbee/mcp-dependency-auditor audit . --fail-on=none --fail-on-kev --fail-on-epss=0.1

退出代码： 0 = 无问题 · 1 = 发现超过阈值的问题 · 2 = 错误

GitHub Actions

name: Dependency Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Audit dependencies
        run: npx @guardbee/mcp-dependency-auditor audit . --fail-on=high

GitLab CI

dependency-audit:
  image: node:20
  script:
    - npx @guardbee/mcp-dependency-auditor audit . --fail-on=high
  only:
    - merge_requests
    - main

Pre-commit Hook

# .git/hooks/pre-push
npx @guardbee/mcp-dependency-auditor audit . --fail-on=critical || exit 1

---

开发

npm install
npm test          # 20 unit tests
npm run build     # TypeScript compile

---

许可证

MIT — GuardBee

反馈

有疑问、想法，或发现误报？请在 GitHub Discussions 中发起讨论，或提交问题。如果 GuardBee 对你有帮助，请在仓库点个 ⭐，帮助其他人发现它。