The AI assistant breaks this into tool calls:```
r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

### コア基盤（37モジュール）

`reversecore_mcp/core/` ディレクトリには、すべてのツールが依存する共有インフラストラクチャが含まれています：

| モジュール | 目的 |
|---|---|
| `config.py` | 34以上の環境変数を備えたPydantic BaseSettings |
| `security.py` | 入力サニタイズ、コマンド引数の検証 |
| `validators.py` | TOCTOU対策、シンボリックリンク解決を備えたファイル・バイナリパス検証 |
| `r2_pool.py` | 設定可能なサイズのスレッドセーフなRadare2接続プール |
| `r2_helpers.py` | 構造化されたRadare2出力の解析 |
| `metrics.py` | ツールごとの実行時間、呼び出し回数、エラー率、キャッシュ統計 |
| `memory.py` | セッション間で分析結果を永続化する非同期SQLiteベースのAIメモリストア |
| `mitre_mapper.py` | MITRE ATT&CKテクニックIDマッピングエンジン |
| `evidence.py` | 証拠分類システム：`OBSERVED`、`INFERRED`、`POSSIBLE` |
| `resilience.py` | リトライ、サーキットブレーカー、タイムアウトのデコレータパターン |
| `task_queue.py` | Redis + arqによるバックグラウンドタスクキュー |
| `extension_registry.py` | プラグイン登録とライフサイクル管理 |
| `arch_registry.py` | マルチアーキテクチャマッピング（x86、x86_64、ARM32、ARM64、MIPS、RISC-V、PPC → r2のarch/bits/registers） |
| `result_cache.py` | SHA256ベースのツール結果キャッシュデコレータ（`@cache_tool_result`） |
| `analysis_cache.py` | 多層逆コンパイルキャッシュ（L1：Redis、L2：SQLite） |
| `result.py` | `ToolSuccess` / `ToolError` Pydanticモデル |
| `exceptions.py` | `RCMCP-E*`エラーコードを持つ17の例外クラス |
| `decorators.py` | `@log_execution`、`@track_metrics` |
| `error_handling.py` | `@handle_tool_errors`デコレータ |
| `error_formatting.py` | 構造化されたエラーレスポンスのフォーマット |
| `execution.py` | タイムアウトと出力制限付きの安全なサブプロセス実行 |
| `command_spec.py` | サブプロセス呼び出しのコマンド仕様 |
| `loader.py` | 動的ツールモジュールローダー |
| `plugin.py` | プラグイン基底クラス |
| `extension.py` | 拡張機能基底クラス |
| `container.py` | コンテナ/サンドボックス実行サポート |
| `audit.py` | 監査ログ |
| `binary_cache.py` | バイナリファイルキャッシュ |
| `json_utils.py` | orjsonによるJSONシリアライゼーション（標準ライブラリのjsonより3〜5倍高速） |
| `logging_config.py` | Loguruベースの構造化ロギング |
| `report_generator.py` | レポートレンダリングエンジン（Markdown、xhtml2pdfによるPDF） |
| `resource_manager.py` | MCPリソースライフサイクル管理 |
| `sast/python_ast_scanner.py` | Python ASTベースの脆弱性スキャナー |
| `sast/regex_scanner.py` | C/C++正規表現ベースの脆弱性スキャナー |
| `sast/rule_manager.py` | SASTルールの読み込みと管理 |

---

## ツールカタログ（120ツール）

すべてのツールは構造化された`ToolResult`を返します — 型付き`data`を持つ`ToolSuccess`か、`RCMCP-E*`エラーコードを持つ`ToolError`のいずれかです。ツールは8つのプラグインに編成されています。

---

### 🔍 静的解析プラグイン（24ツール）

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 1 | `run_strings` | `strings` CLI | 設定可能な最小長でのASCII/Unicode文字列抽出 |
| 2 | `run_binwalk` | Binwalk | 組み込みシグネチャとファイルシステムのファームウェア深層スキャン |
| 3 | `run_binwalk_extract` | Binwalk | binwalkで検出された埋め込みファイルの抽出 |
| 4 | `parse_binary_with_lief` | LIEF | PE/ELF/Mach-Oヘッダー、セクション、インポート/エクスポート、TLSの完全解析 |
| 5 | `detect_packer` | DIE | クイックパッカー/コンパイラ検出 |
| 6 | `detect_packer_deep` | DIE（`diec`） | Detect It Easyによる深層パッカー/プロテクター解析 |
| 7 | `run_capa` | CAPA（Mandiant FLARE） | 機能検出 — 「データを暗号化」「永続化を作成」など |
| 8 | `run_capa_quick` | CAPA | ルールサブセットによるクイック機能スキャン |
| 9 | `generate_signature` | Radare2 | 識別用のバイナリシグネチャ生成 |
| 10 | `generate_yara_rule` | Radare2 + YARA | バイナリパターンからのYARA検出ルール生成 |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | 行動指標を含む高度なYARAルール |
| 12 | `scan_for_versions` | LIEF + strings | バイナリ内の埋め込みバージョン文字列のスキャン |
| 13 | `extract_rtti_info` | Radare2 | C++ RTTI（実行時型情報）の抽出 |
| 14 | `diff_binaries` | Radare2 | 2つのファイルバージョン間の意味的バイナリ差分 |
| 15 | `analyze_variant_changes` | Radare2 | バイナリバリアント間の変更分析 |
| 16 | `match_libraries` | Radare2 | 関数フィンガープリントによる静的リンクライブラリの識別 |
| 17 | `patch_diff_1day` | Radare2 + ヒューリスティクス | 1-day脆弱性研究のための自動パッチ差分解析 |
| 18 | `analyze_patch_diff_auto` | Radare2 + 推論 | 自動パッチ脆弱性推論 |
| 19 | `emulate_binary` | Radare2 ESIL | レジスタ/メモリ追跡コードエミュレーション |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | 特定の関数をターゲットにしたファジングハーネスの生成 |
| 21 | `run_fuzzing_campaign` | AFL++ | クラッシュ収集付きの完全なファジングキャンペーンの実行 |
| 22 | `triage_crash` | GDB | クラッシュ解析と悪用可能性評価 |
| 23 | `verify_path_and_get_args` | angr | シンボリック実行 — パスの到達可能性を証明し、具体的な入力を計算 |
| 24 | `taint_trace` | Radare2 + angr | ソースからシンクへのデータフローテイント解析 |

---

### 🔐 ソースコード監査プラグイン（1ツール）

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | 危険なパターンに対するPython ASTスキャン + C/C++正規表現スキャン |

---

### 🛠️ 共通ユーティリティプラグイン（20ツール）

**ファイル操作（5ツール）**

| # | ツール | 説明 |
|---|---|---|
| 26 | `run_file` | ファイルタイプ、アーキテクチャ、コンパイラのフィンガープリンティング |
| 27 | `copy_to_workspace` | 解析ワークスペースへのファイルコピー |
| 28 | `create_directory` | ワークスペース内のディレクトリ作成 |
| 29 | `list_workspace` | ワークスペース内の全ファイルの一覧表示 |
| 30 | `scan_workspace` | ファイルメタデータ付きの完全なワークスペーススキャン |

**パッチ説明（1ツール）**

| # | ツール | 説明 |
|---|---|---|
| 31 | `explain_patch` | バイナリパッチを自然言語で説明 |

**アセンブラ（1ツール）**

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | 命令をマシンコードにアセンブル（x86、ARM、MIPSなど） |

**AIメモリ管理（11ツール）**

これらのツールにより、AIは非同期SQLiteデータベースを使用して解析セッション間で結果を永続化・再呼び出しできます：

| # | ツール | 説明 |
|---|---|---|
| 33 | `create_memory_session` | 解析用の新しいメモリセッションの開始 |
| 34 | `store_analysis_finding` | タグ付きの解析結果の永続化 |
| 35 | `query_analysis_memories` | クエリによる過去の結果の検索 |
| 36 | `get_binary_analysis_context` | 特定のバイナリの全コンテキストの取得 |
| 37 | `tag_analysis_session` | 整理用にセッションへタグを追加 |
| 38 | `search_memories_by_tag` | タグによるセッション/結果の検索 |
| 39 | `delete_analysis_session` | セッションとその結果の削除 |
| 40 | `cleanup_expired_sessions` | しきい値より古いセッションの削除 |
| 41 | `list_analysis_sessions` | すべてのアクティブなセッションの一覧表示 |
| 42 | `export_memory_store` | すべてのメモリをポータブル形式にエクスポート |
| 43 | `import_memory_store` | エクスポートファイルからメモリをインポート |

**サーバーモニタリング（2ツール）**

| # | ツール | 説明 |
|---|---|---|
| 44 | `get_server_health` | 稼働時間、メモリ使用量、読み込まれたツール、Pythonバージョン |
| 45 | `get_tool_metrics` | ツールごとの呼び出し回数、平均実行時間、エラー率、キャッシュヒット/ミス |

---

### ⚙️ Radare2 & r2ghidraプラグイン（30ツール）

すべてのRadare2ツールは、r2pipeセッションを自動管理するスレッドセーフな接続プール（`r2_pool.py`）を使用します。

| # | ツール | 説明 |
|---|---|---|
| 46 | `Radare2_open_file` | Radare2でバイナリファイルを開く |
| 47 | `Radare2_close_file` | Radare2セッションを閉じる |
| 48 | `Radare2_list_open_files` | 現在開いているファイルの一覧表示 |
| 49 | `Radare2_analyze_binary` | 完全な自動解析（`aaa`）の実行 |
| 50 | `Radare2_list_functions` | 検出されたすべての関数の一覧表示 |
| 51 | `Radare2_disassemble_function` | 特定の関数の逆アセンブル |
| 52 | `Radare2_disassemble_address` | 特定のアドレスでの逆アセンブル |
| 53 | `Radare2_decompile_function` | r2ghidraによる逆コンパイル（r2に組み込まれたGhidraエンジン、JVM不要） |
| 54 | `Radare2_list_exports` | エクスポートされたシンボルの一覧表示 |
| 55 | `Radare2_list_imports` | インポートされた関数の一覧表示 |
| 56 | `Radare2_list_sections` | エントロピー付きのバイナリセクションの一覧表示 |
| 57 | `Radare2_list_strings` | バイナリ内で見つかった文字列の一覧表示 |
| 58 | `Radare2_find_cross_references` | 関数呼び出しとデータ参照の追跡 |
| 59 | `Radare2_search_bytes` | バイナリ内のバイトパターンの検索 |
| 60 | `Radare2_get_binary_info` | バイナリメタデータの取得（arch、format、エンディアン） |
| 61 | `Radare2_execute_command` | 生のRadare2コマンドの実行 |
| 62 | `Radare2_esil_emulate` | 特定のアドレスでのESILエミュレーション |
| 63 | `Radare2_get_hexdump` | 仮想アドレスでの16進ダンプ |
| 64 | `Radare2_get_cfg_data` | 制御フローグラフデータの抽出 |
| 65 | `Radare2_generate_cfg_png` | CFGをPNG画像として生成 |
| 66 | `Radare2_generate_callgraph` | 関数呼び出しグラフの生成 |
| 67 | `Radare2_recover_structures` | C構造体の自動復元と注釈データベースへの永続化 |
| 68 | `Radare2_decompile_with_r2ghidra` | キャッシュ付きの高品質C逆コンパイル |
| 69 | `Radare2_annotate_binary` | バイナリへの注釈の追加 |
| 70 | `Radare2_get_annotations` | 注釈の取得 |
| 71 | `Radare2_export_annotations` | 注釈のファイルへのエクスポート |
| 72 | `Radare2_import_annotations` | ファイルからの注釈のインポート |
| 73 | `Radare2_detect_crypto_constants` | 暗号定数の検出（AES S-boxなど） |
| 74 | `Radare2_find_gadgets` | ROP/JOPガジェットの検索 |
| 75 | `Radare2_calculate_entropy` | セクションごとのエントロピー計算 |

---

### 🦠 マルウェア解析プラグイン（9ツール）

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + ヒューリスティクス | 隠れたバックドア、孤立関数、タイムボム、ロジックボムの発見 |
| 77 | `adaptive_vaccine` | YARA + Radare2 | 検出用YARAルール + 脅威を無力化するバイナリパッチの生成 |
| 78 | `vulnerability_hunter` | Radare2 + 解析 | 危険なAPIパターン（strcpy、sprintf）とROPガジェットチェーンの検出 |
| 79 | `extract_iocs` | Regex + LIEF | IP、URL、ドメイン、ハッシュ、レジストリキー、暗号アドレスの抽出 |
| 80 | `run_yara` | YARA | カスタムルールファイルと組み込みルールセットでのスキャン |
| 81 | `generate_poc_exploit` | pwntools | 概念実証エクスプロイトコードの生成 |
| 82 | `build_rop_chain` | ROPgadget + pwntools | 自動ROPチェーン構築 |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | 自律型脆弱性ハンティングパイプライン |
| 84 | `analyze_heap_exploit` | Radare2 + ヒューリスティクス | ヒープ悪用解析（UAF、ダブルフリー、オーバーフロー） |

---

### 🕵️ デジタルフォレンジックプラグイン（22ツール）

**メモリフォレンジック（6ツール）**

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | 完全なメモリダンプ解析 |
| 86 | `memory_list_processes` | Volatility3 | メモリダンプから実行中プロセスの一覧表示 |
| 87 | `memory_detect_injections` | Volatility3 | プロセスメモリ内のコードインジェクションの検出 |
| 88 | `memory_extract_strings` | Volatility3 | プロセスメモリからの文字列抽出 |
| 89 | `memory_dump_module` | Volatility3 | メモリから読み込まれたモジュールのダンプ |
| 90 | `memory_list_symbols` | Volatility3 | メモリからのシンボルの一覧表示 |

**ディスクフォレンジック（6ツール）**

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | ディスクパーティションの一覧表示 |
| 92 | `disk_list_files` | Sleuth Kit | ディスクイメージ内のファイルの一覧表示 |
| 93 | `disk_recover_deleted` | Sleuth Kit | 削除されたファイルの復元 |
| 94 | `disk_analyze_mft` | Sleuth Kit | NTFSマスターファイルテーブルの解析 |
| 95 | `disk_extract_file` | Sleuth Kit | ディスクイメージからのファイル抽出 |
| 96 | `disk_hash_verify` | Sleuth Kit | ハッシュによるファイル整合性の検証 |

**ネットワークフォレンジック（5ツール）**

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | PCAP解析：プロトコル内訳、異常検出 |
| 98 | `pcap_list_connections` | Scapy | すべてのネットワーク接続の一覧表示 |
| 99 | `pcap_extract_dns` | Scapy | DNSクエリとレスポンスの抽出 |
| 100 | `pcap_extract_c2` | Scapy | 潜在的なC2通信の識別 |
| 101 | `pcap_reconstruct_stream` | Scapy | TCPストリームの再構築 |

**アーティファクト解析（5ツール）**

| # | ツール | バックエンド | 説明 |
|---|---|---|---|
| 102 | `artifact_collect` | カスタムパーサー | ブラウザ履歴、レジストリハイブ、イベントログ、プリフェッチの収集 |
| 103 | `artifact_correlate_ioc` | カスタムパーサー | 既知のIOCとのアーティファクト相関 |
| 104 | `artifact_generate_yara` | YARA | アーティファクトパターンからのYARAルール生成 |
| 105 | `artifact_timeline` | カスタムパーサー | 複数のアーティファクトソースからのタイムライン構築 |
| 106 | `artifact_report` | カスタムパーサー | アーティファクト解析レポートの生成 |

---

### 📝 レポート生成プラグイン（14ツール）

| # | ツール | 説明 |
|---|---|---|
| 107 | `get_system_time` | サーバータイムスタンプの取得（AIによる日付の捏造を防止） |
| 108 | `set_timezone` | レポート用タイムゾーンの設定 |
| 109 | `get_timezone_info` | 現在のタイムゾーン情報の取得 |
| 110 | `start_report_session` | 一意のIDを持つ計時解析セッションの開始 |
| 111 | `end_report_session` | セッションの確定：期間の計算、IOC/ATT&CKリストのロック |
| 112 | `get_report_session_status` | セッションステータスの確認 |
| 113 | `list_report_sessions` | すべてのアクティブ/完了セッションの一覧表示 |
| 114 | `add_ioc` | ライブセッション中のIOCの収集とタグ付け |
| 115 | `add_analysis_note` | 分類されたメモの追加（finding、warning、behavior） |
| 116 | `add_mitre_technique` | MITRE ATT&CKテクニックIDの記録 |
| 117 | `set_severity` | セッションの重大度の設定（low/medium/high/critical） |
| 118 | `create_analysis_report` | 4モードでのレポートレンダリング：`full_analysis`、`quick_triage`、`ioc_summary`、`executive_brief` |
| 119 | `generate_vex_report` | VEX（Vulnerability Exploitability eXchange）レポートの生成 |
| 120 | `generate_sigma_rule` | SIGMA検出ルールの生成 |

---

## ガイド付き解析プロンプト（22モード）

プロンプトは、構造化されたペルソナ、ステップバイステップのツール使用シーケンス、証拠分類ルールでAIを準備する事前構築済みの解析ワークフローです。AIクライアントでプロンプト名を参照することでアクティブ化します。

### マルウェア解析（9プロンプト）

| プロンプト | ユースケース |
|---|---|
| `full_analysis_mode` | 6フェーズの包括的解析：トリアージ → 逆アセンブル → 動作 → ネットワーク → 永続化 → レポート |
| `malware_analysis_mode` | 脅威分類付きの焦点を絞ったマルウェア解析 |
| `basic_analysis_mode` | 初期評価と迅速な判定のための高速トリアージ |
| `apt_hunting_mode` | APT固有のハンティング：横移動、永続化、データ窃取 |
| `malware_defense_mode` | 防御指向：検出ルールと緩和策の生成 |
| `unpacking_mode` | パッキング/難読化の解析と回避（Themida、VMProtect、UPX） |
| `c2_extraction_mode` | C2通信インフラストラクチャの抽出と解析 |
| `ransomware_triage_mode` | ランサムウェア固有のトリアージ：暗号化解析、鍵回復評価 |
| `code_similarity_mode` | コード類似性と共通系統のためのバイナリ比較 |

### セキュリティ研究（6プロンプト）

| プロンプト | ユースケース |
|---|---|
| `vulnerability_research_mode` | バグハンティング：バッファオーバーフロー、UAF、コマンドインジェクション |
| `crypto_analysis_mode` | 暗号実装の解析と弱点検出 |
| `firmware_analysis_mode` | IoT/組み込みファームウェア：binwalk抽出、UART文字列、ハードコードされた認証情報 |
| `patch_analysis_mode` | セキュリティパッチ解析と回帰テスト |
| `source_code_audit_mode` | ソースコードセキュリティ監査（Python、C、C++） |
| `autonomous_vuln_hunt_mode` | 自律型脆弱性ハンティングパイプライン |

### CVE研究 & エクスプロイト開発（5プロンプト）

| プロンプト | ユースケース |
|---|---|
| `taint_analysis_mode` | データフローテイント解析：自動ソース→シンクパス発見 |
| `heap_exploit_mode` | ヒープ悪用解析とPoC生成 |
| `fuzzing_mode` | ファジングキャンペーン設定とクラッシュトリアージ |
| `patch_diff_auto_mode` | 1-day脆弱性研究のための自動パッチ差分 |
| `cve_discovery_pipeline_mode` | 完全なCVE発見パイプライン：パッチ差分から動作するエクスプロイトまで |

### その他（2プロンプト）

| プロンプト | ユースケース |
|---|---|
| `game_analysis_mode` | ゲームクライアント解析：アンチチート検出、プロトコルリバースエンジニアリング、メモリ検査 |
| `report_generation_mode` | MITRE ATT&CKテクニックマッピング付きの構造化セッションワークフロー |

> **プロンプトの仕組み：** 各プロンプトは、構造化された解析ペルソナでAIを準備します。Chain-of-Thought推論チェックポイント（AIが先に進む前に停止して評価する必要がある箇所）と、AIが推測を事実として述べることを防ぐ証拠分類ルールが含まれています。すべての結果は`OBSERVED`（直接検証済み）、`INFERRED`（静的解析から論理的に導出）、`POSSIBLE`（さらなる検証が必要）のいずれかにラベル付けする必要があります。

---

## MCPリソース（11 URI）

リソースは、AIクライアントがURIテンプレートを通じてアクセスできる読み取り専用のデータエンドポイントです。明示的なツール呼び出しを必要とせずに構造化データを提供することでツールを補完します。

### 静的リソース

| URI | 説明 |
|---|---|
| `reversecore://guide` | ファイルパスルールとベストプラクティスを含むツール使用ガイド |
| `reversecore://guide/structures` | 構造体復元とクロスリファレンス解析の技術ガイド |
| `reversecore://tools` | 登録済みの全120ツールの完全なドキュメント |
| `reversecore://logs` | アプリケーションログ（最後の100行） |

