skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
allthingsida/idasql-skills49 installs

connect

Connect to IDA databases and bootstrap sessions. Use when starting analysis, routing to other skills, setting up CLI/HTTP/MCP connections, or reading and changing IDA configuration options.

How do I install this agent skill?

npx skills add https://github.com/allthingsida/idasql-skills --skill connect
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubwarn

    This skill provides a SQL-based interface for interacting with IDA Pro, a standard reverse engineering tool. It includes high-privilege features such as the ability to execute arbitrary Python scripts (IDAPython) and read/write local file bytes. While these are legitimate features for a professional binary analysis tool, they provide a surface for dynamic code execution and indirect prompt injection if the agent is used to analyze malicious or attacker-controlled files.

  • Socketpass

    No alerts

  • Snykfail

    Risk: CRITICAL · 3 issues

What does this agent skill do?

CLI Help (verbatim idasql --help)

idasql v0.0.20 - SQL interface to IDA databases
Copyright (c) 2024-2026 Elias Bachaalany

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 server mode (MCP has no auth)
  -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

Commands (no database is opened; `idasql <command> --help` for details):
  link <verb>               ida:// deep links: open | status | register | unregister | source | config
  instances [--json]        running IDA instances and the databases they have open
  rescue <db> [--kill]      save a copy of the database a stuck IDA has open
  close <db|url>            end an IDA cleanly: --save or --discard
  http start|stop <db|pid>  start or stop another IDA's HTTP server (needs remote on there)
  mcp start|stop <db|pid>   the same for its MCP server
  remote on|off <db|pid>    let other processes start/stop that IDA's servers

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

Key takeaway: -s accepts either an existing IDA database or a raw binary. No manual idat -A -B / ida -B pre-step is needed — point -s straight at the .exe/.dll/firmware/etc. and idalib creates the database on first open.


Additional Resources

Autostart pinning (HTTP/MCP)

.pin http|mcp [bindinterface] [port] pins a server so the IDA plugin auto-starts it when the database opens (the pin lives in the IDB; CLI changes persist only with -w). The port is optional:

  • Fixed port — .pin http 0.0.0.0 8080 → autostarts on that stable port every launch (use for stable automation).
  • Random port — .pin http (port omitted, stored as 0) → autostarts on a fresh random port each launch (a real pinned setting, not "unset"); read the chosen port from the live status. .pin status shows <random port each launch>.

[bindinterface] is the host/interface (default 127.0.0.1). .pin on|off http|mcp toggles autostart without dropping the host/port; .pin clear [http|mcp|all] removes it. .http start / .mcp start with no port reuse the pinned host/port. Full grammar: references/cli-reference.md.


Find a Running IDA (idasql instances)

Before asking for a URL or opening a file yourself, look for the IDA the user already has open. No database is opened by this:

idasql instances --json

One object per running IDA:

FieldMeaning
pidprocess id
hostgui (an IDA window) or idalib (an idasql -s session)
idb_path, idb_namethe database it has open
httpits idasql HTTP server URL, or null when it serves none
http_authtrue: the server needs a token. Ask the user for it (it is never listed)
mcp, mcp_auththe same for an MCP server
rescueidasql rescue can reach it
remotetrue: other processes may start/stop its servers (idasql http start, below). Only an IDA window has it; always false for idalib
idasqlthe idasql plugin (or session) is running there
ipc, responsiveIDA 9.4+: found through IDA's own endpoint, and whether its UI answers
startedwhen that idasql session started (UTC)

Choosing the target:

  1. The user named a database → the instance with that database.
  2. Otherwise pick the obvious one, in this order: the database named earlier in the conversation; else the only GUI instance; else the most recently started. Do not stop to ask: say which one you used (database and pid) in the answer, so the user can correct you in one word.
  3. Retain its host as connection context for this target: gui permits deep links; idalib is headless and gets plain names/addresses, with no deep-link queries. Connect to its http URL as in "Attach to a Running Server" below, then confirm what you are bound to before the first real answer:
    SELECT key, value FROM binary WHERE key IN ('filename', 'idb_path', 'sha256');
    
    idb_path tells apart two same-named databases; sha256 tells whether two databases analyse the same sample.

