shadow-mcp

shadow-mcp

このマシンに実際に存在する MCP サーバーを検出し、リスクを評価します。

多くの MCP セキュリティツールは、監査対象のサーバー一覧がすでにあることを前提としています。 しかし、実際の開発者マシンではそうではありません。サーバーは Claude Code、 Codex、Claude Desktop、プロジェクトローカルの .mcp.json ファイル、DXT 拡張機能、 ポートをバインドしない実行中のプロセスなど、あちこちに存在します。shadow-mcp はまずそれらを検出し、次に評価します。

これは、OWASP MCP09:2025 — シャドー MCP サーバーに対するローカルファーストのソリューションです。

機能

discover  ->  inventory  ->  risk-grade  ->  report

1. 検出（読み取り専用）：サポート対象の設定およびランタイムソースから MCP サーバーを検出します。 Claude Code（~/.claude.json、ユーザーとプロジェクトのスコープ）、claude mcp list （ファイルに記載されていないリモートサーバーとプラグインサーバーも検出）、Codex （~/.codex/config.toml とプロファイル）、プロジェクトの .mcp.json、Claude Desktop の設定と DXT 拡張機能のマニフェスト、実行中のプロセス一覧が対象です。
2. インベントリ作成：サーバーがホストごとに異なる名前（personal-ops と personal_ops など）で登録されていても、検出結果を論理サーバーごとに 1 つのエントリーへ統合し、 すべての出所を記録します。
3. リスク評価：既存エンジンを再実装せず、委譲して利用します。
   • MCPAudit：0〜10 の機能複合評価とインジェクションの検出結果
   • mcp-trust：権威ある A〜F の危険度評価（既知の場合）
   • エンジンが十分にカバーしていない、設定に基づく OWASP の側面を対象とする薄いローカルレイヤー （シークレット／MCP01、サプライチェーンの出所／MCP04、トランスポートの露出／MCP07）
4. レポート：順位付きのターミナル表、機械可読な JSON インベントリ、または Markdown に加えて、重要な差分を示す 影響と要注意項目のセクションを出力します （実行中だが未設定、広範な影響範囲、能力は高いが未評価）。

リスクモデルと OWASP との対応は docs/risk-model.md にあります。

インストール

このリポジトリのルートで、uv を使います。

make setup

評価エンジン（mcp-audits と mcp-trust）は、編集可能な兄弟チェックアウトや engines グループではなく、PyPI から解決されるランタイム依存関係です。 インストールされた mcp-trust パッケージがシードカタログを提供します。--registry-db または SHADOW_MCP_MCPTRUST_DB を指定すると、明示的に選択したローカルレジストリが使用されます。

使い方

uv run shadow-mcp scan                      # full pipeline, terminal report
uv run shadow-mcp scan --json out.json      # machine-readable inventory
uv run shadow-mcp scan --format markdown    # markdown report
uv run shadow-mcp discover                  # inventory only, no grading
uv run shadow-mcp sources                   # per-collector counts
uv run shadow-mcp grade-missing             # A-F for servers the registry hasn't scanned
uv run shadow-mcp deep-scan cost-tracker    # connect to a server, grade its real tools

便利なフラグ：--no-processes（実行中のプロセスのスキャンをスキップ）、--no-cli（ claude mcp list をスキップ）、--no-mcpaudit（インベントリ作成と mcp-trust のみを実行）、--home PATH （検出対象をフィクスチャツリーに指定）。

静的評価と接続評価

デフォルトの評価は静的（設定のみ）です。サーバーは起動されないため、評価結果は設定から確認できる内容を反映します。安全ですが、大まかな評価です。サーバーの実際の能力がわかるのは、接続してツールを一覧表示したときだけです。

shadow-mcp scan --connect（または deep-scan [names...]）を実行すると、各 stdio サーバーを起動して実際のツールを列挙し、MCPAudit の接続エンジンに委譲して、能力を実際に区別できる評価を行います（ファイルシステムサーバーは静的評価の A から接続評価の D に変わります）。サーバーへの接続はサーバーを実行するため、これはオプトインです。リモートエンドポイントは起動されません（ネットワークスキャンの段階で扱います）。また、起動に実際のシークレットが必要なサーバーは、静的評価にフォールバックします。

開発と安全な検証

コミット済みの uv.lock により、PyPI の実行時依存関係と開発用依存関係が固定されています。リポジトリのルートから、次を実行してください。

make check

