Heimdall — Mcp Security Scanner

Heimdall

エージェントの門を守る見張り番。

Model Context Protocol（MCP）サーバー向けのローカルで実行する事前セキュリティスキャナーです。サーバー単体、またはエージェントの設定全体を検査してから、エージェントに信頼させられます。アカウントもバックエンドも不要で、デフォルトではサーバーを実行しません。

MCP サーバーは未検証のコードであり、自然言語を介した攻撃対象になり得ます。ツールの説明はモデルにそのまま渡され、サーバーはあなたのマシンのアクセス権限で実行されるためです。Heimdall はサーバーの主張ではなく、実際にできることを評価し、正確な証拠を示します。すべてマシン上で実行され、アカウントは不要で、デフォルトではサーバーを実行しないため、パッケージをインストールする前に検査し、CI でゲートできます。

クイックスタート

npx mcp-heimdall-scan firecrawl-mcp                   # scan a published server
npx mcp-heimdall-scan ./claude_desktop_config.json    # audit your whole agent config
npx mcp-heimdall-scan firecrawl-mcp --online          # + check its deps for known CVEs (OSV.dev)
npx mcp-heimdall-scan ./my-server --policy strict     # gate it in CI

インストール不要で、ローカルで実行され、マシンの外にデータが出ることもありません。

またはブラウザーでお試しください： caglarbozkurt.github.io/mcp-heimdall — スキャナー全体が100％クライアントサイドで実行されます（npm パッケージは jsDelivr 経由で取得するか、 tools.json / MCP 設定を貼り付けてください）。バックエンドはなく、アップロードもありません。ローカルパスと --handshake には CLI が必要です。

検査項目

各検出結果には file:line または tool:name が示されます。機能 ≠ リスク： 生の能力は参考情報としてプロファイルに表示され、スキャンが失敗することはありません。失敗の原因となるのは、明確なゲートと実際の異常だけです。

特長

• ローカルで動作し、サーバーを実行しません。 すべて静的解析で、デフォルトではオフラインです。アカウントもバックエンドも不要で、データがアップロードされることもありません。また、使い捨て VM でのみ使用するよう記載されている --handshake を有効にしない限り、信頼できないコードを実行することはありません。インストールする前に、パッケージを確認できます。
• データの流れを明らかにします。 汚染解析／データフロー解析により、「ファイルを読み取り、かつネットワークを使うなら失敗」という判定を、場所を特定した具体的なデータの流れに置き換えます。そのため、設定ファイルの読み取りと無関係な API 呼び出しを誤検知しません。
• ゲート全体を把握します。 設定済みのサーバーの集合を横断して分析するため、各サーバー単独では見えない、サーバー間の情報流出経路も検出できます。ほとんどのスキャナーは、一度に 1 つのサーバーしか確認しません。
• 制御できるゲートです。 検出器は事実を出力し、ユーザーが定義したポリシーが、それを合格／警告／失敗に判定します。機能を拒否し、出所情報を必須にし、監査可能な例外を追加し、CI にゲートを設定できます。

使い方

heimdall <target> [options]

--tools <file>     supplement analysis with a tools/list (or {tools,resources,prompts}) dump
--policy <p>       "default", "strict", or a JSON policy file
--baseline <file>  diff against a prior --json report (drift / rug-pull detection)
--handshake        RUN the server(s) for the live tool list (untrusted code — VM/container only)
--online           check declared deps against OSV.dev for known CVEs (sends dep names, not source)
--json             machine-readable report
--sarif            SARIF 2.1.0 (GitHub code-scanning / CI)
--no-fail          always exit 0

Exit codes: 0 pass/warn · 1 fail · 2 error

ポリシー

検出器は事実を出力し、ポリシーがそれを判定に変換します。デフォルトのポリシーを使用するか、strict を選ぶか、調達・セキュリティの基準を独自に記述してください。

{
  "name": "acme-procurement",
  "denyCapabilities": ["exec", "dynamic-eval", "secret-access"],
  "require": ["has_repository", "has_license"],
  "failOnSeverity": "high",
  "warnOnSeverity": "low",
  "allow": [{ "id": "capability/scope-mismatch", "reason": "reviewed", "expires": "2026-12-31" }]
}

ライブラリ

import { scan } from "mcp-heimdall-scan";

const report = await scan("some-mcp-server", { policy: "strict" });
if (report.verdict === "fail") throw new Error(report.reasons.join("; "));

Claude Code スキル（skill/）としても提供されます。インストール前に、会話中にサーバーを確認できます。

MCP サーバーとして使う

エージェントに scan_mcp_server ツールを追加すると、接続する前にサーバーを確認できます。「追加する前にスキャンしてください」。Heimdall を MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": ["-y", "--package", "mcp-heimdall-scan", "heimdall-mcp"]
    }
  }
}

このツールは target（npm パッケージ、pypi:<name>、パス、GitHub URL、tools.json、またはクライアント設定）と、任意の policy および online を受け取ります。これは静的解析専用です。サーバーをダウンロードしますが、実行することはありません。また、コード実行モード（--handshake、validate）は意図的にエージェントに公開していません。

