Deepsleuth

Deepsleuth — 細部まで読み解く

Deepsleuth は、MCP サーバー向けの決定論的な、LLM を使わないセキュリティスキャナーです。 サーバーが 何を言っているか、そしてさらに重要な、何をしているか を監査します。

ほとんどの MCP スキャナーが読み取るのは、宣言されたマニフェスト（tools/list の名前、説明、スキーマ）だけです。サーバーを起動せず、ツールを呼び出さず、応答も実装ソースも読み取らず、呼び出しをまたいだ推論もしません。そのため、攻撃の多くの種類が構造上検出できません。

Deepsleuth はそれらを検出します。 フロントエンドに依存しない単一の検出コアに、2 つのフロントエンドを備えています。

• フロントエンド A — インライン MCP ゲートウェイ／プロキシ（目玉となる機能）。 エージェントにとっては MCP サーバー、下流の 1 つのサーバーにとっては MCP クライアントとなる、透過的なプロキシです。起動時にツールの説明を監査し、すべての tools/call の前にゲートを適用し、返却前にすべての応答をスキャンします。オフラインで採点するためのヘッドレスな proxy-eval モードも含まれています。
• フロントエンド B — バッチ／サンドボックススキャナー。 Docker サンドボックス内でサーバーを起動し、合成した呼び出しと仕込んだカナリアで挙動を積極的に引き出して、検出結果を生成する事前監査ツールです。オフライン採点ハーネスでもあります。

どちらのフロントエンドでも、同じ Context に対して同じ検出器を実行します。検出器は一度書けば、どちらでも動作します。

LLM は一切使いません。

完全に決定論的です。解析、静的 AST と汚染／データフロー分析、正規化した正規表現／トークンのヒューリスティクス、Unicode／エンコーディング／エントロピー分析、構造的差分分析、計装を施したサンドボックス内での動的実行を行います。同じ入力 → バイト単位で同一の検出結果。 オフラインで動作します（ネットワークへの送信は Docker デーモン宛てのみ）。脅威フィードは使いません。

---

インストール

Python 3.11 以降が必要です。必須のサードパーティーパッケージはありません。スキャナー自身が stdio 経由で MCP を扱うため、外部管理（PEP 668）環境にもインストールできます。

pip install security-scanner-deepsleuth-mcp                             # published on PyPI
# or from source:
pip install git+https://github.com/DeepSleuth/deepsleuth-mcp.git   # zero required dependencies
deepsleuth --help
# or straight from the source tree:
python -m deepsleuth --help

PyPI のディストリビューション名は security-scanner-deepsleuth-mcp（内容とブランドを表す名前）です。ツール、リポジトリ、MCP サーバーの名前は deepsleuth です。 パッケージをインストールすると、deepsleuth コンソールコマンドが使えるようになります。また、ディストリビューション名と同じ名前のエイリアススクリプトもインストールされるため、レジストリーのクライアントは uvx security-scanner-deepsleuth-mcp でサーバーを実行できます。

Deepsleuth 自体が MCP サーバーなので、エージェントから直接スキャンできます。

{"mcpServers": {"deepsleuth": {"command": "python", "args": ["-m", "deepsleuth.mcp_server"]}}}

ツール：list_detectors、check_listing、scan_target。

エージェントプラグインとしてインストールする

このリポジトリは有効な Agent Plugins パッケージです（plugin.json + mcp.json、仕様 1.0.0）。互換性のあるクライアントならどれでもリポジトリから直接インストールでき、deepsleuth MCP サーバーと audit-mcp-server スキルを利用できます。stdio エントリ（bin/deepsleuth-mcp）に必要なのは python3.11+ だけです。スキャナーにサードパーティーの依存関係はありません。

{"type": "stdio", "command": "./bin/deepsleuth-mcp"}

動的レイヤー（フロントエンド B と proxy-eval）には、Docker CLI とデーモンが必要です。Docker がなくてもスキャナーは適切に機能を縮退させます。静的／マニフェスト検出器は引き続き実行され、スキップされた動的カバレッジはレポートされます（クラッシュすることはありません）。

実行

# Frontend B — batch/sandbox scanner (also the offline scoring harness)
python -m deepsleuth scan <target> [--no-dynamic] [--json out.json] [--timeout N] [--reference-listing tools.json]

# Frontend A — inline MCP gateway/proxy (the gate); speaks MCP on stdio to the agent
python -m deepsleuth proxy <target> [--policy policy.yaml] [--fail-closed] [--log run.jsonl]

# Frontend A headless — drive a deterministic call plan through the proxy, emit the findings JSON
python -m deepsleuth proxy-eval <target> [--json out.json] [--timeout N] [--policy p]

# list every registered detector
python -m deepsleuth detectors

