connect

CLI 帮助（idasql --help 原文）

idasql vX.Y.Z - SQL interface to IDA databases

Usage: idasql -s <file> [-q <query>] [-f <file>] [-i] [--export <file>]

Options:
  -s <file>            IDA database (.idb/.i64) OR raw binary (.exe/.dll/firmware/etc.)
                       — raw binaries trigger fresh idalib analysis and string-list rebuild
                       — legacy 32-bit .idb files upgrade to .i64 and require an explicit reopen
  --token <token>      Auth token for HTTP/MCP server mode (if server requires it)
  -q <sql>             Execute SQL query or semicolon-separated script
  -f <file>            Execute SQL from file
  -i                   Interactive REPL mode
  -w, --write          Save database on exit (persist changes)
  --export <file>      Export tables to SQL file (local mode only)
  --export-tables=X    Tables to export: * (all, default) or table1,table2,...
  --http [port]        Start HTTP REST server (default: 8080, local mode only)
  --bind <addr>        Bind address for HTTP/MCP server (default: 127.0.0.1)
  --mcp [port]         Start MCP server (default: random port, use in -i mode)
                       Or use .mcp start in interactive mode
  -h, --help           Show this help
  --version            Show version

Examples:
  idasql -s test.i64 -q "SELECT name, size FROM funcs LIMIT 10"
  idasql -s test.i64 -f queries.sql
  idasql -s test.i64 -i
  idasql -s test.i64 --export dump.sql
  idasql -s test.i64 --http 8080
  idasql -s sample.exe --http            # raw PE: idalib auto-analyzes, then serves SQL (default port 8080)
  idasql -s firmware.bin -q "SELECT * FROM binary"
  idasql -s test.i64 --mcp 9000

要点： -s 可以接受现有的 IDA 数据库或原始二进制文件。无需预先手动执行 idat -A -B / ida -B——直接将 -s 指向 .exe/.dll/固件等文件，idalib 会在首次打开时创建数据库。

---

其他资源

• 权威架构目录：references/schema-catalog.md
• CLI 参考、REPL 命令、服务模式、运行时控制：references/cli-reference.md （包含 .pin 自动启动：打开数据库时，IDA 插件可自动启动固定的 HTTP/MCP 服务）

自动启动固定设置（HTTP/MCP）

.pin http|mcp [bindinterface] [port] 会固定一个服务，使 IDA 插件在数据库打开时自动启动该服务（固定设置保存在 IDB 中；CLI 更改只有使用 -w 才会持久保存）。端口可选：

• 固定端口 — .pin http 0.0.0.0 8080 → 每次启动时都在该固定端口自动启动（用于稳定的自动化）。
• 随机端口 — .pin http（省略端口，存储为 0）→ 每次启动时都在新的随机端口自动启动（这是实际生效的固定设置，并非“未设置”）；可从实时状态中读取所选端口。.pin status 会显示 <random port each launch>。

[bindinterface] 是主机/接口（默认为 127.0.0.1）。.pin on|off http|mcp 可在保留主机/端口的情况下切换自动启动；.pin clear [http|mcp|all] 会移除固定设置。.http start / .mcp start 未指定端口时会复用固定的主机/端口。完整语法： references/cli-reference.md。

• 优化质量门槛：references/optimization-checklist.md
• HTTP 服务指南：references/server-guide.md

---

快速入门注意事项

