binary-analysis

バイナリ解析 — エージェントスキル

Ghidra を想定した、決定論的で対話を必要としない CLI を使って、不明なバイナリファイルの解析を計画します。ただし、以下の実装上の制限を参照してください。このスキルでは、バイナリについての推論方法、トリアージと詳細分析を使い分けるタイミング、標準的な証拠の解釈方法、監査可能なレポートの作成方法を説明します。観測可能な操作はすべて binary CLI を通じて行います。Ghidra API を直接呼び出すことはありません。

実装状況

このリリースでは、ライブ Ghidra 解析は提供されません。インポート、解析、メタデータ、構造・関数のクエリ、検索、トリアージ、レポート生成は、明示的なバックエンドエラーで停止します。依存関係をインストールしても、未完成のアダプターは動作するようになりません。プロジェクトの管理と依存関係の診断は引き続き利用できます。本番用 CLI は FakeAdapter を読み込んだり選択したりしません。テストでは明示的にインジェクトします。フィクスチャ／デモ用の CLI スイッチや環境変数によるオーバーライドはありません。

以下のワークフローは、想定されるインターフェースを説明するものであり、このリリースで実行可能な解析手順ではありません。バックエンドエラーが発生した時点で停止し、この制限を説明してください。古いプロジェクトが READY とマークされていても、古いフィクスチャ由来のレポートをユーザーのバイナリに関する証拠として引用しないでください。将来のライブバックエンドでは、結果を観測事実として扱う前に、異なる既知のバイナリを使った検証が必要です。

使用する場合

以下の条件に当てはまる場合は、このスキルを読み込んでください。

• ユーザーがバイナリファイル（PE、ELF、Mach-O、ファームウェアイメージ）を提供し、その動作、インポートする API、不審かどうかを尋ねている。
• ユーザーが、特定の関数やアドレスの逆コンパイル、逆アセンブル、コールグラフの調査、クロスリファレンス解析を依頼している。
• ユーザーが、不明なバイナリについて、構造化されたトリアージレポート、不審な API の解析、または機能マップを求めている。
• ユーザーが、2 つのバイナリの比較、エクスポートテーブルの検証、またはパターンに一致する文字列の抽出を依頼している。
• ユーザーが、解析ツールチェーン（binary doctor、binary bootstrap）のセットアップや解析プロジェクトの管理を希望している。

使用しない場合

以下の場合は、このスキルを読み込まないでください。

• ランタイム解析または動的解析 — デバッグ、strace/dtrace、サンドボックスでの実行、プロセスの監視。このスキルの対象は静的解析のみです（V1）。
• バイナリのパッチ適用または変更 — 16 進エディターによる編集、リソースの編集、再パッケージ化。解析ハーネスは設計上、読み取り専用です。
• すでに完全に把握しているバイナリ — 既知のコードのドキュメントや説明をユーザーが求めている場合は、汎用スキルを使用してください。
• ソースコードの解析 — C、C++、Rust、またはアセンブリのソースファイル。代わりに、言語固有のコード解析スキル、または汎用コード解析スキルを使用してください。
• ネットワークフォレンジックまたはパケットキャプチャ — PCAP 解析、ワイヤレベルでのプロトコルのリバースエンジニアリング。ネットワークに特化したスキルを使用してください。
• ライブメモリフォレンジック — プロセスメモリのダンプ、ヒープ解析。ファイル内のメモリマップ領域の静的解析は対象ですが、ライブプロセスの内省は対象外です。

エージェントが担うことと CLI が担うこと

この境界は、このスキルで最も重要な概念です。この境界を越えると、信頼性の低い証拠や、コンテキストの浪費、あるいはその両方につながります。