### 動的リソース（バイナリごとの仮想ファイルシステム）

これらのURIはバイナリごとに解決され、対応する解析ツールをオンデマンドで呼び出します：

| URIテンプレート | 説明 |
|---|---|
| `reversecore://{filename}/strings` | バイナリからすべての文字列を抽出 |
| `reversecore://{filename}/iocs` | IOCの抽出（IP、URL、メール、ハッシュ） |
| `reversecore://{filename}/func/{address}/code` | 関数の逆コンパイルされた疑似Cコード |
| `reversecore://{filename}/func/{address}/asm` | 関数の逆アセンブル |
| `reversecore://{filename}/func/{address}/cfg` | Mermaid形式の制御フローグラフ |
| `reversecore://{filename}/functions` | バイナリ内の全関数の一覧 |
| `reversecore://{filename}/dormant_detector` | 潜伏検出器の解析結果 |

---

## クイックスタート

### オプション1 — PyPI（最も簡単）```bash
pip install reversecore-mcp
reversecore-mcp

### オプション3 — ソースからビルド（Docker Compose）```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### オプション4 — Python（ローカル開発）```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m reversecore_mcp.server

> Intel/AMD を使用している場合は、`reversecore-mcp-arm64` を `reversecore-mcp` に置き換えてください。

---

