IDA-CLI

面向 AI 的 IDA Pro / Hex-Rays JSONL 内核

让你的 AI Agent 以无限制、持久化、低延迟的方式直接操控真实 IDA 数据库 — 无需 GUI，无需 MCP，无需中间层。

[!IMPORTANT] 本项目专为 AI Agent 设计。强烈建议让你的 Agent（Kimi Code / Codex）自行完成安装和配置，而非手动操作。 👉 AI 安装指南

English

为什么选择 IDA-CLI？

现有的 IDA 集成方案通过 MCP 或 REST 暴露一组固定的工具，AI 只能在别人定义好的抽象边界内工作。IDA-CLI 采用完全不同的思路：直接把一个原始 Python 内核交给 Agent，通过 stdin/stdout JSONL 协议连接到活跃的 IDA 数据库。

核心特性

无限制 Python 内核

Agent 发送任意 IDAPython 代码，获得结构化 JSONL 响应。没有预定义的工具边界 — IDA 能做的，Agent 都能做。

AI 辅助层 (ai.*)

40+ 个专为 AI 工作流设计的高层辅助函数，全部返回干净的 JSON：

ai.decompile("main")          # Hex-Rays 伪代码
ai.functions()                 # 所有函数记录
ai.xrefs_to("printf")         # 交叉引用
ai.cfg("vulnerable_func")     # 控制流图
ai.pwn_overview()              # CTF/Pwn 一键分诊
ai.inventory_summary()         # 二进制快速概览
ai.rename(0x401000, "win")     # 数据库变更
ai.focus(["main", "vuln"])     # 多目标证据包

持久缓存与 Artifact

• 内置索引缓存（IDACache），同一会话内避免重复 IDA 查询
• 大结果自动写入 artifact 文件，不会撑爆协议响应
• 缓存跨请求存活 — save_cache() / load_cache() 支持跨会话复用

并行分析

在数据库副本上启动多个隔离的 IDA 内核进行并行分析。真正的进程级隔离，而非在单个 IDA 实例内做不安全的线程并发。

数据库变更

一等公民支持 rename、set_comment、apply_type、patch_bytes、save_database — 提供 propose/apply 分离机制和确定性冲突合并，适配多分支工作流。

Agent Bridge

一行代码接入任意 Agent 框架：

from ida_cli.agent_bridge import AgentSession

with AgentSession.start("target.i64", require_ida=True) as ida:
    overview = ida.result("__result__ = ai.pwn_overview()")
    pseudocode = ida.result("__result__ = ai.decompile('main')")

多 Agent Skill 分发

内置 Kimi Code、Codex、OpenAI Agents 的 skill 文件 — 一条 install_skill.py 命令，Agent 即刻学会驱动 IDA。

快速开始

1. 前置条件

# 激活 idalib（在你的 IDA Pro 安装目录下）
python -m pip install idapro
python py-activate-idalib.py

2. 安装

python -m pip install -e .

3. 安装 Agent Skill

# 安装所有 Agent 风格
python scripts/install_skill.py all --force

# 或者只装一个
python scripts/install_skill.py kimi --force
python scripts/install_skill.py codex --force

4. 验证

python -B -m unittest discover -s tests -v
python -B -m compileall -q src tests benches examples scripts

5. 运行

# 启动内核
ida-ai path/to/target.i64

# 通过 stdin 发送 JSONL 请求
{"id":"probe","code":"__result__ = __backend__"}
{"id":"funcs","code":"__result__ = ai.inventory_summary()"}

Daemon 模式（跨会话常驻内核）

默认每次 ida-ai <target> 都启动一个新内核。Daemon 模式让同一个 IDA 内核跨会话常驻，客户端通过 TCP 连接/断开，数据库、全局变量和缓存全部复用 — 不必为每个会话重复支付 IDA 自动分析和缓存重建的开销。

# 启动（或复用）某个目标的 daemon
ida-ai --daemon path/to/target.i64

# 停止该目标的 daemon
ida-ai --shutdown path/to/target.i64

Python 侧由 AgentSession 自动处理：

from ida_cli.agent_bridge import AgentSession

# 没有 daemon 则启动一个，已有则直接复用
with AgentSession.start("target.i64", daemon=True, require_ida=True) as ida:
    ...

# 挂载到已在运行的 daemon
with AgentSession.connect("target.i64") as ida:
    ...

安全模型：

• 默认只绑定 127.0.0.1（loopback）。设置 IDA_CLI_DAEMON_HOST=0.0.0.0 才会绑定所有网卡（部分 WSL↔Windows 互联场景需要），启动时会打印警告。
• 每个 daemon 启动时生成随机认证 token，与 pid/port 文件一起写入 daemon 目录（~/.ida-cli/daemons/，WSL 下为 /tmp/.ida-cli/daemons，可用 IDA_CLI_DAEMON_DIR 覆盖），文件权限为仅属主可读写。
• 客户端连接后必须先通过 token 认证才会处理请求；AgentSession / DaemonClient 会自动完成认证。

架构

┌──────────────┐     stdin (JSONL)      ┌──────────────────┐
│   AI Agent   │ ──────────────────────▶ │                  │
│              │                         │   ida-ai kernel  │
│  Kimi Code   │ ◀────────────────────── │                  │
│  Codex       │     stdout (JSONL)      │  ┌────────────┐  │
│  OpenAI      │                         │  │  IDAPython  │  │
└──────────────┘                         │  │  + idalib   │  │
                                         │  └────────────┘  │
       ┌─────────────────────────────────┤                  │
       │          AgentSession           │  ┌────────────┐  │
       │    (Python Bridge 替代方案)     │  │  ai.*       │  │
       └─────────────────────────────────┤  │  helpers    │  │
                                         │  └────────────┘  │
                                         │                  │
                                         │  ┌────────────┐  │
                                         │  │  IDACache   │  │
                                         │  │  Artifacts  │  │
                                         │  │  Mutations  │  │
                                         │  └────────────┘  │
                                         └──────────────────┘

IDA-CLI vs IDA MCP

IDA-CLI 不是 MCP server。根据你的 Agent 能力选择：

环境要求

项目结构

src/ida_cli/
├── __init__.py          # 包标识
├── __main__.py          # 入口（ida-ai CLI）
├── kernel.py            # JSONL 内核循环
├── runtime.py           # Python 执行运行时
├── protocol.py          # JSONL 编解码
├── ai_helpers.py        # 40+ AI 辅助函数
├── agent_bridge.py      # AgentSession 外部 Agent 桥接
├── daemon.py            # 跨会话常驻内核守护进程（TCP）
├── cache.py             # 持久索引缓存
├── mutations.py         # 数据库变更辅助
├── conflicts.py         # 确定性冲突合并
├── artifacts.py         # 大结果文件写入
├── parallel_runner.py   # 多内核并行执行
├── supervisor.py        # 工作扇出规划
├── worker_pool.py       # 隔离 Worker 管理
└── wsl.py               # WSL 路径转换与 Python 探测

文档

License

MIT