Special cases:

  • http is null (an IDA window that serves no SQL): start its server yourself, then connect to the URL it prints:
    idasql http start <pid>          # the same as `.http start` in that IDA
    
    Exit 4 means its remote control is off. When the user's request needs that database, switch it on and start again. Never do this for a database the request is not about:
    idasql remote on <pid>           # the same as `.remote on` in that IDA (saved in its database)
    idasql http start <pid>
    
    Always tell the user what you started and where ("started HTTP in quiet.i64, pid 19020, at http://127.0.0.1:8412"). That IDA also prints every request in its Output window. idasql http stop <pid> stops it again. When the user works with that database often, suggest .pin http there, so its server starts every time it opens. idasql mcp start|stop <pid> does the same for MCP. A token is never handed out: a server pinned with one reports http_auth: true, so ask the user for it.
  • host is idalib with http null: an idasql -s session with no server. It cannot be started from outside; open your own idasql -s on a copy, or ask the user.
  • responsive is false: that IDA is hung or busy. Tell the user; if its unsaved work must be kept, idasql rescue "<idb_path>" saves a copy (only when the user asks).
  • Nothing is listed: use a pasted URL (below), or idasql -s <file>.
  • idasql instances --pid 1234[,5678] lists only those processes.

From a session you are already connected to, the same rows are a table, and the same requests are writes to it (one other IDA per statement; useful when you have SQL but no shell):

SELECT pid, host, idb_path, http, remote FROM ida_instances WHERE self = 0;
UPDATE ida_instances SET remote = 1 WHERE pid = 19020;      -- only for a database the request is about
UPDATE ida_instances SET start = 'http' WHERE pid = 19020;  -- then read its http column

Attach to a Running Server (pasted from IDA)

When the request contains an idasql HTTP server URL — typically pasted from the clipboard after .http start in IDA, e.g. idasql HTTP server at http://127.0.0.1:8134 followed by curl lines — the database is already open in that server. Talk to it; do not start idasql -s yourself. A URL alone does not identify a GUI plugin: retain the supplied connection context, or resolve its own host in Session Bootstrap below.

  1. curl <url>/help first: the endpoints and how to discover the schema.
  2. Send SQL as the raw body of POST <url>/query with --data-binary. If the pasted text shows an Authorization: Bearer ... header, send it with every request (only GET / and GET /help work without it). A 401 means the header is missing or wrong.
  3. Run the Session Bootstrap orientation queries below over HTTP, then route to the domain skill for the task that followed the pasted text.
  4. Writes (UPDATE/INSERT/DELETE) change that server's open database immediately. In a GUI plugin the user sees them and saves in IDA; --write does not apply there. A standalone headless server persists edits on exit only if it was started with --write.

Quick Start Guardrails

  • Always provide -s <file>. The file can be either an IDA database (.idb / .i64) or a raw binary (.exe, .dll, firmware blob, etc.) — raw binaries trigger fresh idalib auto-analysis and string-list rebuild. Do not pre-create an IDB with idat -A -B; idasql -s raw.exe does it in one shot.
  • If idasql -s legacy.idb ... exits with code 3 and stdout JSON containing {"status":"upgraded","reopen_with":"..."}, repeat the same requested operation with -s <reopen_with>. Server modes exit before binding in this case.
  • Use --write when you want edits persisted on exit, including HTTP/MCP server shutdown.
  • SQL inputs to -q, HTTP /query, MCP idasql_query, and plugin CLI may be one statement or a semicolon-separated script. Semicolons inside quoted strings are safe.
  • All /query responses use the canonical script envelope — single statement = array of one: {success, statement_count, results:[{statement_index, success, columns, rows, row_count, elapsed_ms, error}], row_count_total, elapsed_ms_total, first_error_index}. Fail-fast is the default. Both standalone CLI --http and REPL/plugin .http honor ?continue_on_error=1 in the query string to run every statement regardless of earlier failures; both also honor ?include_sql=1. MCP has no corresponding arguments.
  • To stop a long-running HTTP query, send POST /cancel from another client. Cancellation is cooperative and uses the same authentication as /query; result-bearing statements may return partial rows plus a cancellation warning.
  • Discover schema before writing queries:
    • REPL: .schema <table>
    • SQL: PRAGMA table_xinfo(<table>);
  • Start orientation with SELECT * FROM binary;.

Schema Catalog

Canonical column shapes and owner-skill mapping live in references/schema-catalog.md. Sourced from pragma_table_list + pragma_table_xinfo. Use it before assuming column names for less-common surfaces.


Session Bootstrap Contract