• 始终提供 -s <file>。该文件可以是 IDA 数据库 （.idb / .i64）或原始二进制文件（.exe、.dll、固件映像等）——原始二进制文件会触发全新的 idalib 自动分析和字符串列表重建。不要使用 idat -A -B 预先创建 IDB； idasql -s raw.exe 一步即可完成。
• 如果 idasql -s legacy.idb ... 以代码 3 退出，且标准输出中的 JSON 包含 {"status":"upgraded","reopen_with":"..."}，请使用 -s <reopen_with> 重复执行相同的请求操作。此时，服务模式会在绑定之前退出。
• 需要在退出时持久保存编辑内容时，请使用 --write，包括在 HTTP/MCP 服务关闭时。
• 传递给 -q、HTTP /query、MCP idasql_query 和插件 CLI 的 SQL 输入，可以是一条语句，也可以是以分号分隔的脚本。引号字符串中的分号不会造成问题。
• 所有 /query 响应都使用规范的脚本封装——单条语句也会作为一个元素的数组返回： {success, statement_count, results:[{statement_index, success, columns, rows, row_count, elapsed_ms, error}], row_count_total, elapsed_ms_total, first_error_index}。 默认遇错即停。只有 REPL/插件的 .http 服务会遵循查询字符串中的 ?continue_on_error=1，在发生错误时仍运行所有语句；CLI --http 处理程序会忽略该参数，MCP 则没有此类参数。
• 编写查询前先探索架构：
  • REPL：.schema <table>
  • SQL：PRAGMA table_xinfo(<table>);
• 可先使用 SELECT * FROM binary; 了解概况。

---

架构目录

权威的列结构和所属技能映射见 references/schema-catalog.md。内容取自 pragma_table_list + pragma_table_xinfo。在使用较少见的接口前，请先查阅此目录，避免对列名作出假设。

---

会话启动约定

深入分析前，严格遵循以下启动流程：

1. 连接到数据库（使用 -s、-i 或 --http）。-s 接受现有 IDB （.idb/.i64）或原始二进制文件（.exe/.dll/固件等）——切勿使用 idat 预先构建 IDB；让 idasql -s raw.exe 来完成。 如果旧版 .idb 升级后返回 status:"upgraded"，请先使用 JSON 中的 reopen_with 路径重新启动，再运行概览查询。
2. 运行概览查询：

SELECT * FROM binary;

3. 验证关键实体是否存在：

SELECT COUNT(*) AS funcs FROM funcs;
SELECT COUNT(*) AS xrefs FROM xrefs;
SELECT COUNT(*) AS strings FROM strings;

4. 在编写复杂 SQL 前，检查目标数据面的架构：

PRAGMA table_xinfo(funcs);
PRAGMA table_xinfo(xrefs);

5. 根据下方路由矩阵选择相应的领域技能。

---

全局 Agent 约定

这些约定适用于所有 idasql 技能，应视为统一的 Agent 行为模型。

先读取约定

• 写入（INSERT/UPDATE/DELETE）前，先读取当前状态（SELECT）。
• 使用稳定标识符（addr、func_addr、idx、label_num）确认目标精度。

禁止猜测约定

• 不要假设长尾数据面的列名或类型。
• 执行不确定的查询前，通过 .schema 或 PRAGMA table_xinfo(...) 检查架构。

强制变更循环

1. 读取当前状态。
2. 应用变更。
3. 如有需要，刷新（对反编译器数据面使用 decompile(..., 1)）。
4. 重新读取并验证预期变更。

性能约定

• 始终使用关键列限制高成本数据面（xrefs、instructions、ctree*、pseudocode）。
• 对于反编译器数据面，除非明确要求进行广泛扫描，否则必须使用 func_addr = X 限定。
• 浏览原始 dirtree 时，优先使用 tree = ?，并结合 path、path LIKE 或 parent_path；进行常规整理时使用 funcs.folder_path 和 types.folder_path。
• dirtree_entries 仅用于只读诊断。递归删除文件夹以及原始恢复/链接操作不属于 SQL 数据面。

故障恢复约定

• 遇到 no such table/column：检查架构后重试。
• 结果为空：检查地址范围、表是否为最新（rebuild_strings()）以及运行时能力。
• 超时：缩小范围、添加限制、分页或拆分查询。

输出约定

• 筛选 - 根据用户意图决定展示内容及数量。直接回答问题（“最大的是 main，500 字节”）；只有在有助于用户核验时才展示支持性行；不要在未被要求时倾倒完整表格；绝不展示仅作为中间推理步骤获取的数据。
• 忠实度 - 展示代码/数据时，应给出真实内容（反编译结果、实际行），绝不使用转述。
• 处理方式 - HTTP /query 响应是 JSON 封装（{success, results:[{columns,rows,...}]}）。直接使用并在回复中呈现。不要通过 python/jq 管道预先渲染表格——这会丢弃 success/elapsed_ms/error 字段，并使推理基于有损视图。CLI（-q/-f）已会打印表格。仅在提取值并将其用于后续查询时，才使用 jq/python。（直接在终端/管道中使用时，服务端可输出 ?format=text|csv|tsv；作为 Agent，应使用 json。）

