clidey/deptrust

来源：https://github.com/clidey/deptrust

deptrust

     __           __                  __
 ___/ /___  ___  / /________  _______/ /_
/ _  / __ \/ _ \/ __/ ___/ / / / ___/ __/
/  __/ /_/ /  __/ /_/ /  / /_/ (__  ) /_
\__,_/\____/ .___/\__/_/   \__,_/____/\__/
           /_/

deptrust 是一个命令行工具，用于检查 npm、PyPI、crates.io、Go 模块、RubyGems、NuGet、Maven、Packagist、pub.dev、CocoaPods、Hex.pm、Hackage、GitHub Actions 等生态系统中软件包版本的已知漏洞。

它作为 CLI 和 MCP 服务器在本地运行。它直接调用公共包注册表和 OSV API；没有需要信任或配置的托管 deptrust 服务。

该工具源于对 AI 代理持续使用旧版本这一问题的厌倦。

目录

• 适用范围
• CLI 使用方法
• 安装
• 代理配置
• 手动 MCP 配置
• MCP 工具
• 仅使用技能（Skill）模式
• 故障排除

适用范围

支持的生态系统：

• npm，包括作用域包如 @clidey/ux
• PyPI
• Cargo / crates.io
• Go 模块
• RubyGems
• NuGet
• Maven，使用 groupId:artifactId 包名
• Packagist / Composer，使用 vendor/package 包名
• pub.dev
• CocoaPods
• Hex.pm
• Hackage
• GitHub Actions，使用 owner/repo 包名以及标签、分支引用或提交 SHA 作为版本

deptrust 当前报告已知漏洞并给出简单建议：

allow 表示在公开数据源中未发现阻止性的已知漏洞，但不证明该包是安全的。

deptrust 还会发出非 CVE 的风险信号。例如，过去 72 小时内发布的版本会被标记为需要审查，防止代理盲目安装全新版本。

同时并行查询以下公告提供者：

• OSV
• GitHub Advisory Database（包括已审查公告和恶意软件公告）

提供者覆盖范围因生态系统而异。如果 deptrust 能解析注册表元数据，但没有任何配置的漏洞提供者支持该生态系统，则返回 unknown，而不是将该包视为安全。

提供者覆盖情况：

JSON 输出包含公告覆盖字段：

• checked_providers：deptrust 实际查询的漏洞提供者
• skipped_providers：因生态系统不支持而跳过的已配置提供者
• advisory_coverage：full、partial、none 或 error
• advisory_coverage_reason：覆盖值的简短说明

CLI 使用方法

检查指定版本：

deptrust check npm lodash 4.17.20

正常响应示例：

npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80

检查最新版本：

deptrust check pypi requests latest

输出 JSON：

deptrust check --json cargo serde latest

检查 Go 模块：

deptrust check go golang.org/x/crypto latest

检查 RubyGems、NuGet 或 Maven：

deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest

检查 Packagist、pub.dev、CocoaPods、Hex.pm、Hackage 或 GitHub Actions：

deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
deptrust check hex plug latest
deptrust check hackage aeson latest
deptrust check github-actions actions/checkout v7.0.0
deptrust check github-actions actions/checkout main

对于 GitHub Actions，完整的提交 SHA 被视为已固定。完整的语义化版本标签（如 v4.2.2）被接受，不会额外发出固定信号。仅主版本号标签（如 v4）和分支引用（如 main）虽然是有效的引用，但 deptrust 会添加审查信号，因为它们可能发生变动。

JSON 响应示例：

{
  "ecosystem": "npm",
  "package": "lodash",
  "version": "4.17.20",
  "latest_version": "4.17.21",
  "known_vulnerabilities_found": true,
  "safe_to_use": false,
  "should_install": false,
  "risk_score": 80,
  "recommendation": "block",
  "classification": "vulnerable",
  "reason": "Found 2 known vulnerability records.",
  "next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
  "summary": "lodash 4.17.20 has 2 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
  "signals": [],
  "checked_providers": [
    "OSV",
    "GitHub Advisory DB"
  ],
  "skipped_providers": [],
  "advisory_coverage": "full",
  "advisory_coverage_reason": "all configured vulnerability providers were checked",
  "vulnerabilities": [
    {
      "id": "GHSA-35jh-r3h4-6jhm",
      "aliases": [
        "CVE-2021-23337"
      ],
      "cve_ids": [
        "CVE-2021-23337"
      ],
      "ghsa_ids": [
        "GHSA-35jh-r3h4-6jhm"
      ],
      "summary": "Command Injection in lodash",
      "severity": "high",
      "source": "OSV",
      "advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
      "affected_ranges": [
        "SEMVER: introduced 0, fixed 4.17.21"
      ],
      "fixed_versions": [
        "4.17.21"
      ],
      "references": [
        {
          "type": "ADVISORY",
          "url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
        }
      ]
    }
  ],
  "provider_errors": []
}

仅当最新版本未发现已知漏洞时，推荐最新版本：

deptrust suggest npm lodash

如果最新版本不被允许，suggest 会检查较旧的已知版本，并返回获得 allow 建议的最新版本。

当公告中包含修复版本时，suggest 会先检查提供者报告的这些修复版本，然后再通过注册表版本列表往回遍历。

比较两个版本：

deptrust compare npm lodash 4.17.20 4.17.21

比较响应示例：

lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target

显示已安装版本：

deptrust version

安装

最简单的安装方式是使用 npx 或 pnpx：

npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install

默认安装是向导式的。它会安装二进制文件，询问要配置哪些代理集成，在修改任何内容前打印用户级目标路径，并要求确认。向导式安装默认启用 MCP、技能回退以及 Codex 和 Claude Code 的依赖安全钩子。添加 --yes 可进行非交互式仅二进制安装，或传递明确的集成标志。

