deptrust

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

deptrust 是一款 CLI 工具，用于检查 npm、PyPI、crates.io、Go modules、RubyGems、NuGet、Maven、Packagist、pub.dev、CocoaPods、Hex.pm、Hackage、GitHub Actions 等生态系统中软件包版本是否存在已知漏洞。

它既可作为 CLI 在本机运行，也可作为 MCP 服务器运行。它直接调用公共软件包注册表和 OSV API；不存在需要信任或配置的托管式 deptrust 服务。

这个工具的诞生源于一个令人沮丧的现状：AI 代理总是使用旧版本。

适用范围

支持的生态系统：

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

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

最高已知严重级别	建议
critical	block
high	block
medium / unknown	review
low	allow
none found	allow

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：对覆盖值的简要说明
registry_verification：当注册表元数据确认了版本时为 verified；当在暂时性注册表故障后仍继续执行精确版本检查时为 unverified
registry_verification_reason：当验证不可用时的注册表错误

当注册表验证暂时不可用时，精确版本检查仍会查询漏洞公告提供方。该结果始终不可安装，也绝不会获得 allow 建议。对 latest、未知软件包以及明确不存在的版本的检查，仍要求成功完成注册表解析。

HTTP 请求对 429、502、503 和 504 响应最多重试三次。重试使用较短的指数退避延迟，并遵循最多两秒的 Retry-After 值；服务器要求更长的等待时会快速失败，以免 CLI 挂起。漏洞公告重试次数用尽会使结果不完整，并阻止给出 allow 建议。

GitHub API 认证

GitHub Advisory Database 和 GitHub Actions API 请求可以使用短期、最低权限的 GitHub App token。在 CI 中，通过 DEPTRUST_GITHUB_TOKEN 传递它：

DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20

凭据的优先级依次为 DEPTRUST_GITHUB_TOKEN、GITHUB_TOKEN，然后是 GH_TOKEN。本地使用时，可通过 DEPTRUST_GITHUB_AUTH=gh deptrust check ... 显式启用可选的 GitHub CLI 回退；它会直接运行 gh auth token，不进行任何提示。如果没有可用凭据，DepTrust 会以未认证方式继续运行。GitHub API 速率限制或权限失败会产生带诊断信息的 unknown，绝不会被视为仅 OSV 的成功结果。

DepTrust 从不存储、捆绑、缓存、记录、遥测或输出 GitHub token。认证头仅发送到 https://api.github.com。

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 被视为固定版本。完整的 semver 标签（如 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",
  "registry_verification": "verified",
  "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、技能和钩子配置。如果某个集成指向旧的 deptrust 二进制文件，或其托管配置已发生变化，安装程序会自动更新；用户无需手动删除并重新添加 MCP 服务器。自定义技能会在替换前进行备份。

要移除用户级二进制文件、技能和 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

Homebrew 安装完成后会打印一条提醒。要使用 Homebrew 二进制文件本身运行引导式 Codex 和 Claude Code 设置（MCP 注册和依赖安全钩子）：

deptrust setup

引导式设置会在启用 MCP 和依赖安全钩子前征求确认。它会保留已使用当前二进制文件的注册，并协调指向较旧 npm、Homebrew 或源码安装路径的现有 DepTrust 注册。

Go 用户可以直接安装：

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

Nix

该项目为已经在使用 Nix 的用户提供了可选的 Nix flake 输出。flake 封装了预构建的发行二进制文件。

# Run without installing
nix run github:clidey/deptrust

# Install into your profile
nix profile install github:clidey/deptrust

常规的发布工作流会从其发布的同一归档生成 Nix 哈希，在发布前评估 flake，然后在更新默认分支之前，针对已发布的资产进行构建和运行。在该工作流运行期间，github:clidey/deptrust 可能会短暂滞后。发布标签指向生成 flake 更新之前的源码提交，可能仍引用之前的二进制文件；当可重现性至关重要时，请固定一个 flake.nix 中包含所需版本的提交。

Devbox

如需可重现的开发环境，请使用 Devbox：

# Install Devbox first (if not already installed)
curl -fsSL https://get.jetify.dev/devbox | bash

# Initialize the environment
devbox shell

# Build the project
devbox run build

devbox.json 约束了工具链版本，已提交的 devbox.lock 固定了确切的软件包版本和 nixpkgs 修订版。当你确实想刷新这些固定版本时，请运行 devbox update。

或者通过 Homebrew 安装 Devbox：

brew install jetify-com/devbox/devbox

代理设置

要安装 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。

当 gh CLI 可用时，引导式设置还会提供使用其现有的本地登录凭据进行钩子检查。这只会写入 DEPTRUST_GITHUB_AUTH=gh，绝不写入 GitHub token，因此钩子子进程可以避免未认证的 GitHub API 速率限制。

如果更倾向于更精细的安装，可以使用以下命令：

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，请提醒你的代理：

Before listing, comparing, or recommending specific package versions, check them with deptrust. This includes answering "what can I update" — do not provide version recommendations until after checking for known vulnerabilities.

对于 CI，请为运行 DepTrust 的进程配置短期、最低权限的 GitHub App token 作为 DEPTRUST_GITHUB_TOKEN。对于本地 GitHub CLI 认证，请使用 DEPTRUST_GITHUB_AUTH=gh deptrust check ...。DepTrust 从不存储 token。

手动 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",
  "registry_verification": "verified",
  "full_response_command": "deptrust check --json npm vite 7.0.0"
}

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

当 GitHub 公告访问受到速率限制或不可用时，MCP 返回 unknown。代理应主动提议配置 token 并重试、跳过或推迟该版本，或仅在用户明确接受该精确版本未解决的 GitHub 覆盖风险后才继续。该例外必须明确标记为用户接受的不确定性；绝不能报告为 allow 或作为该版本安全的证明。

`suggest_safe_version`

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

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

`compare_versions`

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

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

仅使用技能

如果你不需要 MCP，请安装随附的 Codex 技能：

npx @clidey/deptrust skills install

该技能会告诉 Codex 在安装、更新或推荐 npm、PyPI、Cargo、Go module、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 无法从漏洞公告提供方获得完整答案，或无法通过其注册表验证精确版本。

npm	是	是	是
PyPI	是	是	是
Cargo / crates.io	是	是	是
Go modules	是	是	是
RubyGems	是	是	是
NuGet	是	是	是
Maven	是	是	是
Packagist / Composer	是	是	是
pub.dev	是	是	是
CocoaPods	是	否	是
Hex.pm	是	是	是
Hackage	是	是	否
GitHub Actions	是	是	是

deptrust

最受欢迎

deptrust

目录

适用范围

GitHub API 认证

CLI 用法

安装

Nix

Devbox

代理设置

手动 MCP 设置

MCP 工具

check_package

suggest_safe_version

compare_versions

仅使用技能

故障排查

`check_package`

`suggest_safe_version`

`compare_versions`