層	責任	してはならないこと
エージェント（あなた）	バイナリの動作について仮説を立てます。実行する解析とその順序を選択します。CLI の証拠を統合して結論を導きます。ユーザーに調査結果を平易な言葉で説明します。証拠に裏付けられたレポートを作成します。	CLI の出力にない事実を作り上げること。CLI が部分的な結果や低い信頼度を報告しているのに、確実だと主張すること。診断警告を無視すること。
CLI	引数を解析し、プロジェクトのライフサイクルを管理し、Ghidra 解析を実行し、正規エンティティをシリアライズし、JSON エンベロープを出力し、安全制限を適用します。	結果を解釈したり、結論を導いたり、説明文を作成したりすること。

経験則： JSON の data フィールドだけでは、証拠として成立しません。 結果が、指定されたバイナリに対する実装済みのライブバックエンドから得られたことを確認してください。その証拠が直接裏付けていないことを推測したくなった場合は、それがエージェントによる推論であることを明示し、確信度の隔たりを記してください。

基本的なワークフロー

すべての解析セッションは、この手順に従います。各フェーズは次のフェーズが依存する証拠を生成するため、省略しないでください。

フェーズ 1：環境の確認

binary doctor --json

いずれかのコンポーネントが severity: "ERROR" を報告した場合は、ブートストラップ計画を実行します。

binary bootstrap --plan --json

計画を確認します。ユーザーがインストールを許可した場合は、次を実行します。

binary bootstrap --apply --json

binary version --json で確認します。

フェーズ 2：プロジェクトのセットアップ

解析するバイナリごとにプロジェクトを作成します。プロジェクトによって解析状態が分離され、監査証跡が得られます。

binary project create <project-name> --json
binary import <path-to-binary> --project <project-name> --json

再現性を確保するには、コピー方式（デフォルト）を使用します。--reference は、バイナリが大きい場合、読み取り専用の場合、または複数のプロジェクトで共有される場合にのみ使用し、古くなるリスクをユーザーに説明してください。

フェーズ 3：初期解析

まず標準の解析プロファイルを実行します。これは、ほとんどのトリアージワークフローで必要となる構造クエリを網羅しています。

binary analyze --project <project-name> --json

応答を確認します。

• success: true, partial: false — フェーズ 4 に進みます。
• success: true, partial: true — diagnostics を確認して不足点を把握します。制限事項を明記したうえで、範囲が限られた結果を使って進めます。
• success: false, partial: true — タイムアウトです。完了した内容を抽出し、未完了の内容を報告します。
• success: false, partial: false — 致命的な失敗です。diagnostics で失敗の理由を確認します。プロジェクトは FAILED 状態になっているため、binary project clean を実行してリセットします。

フェーズ 4：証拠の収集

ユーザーの質問に基づいて解析を選択します。広範なものから具体的なものへと、以下の順に実行して証拠を積み上げます。

トリアージ（広範な調査）の場合：

binary triage --project <project-name> --json
binary suspicious-apis --project <project-name> --json
binary capability-map --project <project-name> --json

構造の把握の場合：

binary metadata --project <project-name> --json
binary sections --project <project-name> --json
binary entrypoints --project <project-name> --json
binary imports --project <project-name> --json
binary exports --project <project-name> --json
binary strings --project <project-name> --contains "<pattern>" --json

関数レベルの詳細調査の場合：

binary functions --project <project-name> --json
binary decompile --project <project-name> <function-selector> --json
binary disassemble --project <project-name> <target> --json
binary xrefs --project <project-name> <entity-selector> --json
binary callers --project <project-name> <function-selector> --json
binary callees --project <project-name> <function-selector> --json
binary callgraph --project <project-name> <function-selector> --depth 3 --json

パス解析の場合：

binary trace --project <project-name> --from <source> --to <target> --json

フェーズ 5：レポートと引き継ぎ

ユーザーに結果を説明する前に、後から参照できるレポートを生成します。

binary export-report --project <project-name> --type triage --format markdown --json

レポートを読みます。調査結果を明確な説明にまとめます。エージェントの推論と CLI の証拠は、必ず分けて明示してください。例：

## CLI Evidence (deterministic)
- The binary imports VirtualAlloc, WriteProcessMemory, and CreateRemoteThread
  (suspicious-apis, risk_score 8, rule_id: process-injection)
