deptrust

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

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 エージェントが常に古いバージョンを使用するというフラストレーションから生まれました。

目次

• 対象範囲
• CLI の使い方
• インストール
• エージェント設定
• 手動 MCP 設定
• MCP ツール
• スキル専用利用
• トラブルシューティング

対象範囲

対応エコシステム：

• 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 がレジストリメタデータを解決できても、設定された脆弱性プロバイダーがそのエコシステムをサポートしていない場合、パッケージを安全として扱う代わりに 不明 を返します。

プロバイダーカバレッジ：

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 を介して渡します：

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 の使い方

正確なバージョンをチェック：

deptrust check npm lodash 4.17.20

通常の応答例：

npm [email protected]: 2 件の既知の脆弱性が見つかりました
推奨: ブロック
リスクスコア: 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",
  "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 は既知の古いバージョンをチェックし、許可 推奨のある最新のバージョンを返します。

アドバイザリに修正バージョンが含まれている場合、suggest はレジストリバージョンリストを遡る前に、プロバイダーが報告した修正バージョンを最初にチェックします。

2 つのバージョンを比較：

deptrust compare npm lodash 4.17.20 4.17.21

比較応答例：

lodash 4.17.20 -> 4.17.21 はリスクを改善: スコア 80 → 0。
推奨: 許可
次のアクション: 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 出力を提供します。フレークは、プリビルドされたリリースバイナリをラップします。

# インストールせずに実行
nix run github:clidey/deptrust

# プロファイルにインストール
nix profile install github:clidey/deptrust

通常のリリースワークフローは、公開するアーカイブから Nix ハッシュを生成し、公開前にフレークを評価し、公開されたアセットに対してビルドして実行してから、デフォルトブランチを更新します。github:clidey/deptrust は、そのワークフローの実行中に一時的に遅れる場合があります。リリースタグは、生成されたフレーク更新前のソースコミットを指し、以前のバイナリを参照する可能性があります。再現性が重要な場合は、flake.nix が必要なバージョンを含むコミットを固定してください。

Devbox

再現可能な開発環境には、Devbox を使用します：

# Devbox を最初にインストール（まだインストールされていない場合）
curl -fsSL https://get.jetify.dev/devbox | bash

# 環境を初期化
devbox shell

# プロジェクトをビルド
devbox run build

devbox.json はツールチェーンバージョンを制約し、コミットされた devbox.lock は正確なパッケージバージョンと nixpkgs のリビジョンを固定します。これらのピンを意図的に更新する場合は devbox update を実行します。

または、Devbox を Homebrew でインストール：

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 が 確認、ブロック、または 不明 を返した場合、ツール呼び出しをブロックします。インストーラはユーザーレベルのフック設定のみを書き込みます：Codex の場合は ~/.codex/hooks.json、Claude Code の場合は ~/.claude/settings.json。

gh CLI が利用可能な場合、ガイド付きセットアップはフックチェックにその既存のローカルログインを使用するオプションも提供します。これにより、DEPTRUST_GITHUB_AUTH=gh のみが書き込まれ、GitHub トークンは決して書き込まれないため、フックサブプロセスが認証されていない 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 を使用する場合は、エージェントに次のようにリマインドします：

特定のパッケージバージョンを列挙、比較、または推奨する前に、deptrust でチェックしてください。これには「何を更新できるか」への回答も含まれます。既知の脆弱性をチェックするまでバージョン推奨を提供しないでください。

CI の場合、DepTrust を実行するプロセスに対して、有効期間が短く最小権限の GitHub App トークンを DEPTRUST_GITHUB_TOKEN として設定します。ローカルの GitHub CLI 認証には、DEPTRUST_GITHUB_AUTH=gh deptrust check ... を使用します。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",
  "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

最初に最新バージョンをチェックします。最新が許可されていない場合、プロバイダーが報告した修正バージョンを最初にチェックし、次に既知の古いバージョンをチェックし、許可 推奨のある最新のバージョンを提案します。

{
  "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 モジュール、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 設定に配置します。

パッケージチェックで 不明 が返された場合、パッケージを安全として扱わないでください。これは、deptrust がアドバイザリプロバイダーから完全な回答を得られなかったか、レジストリで正確なバージョンを確認できなかったことを意味します。