### 🌐 オプション 2: SSE HTTP モード

ネットワークベースのストリーミング（Server-Sent Events）の場合:```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

### テスト```bash
# Full test suite with coverage report
pytest tests/ -v

# Unit tests only (fast, no external dependencies)
pytest tests/unit/ -v

# Integration tests (requires Docker)
pytest tests/integration/ -v

# Run with coverage threshold enforcement
pytest tests/unit/ --cov=reversecore_mcp --cov-fail-under=80

# Run a specific test
pytest tests/unit/test_cli_tools.py::TestRunFile::test_success -v

# Security boundary tests
pytest tests/ -m security -v

# Benchmarks
pytest tests/ -m benchmark -v

### Pre-commit フック

以下のフックは、コミットのたびに自動的に実行されます：

1. **Ruff** — 自動修正付きのリント + フォーマットチェック
2. **trailing-whitespace** — 末尾の空白を削除
3. **end-of-file-fixer** — ファイルが改行で終わることを保証
4. **check-yaml / check-json** — YAML/JSON 構文の検証
5. **check-added-large-files** — 1 MB を超えるファイルをブロック
6. **check-merge-conflict** — 未解決のマージマーカーを検出
7. **detect-private-key** — 誤ったキーのコミットを防止
8. **Bandit** — Python セキュリティスキャン

