返回更新列表
新发布Jul 21, 2026

deptrust v0.13.0

CLI和MCP服务器,用于检查14+生态系统(包括npm、PyPI、crates.io、Go模块和GitHub Actions)中包版本的已知漏洞。通过钩子和技能与AI代理集成。

分享

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 目前会报告已知漏洞并给出简单建议:

最高已知严重级别建议
criticalblock
highblock
medium / unknownreview
lowallow
none foundallow

allow 表示在公共数据源中未发现阻断性的已知漏洞。它并不能证明某个软件包是安全的。

deptrust 还会发出不属于 CVE 的风险信号。例如,过去 72 小时内发布的版本会被标记为需要审查,这样代理就不会盲目安装全新的发行版。

漏洞公告提供方会被并行查询:

  • OSV
  • GitHub Advisory Database,包括已审核的公告和恶意软件公告

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

提供方覆盖范围:

生态系统注册表元数据OSVGitHub Advisory DB
npm
PyPI
Cargo / crates.io
Go modules
RubyGems
NuGet
Maven
Packagist / Composer
pub.dev
CocoaPods
Hex.pm
Hackage
GitHub Actions

JSON 输出包含以下漏洞公告覆盖字段:

  • checked_providers:deptrust 实际查询过的漏洞提供方
  • skipped_providers:因生态系统不受支持而被跳过的已配置提供方
  • advisory_coveragefullpartialnoneerror
  • advisory_coverage_reason:对覆盖值的简要说明
  • registry_verification:当注册表元数据确认了版本时为 verified;当在暂时性注册表故障后仍继续执行精确版本检查时为 unverified
  • registry_verification_reason:当验证不可用时的注册表错误

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

HTTP 请求对 429502503504 响应最多重试三次。重试使用较短的指数退避延迟,并遵循最多两秒的 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_TOKENGITHUB_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

安装

最简单的安装方式是使用 npxpnpx

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 返回 reviewblockunknown 时,钩子会阻止该工具调用。安装程序仅写入用户级钩子配置: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 无法从漏洞公告提供方获得完整答案,或无法通过其注册表验证精确版本。

分类