Use this exact startup flow before deep analysis:

  1. Find the IDA the user has open (idasql instances --json, see above) and attach to its server (start it with idasql http start <pid> when it serves none), or connect to a database (-s, -i, or --http). -s accepts either an existing IDB (.idb/.i64) or a raw binary (.exe/.dll/firmware/etc.) — never pre-build an IDB with idat; let idasql -s raw.exe do it. If a legacy .idb upgrades and returns status:"upgraded", restart with the JSON reopen_with path before running orientation.
  2. Record connection mode per target. A background idasql -s ... --http/--mcp process you launched is headless; HTTP/MCP transport does not imply a GUI. A known IDA GUI plugin is GUI-connected. For an unknown pasted URL, query SELECT host FROM ida_instances WHERE self = 1; once on that server, not WHERE self = 0 or an unrelated local instance list. Keep unknown mode plain. Known fully headless targets: do not query deep_links, emit ida:// links, probe navigation, enable its gate, or suggest a handler; use names and addresses, without remarking on links or their omission. Re-evaluate only when the target/connection changes or the user asks to open a GUI.
  3. Run orientation query:
SELECT * FROM binary;
  1. Validate key entities exist:
SELECT COUNT(*) AS funcs FROM funcs;
SELECT COUNT(*) AS xrefs FROM xrefs;
SELECT COUNT(*) AS strings FROM strings;
  1. Introspect schema for target surfaces before authoring complex SQL:
PRAGMA table_xinfo(funcs);
PRAGMA table_xinfo(xrefs);
  1. Route to domain skill using routing matrix below.

Global Agent Contracts

These contracts apply across all idasql skills and should be treated as one shared agent behavior model.

Read-First Contract

  • Read current state first (SELECT) before writes (INSERT/UPDATE/DELETE).
  • Confirm target precision using stable identifiers (addr, func_addr, idx, label_num).

Anti-Guessing Contract

  • Do not assume columns/types for long-tail surfaces.
  • Introspect via .schema or PRAGMA table_xinfo(...) before issuing uncertain queries.

Anti-Patterns

Habits that look natural but give wrong or slow answers, and what to do instead:

Don'tDo instead
Parse pseudocode text with LIKE or a regex to find switch cases, calls, comparisons or loopsSwitch cases: switch_cases / switch_tables (decompiler-free). Code structure: ctree and the ctree_v_calls, ctree_v_comparisons, ctree_v_loops, ctree_v_ifs, ctree_v_returns views. Text search on pseudocode is for finding a phrase, not for structure.
Walk a call graph one xref query at a timeOne recursive CTE over disasm_calls (or the call_graph / shortest_path tables) returns the whole chain in a single query.
Decompile functions just to rank or triage themfunc_summary: size, blocks, cyclomatic complexity, calls in and out, loops, switches, data reads and writes, frame size, per function, without the decompiler.
Scan funcs or names with LIKE to find something by nameThe grep table (WHERE pattern = '...') searches functions, labels, types and members in one indexed query.
Keep analysis progress in your own notesnetnode_kv stores it in the database, where the next session finds it.
Test "is this address in function F" with addr >= start AND addr < end_addrfunc_at(addr): functions can have tail chunks outside [addr, end_addr), and one tail can belong to several functions.

Mandatory Mutation Loop

  1. Read current state.
  2. Apply mutation.
  3. Refresh if needed (decompile(..., 1) for decompiler surfaces).
  4. Re-read and verify expected change.

Integer values are exact on every write and scalar argument: 16, 16.0 and '16' are 16; a fraction, a blob, NULL or text like '0x10' is refused with the column named (write hex unquoted: 0x10). An INSERT's address column also takes '0x...' text or a name.

Performance Contract

  • Always constrain high-cost surfaces (xrefs, instructions, ctree*, pseudocode) by key columns.
  • For decompiler surfaces, enforce func_addr = X unless explicitly asked for broad scans.
  • For raw dirtree browsing, prefer tree = ? plus path, path LIKE, or parent_path; for normal organization use funcs.folder_path and types.folder_path.
  • dirtree_entries is read-only diagnostics. Recursive folder delete and raw recovery/link operations are intentionally not SQL surfaces.

Failure Recovery Contract

  • On no such table/column: introspect schema and retry.
  • On empty results: validate address range, table freshness (rebuild_strings()), and runtime capabilities.
  • On timeout: narrow scope, add constraints, paginate, or split query.

Output Contract

  • Selection - decide whether and how much to surface from user intent. Answer questions directly ("biggest is main, 500 bytes"); show supporting rows only when they help the user verify; don't dump full tables unprompted; never surface data fetched only as an intermediate reasoning step.
  • Fidelity - when you do present code/data, show the real artifact (decompilation, actual rows), never a paraphrase.
  • Mechanics - the HTTP /query response is a JSON envelope ({success, results:[{columns,rows,...}]}). Consume it directly and render in your reply. Do not pipe responses through python/jq to pre-render a table - that discards the success/elapsed_ms/error fields and makes you reason over a lossy view. The CLI (-q/-f) already prints a table. Reserve jq/python for extracting a value to feed a later query. (For direct terminal/pipe use the server can emit ?format=text|csv|tsv; as an agent, consume json.)
  • Links - only for a GUI-connected target on IDA 9.4+ builds, make the functions, strings and types you name clickable. Known fully headless targets (including background CLI servers you launched) get plain names and addresses: do not query deep_links or emit ida:// links. For GUI-connected targets: generate each link with the deep_links table (function links view='pseudocode', addresses view='disasm') and write it as [exact_name](uri) outside any code block (see the deep-links skill). Never hand-build an ida:// string.