---

## CI/CD パイプライン

`main` へのプッシュのたびに、11 のパイプラインジョブがトリガーされます。デプロイ前にすべてが成功する必要があります。```
 Lint & Security Gate              Unit Tests (Python Matrix)
   ├─ Gitleaks (secret scan)         ├─ pytest 3.10 --cov-fail-under=80
   ├─ Hadolint (Dockerfile lint)     ├─ pytest 3.11 --cov-fail-under=80
   ├─ Ruff check + format            └─ pytest 3.12 --cov-fail-under=80
   ├─ Mypy type check (108 files)
   ├─ Bandit (all severities)      Wheel Smoke Test
   ├─ pip-audit (no CVEs)            └─ Build wheel → install in /tmp
   └─ Security boundary tests            → verify plugin discovery
                                          → assert __file__ under sys.prefix
 CodeQL Analysis
   └─ Python SAST                  Docker Verification
                                     ├─ Build reversecore-mcp:ci
 Exploit Safety Gate                 ├─ Trivy container scan
   ├─ Bandit on POC templates        ├─ Image size check (< 5 GB)
   ├─ Hypothesis DAST fuzzing        ├─ CLI tool verification
   ├─ Performance benchmarks         ├─ Integration tests in container
   └─ Container isolation test       └─ E2E tool invocation

 In-Container Smoke Test           Build Base Image (amd64 + arm64)
   ├─ Copy test ELF into container   ├─ Compile YARA 4.3.1
   └─ Run scripts/smoke_test.py     ├─ Compile Radare2 6.0.4
                                     ├─ Compile r2ghidra
 Deploy (amd64 + arm64)             └─ Push to GHCR
   ├─ Build app image
   ├─ Push to GHCR                 Merge Manifests
   └─ Trivy rescan on published     └─ Multi-arch manifest → :latest

このイメージは、ツールのバージョンが変更された場合にのみ再ビルドされます。ビルド時間: 約12分。

### レイヤー2: アプリケーションイメージ (`Dockerfile`)

ベースイメージを継承し、アプリケーションコードをコピーします:```
FROM base image
    ├── COPY reversecore_mcp/ (application code)
    ├── COPY scripts/ (smoke test, benchmarks)
    ├── pip install any new requirements
    ├── Security package upgrades
    └── CMD ["python", "-m", "reversecore_mcp.server"]