技能路由矩阵（意图 -> 技能）

使用此确定性映射进行初始路由：

用户意图	主要技能	典型的首个查询
“这个二进制文件是做什么的？”/ 分诊	analysis	SELECT * FROM entries;
反汇编、段、指令	disassembly	SELECT * FROM funcs LIMIT 20;
函数/类型文件夹、审查分类、文件夹生命周期	annotations / types	SELECT addr, name, folder_path FROM funcs WHERE folder_path LIKE 'idasql/%';
交叉引用/调用者/被调用者/导入依赖	xrefs	SELECT * FROM xrefs WHERE to_addr = ...;
按名称模式查找函数/类型/标签/成员	grep	SELECT name, kind, addr FROM grep WHERE pattern = 'main' LIMIT 20;
字符串/字节/模式搜索	data	SELECT * FROM strings LIMIT 20;
反编译/伪代码/ctree/lvars	decompiler	SELECT decompile(0x...);
注释/重命名/重新定型/书签	annotations	更新前对目标行执行 SELECT ...
创建类型/结构体/枚举/成员相关操作	types	SELECT * FROM types LIMIT 20;
断点/修补	debugger	SELECT * FROM breakpoints;
持久化键值笔记	storage	SELECT * FROM netnode_kv LIMIT 20;
SQL 函数查找/签名回忆	functions	SELECT * FROM pragma_function_list;
枚举运行时设置/超时/队列配置	connect	SELECT * FROM runtime_settings;（只读；通过 PRAGMA idasql.<key> = <value> 更改）
实时 IDA UI 上下文问题	ui-context	SELECT get_ui_context_json();（可用时）
SQL 接口中未提供的仅限 IDA SDK 的逻辑	idapython	PRAGMA idasql.enable_idapython = 1; SELECT idapython_snippet('print(...)');
递归恢复源代码/结构	re-source	从函数开始，并递归/移交

当提示词涉及多个领域时，按以下顺序执行：

1. 在 connect 中了解概况
2. 主要领域技能
3. 使用相邻技能补充信息（例如 xrefs + decompiler + annotations）

---

跨技能执行方案

方案：未知二进制文件分诊 -> 深入调查可疑函数 -> 添加注释

1. analysis：根据导入项/字符串/调用模式识别候选项。
2. xrefs/disassembly：绘制调用图和调用点。
3. decompiler：检查逻辑和变量语义。
4. annotations：通过修改循环应用注释/重命名/类型。

方案：字符串 IOC -> 引用图 -> 修补

1. data：定位候选字符串和地址。
2. xrefs：将引用映射到调用函数。
3. debugger 或 annotations：修补或注释特定位置。

方案：根据伪代码恢复类型

1. decompiler：检查 lvars、调用参数和 ctree 模式。
2. types：创建/完善结构体/枚举并应用声明。
3. annotations：完成命名/注释，并验证渲染后的伪代码。

---

UI 上下文路由

对于“我在看什么？”“选中了什么？”“屏幕上是什么？”“看看我在做什么”之类的提示词，或提及“这个/当前/那个”的内容，请使用专用的 ui-context 技能。

ui-context 负责：

• get_ui_context_json() 的捕获/复用策略
• 时间指代规则（this 与 that）
• 响应模板、示例和回退提示

运行时注意事项：

• get_ui_context_json() 仅适用于插件 GUI 运行时，不适用于 idalib/CLI 模式。
• 如果不可用，请说明 UI 上下文不可用，并继续使用非 UI SQL 工作流。

---

二进制

用于快速查看会话元数据的数据库概览。 此处仅包含元数据，不能替代 UI 上下文采集。