Skill Routing Matrix (Intent -> Skill)

Use this deterministic mapping for initial routing:

User intentPrimary skillTypical first query
find the IDA the user has open / which databases are openconnectidasql instances --json (no database needed)
query another open IDA that serves no SQL yetconnectidasql http start <pid> (exit 4: idasql remote on <pid> first, only for the database the request is about)
close an IDA (only when asked) / run an IDA actionconnectidasql close <db|url> --save · SELECT name, description, arg_spec FROM ui_actions WHERE kind <> 'raw' · UPDATE ui_actions SET args = '{"addr": 4198400}', run = 1 WHERE name = 'jump_to'
"what does this binary do?" / triageanalysisSELECT * FROM entries;
rank functions (biggest, most complex, most called)analysisSELECT name, cyclomatic, call_sites_out, callers FROM func_summary ORDER BY cyclomatic DESC LIMIT 20;
disassembly, segments, instructionsdisassemblySELECT * FROM funcs LIMIT 20;
which function contains an address / function chunksdisassemblySELECT name FROM func_at(0x...);
FLIRT signatures: apply one, list applied, library vs own codedisassemblySELECT name, title, state, matches FROM signatures;
function/type folders, review buckets, folder lifecycleannotations / typesSELECT addr, name, folder_path FROM funcs WHERE folder_path LIKE 'idasql/%';
xrefs/callers/callees/import dependenciesxrefsSELECT * FROM xrefs WHERE to_addr = ...;
find functions/types/labels/members by name patterngrepSELECT name, kind, addr FROM grep WHERE pattern = 'main' LIMIT 20;
strings/bytes/pattern searchdataSELECT * FROM strings LIMIT 20;
decompile/pseudocode/ctree/lvarsdecompilerSELECT decompile(0x...);
split a merged store/expression ("Split expression")decompilerINSERT INTO decompiler_splits(addr, piece_size) VALUES (0x..., 4);
comments/renames/retyping/bookmarksannotationsSELECT ... on target row before update
type creation/struct/enum/member worktypesSELECT * FROM types LIMIT 20;
breakpoints/patchingdebuggerSELECT * FROM breakpoints;
persistent key/value notesstorageSELECT * FROM netnode_kv LIMIT 20;
SQL function lookup/signature recallfunctionsSELECT * FROM pragma_function_list;
enumerate runtime settings / timeouts / queue configconnectSELECT * FROM runtime_settings; (writable; change via UPDATE runtime_settings SET value=... WHERE key=...)
IDA configuration options (ida.cfg, hexrays.cfg, ...)connectSELECT key, value, value_source, persisted FROM ida_config WHERE key = 'LOOKBACK';
the database notepadannotationsSELECT text FROM notepad;
checkpoint / undo / redo edits, per-turn rollbackannotationsINSERT INTO checkpoints(label) VALUES ('before edits'); then UPDATE checkpoints SET state='undone' WHERE label='before edits';
SQL from a Python script or plugin inside IDAidapythonimport idasql; idasql.query("SELECT name FROM funcs WHERE size > ?", 100)
live IDA UI context questionsui-contextSELECT get_ui_context_json(); (when available)
clickable links to IDA locations / "open it in IDA"deep-linksSELECT uri FROM deep_links WHERE resource='functions' AND addr=0x... AND view='pseudocode'; (IDA 9.4+ builds)
IDA SDK-only logic not in SQL surfacesidapythonUPDATE runtime_settings SET value='1' WHERE key='enable_idapython'; INSERT INTO idapython_runs(code) VALUES ('print(...)');
recursive source/structure recoveryre-sourcestart from function + recurse/handoff

When prompts span domains, execute in this order:

  1. Orientation in connect
  2. Primary domain skill
  3. Adjacent skills for enrichment (for example xrefs + decompiler + annotations)

Cross-Skill Execution Recipes

Recipe: Unknown binary triage -> suspicious function deep dive -> annotate

  1. analysis: identify candidates from imports/strings/call patterns.
  2. xrefs/disassembly: map call graph and call sites.
  3. decompiler: inspect logic and variable semantics.
  4. annotations: apply comments/renames/types with mutation loop.

