http8080/headless-ida
GitHub: http8080/headless-ida
基于 IDA Pro 官方 headless 库的 CLI 二进制分析系统，让 AI 助手无需 GUI 即可通过 shell 命令执行反编译、反汇编和各类逆向分析任务。
Stars: 0 | Forks: 0
# Headless IDA
[한국어](#한국어) | [English](#english)
## 简体中文
一个基于 CLI 的二进制分析系统，由 **idalib**（Hex-Rays 官方 headless 库）驱动，无需 IDA Pro GUI。
AI 助手（Claude Code、Cursor 等）通过 shell 调用 `ida_cli.py` 执行自动化二进制分析 —— **无需 MCP**。
### 架构
```
User/AI → ida_cli.py → HTTP JSON-RPC → ida_server.py (idalib)
```
- **无 MCP 层** — 纯 HTTP JSON-RPC 通信
- **单线程 HTTPServer** — 符合 idalib 的单线程限制
- **.i64 复用** — 重复分析时可在数秒内重新加载
- **Auth tokens** — 每个实例自动生成 Bearer token
### 为什么不用 MCP？
本项目有意使用普通的 HTTP JSON-RPC 而不是 MCP (Model Context Protocol)。
| | HTTP JSON-RPC (本项目) | MCP |
| --- | --- | --- |
| **依赖** | 仅 Python 标准库 (`http.server`) | 需要 MCP SDK + 传输层 |
| **调试** | 可用 `curl` 单行测试 | 需要 MCP 客户端 |
| **AI 兼容性** | 任何具有 shell 访问权限的 AI (Claude Code, Cursor 等) | 仅限 MCP 兼容客户端 |
| **上下文窗口** | 零开销 — 仅 bash 命令 | 工具 schema 加载到 AI 上下文中，消耗 token |
| **脚本自动化** | 可直接从 bash/Python 脚本调用 | 需要 MCP 客户端库 |
| **部署** | 单个 `.py` 文件，零配置 | 需要 server manifest + schema 注册 |
| **idalib 限制** | 单线程 `HTTPServer` 1:1 映射 | MCP 异步模型与单线程限制冲突 |
### 系统要求
| 组件 | 版本 |
| --------- | ------- |
| IDA Pro | 9.1+ (需要 idalib 支持) |
| Python | 3.12 或 3.13 (必须与 IDA 捆绑版本匹配) |
| OS | Windows 10/11 |
### 安装设置
#### Step 1. 安装 idalib Python 包
```
pip install "/idalib/python/idapro-*.whl"
```
`.whl` 文件包含在您的 IDA Pro 安装目录中。
#### Step 2. 注册 IDA 路径（选择其一）
```
# 选项 A：运行激活脚本（推荐）
python "/idalib/python/py-activate-idalib.py"
# 选项 B：设置环境变量
set IDADIR=C:\Program Files\IDA Professional 9.3
```
#### Step 3. 安装依赖
```
pip install requests psutil
```
#### Step 4. 验证并初始化
```
# 检查环境
python tools/ida_cli.py --check
# 创建工作目录
python tools/ida_cli.py --init
```
#### Step 5. 配置（可选）
编辑 `tools/config.json` 以设置 IDA 路径和其他选项：
```
{
"ida": {
"install_dir": "C:/Program Files/IDA Professional 9.3"
},
"paths": {
"idb_dir": "%USERPROFILE%/.ida-headless/idb",
"log_dir": "%USERPROFILE%/.ida-headless/logs"
},
"analysis": {
"max_instances": 3
}
}
```
#### Step 6. 测试运行
```
# 使用任意二进制文件启动实例
python tools/ida_cli.py start ./samples/target.exe
# 检查状态
python tools/ida_cli.py list
# 停止
python tools/ida_cli.py stop
```
如果您看到 `Instance started: id=xxxx` 并且实例出现在 `list` 中，则设置完成。
### AI 集成
环境设置完成后，AI 助手通过 shell 使用 `ida_cli.py` 命令。您不需要记住这些 —— AI 会处理。
#### Claude Code
1. 将 skill 文件复制到您的项目：
```
# 创建技能目录
mkdir -p .claude/commands
# 复制技能文件
cp /tools/ida_cli.py tools/
cp /.claude/commands/ida.md .claude/commands/
```
2. 将 `CLAUDE.md` 复制到您的项目根目录（AI 读取此文件作为命令参考）：
```
cp /CLAUDE.md .
```
3. 在 Claude Code 中使用：
```
/ida ./target.so
```
Claude 将自动启动实例，分析二进制文件，并报告发现。
#### 其他 AI 工具（Cursor、GPT 等）
任何具有 shell/终端 访问权限的 AI 都可以直接调用 `ida_cli.py`。将 `CLAUDE.md` 内容添加到您的 AI 的系统提示或项目上下文中，以便它知道可用的命令。
### 命令参考
命令主要由 AI 使用，此处列出仅供参考。
#### 实例管理
| 命令 | 描述 |
| ------- | ----------- |
| `start ` | 启动分析实例 |
| `stop ` | 停止实例 |
| `wait ` | 等待分析完成 |
| `list` | 列出运行中的实例 |
| `status []` | 显示实例状态 |
| `logs ` | 查看实例日志 |
| `cleanup` | 清理陈旧实例 |
#### 分析（24 个 API）
| 命令 | 描述 |
| ------- | ----------- |
| `functions` | 列出函数 |
| `strings` | 列出字符串 |
| `imports` / `exports` | 列出导入/导出 |
| `segments` | 列出段 |
| `decompile ` | 反编译函数 |
| `disasm ` | 反汇编 |
| `xrefs ` | 交叉引用 |
| `find_func ` | 搜索函数 |
| `func_info ` | 函数详情 |
| `bytes ` | 读取原始字节 |
| `find_pattern ` | 字节模式搜索 |
#### 修改
| 命令 | 描述 |
| ------- | ----------- |
| `rename ` | 重命名符号 |
| `comment "text"` | 添加注释 |
| `save` | 保存数据库 |
#### 常用选项
| 选项 | 描述 |
| ------ | ----------- |
| `--json` | JSON 输出 |
| `-i ` | 指定实例 ID |
| `-b ` | 按二进制名称自动选择 |
| `--out FILE` | 将输出保存到文件 |
### 支持的格式
PE, ELF, Mach-O, FAT, .so, dylib, Raw binary, Intel HEX, SREC
反编译器: x86/x64, ARM/ARM64, MIPS, PowerPC, RISC-V
### 许可证
**Apache License 2.0** — 参见 [LICENSE](LICENSE)。
需要单独有效的 **IDA Pro 许可证**。Hex-Rays 反编译器许可证可选。
## 韩语
IDA Pro GUI 없이 **idalib** (Hex-Rays 공식 헤드리스 라이브러리)을 사용하여 CLI에서 바이너리 분석을 수행하는 시스템.
AI 어시스턴트(Claude Code, Cursor 등)가 shell로 `ida_cli.py`를 호출하여 자동 바이너리 분석 — **MCP 불필요**.
### 架构
```
User/AI → ida_cli.py → HTTP JSON-RPC → ida_server.py (idalib)
```
- **MCP 레이어 없음** — 순수 HTTP JSON-RPC 통신
- **단일 스레드 HTTPServer** — idalib 단일 스레드 제약 준수
- **.i64 재사용** — 반복 분석 시 수 초 만에 로드
- **인증 토큰** — 인스턴스별 Bearer token 자동 생성
### 为什么不使用 MCP？
이 프로젝트는 MCP(Model Context Protocol) 대신 순수 HTTP JSON-RPC를 의도적으로 사용합니다.
| | HTTP JSON-RPC (이 프로젝트) | MCP |
| --- | --- | --- |
| **의존성** | Python 표준 라이브러리만 (`http.server`) | MCP SDK + transport 레이어 필요 |
| **디버깅** | `curl` 한 줄로 테스트 가능 | MCP 지원 클라이언트 필요 |
| **AI 호환성** | shell 접근 가능한 모든 AI (Claude Code, Cursor 등) | MCP 호환 클라이언트에만 종속 |
| **컨텍스트 윈도우** | 오버헤드 없음 — bash 명령어만 사용 | tool schema가 AI 컨텍스트에 로드되어 토큰 소모 |
| **스크립트 자동화** | bash/Python에서 바로 호출 가능 | MCP 클라이언트 라이브러리 필요 |
| **배포** | `.py` 파일 하나, 별도 설정 없음 | 서버 manifest + 스키마 등록 필요 |
| **idalib 제약** | 단일 스레드 `HTTPServer`가 1:1 매핑 | MCP async 모델이 단일 스레드 제약과 충돌 |
### 需求
| 항목 | 버전 |
| ---- | ---- |
| IDA Pro | 9.1 이상 (idalib 지원 필수) |
| Python | 3.12 또는 3.13 (IDA 번들 버전과 일치 필수) |
| OS | Windows 10/11 |
### 环境搭建
#### Step 1. 安装 idalib Python 包
```
pip install "/idalib/python/idapro-*.whl"
```
IDA Pro 설치 디렉토리에 `.whl` 파일이 포함되어 있습니다.
#### Step 2. 注册 IDA 路径（任选其一）
```
# 方法 A：运行激活脚本（推荐）
python "/idalib/python/py-activate-idalib.py"
# 方法 B：设置环境变量
set IDADIR=C:\Program Files\IDA Professional 9.3
```
#### Step 3. 安装依赖包
```
pip install requests psutil
```
#### Step 4. 验证及初始化
```
# 验证环境
python tools/ida_cli.py --check
# 创建工作目录
python tools/ida_cli.py --init
```
#### Step 5. 配置（可选）
`tools/config.json`에서 IDA 경로 등 설정:
```
{
"ida": {
"install_dir": "C:/Program Files/IDA Professional 9.3"
},
"paths": {
"idb_dir": "%USERPROFILE%/.ida-headless/idb",
"log_dir": "%USERPROFILE%/.ida-headless/logs"
},
"analysis": {
"max_instances": 3
}
}
```
#### Step 6. 运行测试
```
# 使用任意二进制文件启动实例
python tools/ida_cli.py start ./samples/target.exe
# 检查状态
python tools/ida_cli.py list
# 终止
python tools/ida_cli.py stop
```
`Instance started: id=xxxx`가 출력되고 `list`에 나타나면 환경 구축 완료.
### AI 集成
환경 구축 완료 후, AI 어시스턴트가 shell로 `ida_cli.py` 명령어를 호출합니다. 사용자가 명령어를 외울 필요 없습니다.
#### Claude Code
프로젝트에 스킬 파일을 복사합니다:
```
# 创建技能目录
mkdir -p .claude/commands
# 复制技能文件
cp /tools/ida_cli.py tools/
cp /.claude/commands/ida.md .claude/commands/
```
프로젝트 루트에 `CLAUDE.md` 복사 (AI가 명령어 레퍼런스로 참조):
```
cp /CLAUDE.md .
```
Claude Code에서 사용:
```
/ida ./target.so
```
Claude가 자동으로 인스턴스를 시작하고, 바이너리를 분석하고, 결과를 보고합니다.
#### 其他 AI 工具 (Cursor, GPT 等)
shell/터미널 접근이 가능한 AI면 `ida_cli.py`를 직접 호출할 수 있습니다. `CLAUDE.md` 내용을 AI의 system prompt나 프로젝트 컨텍스트에 추가하면 됩니다.
### 命令参考
명령어는 주로 AI가 사용하며, 참고용으로 정리합니다.
#### 实例管理
| 명령어 | 설명 |
| ------- | ---- |
| `start ` | 분석 인스턴스 시작 |
| `stop ` | 인스턴스 종료 |
| `wait ` | 분석 완료 대기 |
| `list` | 실행 중인 인스턴스 목록 |
| `status []` | 인스턴스 상태 확인 |
| `logs ` | 인스턴스 로그 보기 |
| `cleanup` | 비정상 인스턴스 정리 |
#### 分析 (24 个 API)
| 명령어 | 설명 |
| ------- | ---- |
| `functions` | 함수 목록 |
| `strings` | 문자열 목록 |
| `imports` / `exports` | imports/exports 목록 |
| `segments` | 세그먼트 목록 |
| `decompile ` | 함수 디컴파일 |
| `disasm ` | 디스어셈블 |
| `xrefs ` | 크로스 레퍼런스 |
| `find_func ` | 함수 검색 |
| `func_info ` | 함수 상세 정보 |
| `bytes ` | Raw 바이트 읽기 |
| `find_pattern ` | 바이트 패턴 검색 |
#### 修改
| 명령어 | 설명 |
| ------- | ---- |
| `rename ` | 심볼 이름 변경 |
| `comment "text"` | 주석 추가 |
| `save` | 데이터베이스 저장 |
#### 通用选项
| 옵션 | 설명 |
| ---- | ---- |
| `--json` | JSON 출력 |
| `-i ` | 인스턴스 ID 지정 |
| `-b ` | 바이너리 이름으로 자동 선택 |
| `--out FILE` | 결과를 파일로 저장 |
### 支持的格式
PE, ELF, Mach-O, FAT, .so, dylib, Raw binary, Intel HEX, SREC
디컴파일러: x86/x64, ARM/ARM64, MIPS, PowerPC, RISC-V
### 许可证
**Apache License 2.0** — [LICENSE](LICENSE) 참조.
이 프로젝트를 사용하려면 별도로 유효한 **IDA Pro 라이선스**가 필요합니다. Hex-Rays 디컴파일러 라이선스는 선택 사항.
标签：AI辅助, Amass, API, Claude, Cursor, CVE检测, Findomain, Hakrawler, Headless, idalib, IDA Pro, JSON-RPC, Python, T1053, T1059, T1071, 二进制分析, 二进制安全, 云安全监控, 云安全运维, 云资产清单, 威胁狩猎, 恶意代码分析, 情报收集, 无GUI, 无后门, 服务器, 漏洞研究, 网络安全, 自动化分析, 跨站脚本, 逆向工具, 逆向工程, 配置文件, 隐私保护, 静态分析