**その他のディレクトリ:**```
tests/
├── unit/                          # 1,957 unit tests
├── integration/                   # Docker-based integration tests
├── fixtures/                      # Test binaries, YARA rules, sample data
└── conftest.py                    # Shared pytest fixtures

scripts/
├── smoke_test.py                  # Multi-layer in-container smoke test
├── check_release_metadata.py      # Version consistency validation
├── fetch_test_binaries.py         # Download test fixtures
├── run-docker.sh                  # Auto-detect architecture and start
└── ...                            # Benchmarks, analysis scripts

docs/
├── getting-started/               # Installation guide
├── development/                   # Architecture, contributing, testing guides
├── api/                           # Tool and module reference
└── user-guide/                    # Analysis workflows

Args:
    file_path: Path to the binary file (relative to workspace).
    option: Optional analysis option.

Returns:
    ToolResult with status='success' and structured content.
"""
try:
    safe_path = validate_file_path(file_path)
    result = await perform_analysis(safe_path)
    return success({"result": result})
except Exception as e:
    return failure(
        error_code="RCMCP-E100",
        message=str(e),
        hint="Check that the file exists and is a valid binary.",
    )

適切なプラグインの `__init__.py` に登録し、`tests/unit/` にテストを追加します。

---

## コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します: `git checkout -b feat/my-feature`
3. コードと並行してテストを作成します — カバレッジは80%を下回らないようにしてください
4. すべてのゲートを通過させます: `pytest`、`ruff check`、`mypy`、`bandit`
5. 明確な説明を添えてプルリクエストを開きます

コード標準、docstring規約（Googleスタイル）、プルリクエストのチェックリストについては、[コントリビューションガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/development/contributing.md)をお読みください。

---

## ドキュメント

| ドキュメント | 説明 |
|---|---|
| [インストールガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/getting-started/installation.md) | すべての環境向けの詳細なセットアップ |
| [アーキテクチャガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/development/architecture.md) | システム設計とコンポーネントの詳細 |
| [コントリビューションガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/development/contributing.md) | コード標準、docstring、PRワークフロー |
| [テストガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/development/testing.md) | テストパターン、フィクスチャ、カバレッジ |
| [APIリファレンス](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/api) | ツールとモジュールのリファレンス |
| [ユーザーガイド](https://github.com/sjkim1127/reversecore_mcp/blob/main/docs/user-guide) | 分析ワークフロー |

---

## 使用例

### 例1: 基本的なマルウェアトリアージ```
User: "Analyze this suspicious file sample.exe"

