ida-agent-bridge
Use when writing ida-domain scripts, querying .i64 databases, or analyzing binaries. Provides short-connection REPL commands (disasm, xrefs, hexdump, pseudocode, rename) and arbitrary Python script execution piped via nc, with real-time file sync on rename/comment/patch.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/tsingshui--ida-agent-bridge)HTML
<a href="/listings/tsingshui--ida-agent-bridge"><img src="/api/listings/tsingshui--ida-agent-bridge/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**环境要求:** IDA Pro 9.1+、Python 3.13+、[uv](https://docs.astral.sh/uv/)
# 1. 设置 IDA 路径 # macOS 示例: export IDADIR="/Applications/IDA Professional 9.3.app/Contents/MacOS" # 2. 安装 git clone https://github.com/TsingShui/ida-agent-bridge.git ~/.claude/skills/ida-agent-bridge uv tool install -e ~/.claude/skills/ida-agent-bridge
两行完事。
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 257 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: ida-agent-bridge
- description: Use when writing ida-domain scripts, querying .i64 databases, or analyzing binaries. Provides short-connection REPL commands (disasm, xrefs, hexdump, pseudocode, rename) and arbitrary Python script execution piped via nc, with real-time file sync on rename/comment/patch.
- ---
- # IDA Domain API Reference
- ## 启动 ida-bridge
- **首先执行 ps 确认现有进程:**
- ```bash
- ps -ef | grep ida-bridge | grep -v grep
- ```
- **根据结果判断:**
- - **有进程** → 从命令行参数里直接读取文件路径和端口号,跳到步骤 2
- - **无进程** → 询问用户:
- > 没有发现正在运行的 ida-bridge。请告诉我:
- > 1. 要分析的文件路径(`.i64` / `.so`)
- > 2. 需要我帮你启动吗?
- **用户确认启动后:**
- ```bash
- ida-bridge /path/to/file.i64 <port> --skip-export &
- ```
- - 端口默认 13120,如有冲突自选其他端口
- - **默认加 `--skip-export`**,不做全量导出(速度更快)
- - 如果任务明确需要导出(批量分析、读 function_index.tsv 等),先问用户:
- > 这个任务可能需要导出函数索引,是否启用导出?(首次较慢)
- 启动后用 `!ping` 确认就绪。
- > **Agent 只使用短连接模式。** `--human-shell` 是给人用的交互模式,Agent 不应使用。
- ---
- ## 工作流
- **优先级:REPL 指令 → Python 脚本 → 原生 ida_* 模块**
- ```
- REPL 快捷指令(echo '!cmd' | nc localhost PORT)
- ↓ 指令无法满足(批量操作/复杂逻辑)
- Python 脚本(cat script.py | nc localhost PORT)
- ↓ ida-domain 没有封装
- 原生 ida_* 模块(直接在脚本中调用)
- ```
- ---
- ## 快捷指令
- 不需要写 Python,直接发单行命令。**这是最快的操作方式。**
- 地址和函数名均可互换(`0x...` 十六进制地址或符号名)。
- ### 探索与查询
- ```bash
- echo '!afl' | nc localhost <port> # 列出所有函数
- echo '!afl jni' | nc localhost <port> # 搜含 jni 的函数名
- echo '!afi main' | nc localhost <port> # 函数详情
- echo '!iz ssl' | nc localhost <port> # 搜含 ssl 的字符串
- echo '!axi malloc' | nc localhost <port> # 导入符号的所有调用点
- ```
- 输出格式:
- ```
- # !afl — TAB 分隔: 地址 名称 大小(hex) callers=N
- 0x11f0 _ossl_fnv1a_hash 0x38 callers=0
- 0x1228 _ossl_ctype_check 0x28 callers=2
- # !afi — 键值对
- name: _ossl_fnv1a_hash
- addr: 0x11f0 - 0x1228
- size: 0x38 (56)
- callers: 0
- callees: 0
- # !iz — 地址 内容 refs=N [引用函数]
- 0x810ee ossltest refs=1 [_alpn_select_cb]
- # !axi — 地址 引用类型 [所在函数]
- 0x12f0 CALL_NEAR [in: _SSL_read]
- ```
- ### 交叉引用
- ```bash
- echo '!axt 0x1234' | nc localhost <port> # xrefs to 地址
- echo '!axf main' | nc localhost <port> # xrefs from 函数名
- ```
- 输出格式:
- ```
- # !axt / !axf — 地址 引用类型 [所在函数]
- 0x2f020 CALL_NEAR [in: _ossl_qlog_set_filter]
- 0x2f064 CALL_NEAR [in: _ossl_qlog_set_filter]
- ```
- ### 反汇编与伪代码
- ```bash
- echo '!pd 0x1234' | nc localhost <port> # 从地址反汇编 16 条(默认)
- echo '!pd 0x1234 32' | nc localhost <port> # 反汇编 32 条
- echo '!pdf main' | nc localhost <port> # 整函数反汇编(带 CFG block 标注)
- echo '!pdc 0x1234' | nc localhost <port> # 伪代码
- echo '!pdc 0x1234 -s' | nc localhost <port> # 过滤变量声明(大函数用)
- echo '!mc main' | nc localhost <port> # 微码(默认 generated)
- echo '!mc main lvars' | nc localhost <port> # 微码 maturity: generated/preopt/locopt/calls/glbopt1/glbopt2/glbopt3/lvars
- echo '!deps main' | nc localhost <port> # 递归调用链(默认深度 3)
- echo '!deps main 5' | nc localhost <port> # 调用链深度 5
- ```
- 输出格式:
- ```
- # !pd — 地址 指令助记符 操作数
- 0x11f0 MOV X8, X0
- 0x11f4 MOV X0, #0xCBF29CE484222325
- # !pdf — 带 CFG block 标注的反汇编
- ; block 0 [0x11f0 - 0x1208]
- 0x11f0 MOV X8, X0
- 0x1204 CBZ X1, locret_1224 ; true→ 0x1224 false→ 0x1208
- ; block 1 [0x1208 - 0x1210]
- 0x1208 MOV X9, #0x100000001B3 ; → 0x1210
- # !pdc — C 伪代码,首行注释标注函数名和地址
- ; _ossl_fnv1a_hash @ 0x11f0
- __int64 __fastcall ossl_fnv1a_hash(unsigned __int8 *a1, __int64 a2)
- {
- ...
- }
- # !deps — 缩进树形调用链
- _ossl_isdigit [0x1250]
- _ossl_ctype_check [0x1228]
- ```
- ### 修改与注释
- ```bash
- echo '!afn 0x1234 sign_request' | nc localhost <port> # 重命名函数(自动同步导出,caller 级联刷新)
- echo '!cc main entry point' | nc localhost <port> # 设置函数级注释(Function Comment)
- echo '!ca 0x1234 key check here' | nc localhost <port> # 设置地址级注释(Address Comment)
- ```
- ### 工具
- ```bash
- echo '!sb 01 14 40 f9' | nc localhost <port> # 搜索字节序列(全局)
- echo '!sb 01 14 40 f9 0x1000 0x5000' | nc localhost <port> # 限定地址范围搜索
- echo '!hd 0x1234' | nc localhost <port> # hexdump 64 字节(默认)
- echo '!hd 0x1234 128' | nc localhost <port> # hexdump 128 字节
- echo '!hd func_name' | nc localhost <port> # 符号名同样支持
- echo '!ping' | nc localhost <port> # 探活,返回打开的文件路径
- echo '!pwd' | nc localhost <port> # 当前工作目录
- echo '!quit' | nc localhost <port> # 关闭服务
- ```
- 输出格式:
- ```
- # !sb — 地址 函数名+偏移 [所在函数]
- 0x2e00 _ssl_ctrl+0x20 [in: _ssl_ctrl]
- 0x3a1f _dtls1_start_timer+0x43 [in: _dtls1_start_timer]
- # !hd — 地址 hex bytes ASCII
- 0x11f0 e8 03 00 aa a0 64 84 d2 40 84 b0 f2 80 9c d3 f2 .....d..@.......
- # !ping — 返回当前打开的文件绝对路径
- /path/to/libssl.dylib
- ```
- ### 与 Bash 工具联动
- REPL 输出是纯文本,可直接接 `grep`、`sort`、`awk`、`jq` 等工具处理,无需额外解析。
- ```bash
- # 找被调用最多的函数
- echo '!afl' | nc localhost <port> | sort -t= -k2 -rn | head -10
- # 找所有大于 0x200 字节的未命名函数
- echo '!afl' | nc localhost <port> | awk -F'\t' '$3 >= 0x200 && $2 ~ /^sub_/'
- # 从伪代码提取所有被调用函数名
- echo '!pdc _wpacket_intern_close' | nc localhost <port> | grep -oP '\b\w+(?=\()' | sort -u
- # 找包含特定字符串的函数(先搜字符串,再查引用)
- ADDR=$(echo '!iz encrypt' | nc localhost <port> | awk 'NR==1{print $1}')
- echo "!axt $ADDR" | nc localhost <port>
- # 批量对所有 JNI 函数生成伪代码并保存
- echo '!afl jni' | nc localhost <port> | awk '{print $1}' | while read addr; do
- echo "!pdc $addr" | nc localhost <port> > "/tmp/pdc_${addr}.c"
- done
- ```
- ---
- ## Python 脚本
- 指令不够用时才写脚本。`db` 已预注入,无需 import。
- 导出目录结构(启动时指定的 `<export_dir>`,默认 `./ida-bridge-<文件名>/`):
- ```
- <export_dir>/
- ├── decompile/ <name>.c — 每个函数的 Hex-Rays 伪代码
- ├── strings.tsv addr\tencoding\tcontents
- ├── imports.tsv addr\tmodule\tname
- ├── exports.tsv addr\tname
- ├── function_index.tsv addr\tname\tlogic_lines\tbranch_density\tcall_density\tstring_density\topaque_density\ttotal_insns\tbitop_density\txor_density\tcaller_count\tfile\tcallers\tcallees
- ├── hash_index.json 函数地址→CRC32 hash,增量导出用
- └── export_config.json 导出配置(compute_metrics 等)
- ```
- ```bash
- cat my_script.py | nc localhost <port>
- ```
- 典型脚本模式:
- ```python
- # 批量重命名(hooks 自动同步导出)
- for func in db.functions.get_all():
- name = db.functions.get_name(func)
- if name.startswith("sub_") and func.end_ea - func.start_ea > 0x200:
- print(hex(func.start_ea), name)
- db.names.set_name(0x12AB, 'sign_request')
- ```
- ---
- ## API 文档规则
- **写脚本前必须先读对应 API 文档:**
- 1. **`${CLAUDE_SKILL_DIR}/reference/ida-domain.md`** — 日常必用 API(函数、名称、字节、xrefs、指令、字符串、导入、类型、伪代码基础、微码基础)。覆盖 ~90% 场景。
- 2. **`${CLAUDE_SKILL_DIR}/reference/ida-domain-advanced.md`** — Pseudocode CTree 深层操作和 Microcode 修改/分析的高级 API。
- **不确定 API 用法时,先 Read 文档,不要在 REPL 里试探。**
- `ida-domain` 做不到的降级到原生 `ida_*` 模块。`ida-domain` 对象可直接传给原生 SDK 函数。
- | Avoid | Do Instead |
- |-------|------------|
- | `idc.*` functions | Use `ida_*` modules |
- | Hardcoded addresses | Use names, patterns, or xrefs |
README.md · README · 224 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # ida-agent-bridge
- [English](README.en.md)
- **让 AI 像读源码一样读二进制。**
- ida-agent-bridge 是一个无头的 IDA Pro 桥,把 IDA 的全部能力——反编译、交叉引用、类型系统、字节级操作——暴露为纯文本短连接协议。反编译结果实时同步到本地文件系统;重命名、注释、patch 字节——改动瞬间落盘,调用方级联刷新。
- 一条管道,从二进制到答案。
- ## 30 秒体验
- ```
- $ ida-bridge a.out &
- INFO sync done in 47.2s
- $ cc "分析 a.out 里的 JNI 函数,找出签名逻辑"
- ```
- Agent 自动开始工作:
- ```
- > 读 ida-bridge-a.out/function_index.tsv,搜 jni...
- 找到 3 个函数:jni_sign_data (0x401320)、jni_verify_sig (0x4014d8)、JNI_OnLoad (0x4012a0)
- > echo '!pdc 0x401320' | nc localhost 13120
- void *jni_sign_data(JNIEnv *env, jobject thiz, jbyteArray data) {
- v3 = HMAC_CTX_new();
- HMAC_Init_ex(v3, &g_secret_key, 32, EVP_sha256(), 0);
- ...
- }
- > echo '!axt 0x401320' | nc localhost 13120
- 0x4012a0 CALL_NEAR [in: JNI_OnLoad]
- > echo '!afn 0x401320 Java_com_example_Crypto_sign' | nc localhost 13120
- renamed: jni_sign_data → Java_com_example_Crypto_sign
- > 读 ida-bridge-a.out/decompile/401320.c ← 确认同步
- ; Java_com_example_Crypto_sign @ 0x401320 ✓
- 结论:签名使用 HMAC-SHA256,密钥硬编码在 g_secret_key (0x60A0B0),长度 32 字节。
- ```
- **这就是它的全部理念:** Agent 读文件系统发现函数,发一行命令获取伪代码,再发一行命令追踪引用——如同人类逆向工程师在 IDA 里的操作流程,只是每一步都是可以管道化的纯文本。
- ---
- ## 安装
- **环境要求:** IDA Pro 9.1+、Python 3.13+、[uv](https://docs.astral.sh/uv/)
- ```bash
- # 1. 设置 IDA 路径
- # macOS 示例:
- export IDADIR="/Applications/IDA Professional 9.3.app/Contents/MacOS"
- # 2. 安装
- git clone https://github.com/TsingShui/ida-agent-bridge.git ~/.claude/skills/ida-agent-bridge
- uv tool install -e ~/.claude/skills/ida-agent-bridge
- ```
- 两行完事。
- ## 使用
- ```bash
- ida-bridge a.out # 启动,导出到 ./ida-bridge-a.out/
- ida-bridge a.out --human-shell # 另开交互 shell(端口 13121)
- ida-bridge a.out --skip-export # 跳过导出,仅启动 REPL
- ```
- 首次启动做一次全量导出(IDA 自动分析 + 反编译所有函数)。之后每次启动对比 CRC32 hash,只增量导出变更函数,秒级完成。
- ---
- ## 设计理念
- ### 文件系统即 API
- 启动后,二进制的全部结构被映射为本地文件——Agent 无需任何 SDK,`cat` 一个文件就能读到伪代码:
- ```
- ida-bridge-a.out/
- ├── decompile/ 每个函数一个 .c 文件(伪代码 + 元数据)
- ├── function_index.tsv 全量函数索引(地址、名称、复杂度指标、调用图)
- ├── strings.tsv 字符串表
- ├── imports.tsv 导入表
- ├── exports.tsv 导出表
- ├── hash_index.json CRC32 增量检测
- └── export_config.json 导出配置
- ```
- ### 实时同步
- 通过 REPL 重命名函数、修改注释、patch 字节——对应的 `.c` 文件和索引瞬间更新,调用方级联刷新:
- | 操作 | 更新范围 |
- |------|----------|
- | 重命名函数/符号 | 该函数 + 所有 caller |
- | 修改注释 | 该函数 |
- | 重命名栈帧变量 | 该函数 |
- | 修改类型信息 | 该函数 |
- | patch 字节(代码段) | 该函数 |
- | patch 字节(数据段) | strings.tsv |
- | 删除函数 | 删除 .c 文件 + 更新索引 |
- ### Unix 哲学:一切皆文本
- 每条命令输出纯文本到 stdout。不需要 JSON 解析器,不需要 SDK——`grep`、`awk`、`sort` 就是你的工具箱:
- ```bash
- # 找被调用最多的前 10 个函数
- echo '!afl' | nc localhost 13120 | sort -t= -k2 -rn | head -10
- # 所有大于 0x200 字节的未命名函数
- echo '!afl' | nc localhost 13120 | awk -F'\t' '$3 >= 0x200 && $2 ~ /^sub_/'
- # 从伪代码提取所有被调用函数名
- echo '!pdc main' | nc localhost 13120 | grep -oP '\b\w+(?=\()' | sort -u
- # 批量搜索引用加密相关字符串的函数
- ADDR=$(echo '!iz encrypt' | nc localhost 13120 | awk 'NR==1{print $1}')
- echo "!axt $ADDR" | nc localhost 13120
- ```
- ---
- ## 命令速查
- 所有命令通过 `echo '!cmd' | nc localhost 13120` 短连接发送,地址支持十六进制(`0x1388`)或符号名(`main`)。
- **查询**
- ```
- !afl [pat] 函数列表(支持模糊搜索)
- !afi <addr|name> 函数详情
- !iz [pat] 字符串搜索
- !axi <name> 导入符号的调用点
- !axt <addr|name> 交叉引用 to
- !axf <addr|name> 交叉引用 from
- !deps <addr|name> [d=3] 递归调用链
- ```
- **反编译 / 反汇编**
- ```
- !pdc <addr|name> [-s] 伪代码(-s 去掉变量声明)
- !pdf <addr|name> 整函数反汇编(带 CFG 标注)
- !pd <addr|name> [n=16] 从地址反汇编 n 条指令
- !mc <addr|name> [maturity] 微码
- ```
- **修改**
- ```
- !afn <addr|name> <new_name> 重命名函数
- !cc <addr|name> <text> 设函数注释
- !ca <addr> <text> 设地址注释
- ```
- **工具**
- ```
- !hd <addr|name> [n=64] hexdump
- !sb <hex> [start] [end] 搜字节序列
- !syms <path> 导出符号表
- !ping 探活,返回打开的文件路径
- !pwd 工作目录
- !quit 关闭服务
- ```
- ---
- ## Python 脚本
- 命令不够用时发 Python 脚本。`db`([ida-domain](https://github.com/kohnakagawa/ida-domain))已预注入,原生 `ida_*` 模块同样可用:
- ```bash
- cat script.py | nc localhost 13120
- ```
- ```python
- # 找大函数 + 高调用量 → 可能是核心逻辑
- for func in db.functions.get_all():
- size = func.end_ea - func.start_ea
- name = db.functions.get_name(func)
- if size > 0x500 and name.startswith("sub_"):
- callers = list(db.functions.get_callers(func))
- print(f"{hex(func.start_ea)} {size:#x} callers={len(callers)} {name}")
- ```
- 脚本中的修改(重命名、注释等)同样自动触发文件系统同步。
- ## 交互 Shell
- 给人用的模式——带命令历史和实时补全:
- ```bash
- ida-bridge a.out --shell
- rlwrap nc localhost 13121
- ```
- ```
- > !afl jni
- 0x4012a0 JNI_OnLoad 0x80 callers=0
- 0x401320 jni_sign_data 0x1b4 callers=1
- 0x4014d8 jni_verify_sig 0xc8 callers=1
- > !deps jni_sign_data 2
- jni_sign_data [0x401320]
- CRYPTO_sign [0x402100]
- EVP_DigestSign [0x403800]
- ...
- > !afn 0x401320 Java_com_example_sign
- renamed 0x401320: jni_sign_data → Java_com_example_sign
- ```
- ---
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.