Recipe: String IOC -> reference graph -> patch

  1. data: locate candidate strings and addresses.
  2. xrefs: map references to caller functions.
  3. debugger or annotations: patch or annotate specific sites.

Recipe: Type recovery from pseudocode

  1. decompiler: inspect lvars, call args, and ctree patterns.
  2. types: create/refine structs/enums and apply declarations.
  3. annotations: finalize naming/comments and verify rendered pseudocode.

UI Context Routing

For prompts like "what am I looking at?", "what's selected?", "what is on the screen?", "look at what I'm doing", or references to "this/current/that", use the dedicated ui-context skill.

ui-context owns:

  • get_ui_context_json() capture/reuse policy
  • temporal reference rules (this vs that)
  • response template, examples, and fallback messaging

Runtime caveat:

  • get_ui_context_json() is plugin GUI runtime only, not idalib/CLI mode.
  • If unavailable, state that UI context is unavailable and continue with non-UI SQL workflows.

binary

Database orientation surface for quick session metadata. This is metadata-only and not a replacement for UI context capture.

Key/value shape — (key TEXT, value TEXT, type TEXT), one row per metadata fact, type ∈ {string, hex, bool, int}. The shape and the canonical key names are shared across the tool family, so the same WHERE key = '…' query works on every engine. The summary row is emitted first, so SELECT * FROM binary shows the digest up top.

KeyTypeDescription
summarystringOne-line database summary (first row)
tool_namestringAlways idasql
tool_versionstringIDASQL build version (canonical name)
idasql_versionstringIDASQL build version (legacy-named duplicate)
processorstringProcessor/module name
filetypestringLoader file-type description (e.g. PE, ELF)
image_basehexImage base address
entry_pointhexEntry/start address (was the start_addr column)
min_addrhexMinimum address in database
max_addrhexMaximum address in database
is_64bitbooltrue/false
bitsintApplication bitness: 16, 32, or 64
endiannessstringlittle or big
filenamestringBare input filename (no path)
entry_namestringEntry symbol name (if known)
funcs_countintNumber of detected functions
segments_countintNumber of segments
names_countintNumber of named addresses
strings_countintCurrent IDA string-list count
input_file_pathstringOriginal input file path recorded in the IDB
idb_pathstringOn-disk path of the IDB/I64 (may differ if moved)
md5stringLowercase hex MD5 of the input file (empty if unavailable)
sha256stringLowercase hex SHA-256 of the input file (empty if unavailable)

Use the filename, idb_path, md5, or sha256 keys to confirm which binary/instance this connection is bound to.

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

For canonical schema and owner mapping, see references/schema-catalog.md.


ida_config

IDA's configuration keys: the analysis and display options of ida.cfg, the decompiler's hexrays.cfg, the GUI's idagui.cfg. IDA has no API that lists them, so the rows are the keys those files set, read the way IDA reads them: IDADIR/cfg then IDAUSR/cfg (later files win, the user's idauser.cfg included) and, in ida.cfg, the section for the database's processor. A key the files only mention in a comment or in another processor's section is listed when IDA can report its value (LOOKBACK on x86, for example).

ColumnTypeDescription
keyTEXTDirective name, case-sensitive (LOOKBACK, MAX_AUTONAME_LEN, BLOCK_INDENT)
fileTEXTThe file that sets it (ida.cfg, hexrays.cfg, idagui.cfg, idauser.cfg)
valueTEXTWritable. The value in .cfg syntax: a number, YES/NO, a quoted string. NULL when it cannot be known
value_sourceTEXTruntime (IDA reports the current value), inf (stored in the database), session (IDA cannot report it; what this session applied), file (IDA cannot report it; what the files set)
writableINT1 when an UPDATE can reach it here: 0 for idagui.cfg keys outside the GUI and for decompiler keys without the decompiler
persistedINT1 when a change is saved with the database (the inf keys); 0 means it lasts until the database is closed
messageTEXTIDA's warning from this session's last UPDATE of the key (for example a clamp), else NULL
-- What is set, and what survives a save
SELECT key, value, value_source, persisted FROM ida_config ORDER BY file, key;

-- One key
SELECT value FROM ida_config WHERE key = 'LOOKBACK';

-- Change it: applies LOOKBACK=88 and reads it back
UPDATE ida_config SET value = '88' WHERE key = 'LOOKBACK';

-- YES/NO keys also take 1/0, on/off; string keys are quoted for you
UPDATE ida_config SET value = 'no' WHERE key = 'SHOW_XREF_FUNC';