- Entry point at 0x401000, 3 sections (.text, .rdata, .data)

## Agent Assessment (inference)
- The API combination suggests process injection capability. This is a
  heuristic, not a confirmed behavior. The binary would need to be executed
  (out of scope for static analysis) to confirm.

安全境界

CLI はこれらの境界を自動的に適用します。ユーザーに求められた場合でも、決して回避しようとしてはいけません。

境界	適用方法	理由
対象を決して実行しない	CLI が拒否します。実行経路は存在しません	静的解析のみ
対象をライブラリとして決して読み込まない	実装されていません。dlopen/LoadLibrary の経路はありません	意図しないコード実行を防止します
ネットワークリスナーを決して公開しない	HTTP、MCP、ソケットの各サーバーはありません	CLI はローカルツールです
ハッシュやサンプルを決してアップロードしない	テレメトリや外部への呼び出しはありません	プライバシーとセキュリティを守ります
パスの封じ込め	すべてのプロジェクトパスでパストラバーサルを検証します	ワークスペースからの脱出を防止します
出力サイズの上限	デフォルトは 64 MB、JSON の最大値は 256 MB です	コンテキストの枯渇を防止します
メモリ制限	操作ごとの上限を設定できます	大規模な解析時の OOM を防止します
タイムアウトの適用	デフォルトは 300s で、コマンドごとに設定できます	操作を制限します
結果数の上限	ページネーションを使用し、デフォルトは 100、最大は 1000 です	出力が際限なく増えるのを防止します
グラフの深さの上限	コールグラフの深さは 10 に制限されます	無限再帰を防止します

証拠の基準

すべての CLI による証拠には、信頼度の階層があります。レポートや説明で証拠を引用する際は、これらの基準に従ってください。

証拠のカテゴリ（トリアージ出力）

カテゴリ	定義	例
観察	バックエンドから得られる直接的で決定的な事実です。confidence フィールドはありません。	「セクション .text は実行可能で、サイズは 4096 bytes です」
ヒューリスティック	明示的な confidence を伴う、ルールに基づく解釈です。	「不審な API：VirtualAlloc（risk_score: 8、confidence: HIGH）」
不明	特定のアドレスに関する、未解決であることを明示した問いです。	「0x402080 の間接呼び出し先を解決できませんでした」

信頼度レベル

レベル	意味	引用する際の扱い
HIGH	バックエンドがこの結果を確実と判断しています	事実として引用します
MEDIUM	バックエンドは妥当な確信を持っています	「可能性が高い」などの限定表現を添えて引用します
LOW	バックエンドは最善の推測を行いました	明確な但し書きを添える場合に限り引用します
UNKNOWN	バックエンドは判断できませんでした	未解決の問いとして提示します

エージェントによる推論

複数の CLI による観察結果をまとめて結論を導く場合は、それがエージェントによる推論であることを明示してください。推論を CLI の事実として提示してはいけません。次のような表現を使用してください。

• 「X と Y の組み合わせに基づき、エージェントは……と評価します」
• 「CLI は Z をヒューリスティック（confidence: MEDIUM）として報告しています。エージェントはこれを……と整合するものと解釈します」
• 「CLI は W を判断できませんでした。エージェントは、これが未解決の問いであると指摘します」

参照資料のルーティング

参照資料は必要に応じて読み込みます。起動時にすべて読み込まないでください。現在のタスクに適した参照ファイルを選ぶには、この表を使用してください。