AI calls:
  1. run_file("sample.exe")           → PE32 executable, x86, MSVC
  2. detect_packer("sample.exe")      → Not packed
  3. extract_iocs("sample.exe")       → 3 IPs, 2 URLs, 1 mutex
  4. run_capa("sample.exe")           → "creates persistence", "encrypts data"
  5. dormant_detector("sample.exe")   → 2 orphan functions with network calls
  6. generate_yara_rule("sample.exe") → Detection rule generated

AI response: "This PE32 binary shows ransomware-like behavior. CAPA detected
encryption and persistence capabilities. I found 2 hidden network functions
that may serve as a backup C2 channel. Here's a YARA rule for detection..."

### 例3：デジタルフォレンジック調査```
User: "Analyze this memory dump from a compromised server"

AI calls:
  1. memory_list_processes("memdump.raw")
     → 47 processes, 2 with suspicious names

  2. memory_detect_injections("memdump.raw")
     → Code injection detected in PID 1842 (svchost.exe)

  3. memory_extract_strings("memdump.raw", pid=1842)
     → C2 domain strings extracted

  4. artifact_correlate_ioc(artifacts={"domains": ["evil-c2.com"]})
     → Matches known APT group IOCs

  5. create_analysis_report(template_type="full_analysis")
     → PDF report with timeline and MITRE ATT&CK mapping

