tomevault-io IDA Domain API Reference
启动 ida-bridge
首先执行 ps 确认现有进程：
ps -ef | grep ida-bridge | grep -v grep
根据结果判断：
- 有进程 → 从命令行参数里直接读取文件路径和端口号，跳到步骤 2
- 无进程 → 询问用户：
没有发现正在运行的 ida-bridge。请告诉我：
- 要分析的文件路径（
.i64/.so） - 需要我帮你启动吗？
- 要分析的文件路径（
用户确认启动后：
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... 十六进制地址或符号名）。
探索与查询
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]
交叉引用
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]
反汇编与伪代码
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]
修改与注释
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）
工具
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 等工具处理，无需额外解析。
# 找被调用最多的函数
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 等）
cat my_script.py | nc localhost <port>
典型脚本模式：
# 批量重命名（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 文档：
${CLAUDE_SKILL_DIR}/reference/ida-domain.md— 日常必用 API（函数、名称、字节、xrefs、指令、字符串、导入、类型、伪代码基础、微码基础）。覆盖 ~90% 场景。${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 |
Source: TsingShui/ida-agent-bridge — distributed by TomeVault.