<target>には、サーバーディレクトリ（mcp.jsonおよび／またはソースを含む）、mcp.jsonの起動仕様、または生のstdio起動コマンド（例："python3 server.py"）を指定できます。scanは問題がなければ0で終了し、検出結果が--fail-severity（デフォルトはhigh）以上に達すると0以外で終了します。

--allow-unsandboxedを指定すると、Dockerを使わずに動的レイヤーを実行します。ご自身が信頼するフィクスチャに限って使用してください。信頼できないサーバーには決して使用しないでください。

--reference-listing tools.jsonを指定すると、別のサーバーのツール一覧（{name, description, inputSchema}エントリのJSON配列、またはtoolsキーを持つオブジェクト）が提供され、2つ目のサーバーを起動せずに、その一覧と照合してサーバー間の名前比較を実行します。同じ比較は、1つのmcp.json内に複数のエントリがある場合や、1つのディレクトリ内に複数のサーバーエントリモジュールが見つかった場合にも自動的に実行されます。

プロキシをエージェントに接続する

実際のサーバーではなくプロキシにMCPクライアントを接続してください。プロキシが下流で実際のサーバーを起動します。

{ "mcpServers": {
    "guarded-fs": {
      "command": "python", "args": ["-m", "deepsleuth", "proxy",
        "/path/to/real-server", "--policy", "policy.example.yaml", "--log", "gate.jsonl"]
    } } }

同梱のフィクスチャで試す

python -m deepsleuth scan tests/fixtures/injection --no-dynamic          # source taint + hint violation
python -m deepsleuth scan tests/fixtures/poisoned  --no-dynamic          # poisoned descriptions
python -m deepsleuth scan tests/fixtures/supplychain --no-dynamic        # install-time hook + typosquat
python -m deepsleuth proxy-eval tests/fixtures/runtime --allow-unsandboxed  # response injection + cross-call leak, with gate decisions
python tests/run_all.py                                                    # unit + e2e tests (no pytest needed)

対応範囲

証拠の所在 — deepsleuthは8つすべてを検出し、マニフェストのみのスキャナーでは見落とす5つを特に強力に検出します。

証拠の所在	マニフェストのみで検出可能か	deepsleuth
description、name、schema	はい	✅ 正規化されたメカニズムルール＋難読化
source	いいえ	✅ ASTによる汚染解析、ヒントと動作の照合、ラグプル判定、認証／監査
runtime-response	いいえ	✅ レスポンスインジェクション＋カナリア／認証情報の漏えいスキャン
multi-call-state	いいえ	✅ 呼び出しをまたぐカナリア漏えい、再リストとの差分、レスポンスの差分
server-identity	まれに可能	✅ ハンドシェイクと設定／パッケージの識別情報の照合
install-time-script	いいえ	✅ npm／pipのインストールフック＋タイポスクワッティング解析

メカニズムのカテゴリ： tool-poisoning、agent-config-poisoning、 tool-shadowing、prompt-injection、credential-exposure、command-injection、 path-traversal、ssrf、data-exfiltration、confused-deputy、 auth-misconfiguration、denial-of-service、excessive-privilege、 supply-chain、information-disclosure、client-side-vulnerability、other。

すべての検出結果は固定の検出結果スキーマに照らして検証され、トップレベルに evidence_locationとconfidenceを持ちます。また、プロキシ経由の場合はゲートの 判定がraw.gate_decisionに記録されます。各検出器の既知の検出漏れを含む説明は DETECTORS.mdを、各レイヤーの連携方法と検出器の追加方法は ARCHITECTURE.mdを参照してください。

既知の制限事項（v1）

• ソース解析はPythonを優先します。 Node／TSのサーバーではマニフェスト、インストールフック、動的解析に対応していますが、v1のソース汚染解析はPythonのみです（JSの解析は正規表現を簡易的に使うものです）。
• 汚染解析はプロシージャ内に限られます。 モジュール内のヘルパー関数／クラスを経由するデータフローは近似的に扱い、完全には追跡しません。
• プロキシが接続する下流サーバーは1つだけです（v1の範囲です。複数サーバーの名前空間化に向けた構造はありますが、まだ実装されていません）。
• 稼働中のプロキシにおけるエリシテーションの往復処理と、下流から開始されるリクエストの転送はベストエフォートです。 すべてのゲート／監査／差分／レスポンスのロジックはproxy-evalで完全にテストされており、オフライン評価の採点対象もこちらです。
• Dockerがない場合、動的検出器はスキップされます（その旨が報告され、黙って無効になることはありません）。

参加する

貢献を歓迎します。CONTRIBUTING.mdをご覧ください。 セキュリティ上の問題を見つけましたか？SECURITY.mdの手順に従ってください。

---

公式MCPレジストリに掲載されています：

mcp-name: io.github.DeepSleuth/deepsleuth