---

## マルチアーキテクチャ対応

`arch_registry.py` モジュールは、アーキテクチャ名をRadare2の設定パラメータにマッピングし、手動設定なしで様々なCPUアーキテクチャを横断してツールを動作させることができます：

| アーキテクチャ | キー | r2 Arch | ビット幅 | PCレジスタ | SPレジスタ |
|---|---|---|---|---|---|
| Intel 32ビット | `x86` | `x86` | 32 | `eip` | `esp` |
| Intel/AMD 64ビット | `x86_64` | `x86` | 64 | `rip` | `rsp` |
| ARM 32ビット / Thumb | `arm32` | `arm` | 16, 32 | `r15` | `r13` |
| ARM 64ビット (AArch64) | `arm64` | `arm` | 64 | `pc` | `sp` |
| MIPS | `mips` | `mips` | 32, 64 | `pc` | `sp` |
| RISC-V | `riscv` | `riscv` | 32, 64 | `pc` | `sp` |
| PowerPC | `ppc` | `ppc` | 32, 64 | `pc` | `r1` |

**エイリアス解決**は自動的に処理されます：
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `bits=64` の `arm` → `arm64`
- `bits=16` または `bits=32` の `arm` → `arm32`

`Radare2_esil_emulate`、`assemble_instructions`、`r2_simulate_patch` などのツールは、このレジストリを使用して、任意のターゲットバイナリに対して解析環境を正しく設定します。

