ida-cli

macOS および Linux 向けのヘッドレス IDA CLI およびスキルファーストのバイナリ解析ツールキット。ida-cli はランタイムバックエンドを自動選択し、必要に応じてローカルサーバーを自動起動し、フラット CLI、stdio MCP トランスポート、Streamable HTTP MCP トランスポートとして同じサーフェスを公開します。

中文说明

2つのユーザー向けエントリーポイント

• ローカル ida-cli バイナリ（1つの実行ファイルにクライアント＋サービスを内包）
• エージェント環境向けのインストール可能な ida-cli スキル（skill/SKILL.md）

基盤となるワーカー／ルーターサービス層は、CLI によって自動的に起動・終了されます。実際に長時間稼働する外部から到達可能なサービスが必要な場合にのみ、serve / serve-http を明示的に実行する必要があります。

サポートマトリクス

ホストプラットフォーム

• サポート対象: macOS、Linux
• 非サポート: Windows

IDA ランタイムポリシー

バックエンドの選択は、実行時に probe-runtime によって行われます。ビルドには依然として IDA SDK が必要です。ベンダリングされたネイティブレイヤーが SDK にリンクされるためです。実行時には、CLI が IDADIR または正規化された一般的なインストールパスから IDA 自体を起動します。

現在の機能

サポート対象の IDA 9.x ランタイムで、ida-cli は以下が可能です：

• 生の PE / ELF / Mach-O バイナリを開き、キャッシュされた .i64 データベースを再利用
• 関数の一覧表示と解決、アドレスまたは名前による逆アセンブル、Hex-Rays による逆コンパイル
• セグメント、文字列、インポート、エクスポート、エントリーポイント、グローバルシンボルの照会
• アドレス ↔ セグメント／関数／シンボルのコンテキストを解決
• バイト／文字列／整数の読み取り、read_* および convert_number ヘルパーの適用
• アドレスへの／からの xref の照会（文字列や構造体フィールドへの xref を含む）
• コールグラフ、基本ブロック、制御フローパスの構築
• テキスト、即値、バイト、命令、オペランド、擬似コードの検索
• 型の宣言／適用、シンボルとローカルの名前変更、コメントの設定
• run_script による IDAPython スニペットの実行

未対応事項: 一部の書き込み中心の操作や高度な型編集操作は、idat-compat ではまだ部分的です。生成されたツール一覧については docs/TOOLS.md を参照してください。

クイックスタート

推奨: スキルのインストール

デフォルトのエントリーポイントは ida-cli スキルであり、手動での CLI インストールではありません。

# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list

# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global

インストール後、スキルには独自のブートストラップラッパーが同梱されます：

~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20

ida-cli が見つからない場合、ラッパーはコマンドを転送する前にリポジトリのインストーラーを通じてインストールします。

CLI の直接インストール（任意）

これは、スキルを経由せずにスタンドアロン CLI が必要な場合にのみ使用してください。

curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path

便利なバリエーション：

# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path

# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path

注意事項：

• インストーラーはデフォルトでランチャーを ~/.local/bin/ida-cli に配置します。
• --add-path は、その bin ディレクトリをシェルの rc ファイルに追加します。
• IDASDKDIR と IDALIB_SDK のどちらも設定されておらず、ローカルビルドが必要な場合、インストーラーはオープンソースの HexRaysSA/ida-sdk を自動的にクローンします。
• 複数の IDA インストールが存在する場合は、ida-cli をインストールまたは実行する前に IDADIR を明示的にエクスポートしてください。

ソースからのビルド

git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help

CLI の使用

ida-cli はクライアントファーストです。任意のクライアントサブコマンドは、ランダムポートにバインドされたローカルの Streamable-HTTP サーバーを自動起動し、検出用に /tmp/ida-cli.socket を書き込みます：

./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'

最初の引数がサービスサブコマンド（serve、serve-http、serve-worker、probe-runtime）であるコマンドは、代わりにサービスモードに入ります：

./target/debug/ida-cli serve                          # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime

バックエンドプローブ出力の例：

{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}

{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}

完全な CLI サーフェスについては skill/references/cli-tool-reference.md を参照してください。

ビルド要件

• Rust 1.87+
• LLVM / Clang
• macOS または Linux ホスト
• IDADIR による IDA インストール（ランタイムサポートは IDA 9.0 以降）
• IDASDKDIR または IDALIB_SDK による IDA SDK

SDK パスは次のいずれかのレイアウトを指すことができます：

• /path/to/ida-sdk
• /path/to/ida-sdk/src

ランタイムに関する注意事項

idat-compat

IDA 9.0〜9.2 互換バックエンド。idat にシェルアウトし、短い IDAPython スクリプトを実行して、構造化された JSON を CLI ランタイムに返します。

native-linked

IDA 9.3+ バックエンド。ベンダリングされた idalib 系統にリンクし、データベースをインプロセスで開きます。

キャッシュとローカルランタイムパス

• データベースキャッシュ: ~/.ida/idb/
• ログ: ~/.ida/logs/server.log
• サーバー Unix ソケット: ~/.ida/server.sock
• サーバー PID ファイル: ~/.ida/server.pid
• CLI 検出ファイル（フラット CLI を稼働中のソケットにマッピング）: /tmp/ida-cli.socket
• 大きな JSON レスポンスのキャッシュ: /tmp/ida-cli-out/

CI とリリース

GitHub Actions は、ホスト型ランナー上でオープンソースの HexRaysSA/ida-sdk に対してツリーをコンパイルおよびテストするため、CI はプライベートなマシン構成に依存しません。

現在のワークフロー動作：

• master へのプッシュとプルリクエストは検証を実行
• v0.9.3 のようなタグ付きプッシュは、Linux と macOS 向けのリリースアーカイブをビルド
• リリースには install.sh とプラットフォーム別アーカイブが添付

リリースバイナリは SDK スタブに対してビルドされます。インストール時に、install.sh によって生成されたランチャーは、ida-cli を呼び出す前に IDADIR または正規化された一般的なインストールパスのセットを通じてローカルの IDA ランタイムを解決します。

ドキュメント

• docs/BUILDING.md — ソースからのビルド
• docs/ARCHITECTURE.md — ルーター、バックエンド、フェデレーション
• docs/TRANSPORTS.md — stdio、Streamable HTTP、マルチ IDB
• docs/TOOLS.md — 生成されたツールカタログ
• docs/TESTING.md — 統合テストとユニットテスト
• skill/SKILL.md — スキルのブートストラップと利用ポリシー
• skill/references/cli-tool-reference.md — 完全な CLI サーフェス

ライセンス

MIT