raven-nest-mcp

Raven Nest MCP

MCP サーバーとして動作するペンテストツールキットです。安全性を強化したインターフェースを通じて、AI アシスタントが業界標準のセキュリティツールを構造化された形で利用できます。

許可された用途に限ります。 Raven Nest は、所有しているシステム、または評価について明示的な書面による許可を得たシステムのテストのみを目的とした、攻撃的セキュリティツールです。無許可のスキャン、列挙、悪用は違法となる可能性があります。許可の取得と適用されるすべての法律の遵守は、利用者自身の責任です。本ソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。詳しくはLICENSEをご覧ください。

デモ

ツールへの実際の MCP 通信です。LLM は介在せず、完全に決定論的です。対象は、許可を得た公開テストホスト example.com / scanme.nmap.org です。

スキャン → 構造化された検出結果 → レポート

偵察フロー - 接続性、ポート、Web スタック

Metasploit モジュールの検出 - MSF 対応ビルドが必要です。デフォルトのコンテナイメージには Metasploit は含まれていません

機能

Raven Nest は、22 種類のセキュリティツールと Metasploit Framework を、入力検証、出力品質評価、セッションを考慮したコンテキスト予算管理、安全制限の設定機能を備えた MCP インターフェースの背後で利用できるようにします。ツールの実行、再起動後も安全なバックグラウンドスキャン（完了済みの結果はサーバー再起動後も保持され、中断されたスキャンは失敗として表示されます）、脆弱性検出結果の永続化、対象の検出状況の追跡、スキャン結果の差分表示、複数形式（Markdown、JSON、SARIF、HTML）でのレポート生成に対応しています。検出結果、レポート、スキャンは、閲覧用の MCP リソースとしても公開されます。MCP エンドポイントは合計 46 個です。

対応ツール

カテゴリー	ツール
偵察	nmap, masscan, whatweb, httpx, subfinder, dnsx, dnsrecon
クロール	katana
SMB/AD	enum4linux-ng
認証情報を使用した列挙（制限付き）	netexec
脆弱性	nuclei, nikto, wpscan, dalfox (XSS)
Web ファジング	feroxbuster, ffuf
エクスプロイト	sqlmap, hydra
パスワードクラッキング	john
シークレットスキャン	gitleaks, trufflehog
TLS/SSL	testssl.sh
Metasploit	msf_search, msf_module_info, msf_exploit, msf_auxiliary, msf_sessions, msf_post
ユーティリティ	ping_target, http_request
スキャン管理	launch_scan, get_scan_status, get_scan_results, list_scans, cancel_scan
検出結果	save_finding, get_finding, list_findings, list_findings_by_scan, delete_finding, generate_report
エンゲージメント	set_engagement, list_engagements
検出状況の追跡	get_target_info, list_targets, diff_scans

全体の仕組み

Raven Nest は MCP サーバーです。単独では何も行いません。MCP ホストが stdio 経由で起動し、ツールを実行します。用途に合ったホストをお選びください。

• 任意の MCP ホスト（推奨） - Claude Desktop、Cursor、または任意の MCP クライアントから、以下の Docker イメージを指定します。ホストがサーバーを起動します。
• コンパニオン REPL - raven-nest-client は、Raven Nest を手動で操作するための TypeScript 製ターミナルクライアントです（タブ補完、スキャン／検出結果／レポート用コマンド、エンゲージメントのスコープ設定）。ローカルの raven-server ビルドまたは Docker イメージを起動できます。

どちらの場合も、サーバーは同じ stdio バイナリです。

クイックスタート

Docker で実行する（推奨）

公開済みのイメージには、Kali ベースの環境に raven-server とラップされた 22 個すべてのツールが含まれているため、自分でインストールする必要はありません。MCP クライアントから stdio 経由で接続します。

{
  "mcpServers": {
    "raven-nest": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/tidynest/raven-nest-mcp:latest"]
    }
  }
}

masscan と nmap -O には raw socket が必要です。これらを使用する場合は、args に --cap-add=NET_RAW と --cap-add=NET_ADMIN を追加してください（コンテナは専用の非 root ユーザーとして実行されます。ランタイムがこれらのケイパビリティをコンテナプロセスに直接付与するため、root でなくても引き続き機能します）。このサーバーは、 MCP Registry にも io.github.tidynest/raven-nest-mcp として登録されています。

前提条件

