HexWitness

リバースエンジニアリングエージェントに、記憶と地図、そして証拠を与えましょう。
HexWitness は、静的解析、実行時キャプチャ、人間による結論を、永続的なひとつのエビデンスグラフにまとめます。

クイックスタート · 役立つ理由 · 使用例 · ドキュメント · 比較

---

昨日、エージェントはパーサーを見つけ、呼び出し元を特定し、どの実行時イベントがそこに到達したかを証明しました。今日、新しいチャットを開くと、ライブ逆アセンブラーにすべてを再発見させることになります。

HexWitness は、この繰り返しを止めます。

flowchart LR
  V["Binary Ninja · IDA · Ghidra"] --> X["Reviewed evidence"]
  R["Frida · debugger · wire observer"] --> C["Sealed capture"]
  C --> X
  X --> E[("HexWitness memory")]
  E --> A["Your AI agent"]
  A --> Q["Answer with proof"]
  A -.->|one named gap| V

ライブビューアーは、引き続きエージェントの目となります。HexWitness は、正確なビルドに紐づき、ツール横断で検索でき、矛盾を正直に示し、次のエージェントがすぐに使えるケースファイルになります。

60 秒で動作を確認

必要なもの：Git と Node.js 22.13 以降。

npm install --global hexwitness
hexwitness setup
hexwitness demo

セットアップウィザードでは、HexWitness を Codex、Claude Code、Cursor、VS Code/Copilot、Claude Desktop、または汎用 MCP クライアントに接続できます。選択したエージェント向けに作成されたガイダンスもインストールされます。必要に応じて MCP エントリーがローカルの読み取り専用デーモンを起動するため、サービスの起動手順を調整する必要はありません。

次のように尋ねてみましょう：

Use HexWitness to explain 0x401120 in build toy-v1.
Show proof, contradictions, and missing evidence separately.

デモでは、合成された再配布可能なエビデンスを使用します。HexWitness にサードパーティーのバイナリデータは同梱されません。

ソースをチェックアウトして使いたい場合は？

git clone https://github.com/siaginw/HexWitness.git
cd HexWitness
npm install
npm run demo
npm run setup -- --client codex --viewer none --yes
npm run doctor

必要に応じて、codex を claude-code、cursor、copilot、または generic に置き換えてください。セットアップコマンドは、チェックアウト内のローカルランタイムの絶対パスを解決し、選択したエージェントに合わせたガイダンスをインストールして、グローバルインストールを必要とせずに MCP 接続を設定します。セットアップ後、選択した AI クライアントを再起動し、hexwitness_health と hexwitness_contract を呼び出すよう指示してください。どちらも成功してから、非公開のエビデンスを使用してください。

重要

チェックイン済みの .mcp.json.example は、npm install --global hexwitness を前提としています。ソースをチェックアウトしている場合は、この例をコピーせずに npm run setup を実行してください。セットアップによって、正しいローカルの Node.js パスとバンドル済みランタイムのパスが記録されます。

HexWitness は、ひとつのコマンドでインストールできます。サービス、MCP トランスポート、インストーラー、キャプチャパイプライン、アダプターカタログは、このコマンドの背後にまとめられています。

hexwitness agent                 # daemon autostart + MCP for AI clients
hexwitness serve                 # REST daemon only
hexwitness adapters              # list every included viewer/runtime adapter
hexwitness adapters binary-ninja # print one adapter's exact path and capabilities
hexwitness contract              # inspect the stable 1.x public contract
hexwitness backup ./evidence.db  # create and verify a consistent snapshot

公式 MCP Registry の識別子：io.github.siaginw/hexwitness。レジストリ対応クライアントは、npm 経由で公開されているものと同じローカルの stdio サーバーを検出します。宣言されている起動コマンドは hexwitness agent です。

npm パッケージには、内部モジュールツリーを公開する代わりに、ひとつのバンドル済みランタイムが含まれています。Python は、Binary Ninja、IDA、Ghidra のエクスポーターに限って使用されます。これらの製品では、サポート対象の自動化 API が Python を通じて提供されるためです。大きな JSONL エクスポートや長時間のキャプチャは、すべてをメモリに読み込むのではなく、アトミックな取り込みとディスクベースの正規化によってストリーミング処理されます。

HexWitness が異なる点

多くの RE 統合が解決するのはアクセスです。エージェントが逆コンパイラー、デバッガー、トレースを読み取れるようにします。HexWitness が解決するのは継続性です。そのツール、ビルド、チャットがなくなった後も、有用な結果を保持します。

アプローチ	特に優れている用途	HexWitness が埋めるギャップ
ビューアー MCP	ライブ逆コンパイル、クロスリファレンス、名前変更、解析の制御	昇格しない限り、調査結果はセッションの範囲内にとどまります
メモとレポート	人間向けの説明	クエリ、比較、正確な証拠への追跡が困難です
汎用エージェントメモリ	設定や広範なプロジェクトコンテキスト	ビルド、アドレス、コールグラフ、キャプチャ、来歴に特化した契約がありません
HexWitness	永続的な RE 証拠とランタイムの再構築	ビューアーを置き換えるのではなく、ビューアーと組み合わせて使えます

