Claude CodeにSonatype Guideプラグインを入れて依存関係を検査する

Sonatype Guideプラグインは、Claude Codeが依存パッケージを入れる前に、脆弱性とライセンスの状況を確かめさせるプラグインです。MCPサーバーとスキルが1セットで入り、npm install や pip install の前に自動で照会が走ります。

必要なのはSonatype Guideのアカウントとトークンだけです。ここでは導入、動作確認、Claude Codeへの頼み方、返ってくる値の読み方、つまずきやすい点を順に説明します。

このプラグインが追加するもの

プラグインの中身は3つです。マニフェスト(名前は sonatype-guide、作者はSonatype)、MCPサーバーの接続定義、そして依存関係の扱い方を書いたスキルです。

接続定義は短く、HTTP型のMCPサーバーに Authorization: Bearer ${SONATYPE_GUIDE_TOKEN} ヘッダーを付けて接続するだけです。

{
  "sonatype-guide": {
    "type": "http",
    "url": "https://mcp.guide.sonatype.com/mcp",
    "headers": {
      "Authorization": "Bearer ${SONATYPE_GUIDE_TOKEN}"
    }
  }
}

トークンの実値は設定ファイルに埋め込まれず、環境変数から展開されます。.mcp.json の url と headers で ${VAR} を展開できる仕様は、Claude CodeのMCP資料に書かれています。

READMEが挙げる機能は5つです。

Sonatype Guideは、OSS Indexが統合された先のサービスです。サイトには「OSS Index is now part of Sonatype Guide」と案内があります。PURLではnpm・PyPI・Maven・NuGet・Goの書式が使えます。

導入の手順

プラグインの導入は、トークンの取得、環境変数の設定、インストール、接続確認の4段階です。

環境変数の設定は次のとおりです。変数名は SONATYPE_GUIDE_TOKEN と完全に一致させます。

# ~/.zshrc または ~/.bashrc に追記
export SONATYPE_GUIDE_TOKEN="your-token-here"
 
# 反映してからプラグインを入れる
source ~/.zshrc
claude plugin install sonatype-guide

設定ファイル側に書くなら、次の形です。

{
  "env": {
    "SONATYPE_GUIDE_TOKEN": "your-token-here"
  }
}

インストール後に環境変数を足した場合は、Claude Codeを再起動します。READMEのトラブルシューティングも、変数設定後の再起動を求めています。

頼まなくても動く仕組み

このプラグインの特徴は、スキルの説明文が強い言い方で書かれている点です。スキルは、pip install・npm install・cargo add・go get などのパッケージ管理コマンドや、package.json・pyproject.toml・pom.xml・go.mod などへの追記を引き金に起動するよう定義されています。

説明文には「依存関係を追加・更新する前に必ず使う」「ここで確認する前に依存関係を入れたり勧めたりしない」という趣旨の指示があります。つまり、Claude Codeに「requestsを追加して」と頼むだけで、バージョンを決める前に照会が挟まる設計です。

READMEが示す直接の頼み方は次の3例です。

Scan my package.json for vulnerable dependencies
What's the most secure version of spring-core I should use?
Should I use axios or got for HTTP requests?

日本語でも頼めます。たとえば「lockファイルの依存をすべて監査して、Critical/Highだけ表にして」のように、見たい粒度を添えるほうが出力が締まります。

4つの作業の流れ

スキルは作業を4つに分けています。

MCPツールは3つです。いずれもPackage URL(PURL)の配列を受け取り、1回に最大20件まで照会できます。

• getComponentVersion: 特定バージョンのCVEとCVSS、ライセンス、悪意の有無、サポート終了、ポリシー準拠を返す
• getLatestComponentVersion: 最新バージョンを探す。PURLのバージョンは省略できる
• getRecommendedComponentVersions: 信頼スコア、破壊的変更の数、脆弱なメソッドのシグネチャつきで、順位づけした推奨を返す

PURLは pkg:npm/express@4.18.2 や pkg:pypi/requests@2.31.0 のような書式です。Maven・NuGet・Goにも対応する形式が用意されています。

監査の頼み方を固定する

毎回口頭で頼むより、プロジェクトのCLAUDE.mdに監査の約束事を書いておくと、出力の粒度が揃います。次は、スキルの出力ルールに合わせて組んだ一例です。

## 依存関係の検査
- 依存を追加・更新するときは、コマンドを実行する前にSonatype Guideで照会する
- 監査は package-lock.json など、バージョンが確定するlockファイルを基準にする
- 報告は「Critical/Highのみ」「ポリシー違反あり」の2区分で、表にまとめる
- 照会に失敗したときは、検査できなかったと明記する

