Skip to content
Back to search

ida-agent-bridge

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tsingshui--ida-agent-bridge/badge.svg)](/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

i

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)

  1. ---
  2. name: ida-agent-bridge
  3. 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.
  4. ---
  5. # IDA Domain API Reference
  6. ## 启动 ida-bridge
  7. **首先执行 ps 确认现有进程:**
  8. ```bash
  9. ps -ef | grep ida-bridge | grep -v grep
  10. ```
  11. **根据结果判断:**
  12. - **有进程** → 从命令行参数里直接读取文件路径和端口号,跳到步骤 2
  13. - **无进程** → 询问用户:
  14. > 没有发现正在运行的 ida-bridge。请告诉我:
  15. > 1. 要分析的文件路径(`.i64` / `.so`)
  16. > 2. 需要我帮你启动吗?
  17. **用户确认启动后:**
  18. ```bash
  19. ida-bridge /path/to/file.i64 <port> --skip-export &
  20. ```
  21. - 端口默认 13120,如有冲突自选其他端口
  22. - **默认加 `--skip-export`**,不做全量导出(速度更快)
  23. - 如果任务明确需要导出(批量分析、读 function_index.tsv 等),先问用户:
  24. > 这个任务可能需要导出函数索引,是否启用导出?(首次较慢)
  25. 启动后用 `!ping` 确认就绪。
  26. > **Agent 只使用短连接模式。** `--human-shell` 是给人用的交互模式,Agent 不应使用。
  27. ---
  28. ## 工作流
  29. **优先级:REPL 指令 → Python 脚本 → 原生 ida_* 模块**
  30. ```
  31. REPL 快捷指令(echo '!cmd' | nc localhost PORT)
  32. ↓ 指令无法满足(批量操作/复杂逻辑)
  33. Python 脚本(cat script.py | nc localhost PORT)
  34. ↓ ida-domain 没有封装
  35. 原生 ida_* 模块(直接在脚本中调用)
  36. ```
  37. ---
  38. ## 快捷指令
  39. 不需要写 Python,直接发单行命令。**这是最快的操作方式。**
  40. 地址和函数名均可互换(`0x...` 十六进制地址或符号名)。
  41. ### 探索与查询
  42. ```bash
  43. echo '!afl' | nc localhost <port> # 列出所有函数
  44. echo '!afl jni' | nc localhost <port> # 搜含 jni 的函数名
  45. echo '!afi main' | nc localhost <port> # 函数详情
  46. echo '!iz ssl' | nc localhost <port> # 搜含 ssl 的字符串
  47. echo '!axi malloc' | nc localhost <port> # 导入符号的所有调用点
  48. ```
  49. 输出格式:
  50. ```
  51. # !afl — TAB 分隔: 地址 名称 大小(hex) callers=N
  52. 0x11f0 _ossl_fnv1a_hash 0x38 callers=0
  53. 0x1228 _ossl_ctype_check 0x28 callers=2
  54. # !afi — 键值对
  55. name: _ossl_fnv1a_hash
  56. addr: 0x11f0 - 0x1228
  57. size: 0x38 (56)
  58. callers: 0
  59. callees: 0
  60. # !iz — 地址 内容 refs=N [引用函数]
  61. 0x810ee ossltest refs=1 [_alpn_select_cb]
  62. # !axi — 地址 引用类型 [所在函数]
  63. 0x12f0 CALL_NEAR [in: _SSL_read]
  64. ```
  65. ### 交叉引用
  66. ```bash
  67. echo '!axt 0x1234' | nc localhost <port> # xrefs to 地址
  68. echo '!axf main' | nc localhost <port> # xrefs from 函数名
  69. ```
  70. 输出格式:
  71. ```
  72. # !axt / !axf — 地址 引用类型 [所在函数]
  73. 0x2f020 CALL_NEAR [in: _ossl_qlog_set_filter]
  74. 0x2f064 CALL_NEAR [in: _ossl_qlog_set_filter]
  75. ```
  76. ### 反汇编与伪代码
  77. ```bash
  78. echo '!pd 0x1234' | nc localhost <port> # 从地址反汇编 16 条(默认)
  79. echo '!pd 0x1234 32' | nc localhost <port> # 反汇编 32 条
  80. echo '!pdf main' | nc localhost <port> # 整函数反汇编(带 CFG block 标注)
  81. echo '!pdc 0x1234' | nc localhost <port> # 伪代码
  82. echo '!pdc 0x1234 -s' | nc localhost <port> # 过滤变量声明(大函数用)
  83. echo '!mc main' | nc localhost <port> # 微码(默认 generated)
  84. echo '!mc main lvars' | nc localhost <port> # 微码 maturity: generated/preopt/locopt/calls/glbopt1/glbopt2/glbopt3/lvars
  85. echo '!deps main' | nc localhost <port> # 递归调用链(默认深度 3)
  86. echo '!deps main 5' | nc localhost <port> # 调用链深度 5
  87. ```
  88. 输出格式:
  89. ```
  90. # !pd — 地址 指令助记符 操作数
  91. 0x11f0 MOV X8, X0
  92. 0x11f4 MOV X0, #0xCBF29CE484222325
  93. # !pdf — 带 CFG block 标注的反汇编
  94. ; block 0 [0x11f0 - 0x1208]
  95. 0x11f0 MOV X8, X0
  96. 0x1204 CBZ X1, locret_1224 ; true→ 0x1224 false→ 0x1208
  97. ; block 1 [0x1208 - 0x1210]
  98. 0x1208 MOV X9, #0x100000001B3 ; → 0x1210
  99. # !pdc — C 伪代码,首行注释标注函数名和地址
  100. ; _ossl_fnv1a_hash @ 0x11f0
  101. __int64 __fastcall ossl_fnv1a_hash(unsigned __int8 *a1, __int64 a2)
  102. {
  103. ...
  104. }
  105. # !deps — 缩进树形调用链
  106. _ossl_isdigit [0x1250]
  107. _ossl_ctype_check [0x1228]
  108. ```
  109. ### 修改与注释
  110. ```bash
  111. echo '!afn 0x1234 sign_request' | nc localhost <port> # 重命名函数(自动同步导出,caller 级联刷新)
  112. echo '!cc main entry point' | nc localhost <port> # 设置函数级注释(Function Comment)
  113. echo '!ca 0x1234 key check here' | nc localhost <port> # 设置地址级注释(Address Comment)
  114. ```
  115. ### 工具
  116. ```bash
  117. echo '!sb 01 14 40 f9' | nc localhost <port> # 搜索字节序列(全局)
  118. echo '!sb 01 14 40 f9 0x1000 0x5000' | nc localhost <port> # 限定地址范围搜索
  119. echo '!hd 0x1234' | nc localhost <port> # hexdump 64 字节(默认)
  120. echo '!hd 0x1234 128' | nc localhost <port> # hexdump 128 字节
  121. echo '!hd func_name' | nc localhost <port> # 符号名同样支持
  122. echo '!ping' | nc localhost <port> # 探活,返回打开的文件路径
  123. echo '!pwd' | nc localhost <port> # 当前工作目录
  124. echo '!quit' | nc localhost <port> # 关闭服务
  125. ```
  126. 输出格式:
  127. ```
  128. # !sb — 地址 函数名+偏移 [所在函数]
  129. 0x2e00 _ssl_ctrl+0x20 [in: _ssl_ctrl]
  130. 0x3a1f _dtls1_start_timer+0x43 [in: _dtls1_start_timer]
  131. # !hd — 地址 hex bytes ASCII
  132. 0x11f0 e8 03 00 aa a0 64 84 d2 40 84 b0 f2 80 9c d3 f2 .....d..@.......
  133. # !ping — 返回当前打开的文件绝对路径
  134. /path/to/libssl.dylib
  135. ```
  136. ### 与 Bash 工具联动
  137. REPL 输出是纯文本,可直接接 `grep`、`sort`、`awk`、`jq` 等工具处理,无需额外解析。
  138. ```bash
  139. # 找被调用最多的函数
  140. echo '!afl' | nc localhost <port> | sort -t= -k2 -rn | head -10
  141. # 找所有大于 0x200 字节的未命名函数
  142. echo '!afl' | nc localhost <port> | awk -F'\t' '$3 >= 0x200 && $2 ~ /^sub_/'
  143. # 从伪代码提取所有被调用函数名
  144. echo '!pdc _wpacket_intern_close' | nc localhost <port> | grep -oP '\b\w+(?=\()' | sort -u
  145. # 找包含特定字符串的函数(先搜字符串,再查引用)
  146. ADDR=$(echo '!iz encrypt' | nc localhost <port> | awk 'NR==1{print $1}')
  147. echo "!axt $ADDR" | nc localhost <port>
  148. # 批量对所有 JNI 函数生成伪代码并保存
  149. echo '!afl jni' | nc localhost <port> | awk '{print $1}' | while read addr; do
  150. echo "!pdc $addr" | nc localhost <port> > "/tmp/pdc_${addr}.c"
  151. done
  152. ```
  153. ---
  154. ## Python 脚本
  155. 指令不够用时才写脚本。`db` 已预注入,无需 import。
  156. 导出目录结构(启动时指定的 `<export_dir>`,默认 `./ida-bridge-<文件名>/`):
  157. ```
  158. <export_dir>/
  159. ├── decompile/ <name>.c — 每个函数的 Hex-Rays 伪代码
  160. ├── strings.tsv addr\tencoding\tcontents
  161. ├── imports.tsv addr\tmodule\tname
  162. ├── exports.tsv addr\tname
  163. ├── 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
  164. ├── hash_index.json 函数地址→CRC32 hash,增量导出用
  165. └── export_config.json 导出配置(compute_metrics 等)
  166. ```
  167. ```bash
  168. cat my_script.py | nc localhost <port>
  169. ```
  170. 典型脚本模式:
  171. ```python
  172. # 批量重命名(hooks 自动同步导出)
  173. for func in db.functions.get_all():
  174. name = db.functions.get_name(func)
  175. if name.startswith("sub_") and func.end_ea - func.start_ea > 0x200:
  176. print(hex(func.start_ea), name)
  177. db.names.set_name(0x12AB, 'sign_request')
  178. ```
  179. ---
  180. ## API 文档规则
  181. **写脚本前必须先读对应 API 文档:**
  182. 1. **`${CLAUDE_SKILL_DIR}/reference/ida-domain.md`** — 日常必用 API(函数、名称、字节、xrefs、指令、字符串、导入、类型、伪代码基础、微码基础)。覆盖 ~90% 场景。
  183. 2. **`${CLAUDE_SKILL_DIR}/reference/ida-domain-advanced.md`** — Pseudocode CTree 深层操作和 Microcode 修改/分析的高级 API。
  184. **不确定 API 用法时,先 Read 文档,不要在 REPL 里试探。**
  185. `ida-domain` 做不到的降级到原生 `ida_*` 模块。`ida-domain` 对象可直接传给原生 SDK 函数。
  186. | Avoid | Do Instead |
  187. |-------|------------|
  188. | `idc.*` functions | Use `ida_*` modules |
  189. | 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)

  1. # ida-agent-bridge
  2. [English](README.en.md)
  3. **让 AI 像读源码一样读二进制。**
  4. ida-agent-bridge 是一个无头的 IDA Pro 桥,把 IDA 的全部能力——反编译、交叉引用、类型系统、字节级操作——暴露为纯文本短连接协议。反编译结果实时同步到本地文件系统;重命名、注释、patch 字节——改动瞬间落盘,调用方级联刷新。
  5. 一条管道,从二进制到答案。
  6. ## 30 秒体验
  7. ```
  8. $ ida-bridge a.out &
  9. INFO sync done in 47.2s
  10. $ cc "分析 a.out 里的 JNI 函数,找出签名逻辑"
  11. ```
  12. Agent 自动开始工作:
  13. ```
  14. > 读 ida-bridge-a.out/function_index.tsv,搜 jni...
  15. 找到 3 个函数:jni_sign_data (0x401320)、jni_verify_sig (0x4014d8)、JNI_OnLoad (0x4012a0)
  16. > echo '!pdc 0x401320' | nc localhost 13120
  17. void *jni_sign_data(JNIEnv *env, jobject thiz, jbyteArray data) {
  18. v3 = HMAC_CTX_new();
  19. HMAC_Init_ex(v3, &g_secret_key, 32, EVP_sha256(), 0);
  20. ...
  21. }
  22. > echo '!axt 0x401320' | nc localhost 13120
  23. 0x4012a0 CALL_NEAR [in: JNI_OnLoad]
  24. > echo '!afn 0x401320 Java_com_example_Crypto_sign' | nc localhost 13120
  25. renamed: jni_sign_data → Java_com_example_Crypto_sign
  26. > 读 ida-bridge-a.out/decompile/401320.c ← 确认同步
  27. ; Java_com_example_Crypto_sign @ 0x401320 ✓
  28. 结论:签名使用 HMAC-SHA256,密钥硬编码在 g_secret_key (0x60A0B0),长度 32 字节。
  29. ```
  30. **这就是它的全部理念:** Agent 读文件系统发现函数,发一行命令获取伪代码,再发一行命令追踪引用——如同人类逆向工程师在 IDA 里的操作流程,只是每一步都是可以管道化的纯文本。
  31. ---
  32. ## 安装
  33. **环境要求:** IDA Pro 9.1+、Python 3.13+、[uv](https://docs.astral.sh/uv/)
  34. ```bash
  35. # 1. 设置 IDA 路径
  36. # macOS 示例:
  37. export IDADIR="/Applications/IDA Professional 9.3.app/Contents/MacOS"
  38. # 2. 安装
  39. git clone https://github.com/TsingShui/ida-agent-bridge.git ~/.claude/skills/ida-agent-bridge
  40. uv tool install -e ~/.claude/skills/ida-agent-bridge
  41. ```
  42. 两行完事。
  43. ## 使用
  44. ```bash
  45. ida-bridge a.out # 启动,导出到 ./ida-bridge-a.out/
  46. ida-bridge a.out --human-shell # 另开交互 shell(端口 13121)
  47. ida-bridge a.out --skip-export # 跳过导出,仅启动 REPL
  48. ```
  49. 首次启动做一次全量导出(IDA 自动分析 + 反编译所有函数)。之后每次启动对比 CRC32 hash,只增量导出变更函数,秒级完成。
  50. ---
  51. ## 设计理念
  52. ### 文件系统即 API
  53. 启动后,二进制的全部结构被映射为本地文件——Agent 无需任何 SDK,`cat` 一个文件就能读到伪代码:
  54. ```
  55. ida-bridge-a.out/
  56. ├── decompile/ 每个函数一个 .c 文件(伪代码 + 元数据)
  57. ├── function_index.tsv 全量函数索引(地址、名称、复杂度指标、调用图)
  58. ├── strings.tsv 字符串表
  59. ├── imports.tsv 导入表
  60. ├── exports.tsv 导出表
  61. ├── hash_index.json CRC32 增量检测
  62. └── export_config.json 导出配置
  63. ```
  64. ### 实时同步
  65. 通过 REPL 重命名函数、修改注释、patch 字节——对应的 `.c` 文件和索引瞬间更新,调用方级联刷新:
  66. | 操作 | 更新范围 |
  67. |------|----------|
  68. | 重命名函数/符号 | 该函数 + 所有 caller |
  69. | 修改注释 | 该函数 |
  70. | 重命名栈帧变量 | 该函数 |
  71. | 修改类型信息 | 该函数 |
  72. | patch 字节(代码段) | 该函数 |
  73. | patch 字节(数据段) | strings.tsv |
  74. | 删除函数 | 删除 .c 文件 + 更新索引 |
  75. ### Unix 哲学:一切皆文本
  76. 每条命令输出纯文本到 stdout。不需要 JSON 解析器,不需要 SDK——`grep`、`awk`、`sort` 就是你的工具箱:
  77. ```bash
  78. # 找被调用最多的前 10 个函数
  79. echo '!afl' | nc localhost 13120 | sort -t= -k2 -rn | head -10
  80. # 所有大于 0x200 字节的未命名函数
  81. echo '!afl' | nc localhost 13120 | awk -F'\t' '$3 >= 0x200 && $2 ~ /^sub_/'
  82. # 从伪代码提取所有被调用函数名
  83. echo '!pdc main' | nc localhost 13120 | grep -oP '\b\w+(?=\()' | sort -u
  84. # 批量搜索引用加密相关字符串的函数
  85. ADDR=$(echo '!iz encrypt' | nc localhost 13120 | awk 'NR==1{print $1}')
  86. echo "!axt $ADDR" | nc localhost 13120
  87. ```
  88. ---
  89. ## 命令速查
  90. 所有命令通过 `echo '!cmd' | nc localhost 13120` 短连接发送,地址支持十六进制(`0x1388`)或符号名(`main`)。
  91. **查询**
  92. ```
  93. !afl [pat] 函数列表(支持模糊搜索)
  94. !afi <addr|name> 函数详情
  95. !iz [pat] 字符串搜索
  96. !axi <name> 导入符号的调用点
  97. !axt <addr|name> 交叉引用 to
  98. !axf <addr|name> 交叉引用 from
  99. !deps <addr|name> [d=3] 递归调用链
  100. ```
  101. **反编译 / 反汇编**
  102. ```
  103. !pdc <addr|name> [-s] 伪代码(-s 去掉变量声明)
  104. !pdf <addr|name> 整函数反汇编(带 CFG 标注)
  105. !pd <addr|name> [n=16] 从地址反汇编 n 条指令
  106. !mc <addr|name> [maturity] 微码
  107. ```
  108. **修改**
  109. ```
  110. !afn <addr|name> <new_name> 重命名函数
  111. !cc <addr|name> <text> 设函数注释
  112. !ca <addr> <text> 设地址注释
  113. ```
  114. **工具**
  115. ```
  116. !hd <addr|name> [n=64] hexdump
  117. !sb <hex> [start] [end] 搜字节序列
  118. !syms <path> 导出符号表
  119. !ping 探活,返回打开的文件路径
  120. !pwd 工作目录
  121. !quit 关闭服务
  122. ```
  123. ---
  124. ## Python 脚本
  125. 命令不够用时发 Python 脚本。`db`([ida-domain](https://github.com/kohnakagawa/ida-domain))已预注入,原生 `ida_*` 模块同样可用:
  126. ```bash
  127. cat script.py | nc localhost 13120
  128. ```
  129. ```python
  130. # 找大函数 + 高调用量 → 可能是核心逻辑
  131. for func in db.functions.get_all():
  132. size = func.end_ea - func.start_ea
  133. name = db.functions.get_name(func)
  134. if size > 0x500 and name.startswith("sub_"):
  135. callers = list(db.functions.get_callers(func))
  136. print(f"{hex(func.start_ea)} {size:#x} callers={len(callers)} {name}")
  137. ```
  138. 脚本中的修改(重命名、注释等)同样自动触发文件系统同步。
  139. ## 交互 Shell
  140. 给人用的模式——带命令历史和实时补全:
  141. ```bash
  142. ida-bridge a.out --shell
  143. rlwrap nc localhost 13121
  144. ```
  145. ```
  146. > !afl jni
  147. 0x4012a0 JNI_OnLoad 0x80 callers=0
  148. 0x401320 jni_sign_data 0x1b4 callers=1
  149. 0x4014d8 jni_verify_sig 0xc8 callers=1
  150. > !deps jni_sign_data 2
  151. jni_sign_data [0x401320]
  152. CRYPTO_sign [0x402100]
  153. EVP_DigestSign [0x403800]
  154. ...
  155. > !afn 0x401320 Java_com_example_sign
  156. renamed 0x401320: jni_sign_data → Java_com_example_sign
  157. ```
  158. ---
  159. ## License
  160. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.