テストスイートでは合成ホームディレクトリを使用します。SHADOW_MCP_RUN_CONNECT は未設定のままにしてください。明示的にオプトインする接続テストは、サーバー実行を行う別のレーンです。CI では Python 3.11 から 3.15 まで、同じ一括ゲートを実行します。ワークフローを参照してください。make build は、リリースワークフローで使用する wheel と sdist を作成します。

通常の scan、discover、sources、grade-missing、または MCP ツールの呼び出しを、開発時のスモークテストに使用しないでください。これらはデフォルトでマシンの情報を収集します。CLI の deep-scan と scan --connect は、さらにサーバーを実行します。変更した JSON または Markdown レポートについては、対応するフィクスチャテスト（tests/test_report.py）を確認し、合成出力を調べてください。この CLI にブラウザー UI はありません。実際のワークステーションでの動作や接続時の動作を検証するには、個別に明示的な許可を得る必要があります。

安全性

• 読み取り専用の検出。 コレクターは設定を解析し、claude mcp list を実行し（--no-cli が設定されている場合を除く）、プロセスを一覧表示します。検出した内容を変更することはありません。（--connect／deep-scan はサーバーを実行する唯一の経路であり、明示的に指定した場合にのみ実行します。）
• シークレットは保存しません。 MCP01 に従ってシークレットを含むサーバーを判別するため、環境変数の名前は記録しますが、値は記録しません。コマンド引数、URL、プロセスの親コマンドに含まれるインライン認証情報は、保存前に秘匿化されます。収集したインベントリにはローカルパスやホスト名が含まれるため、*.inventory.json は非公開情報として扱ってください（デフォルトで Git の追跡対象外です）。

MCP サーバーとして使用する

shadow-mcp は、自身のインベントリ用ツールを MCP サーバーとして提供できます。これにより、エージェントは会話を離れることなく、ローカルの MCP サーフェスを照会できます。

ツール

ツール	説明
scan_local	一連の処理をすべて実行します（検出 → インベントリ作成 → 評価 → レポート）。JSON を返します。
discover_local	評価を行わずに、すべての MCP サーバーのインベントリを作成します。JSON を返します。
deep_scan	指定されたサーバーを評価します。リストが空の場合は、すべてのサーバーを評価します（静的評価であり、サーバーの起動はありません）。names: list[str] を受け付けます。JSON を返します。
list_sources	検出の実行結果から、コレクターごとのソース件数を返します。JSON を返します。

サーバーを起動する

# directly from a local checkout
uv run shadow-mcp mcp-serve

# via uvx (once published to PyPI)
uvx shadow-mcp mcp-serve

ローカル環境専用です。 MCP ツールはローカル設定とプロセステーブルを読み取り、claude mcp list をスキップします。また、ホストされた MCP エンドポイントへの接続やサーバーの起動は行いません。評価は静的（設定ベース）であり、connect=False が常に強制されます。

対象範囲

これはローカル優先のツールです。1 台のマシンを、設定とプロセスに基づいてインベントリ化します。ネットワークスキャンへの拡張（ホスト／ポートを調べてリモート MCP エンドポイントを検出すること、組織全体のマシン群をインベントリ化すること、類似名のタイポスクワッティングに関する来歴を確認すること）は、意図的に対象外としています。追加される機能については、docs/risk-model.md の末尾とプロジェクトメモを参照してください。

ステータス

技術スタック

Python 3.11 以降、uv で管理された固定依存関係、Ruff、mypy、pytest によるチェック、Hatchling による wheel と sdist のビルド。

既知のリスク

• Python の最小バージョンは、3.12 への引き上げに関するオーナーの判断が保留中のため、3.11 のままです。
• MCP ツール名 deep_scan は、オーナーの判断が保留中のため変更されていません。同名に近い CLI コマンドはサーバーに接続することがあります。
• 識別情報とインベントリの照合における識別子の衝突。
• プロセスの検出結果は、所有者を分類する前に名前で重複排除されます。
• 評価の根拠は最大 8 件の検出事項に限られ、critical は low より低い順位です。
• コレクターの失敗が表面化しないことがあります。
• sources と grade-missing では --json が無視されます。
• レポートの書き込みはアトミックではありません。
• Markdown と Rich の出力ではエスケープ方法が異なります。
• 依存関係のメジャーバージョン更新、Hatchling からの移行、カバレッジのしきい値、パッケージの公開、タグ、リリースは対象外です。

次のステップ

Python の最小バージョンと MCP ツール名に関する判断を確定し、続いて一覧に挙げた動作上のリスクに次の段階で対処します。