最後の1行は、スキル側にも同趣旨の指示があります。MCP呼び出しが失敗したときは、黙って飛ばしたり安全だと仮定したりせず、検査を完了できなかったと伝える決まりです。

返ってくる値の読み方

結果は数字が多く、読み間違えやすい項目がいくつかあります。スキルが定めている解釈を順に見ます。

開発者信頼スコア

開発者信頼スコアは、Sonatype独自の0〜100の品質指標です。セキュリティ、ライセンス準拠、品質、保守性を織り込んだものとされています。スキルは次の目安で読むよう指示しています。

この区分はスキルの記述であり、Sonatypeのサービス全体の公式基準として別途示されたものではありません。社内ポリシーとして使うなら、自社の基準に置き換えてください。

CVSSは標準のNVD v3.x区分で扱い、9.0以上のCriticalと7.0以上のHighを「対応が必要」として目立たせます。

nullは「問題なし」ではない

見落としやすいのが、値が null のときの意味です。

脆弱なメソッドの項目も同様で、null は未確認、空配列は確認して見つからなかった、を意味します。メソッドごとのシグネチャが空配列のときは、CVEは確認済みでも該当メソッドがまだ整理されていない状態です。

ダウングレードと悪意のあるパッケージ

スキルには2つの強い禁止事項があります。

• 利用者が現在のバージョンを示したときは、推奨をすべてそのバージョン以上にする。MCPが返す推奨には古いバージョンが混ざり得るため、提示前に除く。例外は、利用者が警告後も繰り返し求める場合と、現行以降の全バージョンに修正のない致命的な脆弱性がある場合だけ
• malicious: true のパッケージは、注意つきでも勧めない。見つけたらすぐに警告する

さらに、推奨は利用者が使っているメジャーバージョンの中で最もスコアの高いものを第一候補にし、上位メジャーは「第二の選択肢」として破壊的変更の警告つきで並べます。express 4.18.2の例なら、第一候補は4.x系の最良版、第二候補が5.x系です。

READMEとスキルで食い違う点

導入前に知っておきたい食い違いが1つあります。READMEの機能一覧には、CVEを「直接依存と推移的依存を区別して」示すとあります。一方、スキルには、APIは直接と推移的を区別せず、CVEを1つの配列でまとめて返すと明記されています。

スキルが基準にするのは、MCPが返す実際の応答の形です。そのため、直接依存と推移的依存のどちらで見つかった脆弱性かは、Sonatype Guideの結果だけでは分かりません。区別が必要なら、lockファイルの依存ツリーをClaude Codeに読ませて、照会結果と突き合わせる作業を自分で頼むことになります。

自分のコードが脆弱なメソッドを実際に呼んでいるかは、脆弱なメソッドのシグネチャが返っているときだけ手がかりになります。

SCAツールとの役割の違いは、別の記事が扱っています。ローカルでスキャナーを回して再スキャンで閉じる流れはClaude CodeでTrivyを回して脆弱性を直す手順に、SBOMを突合する流れはSBOMをOSV-Scannerで突合する手順にあります。Sonatype Guideのスキルが引き金にしているのは、パッケージの追加や更新の直前です。

つまずきやすい点

READMEのトラブルシューティングは2系統です。

変数が未設定のままだと、${SONATYPE_GUIDE_TOKEN} の文字列がそのまま使われます。Claude CodeのMCP資料では、未設定の変数は警告つきで読み込まれ、claude mcp list の出力にその警告が出ると説明されています。接続が失敗するときは、まず claude mcp list と /mcp の表示を見ます。

プラグインの仕組み自体(/plugin の使い方、マーケットプレイス、自作と配布)はClaude Codeプラグイン完全ガイドにまとまっています。同じくCVEを扱うプラグインとしては、Snyk Studioの導入記事も参考になります。

向く場面と向かない場面

向くのは、依存を頻繁に足す開発です。新規にライブラリを選ぶ場面では、選定の時点で信頼スコアとライセンスを見られるため、後から入れ替える手間を減らせます。

一方で、READMEとスキルが説明しているのは、パッケージとバージョン単位の情報です。自分のコードそのものの脆弱性や、ランタイムでの到達可能性についての記述はありません。そこはコード解析やランタイム側のツールで補う領域です。

最後に運用面を1つ。スキルの発動はClaude Codeの判断に依存します。依存追加のたびに確実に照会させたいなら、CLAUDE.mdに「依存を追加する前に必ずSonatype Guideで照会する」と明記し、/mcp で接続状態を見る習慣を付けておくのが堅実です。