参照資料	読み込むタイミング
references/installation.md	Ghidra、Java、または PyGhidra をセットアップする場合。binary doctor または binary bootstrap を実行する場合。依存関係のトラブルシューティングを行う場合。
references/cli-reference.md	フラグ、終了コード、例を含む完全なコマンドリファレンスが必要な場合。特定のコマンドやフラグについて詳しく知りたい場合。
references/triage-workflow.md	不明なバイナリのトリアージを行う場合。段階的なトリアージ手法と解釈ガイドが必要な場合。
references/function-analysis.md	関数を逆コンパイル、逆アセンブル、またはトレースする場合。デコンパイラーの出力やコールグラフ分析を理解する場合。
references/binary-formats.md	PE、ELF、または Mach-O 形式の特性を特定または解釈する場合。セクションフラグ、エントリーポイントの規約、または形式固有の仕様を理解する場合。
references/security.md	不審な API の結果、機能マップ、またはセキュリティルールの一致を解釈する場合。リスクスコアリングやルールの優先順位を理解する場合。
references/evidence-and-confidence.md	CLI の証拠とエージェントの推論を区別したレポートを作成する場合。証拠に裏付けられた論拠を構築する場合。
references/packed-and-obfuscated.md	バイナリがパック、圧縮、または難読化されている疑いがある場合。エントロピーの高いセクション、インポートの欠落、または小規模なインポートテーブルがある場合。
references/firmware.md	ファームウェアイメージを分析する場合。ファームウェア固有のロードアドレス規約、ファイルシステムの抽出パターン、またはブートローダーの分析が必要な場合。
references/troubleshooting.md	CLI が予期しないエラー、タイムアウト、または部分的な結果を返す場合。Ghidra の起動に失敗する場合。プロジェクトの状態が停止したままの場合。
references/reporting.md	binary export-report を使用してレポートを生成する場合。レポートの種類や形式を選ぶ場合。レポートの構造を解釈する場合。

レポートに関する要件

エージェントがタスクの完了と判断する前に、すべての分析セッションで次のいずれかの出力を少なくとも 1 つ作成する必要があります。

1. トリアージレポート — 不明なバイナリ向けです。観察事項、ヒューリスティクス、不明点、および CLI の証拠とは明確に分けたエージェント評価のセクションを記載します。
2. 焦点を絞った分析 — 特定の関数、インポート、または動作に関する具体的な質問向けです。まず CLI の証拠を示し、次にエージェントの解釈を示して、ユーザーの質問に回答します。
3. 機能の概要 — 「このバイナリは何をするのか」という質問向けです。証拠のソースと確信度を示しながら、機能領域を整理します。

レポートでは、以下を行う必要があります。

• CLI の証拠（決定論的な結果）とエージェントの評価（解釈）を分けます。
• ヒューリスティックに基づくすべての主張に確信度を示します。
• 出所情報として、プロジェクト ID、バイナリの SHA-256、アダプターとバックエンドのバージョンを記載します。
• 部分的な結果、タイムアウト、診断の警告を記載し、制限事項を隠さないでください。

検証マトリックス

結果をユーザーに提示する前に、以下を確認してください。

確認項目	方法
CLI コマンドがすべて success: true または文書化された partial: true を返した	各レスポンスエンベロープの success と partial を確認します
診断の警告が黙って無視されていない	すべてのレスポンスの diagnostics 配列を確認します
証拠の引用元を CLI の出力まで追跡できる	すべての事実に関する主張が data ブロック内のフィールドと一致していることを確認します
エージェントの推論が明示的に示されている	出力を検索し、条件や根拠を示さない主張がないか確認します
プロジェクトの状態がクリーンである	binary project status --project <name> --json を実行します
レポートが生成され、確認されている	プロジェクトの reports/ ディレクトリにレポートファイルが存在することを確認します

終了条件

次の場合は停止し、結果を報告してください。

• トリアージレポートが生成され、証拠に基づく調査結果でユーザーの質問に回答できている。
• 集中的な分析により、要求された具体的な情報（逆コンパイルされた関数、呼び出し経路、インポート一覧）が、その出所とともに得られている。
• 同じ問題に対して、収束しない診断を3回試みている。収集した証拠と障害となっている点を報告してください。
• バイナリ形式がサポートされていない（終了コード5）。形式上の制限を報告してください。
• 必須の依存関係が不足しており、ユーザーがインストールを希望しない。不足している点を報告してください。

1回の構造クエリだけでユーザーの質問に完全に回答できる場合を除き、それだけで停止しないでください。静的解析は反復的に行います。広範な調査を行ってから、詳細に掘り下げてください。