键值格式为 (key TEXT, value TEXT, type TEXT)，每条元数据对应一行， type ∈ {string, hex, bool, int}。整个工具系列共用此格式和规范键名，因此在 每个引擎上都可以使用相同的 WHERE key = '…' 查询。summary 行会首先输出， 因此执行 SELECT * FROM binary 时，摘要会显示在最上方。

键	类型	描述
summary	string	单行数据库摘要（首行）
tool_name	string	始终为 idasql
tool_version	string	IDASQL 构建版本（规范名称）
idasql_version	string	IDASQL 构建版本（旧名称副本）
processor	string	处理器／模块名称
filetype	string	加载器文件类型描述（例如 PE、ELF）
image_base	hex	映像基址
entry_point	hex	入口／起始地址（原为 start_addr 列）
min_addr	hex	数据库中的最小地址
max_addr	hex	数据库中的最大地址
is_64bit	bool	true／false
bits	int	应用程序位数：16、32 或 64
endianness	string	little 或 big
filename	string	输入文件名（不含路径）
entry_name	string	入口符号名称（如果已知）
funcs_count	int	检测到的函数数量
segments_count	int	段数量
names_count	int	已命名地址的数量
strings_count	int	当前 IDA 字符串列表数量
input_file_path	string	IDB 中记录的原始输入文件路径
idb_path	string	IDB／I64 的磁盘路径（移动后可能不同）
md5	string	输入文件的小写十六进制 MD5（不可用时为空）
sha256	string	输入文件的小写十六进制 SHA-256（不可用时为空）

使用 filename、idb_path、md5 或 sha256 键，确认此连接绑定到哪个 二进制文件／实例。

SELECT * FROM binary;
SELECT key, value FROM binary WHERE key IN ('filename','idb_path','md5','sha256');
SELECT value FROM binary WHERE key = 'idasql_version';

有关规范架构和所有者映射，请参阅 references/schema-catalog.md。

---

什么是 IDA？为什么使用 SQL？

IDA Pro 是业界标准的反汇编和逆向工程工具。它能够分析已编译的二进制文件（可执行文件、DLL、固件），并生成：

• 反汇编代码 - 人类可读的汇编代码
• 函数 - 检测到的代码边界及其名称
• 交叉引用 - 谁调用了什么、谁引用了哪些数据
• 类型 - 结构体、枚举、函数原型
• 反编译结果 - 类似 C 语言的伪代码（需使用 Hex-Rays 插件）

IDASQL 通过 SQL 虚拟表公开所有这些分析数据，从而支持：

• 跨多种数据类型执行复杂查询（JOIN）
• 聚合与统计（COUNT、GROUP BY）
• 在整个二进制文件中检测模式
• 无需编写 IDA 插件或 IDAPython 脚本即可执行可脚本化分析

---

二进制分析的核心概念

地址（ea_t）

二进制文件中的所有内容都有一个地址——代码或数据所在的内存位置。IDA 使用 ea_t（有效地址）表示无符号 64 位整数。SQL 将这些值显示为整数；使用 printf('0x%X', addr) 以十六进制显示。

地址相关的 SQL 函数接受：

• 整数 EA 值（建议用于确定性脚本）
• 数字字符串（'4198400'、'0x401000'）
• 使用 get_name_ea(BADADDR, name) 解析的符号名称（全局名称）

大多数表谓词应将地址列与整数 EA 值进行比较，例如 addr = 0x401000。applied_types.addr 是一个特例：用于相等筛选条件和写入时，它也接受数字字符串和符号名称，因此可以直接将类型应用到名称。

示例：

SELECT decompile('DriverEntry');
UPDATE applied_types
SET decl = 'NTSTATUS DriverEntry(PDRIVER_OBJECT, PUNICODE_STRING);'
WHERE addr = 'DriverEntry';
SELECT (SELECT comment FROM comments WHERE addr = 0x401000 LIMIT 1);

解析目标 EA 后，从 comments 表读取地址注释。

如果无法解析符号，SQL 函数会返回明确的错误，例如： Could not resolve name to address: <name>。