要删除用户级二进制文件、技能和 MCP 条目：

npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall

Homebrew 用户可从 Clidey tap 安装：

brew install clidey/tap/deptrust

或者先添加 tap，然后按常规方式安装和升级：

brew tap clidey/tap
brew install deptrust
brew upgrade deptrust

Go 用户可直接安装：

go install github.com/clidey/deptrust/cmd/deptrust@latest

代理配置

要安装 deptrust 并注册安装程序可配置的所有内容，无需引导提示：

npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all

--all 会安装二进制文件、在 codex CLI 可用时注册 Codex MCP、安装 Codex 技能回退、在 claude CLI 可用时注册 Claude Code MCP，并安装 Codex 和 Claude Code 的依赖安全钩子。

这些钩子是 PreToolUse 钩子。它们在包安装命令运行前进行检查，并且还会检查通过代理文件编辑工具添加到工作流文件中的 GitHub Actions。当 deptrust 返回 review、block 或 unknown 时，钩子会阻止工具调用。安装程序仅写入用户级钩子配置：Codex 的 ~/.codex/hooks.json 和 Claude Code 的 ~/.claude/settings.json。

如需更精细的安装，可使用以下命令：

npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
pnpx @clidey/deptrust@latest install --codex-mcp
pnpx @clidey/deptrust@latest install --claude-code-mcp
pnpx @clidey/deptrust@latest skills install

MCP 设置完成后，代理在推荐更新或更改前会自动检查包。MCP 服务器会发送指令，要求代理审查所有依赖版本——包括回答“我可以更新什么”或“哪些依赖可以安全升级”这类问题——然后再提供建议。

如果在非 MCP 环境中使用 deptrust，请提醒你的代理：

在列出、比较或推荐特定包版本之前，先使用 deptrust 进行检查。这包括回答“我可以更新什么”——在检查已知漏洞之前，不要提供版本建议。

手动 MCP 配置

如果你的客户端支持 stdio MCP 服务器，将其配置为运行：

/absolute/path/to/deptrust mcp

许多客户端使用以下 JSON 格式：

{
  "mcpServers": {
    "deptrust": {
      "command": "/absolute/path/to/deptrust",
      "args": ["mcp"]
    }
  }
}

对于 Codex，你也可以通过以下命令添加：

codex mcp add deptrust -- /absolute/path/to/deptrust mcp

对于 Claude Code：

claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp

在 initialize 时，服务器会返回 MCP instructions，告诉代理何时使用这些工具（在添加、升级或推荐依赖之前，或当询问某个版本是否安全时）。显示服务器指令的客户端会自动应用此功能，因此以上的人工提醒是可选而非必需的。

MCP 工具

check_package

检查包版本并返回已知漏洞及建议。

{
  "ecosystem": "npm",
  "package": "lodash",
  "version": "4.17.20"
}

version 可以省略或设为 latest。如果确切的版本不存在，deptrust 会返回错误并建议最新的显式版本。

MCP 输出有意保持简洁，以便代理无需将完整的公告正文拉入上下文即可决定是否安装依赖。如果用户要求查看完整详情，代理可以运行 full_response_command。

简洁的 MCP 结构化输出示例：

{
  "ecosystem": "npm",
  "package": "vite",
  "version": "7.0.0",
  "latest_version": "8.0.16",
  "known_vulnerabilities_found": true,
  "safe_to_use": false,
  "should_install": false,
  "risk_score": 80,
  "classification": "vulnerable",
  "recommendation": "block",
  "reason": "Found 7 known vulnerability records.",
  "next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
  "summary": "vite 7.0.0 has 7 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
  "vulnerability_count": 7,
  "vulnerability_counts": {
    "critical": 0,
    "high": 2,
    "medium": 3,
    "low": 2,
    "unknown": 0
  },
  "highest_severity": "high",
  "checked_providers": [
    "OSV",
    "GitHub Advisory DB"
  ],
  "skipped_providers": [],
  "advisory_coverage": "full",
  "advisory_coverage_reason": "all configured vulnerability providers were checked",
  "full_response_command": "deptrust check --json npm vite 7.0.0"
}

简洁的 MCP 响应省略了漏洞数组、公告 details 以及重复的 references。代理应默认使用计数、最高严重级别、提供者覆盖情况、建议和下一步操作。如果用户要求查看完整的公告详情，请运行 full_response_command。

suggest_safe_version

首先检查最新版本。如果最新版本不被允许，则先检查提供者报告的修复版本，再检查较旧的已知版本，并建议获得 allow 建议的最新版本。

{
  "ecosystem": "npm",
  "package": "lodash"
}

compare_versions

比较当前版本和目标版本，包括已解决和新增的漏洞。

{
  "ecosystem": "npm",
  "package": "lodash",
  "from_version": "4.17.20",
  "to_version": "4.17.21"
}

仅使用技能（Skill）模式

如果你不想使用 MCP，可以安装附带的 Codex 技能：

npx @clidey/deptrust skills install

该技能会告诉 Codex 在安装、更新或推荐 npm、PyPI、Cargo、Go 模块、RubyGems、NuGet、Maven、Packagist、pub.dev、CocoaPods、Hex.pm、Hackage 和 GitHub Actions 包之前调用 deptrust CLI。

故障排除

如果找不到 deptrust：

export PATH="$HOME/.local/bin:$PATH"

如果 MCP 客户端无法启动服务器，请查找完整路径：

which deptrust

然后将该绝对路径放入 MCP 配置。

如果包检查返回 unknown，请不要将该包视为安全。通常这意味着 deptrust 无法从提供者获得完整答案。