-- A clamped value is applied; the warning is in message
UPDATE ida_config SET value = '9999' WHERE key = 'LOOKBACK';
SELECT value, message FROM ida_config WHERE key = 'LOOKBACK';   -- 256, "... too high (must be at most 256)"

-- Changes that will be saved with the database
SELECT key, value FROM ida_config WHERE persisted = 1;

What persists, plainly:

  • persisted = 1 keys (ANALYSIS, MAX_AUTONAME_LEN, SHOW_XREFS, INDENTION, the SHOW_* and STRLIT_* display options, ...) are the database's own settings: a change is saved with the database (save_database() or -w), and on the next open the database's value beats ida.cfg.
  • Every other key (LOOKBACK, the decompiler's keys, colors, ...) lasts until the database is closed; the next open reads the .cfg files again.
  • Nothing here writes .cfg files (IDA offers no API for it). To keep a change across databases, put KEY = value in your own idauser.cfg (under IDAUSR/cfg) or pass -D KEY=VALUE to IDA.
  • Startup keys (DATABASE_MEMORY, VPAGES, WORKDIR, ...) are accepted but act only when a database is next opened.

Failure and recovery:

  • A value IDA rejects fails the UPDATE with IDA's own message (Expected a number, Expected YES/NO or ON/OFF values, ...). Read the row back: a rejected directive can still leave part of it applied.
  • writable = 0: run the UPDATE where that key is read (the GUI plugin for idagui.cfg, a database with the decompiler for hexrays.cfg).
  • value_source = 'session'/'file': IDA cannot report the key's current value; a clamp of such a key shows only in message.
  • One key per row, one KEY=VALUE per UPDATE: a value with an unquoted = is refused (it would start another directive). No INSERT/DELETE.

Performance: each query re-reads the option files and asks IDA for every value (a few tens of milliseconds). Filter by key in the same statement rather than scanning in a loop.


What is IDA and Why SQL?

IDA Pro is the industry-standard disassembler and reverse engineering tool. It analyzes compiled binaries (executables, DLLs, firmware) and produces:

  • Disassembly - Human-readable assembly code
  • Functions - Detected code boundaries with names
  • Cross-references - Who calls what, who references what data
  • Types - Structures, enums, function prototypes
  • Decompilation - C-like pseudocode (with Hex-Rays plugin)

IDASQL exposes all this analysis data through SQL virtual tables, enabling:

  • Complex queries across multiple data types (JOINs)
  • Aggregations and statistics (COUNT, GROUP BY)
  • Pattern detection across the entire binary
  • Scriptable analysis without writing IDA plugins or IDAPython scripts

Core Concepts for Binary Analysis

Addresses (ea_t)

Everything in a binary has an address - a memory location where code or data lives. IDA uses ea_t (effective address) as unsigned 64-bit integers. SQL shows these as integers; use printf('0x%X', addr) for hex display.

Address-taking SQL functions accept:

  • integer EA values (preferred for deterministic scripts)
  • numeric strings ('4198400', '0x401000')
  • symbol names resolved with get_name_ea(BADADDR, name) (global names)

Most table predicates should compare address columns to integer EAs such as addr = 0x401000. applied_types.addr is an intentional exception for equality filters/writes: it also accepts numeric strings and symbol names so type application can target names directly.

Examples:

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);

Read address comments from the comments table after resolving the target EA.

If a symbol cannot be resolved, SQL functions return an explicit error like: Could not resolve name to address: <name>.

Local label lookup that depends on a specific from context is not consulted by default (BADADDR resolution). Use explicit numeric EAs when needed.

High addresses (>= 2^63), e.g. kernel images at 0xFFFFF800...: SQL holds them as negative INTEGERs, so ORDER BY addr lists them first. Write them as hex literals (0xFFFFF80000100000) or the negative decimal, never as a decimal

= 2^63 (SQLite makes that a REAL, which matches nothing). addr >= <high hex> also includes every low address; the high half alone is addr BETWEEN <high hex> AND -1. Details: the disassembly and data skills.

Functions

IDA groups code into functions with:

  • addr / start_addr - Where the function begins (its entry point)
  • end_addr - Where the entry chunk ends (not the whole function)
  • name - Assigned or auto-generated name (e.g., main, sub_401000)
  • size - Total bytes in the function, over all of its chunks
  • chunk_count - Number of chunks (1 for a contiguous function)

Functions are not always contiguous: a function can own tail chunks elsewhere in memory, and one tail can belong to several functions. So never check "X is in function f" with an addr..end_addr range; use func_at(X) (owning function(s) of an address), the owner columns (blocks.func_addr, xrefs.from_func) for joins, and function_chunks for a function's chunks. Details: the disassembly skill.