默认情况下，不会查询依赖特定 from 上下文的局部标签（BADADDR 解析）。需要时请使用明确的数值 EA。

函数

IDA 将代码划分为函数，每个函数包含：

• addr / start_addr - 函数的起始位置
• end_addr - 函数的结束位置
• name - 指定的名称或自动生成的名称（例如 main、sub_401000）
• size - 函数的总字节数

有些地址和反汇编列表不属于任何函数。IDASQL 仍可获取字节、反汇编列表范围等。 对于单个 EA 的反汇编（代码或数据），优先使用 disasm_at(addr[, context])，而不是按函数范围查询。

交叉引用（xrefs）

二进制分析旨在理解关系：

• 代码交叉引用 - 函数调用、代码之间的跳转
• 数据交叉引用 - 代码读取或写入数据位置，或数据引用其他数据（指针）
• from_addr -> to_addr 表示“地址 X 引用地址 Y” 使用表：xrefs(from_addr, to_addr, type, is_code)。

段

使用表：segments(start_addr, end_addr, name, class, perm)（完整的 CRUD 操作）。 UPDATE start_addr 会重定位一个段，end_addr 会调整其大小。

内存划分为用途不同的段。例如，典型的 PE 文件包含以下段：

• .text - 可执行代码（通常如此）
• .data - 已初始化的全局数据
• .rdata - 只读数据（字符串、常量）
• .bss - 未初始化的数据

当然，段名称和类型可能各不相同。你可以查询 segments 表来了解内存布局。

基本块

在函数内部，基本块是顺序执行的代码序列：

• 中间没有分支
• 单一入口、单一出口
• 有助于控制流分析 使用表：blocks(start_addr, end_addr, func_addr, size)。

反编译（Hex-Rays）

Hex-Rays 反编译器可将汇编转换为类似 C 的伪代码：

• ctree - 反编译代码的抽象语法树
• lvars - 反编译器检测到的局部变量
• 比原始汇编更易于分析

反编译器的主要接口：

• decompile(addr)（主要读取/显示接口）
  • 将整个函数作为一个文本块返回。
  • 每行输出都会带前缀，以便关联地址：
    • 带地址的行：/* 401010 */ ...
    • 未锚定的行：/* */ ...（该行没有地址锚点）
  • 用户要求“反编译”“显示代码”“显示伪代码”或“解释函数逻辑”时，首先使用此接口。
• pseudocode 表（结构化/编辑接口）
  • 用于按行筛选（func_addr、addr、line_num）以及通过 addr + comment_placement 键写入注释。
  • 先解析一个可写的伪代码锚点；不要假定 addr == func_addr。
  • 不建议将其用作显示完整函数代码的接口。
• ctree 和 ctree_call_args 用于 AST 级分析
• ctree_lvars 用于更新局部变量的名称、类型和注释

---

性能规则

关键：下推约束

某些表具有经过优化的筛选条件，可使用高效的 IDA SDK API：

表	优化筛选条件	不使用筛选条件
instructions	func_addr = X	O(所有指令) - 慢
blocks	func_addr = X	O(所有基本块)
xrefs	to_addr = X 或 from_addr = X	O(所有交叉引用)
pseudocode	func_addr = X	反编译所有函数
ctree*	func_addr = X	反编译所有函数

始终按 func_addr 筛选反编译器表！

使用整数比较

-- SLOW: String comparison
WHERE mnemonic = 'call'

-- FAST: Integer comparison
WHERE itype IN (16, 18)  -- x86 call opcodes

O(1) 随机访问

-- SLOW: O(n) - sorts all rows
SELECT addr FROM funcs ORDER BY RANDOM() LIMIT 1;

-- FAST: O(1) - direct index access
SELECT addr
FROM funcs
WHERE rowid = ABS(RANDOM()) % (SELECT COUNT(*) FROM funcs);

先使用 CTE 的修改工作流

编辑指令生命周期时，先使用 CTE 找出精确目标，再执行修改：

WITH target AS (
    SELECT addr
    FROM instructions
    WHERE func_addr = 0x401000
    ORDER BY addr DESC
    LIMIT 1
)
DELETE FROM instructions
WHERE addr IN (SELECT addr FROM target);