そのため、HexWitness は次のような場合に特に役立ちます。

• バイナリが変更され、アドレスが移動する場合
• 複数のエージェントやアナリストが作業を共有する場合
• 静的コードとランタイムの動作を一致させる必要がある場合
• 結論に再現可能な証拠の連鎖が必要な場合
• 失敗したキャプチャを成功したキャプチャと比較する必要がある場合
• 「そう考えている」を「証明した」に変える必要がある場合

Why HexWitness で、率直なカテゴリ比較をご覧ください。

実際の質問をする

ユーザーは対象について質問します。ツールはエージェントが選びます。

Which function validates frame length before dispatch?
Reuse retained evidence first. Inspect a live viewer only if one exact edge is missing.

Compare the working and failing login captures.
Find the first meaningful divergence, then resolve its static consumer.

Where is this UUID used, which class owns it, and did its field offset change
between builds?

HexWitness は、ビルド、関数、クラス、UUID、型、フィールド、vtable、呼び出し、クロスリファレンス、パス、データフロー、キャプチャ、矛盾、カバレッジ、証拠の欠落、永続的な調査、失敗した試行、異議申し立て、発見のみの検索に対するファーストクラスのクエリをエージェントに提供します。4 つの MCP プロンプトには、調査、ランタイム比較、ライブ調査結果の昇格、敵対的な証拠レビューのワークフローがまとめられています。

1 つの調査ループ

1. 記憶する。 ライブツールに触れる前に、保持された証拠をクエリします。
2. 固定する。 正確なアーティファクトビルドを選択し、習慣でアドレスをビルド間に持ち越さないようにします。
3. 解決する。 対象を検索し、次にその証拠の全容を記したドシエを読みます。
4. 絞り込む。 必要な呼び出し、フィールド、スライス、またはキャプチャウィンドウのみをたどります。
5. 検証する。 来歴、信頼度、矛盾する主張を明らかにします。
6. エスカレーションする。 証明が途切れたら、不足しているライブ観測のうち最小のものを特定します。
7. 昇格する。 範囲を限定した結果をエクスポートし、次の調査をより効率よく始められるようにします。

長期にわたる作業では、決定論的なプレイブックによって、永続的なチェックリストと操作予算を用意できます。失敗した方法も検索可能なまま保持されます。証拠への異議申し立てでは、対立する見解、裏付けのない主張、未解決の欠落を明らかにできます。エージェント間の合意によって信頼度が不当に高まることはありません。

エージェントは、明示的な MCP ツールを 1 つ使って、許可リストに登録されたローカル RE ユーティリティを実行することもできます。引数は argv のみ、作業ディレクトリはルート配下に限定され、時間制限と出力上限があり、実行記録を生成します。これは OS サンドボックスではありません。ツール出力は、証拠モデルを通じて昇格されるまでは観測結果として扱われます。環境変数による有効化スイッチも、別個のモデルプロバイダーキーも必要ありません。調査ワークベンチをご覧ください。

データベースは証拠を記憶します。別個のプライバシー保護型アクティビティストアは、操作ハッシュ、所要時間、ステータス、件数を記憶します。プロンプト、引数、返された証拠は保存しません。

コマンドを並べずにランタイムをキャプチャ

コレクターは、慣例に沿ったファイルと小さなマニフェストを 1 つのプライベートフォルダーに配置します。

roundtrip/
├── capture.json
├── wire.jsonl
├── hooks.jsonl
├── screen.mp4
└── context.json

次に、以下を実行します。

hexwitness capture ./private/roundtrip

HexWitness は、必要な役割とアクションマーカーを確認し、アーティファクトを分離されたプライベートパックにコピーします。機密フィールドを削除し、ペイロードを長さと SHA-256 に置き換えることで、安全なタイムラインに正規化し、チェックサムを封印して整合性を検証した後、証拠をインポートします。ベースラインアーティファクトが存在しない場合や空の場合は、フェイルクローズで処理されます。正規化に失敗しても、ソースパックは復元可能な状態で残ります。

コレクターとシナリオの契約については、キャプチャパックをご覧ください。

スタックとの連携

ツール	永続化ブリッジ
Binary Ninja	詳細な JSONL エクスポーターと、オプションの公式 Binary Ninja MCP ライブビューアー
IDA / IDAPython	関数、文字列、インポート、参照、ブロック、およびオプションの Hex-Rays 疑似コードとライブ MCP
Ghidra	関数、文字列、インポート、参照、ブロック、型、フィールド、列挙型のエクスポーター
Frida 17	対象を絞ったセマンティックイベントオブザーバーと、フェイルクローズ方式の JSONL 正規化機能
その他のツール	バージョン管理されたアダプターマニフェストとベンダー中立の JSONL スキーマ