There will be addresses and disassembly listing not belonging to a function. IDASQL can still get the bytes, disassembly listing ranges, etc. For single-EA disassembly (code or data), prefer disasm_at(addr[, context]) over function-scoped queries.

Cross-References (xrefs)

Binary analysis is about understanding relationships:

  • Code xrefs - Function calls, jumps between code
  • Data xrefs - Code reading/writing data locations, or data referring to other data (pointers)
  • from_addr -> to_addr represents "address X references address Y" Use table: xrefs(from_addr, to_addr, type, is_code).

Segments

Use table: segments(start_addr, end_addr, name, class, perm) (full CRUD). UPDATE start_addr rebases a segment, end_addr resizes it.

Memory is divided into segments with different purposes. For example, a typical PE file, has these segments:

  • .text - Executable code (typically)
  • .data - Initialized global data
  • .rdata - Read-only data (strings, constants)
  • .bss - Uninitialized data

Of course, segment names and types can vary. You may query the segments table to understand memory layout.

Basic Blocks

Within a function, basic blocks are straight-line code sequences:

  • No branches in the middle
  • Single entry, single exit
  • Useful for control flow analysis Use table: blocks(start_addr, end_addr, func_addr, size).

Decompilation (Hex-Rays)

The Hex-Rays decompiler converts assembly to C-like pseudocode:

  • ctree - The Abstract Syntax Tree of decompiled code
  • lvars - Local variables detected by the decompiler
  • Much easier to analyze than raw assembly

Core decompiler surfaces:

  • decompile(addr) (PRIMARY read/display surface)
    • Returns the entire function as one text block.
    • Each output line is prefixed for address grounding:
      • Addressed line: /* 401010 */ ...
      • Non-anchored line: /* */ ... (no address anchor for that line)
    • Use this first when the user asks to "decompile", "show code", "show pseudocode", or "explain function logic".
  • pseudocode table (structured/edit surface)
    • Use for line-level filtering (func_addr, addr, line_num) and comment writes keyed by addr + comment_placement.
    • Resolve a writable pseudocode anchor first; do not assume addr == func_addr.
    • Not the preferred display surface for full-function code.
  • ctree and ctree_call_args for AST-level analysis
  • ctree_lvars for local variable rename/type/comment updates
  • decompiler_splits for Hex-Rays "Split expression" without a window (INSERT/UPDATE piece_size/DELETE)

Performance Rules

CRITICAL: Constraint Pushdown

Some tables have optimized filters that use efficient IDA SDK APIs:

TableOptimized FilterWithout Filter
instructionsfunc_addr = XO(all instructions) - SLOW
blocksfunc_addr = XO(all blocks)
xrefsto_addr = X or from_addr = XO(all xrefs)
pseudocodefunc_addr = XDecompiles ALL functions
ctree*func_addr = XDecompiles ALL functions

Always filter decompiler tables by func_addr!

Use Integer Comparisons

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

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

O(1) Random Access

-- 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-First Mutation Workflow

For instruction lifecycle edits, use a CTE to identify precise targets first, then mutate. Delete everything that flows into an instruction in the same statement: a lone instruction that code still reaches is re-created by auto-analysis, and that DELETE fails and says so.

WITH target AS (
    SELECT addr
    FROM instructions
    WHERE func_addr = 0x401000
)
DELETE FROM instructions
WHERE addr IN (SELECT addr FROM target);

-- recreate over every chunk of the function (end_addr ends the entry chunk only)
SELECT SUM(make_code_range(chunk_start, chunk_end)) AS created FROM function_chunks WHERE func_addr = 0x401000;

This keeps mutation scope explicit and predictable for both humans and agents.


Summary: When to Use What