---

## 結果キャッシュシステム

2つのキャッシュ層により、冗長な計算を最小限に抑えます：

### ツール結果キャッシュ (`result_cache.py`)

`@cache_tool_result` デコレータは、バイナリファイルのSHA256ハッシュとツールのキーワード引数に基づいて、任意のツールの出力をキャッシュします：```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**ストレージ:** `MEMORY_DB_PATH` で設定されたパスにある非同期SQLiteデータベース（デフォルト: `~/.reversecore_mcp/memory.db`）。

**移植性:** `export_memory_store` と `import_memory_store` を使用して、メモリデータベース全体を環境間で転送します。

---

## Webダッシュボード

HTTPモード（`MCP_TRANSPORT=http`）で実行すると、`http://localhost:8000/dashboard` でWebダッシュボードを利用できます。以下を提供します:

- ドラッグ＆ドロップによるバイナリのアップロード
- リアルタイムの解析ステータス
- 対話型の関数リストと逆アセンブリビュー
- IOC抽出結果
- サーバーヘルスモニタリング

**技術スタック:** FastAPI + Jinja2テンプレート + HTMX（`dashboard/static/` からローカルに読み込まれ、CSP準拠のためのCDN依存なし）。

**セキュリティ機能:**
- すべての状態変更フォームに対するCSRFトークン
- Jinja2の自動エスケープ有効
- 表示前に `html.escape()` でサニタイズされるすべてのユーザー入力
- `validate_file_path()` によるパストラバーサル保護

---

## デプロイメント

### 本番環境チェックリスト

本番環境にデプロイする前に:

| 項目 | 方法 |
|---|---|
| APIキーの設定 | `MCP_API_KEY=<強力なランダムキー>` |
| 非rootユーザーの使用 | 組み込み: コンテナは `appuser`（UID 1000）として実行 |
| リソース制限の設定 | デフォルト: `docker-compose.yml` でCPU 2 / RAM 4 GB |
| 構造化ログの有効化 | ログ集約用に `LOG_FORMAT=json` |
| Redisの設定 | タスクキューとキャッシュ用に `REDIS_URL=redis://<host>:6379/0` |
| ワークスペースパスの設定 | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| レート制限の確認 | `REVERSECORE_RATE_LIMIT=60`（リクエスト/分、必要に応じて調整） |
| サンドボックスの有効化 | 動的解析の分離用に `REVERSECORE_SANDBOX_ENABLED=true` |

### ヘルスチェック

サーバーはオーケストレーション用のHTTPヘルスチェックエンドポイントを提供します:```bash
# Liveness (always 200 if process is running)
curl http://localhost:8000/health/live

# Readiness (checks tool availability)
curl http://localhost:8000/health/ready

# Full health (requires API key if configured)
curl -H "X-API-Key: <key>" http://localhost:8000/health