CI で使う（GitHub Action）

すべてのプルリクエストをゲートし、MCP 設定（またはサーバー）をスキャンして、リスクがある場合はビルドを失敗させます。.github/workflows/ に次の内容を追加してください。

- uses: caglarbozkurt/mcp-heimdall@v1
  with:
    target: ./claude_desktop_config.json   # a path, npm/pypi package, github URL, or tools.json
    policy: strict                          # "default", "strict", or a JSON policy file
    online: true                            # also check deps for known CVEs (OSV.dev)
    sarif: heimdall.sarif                   # optional: emit SARIF for code scanning

すべて独自の CI ランナー上で実行されます。バックエンドは不要で、パブリックリポジトリでは無料です。

検証（動作のクロスチェック）

静的解析では、サーバーが「何をできるか」が分かります。heimdall validate は、それがサーバーの「実際の動作」と一致するかをチェックします。機能の記録機能を事前に読み込ませた状態でサーバーを実行し（fs / net / http(s) / child_process / vm / fetch / process.env をフックします）、各ツールを動作させて、観測された実行時の動作と静的フラグを比較します。

heimdall validate ./my-server            # one server: confirmed / missed / not-exercised
heimdall validate --list servers.txt     # batch: a recall number over observed behavior

• 確認済み — フラグが付いており、実際にも観測されました（静的な判定が裏付けられています）。
• 未実行 — フラグは付いていますが、単純な引数では動作しませんでした（「下限」を示すものであり、フラグが誤りだという証明ではありません）。
• 検出漏れ — 観測されたものの、フラグが付いていませんでした → 静的解析に実際の見落としがあるため、確認が必要です（または、ライブラリの偶発的な副作用です）。

そのため、偽陰性（静的解析の見落とし）の発見には信頼できますが、フラグが誤りだと証明するものではありません。 各サーバーは、継承したシークレットがない使い捨ての HOME と作業ディレクトリで実行されますが、それでも「サーバーを実行し、ツールを呼び出し」ます（ネットワーク／実行の副作用があります）。使い捨ての VM／コンテナで使用してください。

実際のパッケージ 200 件を対象にした動作実行（benchmarks/validate-run.md）： 55 件が起動し、34 件で観測可能な機能が実行されました。サーバーが実行時に「実際に使った」機能のうち、静的スキャンでフラグが付いたのは 80.9%（55/68）でした。初回実行での見落としを修正リストに加えた後の 75.8% から向上しています（依存関係に基づくネットワーク検出を拡張し、ネットワークの見落としをおよそ半減させました）。残る見落としは「構造上のもの」です。静的解析では根本的に検出できない、依存関係の内部またはサブプロセス内で実行される機能です。まさにそのために、バックストップとして validate があります。再現率を正直に公開し、実行ごとに改善しています。

大規模なテスト

npm レジストリから取得した実際の MCP パッケージ 2,500 件（benchmarks/）を対象に実行：1,726 件をスキャンし、約 5 分で完了、0.7% にフラグが付きました。雑多な実環境のコードに対して堅牢に動作します。これとは別に、小規模なラベル付きフィクスチャコーパス（npm run eval、Damn Vulnerable MCP プロジェクトを含む、良性／悪性のフィクスチャ約 10 件）では 100% を達成しています。これは較正チェックであり、幅広い実環境での精度を示す数字ではありません。上記の実環境スキャンにはラベルがなく、堅牢性の確認にのみ使用しています。ログ全文： benchmarks/field-run.md。

このスキャンから分かる、エージェントが信頼するエコシステムの実態：

フラグが付いた 0.7% は、インストール時のコード実行とプロンプトインジェクションによるものでした。ツールの説明に不可視のゼロ幅文字が埋め込まれた実際のサーバーも含まれています。こうしたステルス型のツールポイズニングは、キーワードスキャナーでは見逃されます。

堅牢性と分布の確認を目的とした実行は、精度ベンチマークではありません。2,500 件のサーバーにはラベルが付いていません。フラグが付いた場合は「要確認」を意味し、悪意が証明されたわけではありません。

セキュリティと制限事項

Heimdall はヒューリスティックによる事前チェックであり、安全を保証するものではありません。PASS は安全の証明ではありません。機能、来歴、CVE の分析は JS/TS と Python に対応し、インジェクション検出は言語を問いません。実証済みの汚染追跡／データフロー解析は JS/TS のみです。Python では、機能の併存チェック（実証済みのフローではなく、保守的な判定）にフォールバックします。 デフォルトではすべてオフラインで実行されます。ネットワークに接続するのは --online の場合のみです（依存関係名とバージョンを OSV.dev に送信します。ソースコードは送信しません）。また、CVE の照合対象は宣言された範囲であり、ロックファイルではありません。--handshake は信頼できないコードを実行するため、実際のサンドボックスではありません。脅威モデルの詳細と脆弱性の報告方法については、SECURITY.md を参照してください。

貢献

検出ルールの追加は、最も価値の高い貢献です。詳しくは CONTRIBUTING.md を参照してください。参加することで、行動規範に同意したものとみなされます。

ライセンス

MIT · Çağlar Bozkurt が制作