GoalTable/Function
List all functionsfuncs (cols: addr, name, size, end_addr, prototype, flags, …, chunk_count) → disassembly
List applied FLIRT signatures and what each foundsignatures (name, title, state, matches) → disassembly
Apply a FLIRT signatureINSERT INTO signatures(name) VALUES ('vc32rtf'); pick from available_signatures → disassembly
Library functions (recognized by a signature)funcs WHERE flags & 4 → disassembly
Function containing an addressfunc_at(addr) (tail chunks included) → disassembly
A function's chunksfunction_chunks WHERE func_addr = X → disassembly
Functions by return typefuncs WHERE return_is_integral = 1
Functions by arg countfuncs WHERE arg_count >= N
Void functionsfuncs WHERE return_is_void = 1
Pointer-returning functionsfuncs WHERE return_is_ptr = 1
Functions by calling conventionfuncs WHERE calling_conv = 'fastcall'
Rank or triage functionsfunc_summary (blocks, cyclomatic, calls in/out, callers, loops, switches, data reads/writes, frame size, uses_chkstk) → analysis
Find who calls whatxrefs with kind = 'call' (is_code = 1 also includes jumps)
Find data referencesxrefs with is_code = 0; kind tells read / write / offset apart
Stack frame of a functionfunction_frames WHERE func_addr = X (sizes, stack_base_reg, uses_chkstk) → disassembly
Analyze importsimports (cols: addr, name, ordinal, module) → xrefs / analysis
Find stringsstrings (cols: addr, length, content) → data
Configure string typesrebuild_strings(minlen, types)
Instruction analysisinstructions WHERE func_addr = X
Recreate deleted instructionsmake_code(addr), make_code_range(start, end)
Apply/clear address type declarationsapplied_types (INSERT, UPDATE decl, DELETE)
Apply/clear call-site prototypesUPDATE disasm_calls SET callee_type = ... WHERE addr = X
Create function at EAINSERT INTO funcs(addr) VALUES (...)
View function disassemblydisasm_func(addr) (every chunk); disasm_range(start, end) for an arbitrary range
View decompiled codedecompile(addr)
UI/screen context questionsui-context skill (get_ui_context_json(), plugin UI only)
Edit decompiler commentsResolve writable anchor, then UPDATE pseudocode SET comment = '...' WHERE func_addr = X AND addr = Y
AST pattern matchingctree WHERE func_addr = X
Call patternsctree_v_calls, disasm_calls
Control flowctree_v_loops, ctree_v_ifs
Return value analysisctree_v_returns
Functions returning specific valuesctree_v_returns WHERE return_num = 0
Pass-through functionsctree_v_returns WHERE returns_arg = 1
Wrapper functionsctree_v_returns WHERE returns_call_result = 1
Variable analysisctree_lvars WHERE func_addr = X
Type informationtypes, types_members
Function signaturestypes_func_args (with type classification)
Functions by return typetypes_func_args WHERE arg_index = -1
Typedef-aware type queriestypes_func_args (surface vs resolved)
Hidden pointer typestypes_func_args WHERE is_ptr = 0 AND is_ptr_resolved = 1
Manage breakpointsbreakpoints (full CRUD)
Modify segmentssegments (INSERT/UPDATE/DELETE)
Rename decompiler labelsUPDATE ctree_labels SET name=... WHERE func_addr=... AND label_num=...
Split a merged store ("Split expression")decompiler_splits (INSERT ... (addr, piece_size), DELETE unsplits) → decompiler
Delete instructionsinstructions (DELETE converts to unexplored bytes)
Recreate instructionsmake_code, make_code_range
Bulk patch from file bytesload_file_bytes(path, file_offset, addr, size[, patchable])
EA to physical offset mappingbytes.fpos on mapped byte rows (NULL means no file offset)
Create typestypes (INSERT struct/union/enum)
Add struct memberstypes_members (INSERT)
Add enum valuestypes_enum_values (INSERT)
Modify databasefuncs, names, comments, bookmarks (INSERT/UPDATE/DELETE)
Store custom key-value datanetnode_kv (full CRUD, persists in IDB)
Read or write the database notepadnotepad (UPDATE notepad SET text = ...) → annotations
Undo a batch of edits / an agent turncheckpoints (INSERT before, UPDATE ... SET state='undone' to roll back), undo_state → annotations
Query idasql from IDAPythonimport idasql (query / rows / scalar / script) → idapython
Read or change IDA optionsida_config (UPDATE ida_config SET value = ... WHERE key = ...; persisted says what is saved)
Entity search (structured)grep skill + grep WHERE pattern = '...'

Remember: Always use func_addr = X constraints on instruction and decompiler tables for acceptable performance.


Error Handling

  • No Hex-Rays license: Decompiler tables (pseudocode, ctree*, ctree_lvars) will be empty or unavailable
  • No constraint on decompiler tables: Query will be extremely slow (decompiles all functions)
  • Invalid address: Containing-function table lookups return no row; use a scalar subquery when you need a nullable scalar result
  • Missing function: JOINs may return fewer rows than expected

See Also

  • analysis — first triage after connecting (func_summary, imports, strings, entries).
  • grep — find functions, labels, types and members by name before querying them.
  • functions — the SQL function catalog when you need a signature.
  • deep-links — make functions and addresses clickable for GUI-connected targets (IDA 9.4+); known fully headless targets stay plain.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/allthingsida/idasql-skills/connect">View connect on skillZs</a>