• Rust 1.93 以降（2024 edition）
• 1 つ以上の外部ツールがインストールされていること（nmap、nuclei、nikto など）

ビルド

cargo build --release

MCP クライアントを設定する

プロジェクトのルートに .mcp.json を作成するか、MCP クライアントを直接設定します。

{
  "mcpServers": {
    "raven-nest": {
      "command": "/path/to/raven-server",
      "args": []
    }
  }
}

サーバーは stdio 経由で通信するため、ネットワークポートは必要ありません。

設定

Raven Nest は TOML から設定を読み込み、次の順序で解決します。

1. RAVEN_CONFIG 環境変数（ファイルへのパス）
2. バイナリと同じ場所にある config/default.toml
3. 作業ディレクトリにある config/default.toml
4. 組み込みのデフォルト値

主な設定セクション：

[safety]
allowed_tools = ["nmap", "nuclei", "nikto", "whatweb", "masscan", ". . ."] 
context_budget = 65536          # Model context window in chars (0 = disabled)
expected_tool_calls = 10        # Anticipated calls per session
sudo_tools = ["masscan", "nmap"] # Tools invoked via passwordless sudo
# auto_save_findings = false     # opt-in: auto-extract findings from scanners

[execution]
default_timeout_secs = 600
max_concurrent_scans = 3
output_dir = "/tmp/raven-nest"

# [scope]                        # engagement authorization allowlist (deny-wins)
# enabled = true
# allowed_domains = ["example.com"]

# [network]
# http_proxy = "http://127.0.0.1:8080"

# [metasploit]
# enabled = true
# host = "127.0.0.1"
# port = 55553
# password = "changeme"

# [netexec]                      # gated, read-only credentialed enumeration
# enabled = true

パラメーターの一覧とツールごとの設定オプションについては、docs/USAGE.md をご覧ください。

安全アーキテクチャ

すべてのツール呼び出しは、次の6つのレイヤーを通過します。

1. 許可リスト -- 明示的に許可されたツールのみ実行できます
2. 入力検証 -- 対象は有効なIPアドレス、ホスト名、CIDR、またはURLである必要があります。シェルのメタ文字は拒否されます
3. プリセット引数 -- ユーザーが選択するのはスキャン種別であり、生のCLIフラグは指定できません
4. 実行の隔離 -- kill_on_drop による設定可能なタイムアウト
5. 出力のサニタイズ -- ANSIの除去と、設定可能な上限での切り詰め（UTF-8対応）
6. 品質評価 -- 結果が空の場合、レート制限、WAFによるブロックを検出します

追加の強化策：

• 起動時の設定検証 -- 安全上の制限（sqlmapのlevel/risk、hydraのtasks、masscanのrate）を範囲チェックします。範囲外の値やMSFのデフォルト認証情報が設定されている場合、サーバーは起動を拒否します
• ワードリストのパス検証 -- hydra、john、feroxbuster、ffufでは、/usr/share/、/usr/lib/、または設定済みのoutput_dir以下にあるワードリストのみ受け付けます。パストラバーサル（..）は拒否されます
• 位置引数のガード -- ツールに位置引数として渡される自由入力値は、フラグとして再解析されないよう文字セットをチェックします。hydraのservice（小文字／数字／ハイフン）およびform_params（先頭の-と制御文字は不可）、sqlmapのtechnique（BEUSTQの一部）、ffufのfilter_size（数字／カンマ）が対象です。対象にも同じチェックが適用され、フラグのような-oN/tmp/evilは拒否されます
• ポート指定の検証 -- nmapとmasscanのポートパラメーターに使用できるのは、数字、カンマ、ハイフンのみです
• ファイル権限 -- Cookieファイルとスキャンの一時保存ファイルは0o600（所有者のみ）で作成されます
• Markdownのエスケープ -- レポート生成時に、ユーザーが指定した検出項目のフィールドをエスケープし、Markdownインジェクションを防ぎます
• 検出IDの検証 -- 検出項目の取得／削除操作では有効なUUID形式が必要となり、パストラバーサルを防ぎます
• エンゲージメントのスコープ -- 任意の認可許可リスト（[scope]）を利用できます。有効にすると、すべての対象が許可されたCIDR／ドメインに一致し、拒否対象には一致しない必要があります（拒否が優先されます）。無効化されていない限り、ループバックは許可されます。http_requestはリダイレクトの各段階でスコープを再検証するため、リダイレクトによってスコープ外へ移動することはありません。デフォルトでは無効です
• 監査ログ -- すべてのツール実行について、ツール、対象、秘匿化された引数を{output_dir}/audit.logに追記します
• 事前クールダウン -- 任意のmin_exec_gap_msを設定すると、連続するツールの起動間隔が空き、攻撃性の高いツールを続けて実行して対象のWAFやレート制限に抵触するのを防ぎます。また、per_target_min_gap_msを設定すると、ホストごとに同様の間隔を設けながら、独立した対象への処理は並列で進められます。これはWAF／レート制限のリアクティブな検出を補完します。どちらもデフォルトでは無効です