SELECT make_code_range(addr, end_addr) FROM funcs WHERE addr = 0x401000;

这样可让人和 Agent 都能明确、可预测地控制修改范围。

---

总结：何时使用什么

目标	表/函数
列出所有函数	funcs（列：addr、name、end_addr、prototype、flags、…）→ disassembly
按返回类型查找函数	funcs WHERE return_is_integral = 1
按参数数量查找函数	funcs WHERE arg_count >= N
无返回值函数	funcs WHERE return_is_void = 1
返回指针的函数	funcs WHERE return_is_ptr = 1
按调用约定查找函数	funcs WHERE calling_conv = 'fastcall'
查找谁调用了什么	使用 is_code = 1 的 xrefs
查找数据引用	使用 is_code = 0 的 xrefs
分析导入项	imports（列：addr、name、ordinal、module）→ xrefs / analysis
查找字符串	strings（列：addr、length、content）→ data
配置字符串类型	rebuild_strings(minlen, types)
指令分析	instructions WHERE func_addr = X
重建已删除的指令	make_code(addr)、make_code_range(start, end)
应用/清除地址类型声明	applied_types（INSERT、UPDATE decl、DELETE）
应用/清除调用点原型	UPDATE disasm_calls SET callee_type = ... WHERE addr = X
在 EA 处创建函数	INSERT INTO funcs(addr) VALUES (...)
查看函数反汇编	disasm_func(addr) 或 disasm_range(start, end)
查看反编译代码	decompile(addr)
UI/屏幕上下文问题	ui-context 技能（get_ui_context_json()，仅限插件 UI）
编辑反编译器注释	Resolve writable anchor, then UPDATE pseudocode SET comment = '...' WHERE func_addr = X AND addr = Y
AST 模式匹配	ctree WHERE func_addr = X
调用模式	ctree_v_calls、disasm_calls
控制流	ctree_v_loops、ctree_v_ifs
返回值分析	ctree_v_returns
查找返回特定值的函数	ctree_v_returns WHERE return_num = 0
直通函数	ctree_v_returns WHERE returns_arg = 1
包装函数	ctree_v_returns WHERE returns_call_result = 1
变量分析	ctree_lvars WHERE func_addr = X
类型信息	types、types_members
函数签名	types_func_args（含类型分类）
按返回类型查找函数	types_func_args WHERE arg_index = -1
感知 typedef 的类型查询	types_func_args（表层类型与解析后类型）
隐藏指针类型	types_func_args WHERE is_ptr = 0 AND is_ptr_resolved = 1
管理断点	breakpoints（完整 CRUD）
修改段	segments（INSERT/UPDATE/DELETE）
重命名反编译器标签	UPDATE ctree_labels SET name=... WHERE func_addr=... AND label_num=...
删除指令	instructions（DELETE 会将其转换为未探索字节）
重建指令	make_code、make_code_range
从文件字节批量修补	load_file_bytes(path, file_offset, addr, size[, patchable])
EA 到物理偏移的映射	映射字节行上的 bytes.fpos（NULL 表示没有文件偏移）
创建类型	types（INSERT struct/union/enum）
添加结构体成员	types_members（INSERT）
添加枚举值	types_enum_values（INSERT）
修改数据库	funcs、names、comments、bookmarks（INSERT/UPDATE/DELETE）
存储自定义键值数据	netnode_kv（完整 CRUD，持久化在 IDB 中）
实体搜索（结构化）	grep 技能 + grep WHERE pattern = '...'

请记住： 始终在指令表和反编译器表中使用 func_addr = X 约束，以确保性能可接受。

---

错误处理

• 没有 Hex-Rays 许可证： 反编译器表（pseudocode、ctree*、ctree_lvars）将为空或不可用
• 反编译器表没有约束： 查询会非常慢（反编译所有函数）
• 无效地址： 包含该地址的函数表查找不会返回行；需要可为空的标量结果时，请使用标量子查询
• 缺少函数： JOIN 可能返回少于预期的行