clidey/deptrustCLIおよびMCPサーバーで、npm、PyPI、crates.io、Goモジュール、GitHub Actionsを含む14以上のエコシステムにわたって、パッケージバージョンの既知の脆弱性をチェックします。フックとスキルを介してAIエージェントと統合します。
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
deptrust は、npm、PyPI、crates.io、Go モジュール、RubyGems、NuGet、Maven、Packagist、pub.dev、CocoaPods、Hex.pm、Hackage、GitHub Actions などについて、パッケージバージョンの既知の脆弱性をチェックする CLI です。
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 モジュール
- RubyGems
- NuGet
- Maven（`groupId:artifactId` 形式のパッケージ名を使用）
- Packagist / Composer（`vendor/package` 形式のパッケージ名を使用）
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions（`owner/repo` 形式のパッケージ名と、タグ、ブランチ参照、コミット SHA をバージョンとして使用）
deptrust は現在、既知の脆弱性を報告し、シンプルな推奨を提供します：
| 最高既知の深刻度 | 推奨 |
| --- | --- |
| 重大 | ブロック |
| 高 | ブロック |
| 中 / 不明 | 確認 |
| 低 | 許可 |
| なし | 許可 |
`許可` は、公開データソースでブロックする既知の脆弱性が見つからなかったことを意味します。パッケージが安全であることを証明するものではありません。
deptrust は CVEs ではないリスクシグナルも出力します。たとえば、過去 72 時間以内に公開されたバージョンは確認対象としてマークされ、エージェントが新しいリリースを盲目的にインストールしないようにします。
アドバイザリプロバイダーは並行して照会されます：
- OSV
- GitHub Advisory Database（レビュー済みアドバイザリとマルウェアアドバイザリを含む）
プロバイダーのカバレッジはエコシステムによって異なります。deptrust がレジストリメタデータを解決できても、設定された脆弱性プロバイダーがそのエコシステムをサポートしていない場合、パッケージを安全として扱う代わりに `不明` を返します。
プロバイダーカバレッジ：
| エコシステム | レジストリメタデータ | OSV | GitHub Advisory DB |
| --- | --- | --- | --- |
| npm | あり | あり | あり |
| PyPI | あり | あり | あり |
| Cargo / crates.io | あり | あり | あり |
| Go モジュール | あり | あり | あり |
| 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`：検証が利用できなかった場合のレジストリエラー
正確なバージョンチェックは、レジストリ検証が一時的に利用できない場合でも、アドバイザリプロバイダーに照会します。その結果は常にインストール不可となり、`許可` の推奨は決して受けません。`latest` のチェック、不明なパッケージ、および確定的に存在しないバージョンは、依然として正常なレジストリ解決を必要とします。
HTTP リクエストは、`429`、`502`、`503`、`504` の応答に対して最大 3 回の再試行を行います。再試行では短い指数関数的遅延を使用し、`Retry-After` 値は最大 2 秒まで尊重します。サーバーから要求されたより長い待機は即座に失敗し、CLI がハングしないようにします。アドバイザリの再試行を使い果たすと、結果は不完全になり、`許可` の推奨を防ぎます。
### GitHub API 認証
GitHub Advisory Database および GitHub Actions API リクエストでは、有効期間が短く、最小権限の GitHub App トークンを使用できます。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` の順です。ローカル使用では、オプションの GitHub CLI フォールバックを `DEPTRUST_GITHUB_AUTH=gh deptrust check ...` で明示的に有効にできます。プロンプトなしで `gh auth token` を実行します。認証情報がない場合、DepTrust は認証なしで続行します。GitHub API のレート制限または権限エラーが発生すると、診断情報とともに `不明` が生成され、OSV のみの成功として扱われることはありません。
DepTrust は GitHub トークンを保存、バンドル、キャッシュ、ログ、テレメトリ、または出力することは決してありません。認証ヘッダーは `https://api.github.com` にのみ送信されます。
## CLI の使い方
正確なバージョンをチェック：
```bash
deptrust check npm lodash 4.17.20
```
通常の応答例：
```text
npm [email protected]: 2 件の既知の脆弱性が見つかりました
推奨: ブロック
リスクスコア: 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 は固定として扱われます。`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` は既知の古いバージョンをチェックし、`許可` 推奨のある最新のバージョンを返します。
アドバイザリに修正バージョンが含まれている場合、`suggest` はレジストリバージョンリストを遡る前に、プロバイダーが報告した修正バージョンを最初にチェックします。
2 つのバージョンを比較：
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
比較応答例：
```text
lodash 4.17.20 -> 4.17.21 はリスクを改善: スコア 80 → 0。
推奨: 許可
次のアクション: 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 出力を提供します。フレークは、プリビルドされたリリースバイナリをラップします。
```bash
# インストールせずに実行
nix run github:clidey/deptrust
# プロファイルにインストール
nix profile install github:clidey/deptrust
```
通常の[リリースワークフロー](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml)は、公開するアーカイブから Nix ハッシュを生成し、公開前にフレークを評価し、公開されたアセットに対してビルドして実行してから、デフォルトブランチを更新します。`github:clidey/deptrust` は、そのワークフローの実行中に一時的に遅れる場合があります。リリースタグは、生成されたフレーク更新前のソースコミットを指し、以前のバイナリを参照する可能性があります。再現性が重要な場合は、`flake.nix` が必要なバージョンを含むコミットを固定してください。
### Devbox
再現可能な開発環境には、Devbox を使用します：
```bash
# Devbox を最初にインストール（まだインストールされていない場合）
curl -fsSL https://get.jetify.dev/devbox | bash
# 環境を初期化
devbox shell
# プロジェクトをビルド
devbox run build
```
`devbox.json` はツールチェーンバージョンを制約し、コミットされた `devbox.lock` は正確なパッケージバージョンと nixpkgs のリビジョンを固定します。これらのピンを意図的に更新する場合は `devbox update` を実行します。
または、Devbox を Homebrew でインストール：
```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 が `確認`、`ブロック`、または `不明` を返した場合、ツール呼び出しをブロックします。インストーラはユーザーレベルのフック設定のみを書き込みます：Codex の場合は `~/.codex/hooks.json`、Claude Code の場合は `~/.claude/settings.json`。
`gh` CLI が利用可能な場合、ガイド付きセットアップはフックチェックにその既存のローカルログインを使用するオプションも提供します。これにより、`DEPTRUST_GITHUB_AUTH=gh` のみが書き込まれ、GitHub トークンは決して書き込まれないため、フックサブプロセスが認証されていない 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
特定のパッケージバージョンを列挙、比較、または推奨する前に、deptrust でチェックしてください。これには「何を更新できるか」への回答も含まれます。既知の脆弱性をチェックするまでバージョン推奨を提供しないでください。
```
CI の場合、DepTrust を実行するプロセスに対して、有効期間が短く最小権限の GitHub App トークンを `DEPTRUST_GITHUB_TOKEN` として設定します。ローカルの GitHub CLI 認証には、`DEPTRUST_GITHUB_AUTH=gh deptrust check ...` を使用します。DepTrust はトークンを保存しません。
## 手動 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 は `不明` を返します。エージェントは積極的にトークンを設定して再試行するか、バージョンをスキップまたは延期するか、ユーザーがその正確なバージョンに対する未解決の GitHub カバレッジリスクを明示的に受け入れた場合にのみ続行することを提案する必要があります。その例外は、ユーザーが受け入れた不確実性として明確にラベル付けされなければならず、`許可` またはバージョンが安全である証拠として報告してはいけません。
### `suggest_safe_version`
最初に最新バージョンをチェックします。最新が許可されていない場合、プロバイダーが報告した修正バージョンを最初にチェックし、次に既知の古いバージョンをチェックし、`許可` 推奨のある最新のバージョンを提案します。
```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 モジュール、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 設定に配置します。
パッケージチェックで `不明` が返された場合、パッケージを安全として扱わないでください。これは、deptrust がアドバイザリプロバイダーから完全な回答を得られなかったか、レジストリで正確なバージョンを確認できなかったことを意味します。