Metasploit統合には、5層の安全モデルが追加されます。デフォルトで無効、ツールごとの許可リスト、パス境界に基づくモジュールブロックリスト、エクスプロイトの確認ゲート（実行には2回の呼び出しが必要）、セッションコマンドのフィルタリングです。エラーメッセージ内のパスワードは秘匿化され、TLS証明書の検証回避はローカルホストへの接続に制限されます。docs/METASPLOIT.mdを参照してください。

root権限が必要なツール（masscan、nmapのOS検出）は、サーバー全体の権限を昇格せずに、パスワードなしのsudoで実行できます。設定ドキュメントのsudo_toolsを参照してください。

コンテキスト予算

セッションを認識するコンテキスト予算トラッカーは、残りのコンテキストウィンドウの空き容量に応じて、ツールごとの出力上限を動的に調整します。これにより、コンテキストウィンドウが限られたローカル AI モデル（49-64K トークン）でのコンテキストのオーバーフローを防ぎます。

• フルモード -- すべての検出結果と詳細を表示し、ツール呼び出しあたり最大 8K 文字
• コンパクトモード -- 上位 N 件の結果と、重大度が「致命的」または「高」の検出結果のみを表示（消費量が 40% に達すると切り替わります）
• 最小モード -- 1 行の要約を表示（消費量が 70% に達すると切り替わります）

パーサーの結果上限は scale_cap() によって動的に拡張・縮小され、各ツールの出力パーサーは、アクティブな予算モードに応じて結果の上限を調整します。すべてのツール出力は、中央での ANSI エスケープシーケンスの除去と予算を考慮した切り詰め処理を wrap_result() で行います。

予算を使い切ると、追加のスキャンを実行するのではなく、検出結果を保存してレポートを生成するよう AI に指示するメッセージがサーバーから返されます。

ターゲットの検出追跡とスキャンの差分比較

すべての nmap 結果（run_nmap とバックグラウンドの nmap スキャン）は、ホストごとの検出記録に蓄積されます。記録にはポート、状態、サービス、バージョン、OS 推定値と、初回および最終確認のタイムスタンプが含まれます。再スキャン時には上書きではなくマージされるため、ターゲットの変化を記録で確認できます。

• list_targets / get_target_info は、再スキャンせずに追跡対象のホストと、ホストごとの完全なサービス一覧を取得します。
• diff_scans は、完了した 2 つの nmap スキャンを比較します。追加・削除されたホストとポートに加え、ポートごとの状態／サービス／バージョンの変化も表示します（open (ssh OpenSSH 8.9) → open (ssh OpenSSH 9.0)）。
• 検出データは検出結果と同様にエンゲージメント単位で管理され（{engagement}/targets/）、再起動後も保持されます。

run_nmap と run_nuclei は、コンテキスト予算による上限の対象とならない、機械可読な structured_content（ホスト／ポート／CVE、検出結果リスト）もレスポンスに付加します。これにより、クライアントは文章を解析せずに結果を処理できます。

レポート生成

generate_report エンドポイントは、構造化レポートを生成します。デフォルトは Markdown で、format パラメーターを使って JSON、SARIF、HTML も指定できます。レポートには以下が含まれます。

• 目次：各検出結果へのリンク付き
• エグゼクティブサマリー：重大度の内訳表と全体的なリスク評価付き
• 手法セクション（PTES フレームワーク）
• 使用ツール（検出結果から重複を除いて抽出）
• スコープとタイムライン：評価対象とエンゲージメント期間。検出結果から算出
• 番号付きの検出結果：重大度、ターゲット、ツール、CVSS スコア、CVE 識別子、OWASP Top 10 カテゴリー、証拠、修正ガイダンス付き

