deptrust

# deptrust

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

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 代理总是使用旧版本。

## 目录

- [适用范围](#scope)
- [CLI 用法](#cli-usage)
- [安装](#install)
- [代理设置](#agent-setup)
- [手动 MCP 设置](#manual-mcp-setup)
- [MCP 工具](#mcp-tools)
- [仅使用技能](#skill-only-use)
- [故障排查](#troubleshooting)

## 适用范围

支持的生态系统：

- 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`，而不是将该软件包视为安全。

提供方覆盖范围：

| 生态系统 | 注册表元数据 | OSV | GitHub 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_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` 传递它：

```bash
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 用法

检查精确版本：

```bash
deptrust check npm lodash 4.17.20
```

普通响应示例：

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

检查最新版本：

```bash
deptrust check pypi requests latest
```

返回 JSON：

```bash
deptrust check --json cargo serde latest
```

检查 Go 模块：

```bash
deptrust check go golang.org/x/crypto latest
```

检查 RubyGems、NuGet 或 Maven：

```bash
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：

```bash
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 响应示例：

```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": []
}
```

仅当未发现已知漏洞时建议使用最新版本：

```bash
deptrust suggest npm lodash
```

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

当公告包含已修复版本时，`suggest` 会先检查这些提供方报告的已修复版本，然后再回溯注册表版本列表。

比较两个版本：

```bash
deptrust compare npm lodash 4.17.20 4.17.21
```

比较响应示例：

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

显示已安装版本：

```bash
deptrust version
```

## 安装

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

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

默认安装程序是引导式的。它会安装二进制文件，询问要配置哪些代理集成，在进行任何更改之前打印用户级目标位置，并要求确认。引导式安装程序默认启用 MCP、技能回退以及 Codex 和 Claude Code 的依赖安全钩子。如需非交互式仅安装二进制文件，请添加 `--yes`，或传入显式的集成标志。

重新运行安装程序是安全的。它会静默保留未变的 MCP、技能和钩子配置。如果某个集成指向旧的 deptrust 二进制文件，或其托管配置已发生变化，安装程序会自动更新；用户无需手动删除并重新添加 MCP 服务器。自定义技能会在替换前进行备份。

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

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

Homebrew 用户可以从 Clidey tap 安装：

```bash
brew install clidey/tap/deptrust
```

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

```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```

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

```bash
deptrust setup
```

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

Go 用户可以直接安装：

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

### Nix

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

```bash
# Run without installing
nix run github:clidey/deptrust

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

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

### Devbox

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

```bash
# 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：

```bash
brew install jetify-com/devbox/devbox
```

## 代理设置

要安装 deptrust 并在没有引导提示的情况下注册安装程序可配置的所有内容：

```bash
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 速率限制。

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

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

```text
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 服务器，请将其配置为运行：

```bash
/absolute/path/to/deptrust mcp
```

许多客户端使用这种 JSON 形式：

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

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

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

对于 Claude Code：

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

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

## MCP 工具

### `check_package`

检查某个软件包版本，并返回已知漏洞及建议。

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

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

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

精简 MCP 结构化输出示例：

```json
{
  "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` 建议的最新版本。

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

### `compare_versions`

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

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

## 仅使用技能

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

```bash
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`：

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

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

```bash
which deptrust
```

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

如果软件包检查返回 `unknown`，请不要将该软件包视为安全。这意味着 deptrust 无法从漏洞公告提供方获得完整答案，或无法通过其注册表验证精确版本。