HexWitness は、プロジェクト内に機能の劣る逆アセンブラーを同梱していません。ビューアー MCP はライブで状況を確認できます。エクスポーターは、レビュー済みの調査結果をポータブルなメモリに変換します。ビューアー MCP ブリッジとアダプター SDKをお読みください。

ひとつの真実、3つのインターフェース

インターフェース	最適な用途
MCP	エージェント主導の調査、読み取り専用の証拠ツール、および明示的に許可されたオープンワールドのローカルツールランナー1つ
CLI	インポート、キャプチャのライフサイクル、自動化、復旧、直接クエリ
REST	公開済みのルートマニフェストを使用した、ローカルの読み取り専用連携

3つのインターフェースはすべて、同じ SQLite 証拠グラフを読み取ります。インポートはトランザクション処理され、冪等です。アドレスは、符号なし64ビット値を含め、正規の16進文字列として保持されます。

雰囲気ではなく、証拠

• ビルド — 正確なアーティファクト ID と分析の来歴。
• エンティティ — 関数、型、クラス、フィールド、vtable、ランタイムオブジェクト、またはプロジェクト定義オブジェクト。
• エッジ — 呼び出し、参照、所有権、継承、データフロー、またはランタイムの関係。
• 証拠 — ソース、時刻、分類、信頼度を伴う観測結果。
• 主張 — 裏付けとなる証拠または反証する証拠に関連付けられた解釈。
• キャプチャ — アーティファクト、マーカー、イベント、チェックサムを含む封印済みのシナリオ。
• ギャップ — 振る舞いを証明するために次に必要となる、未取得の事実。

矛盾する主張も表示されたままです。不明な振る舞いは、捏造された回答ではなく、作業リストになります。

デフォルトでプライベート

raw private material  →  normalized project evidence  →  synthetic public fixtures

• デーモンは localhost にバインドし、ループバック専用ダッシュボードを含む GET 専用クエリを提供します。
• ローカル以外へのバインドには API トークンが必要であり、さらに信頼できる TLS トランスポートも必要です。
• 実行可能バイトとデコンパイラーのテキストは、デフォルトではエクスポートされません。
• キャプチャの正規化では、一般的なシークレットフィールドやペイロードフィールドを再帰的に削除します。
• 公開リリース監査では、認証情報、キャプチャ、ダンプ、プロプライエタリなバイナリ形式、大きな埋め込みペイロード、個人のパスをブロックします。

機密性の高い作業をインポートする前に、プライバシーとセキュリティをお読みください。

ドキュメント

まず読むページ	解説する内容
はじめに	ローカルの一連の処理全体を検証できますか？
HexWitness を使う理由	メモ、ビューアー MCP、汎用メモリだけではだめなのはなぜですか？
AI セットアップウィザード	エージェントごとに何がインストールされますか？
AI ファーストのワークフロー	エージェントに何を尋ねればよいですか？
機能マトリックス	何が完了済みで、何が環境により異なり、何が意図的に対象外ですか？
品質契約	どの主張が機械的に検証されますか？
安定性ポリシー	1.x 全体を通じて何が互換性を保ちますか？
互換性	どのランタイムとビューアー境界がサポートされていますか？
リリース準備状況	1.0 の主張には何が含まれますか？
CLI、REST、MCP	どのインターフェースを利用できますか？
アーキテクチャ	各要素はどのように連携しますか？
トラブルシューティング	何が失敗し、それをどのように検証できますか？

プロジェクトの状況

HexWitness 1.0 は、安定版として一般公開された開発者向けリリースです。自動ゲートでは、スキーマの移行、インポーター、証拠グラフ、クエリエンジン、キャプチャのライフサイクル、統合 CLI、バンドル配布、読み取り専用デーモン、並行クエリの動作、MCP サーバー、セットアップウィザード、エージェントに特化したスキル、プライバシー監査、パッケージング、インストール済み環境でのアップグレード、CLI → DB → デーモン → MCP の一連の流れを検証します。正確な信頼境界については、リリース準備状況に記載しています。

商用ビューアー API の仕様は、エディションやリリースによって異なります。HexWitness は、普遍的な互換性を主張するのではなく、その境界を明示しています。正確なテスト対象については、品質をご覧ください。

コントリビューション

焦点の絞られた課題報告とプルリクエストを歓迎します。コントリビューションガイドをお読みください。再配布できないプロプライエタリなバイナリ、ベンダーのデータベース、認証情報、キャプチャは添付しないでください。

Apache-2.0。解析対象のバイナリ、インポートされた証拠、ベンダー SDK、RE データベースには、それぞれ独自の利用条件が適用されます。

SiagiNW が開発・保守しています。
すべてのバイトに証言させましょう。