Markdown 形式と HTML 形式では、目次、手法、スコープ、生成タイムスタンプを含むレポートの全内容が表示されます。JSON 形式と SARIF 形式は、ツール連携向けの構造化エンベロープです。検出結果では、脆弱性を OWASP Top 10 に対応付けるための owasp_category フィールドをサポートしています（例：「A03:2021 Injection」）。

MCP リソース

サーバーはツールに加えて、raven:// スキームの読み取り専用 MCP リソースとしてデータを公開します。これにより、クライアントはツールを呼び出さずにデータを閲覧したり、添付したりできます。

• raven://findings -- 保存済みのすべての検出結果の JSON インデックス
• raven://findings/{id} -- 単一の検出結果を JSON 形式で表示
• raven://reports/{markdown|json|sarif|html} -- リクエストに応じて生成されるレポート
• raven://scans -- バックグラウンドスキャンの JSON インデックス
• raven://scans/{id} -- スキャンで取得された出力

保存済みの各検出結果と追跡対象の各スキャンは個別のリソースとしても一覧に表示されるため、リソースに対応したクライアントから閲覧できます。

出力パーサー

各セキュリティツールには、ツールの生出力から重要なデータを抽出する構造化出力パーサーがあります。

• nmap -- NSE スクリプト抽出機能付き XML パーサー（CVSS による vulners CVE の抽出）
• nuclei -- 重大度フィルタリング機能付き JSONL パーサー
• nikto/feroxbuster/ffuf/masscan -- 設定可能な結果上限を備えた行指向パーサー
• sqlmap -- インジェクションの種類とパラメーターの抽出
• testssl -- 脆弱性と証明書の検出結果の抽出
• hydra/whatweb -- 認証情報とテクノロジーの特定
• subfinder/dnsrecon/dnsx -- サブドメインと DNS レコードの抽出
• httpx/katana -- HTTP フィンガープリントとクロール済みエンドポイントの抽出
• dalfox/wpscan/enum4linux-ng/john -- 構造化された検出結果の抽出
• netexec -- 認証結果とホストごとの列挙結果の抽出

すべてのパーサーは Option<String> を返し、解析に失敗した場合は生出力にフォールバックします。結果の上限は、アクティブな予算モードに応じて動的に調整されます。

認証済みスキャン

http_request ツールは、セッション内およびコンテキストのクリア後も保持される共有 Cookie Jar を維持します（ディスクに保存されます）。外部サブプロセスツール（sqlmap、nikto、feroxbuster など）はこの Cookie Jar を共有しません。各ツールの cookie パラメーターで Cookie を渡してください。

テスト

3 つのクレートにわたる、381 件の単体テストと統合テストがあります。

cargo test --workspace

クレート	テスト数
raven-core	106
raven-report	71
raven-server	191
統合テスト	13

Python ベースの MCP 統合テストハーネスも利用できます。

python3 -u tests/manual_test_harness.py all     # full suite
python3 -u tests/manual_test_harness.py phase0   # single phase

プロジェクト構成

crates/
  raven-core/     # Safety validation, subprocess execution, config (TOML),
                  # scan manager (background scans with disk spill), audit log
  raven-report/   # Finding types (with OWASP categories), file-per-finding
                  # persistence, host/service discovery store (targets),
                  # multi-format report generators (md/json/sarif/html)
  raven-server/   # MCP server (rmcp), tool handlers (one module per tool),
                  # context budget tracker, output parsers, progress ticker,
                  # structured scan results, scan diffing
config/
  default.toml    # Default configuration
  sudoers-raven-nest  # Sudoers drop-in for privilege escalation
tests/
  manual_test_harness.py  # MCP integration test harness

ドキュメント

• docs/USAGE.md -- ツールのインストール、設定リファレンス、全パラメーターのドキュメント
• docs/MCP_TOOLS.md -- 46 個すべてのツールの機械可読マニフェスト（名前と説明）
• docs/LOCAL_AI_INTEGRATION.md -- ローカルモデル（Ollama、LM Studio）で Raven Nest を使用する方法
• docs/METASPLOIT.md -- Metasploit Framework の統合設定と安全性モデル
• docs/DATA_FLOW.md -- データフローと信頼できる情報源：各状態を所有するモジュール
• raven-nest-client -- 対応する TypeScript REPL クライアント（サーバーと同じバージョンで管理）
• CHANGELOG.md -- リリース履歴（現在：v0.4.1）

ライセンス

Apache-2.0