idapython
Execute IDAPython via idasql, and query idasql from IDAPython with import idasql. Use when SQL surfaces are insufficient and direct IDA SDK access is needed via Python snippets or scripts, or when a script or plugin inside IDA needs SQL over the open database.
How do I install this agent skill?
npx skills add https://github.com/allthingsida/idasql-skills --skill idapythonIs this agent skill safe to install?
- Gen Agent Trust Hubfail
This skill provides an interface to execute arbitrary IDAPython code within the IDA Pro environment via SQL queries. While it includes a safety mechanism that requires explicit activation, the ability to run unrestricted Python code allows for full system access, file manipulation, and data exfiltration from the analysis environment.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Python Execution SQL Functions
| Function | Description |
|---|---|
idapython_snippet(code[, sandbox]) | Execute Python snippet and return captured output text |
idapython_file(path[, sandbox]) | Execute Python file and return captured output text |
Runtime Guard
Python execution is disabled by default. Enable it with:
UPDATE runtime_settings SET value='1' WHERE key='enable_idapython';
Captured print output is unbounded by default. To bound a runaway or very
chatty snippet (so it can't exhaust memory / the response), set an optional byte cap;
0 restores unbounded:
UPDATE runtime_settings SET value='65536' WHERE key='idapython_output_max'; -- cap at 64 KiB
UPDATE runtime_settings SET value='0' WHERE key='idapython_output_max'; -- unbounded (default)
Output past the cap is dropped with a ...[idapython output truncated at N bytes]... marker.
To confirm the current values of enable_idapython and
idapython_output_max, query
SELECT * FROM runtime_settings WHERE scope = 'idasql'. The table is the
canonical writable runtime-control surface: read it with SELECT, and change
settable value cells with an exact-key UPDATE. Use
SELECT * FROM runtime_settings to include shared controls. See the connect
skill.
Examples
SELECT idapython_snippet('print("hello from idapython")');
SELECT idapython_file('C:/temp/script.py');
SELECT idapython_snippet('counter = globals().get("counter", 0) + 1; print(counter)', 'alpha');
Notes
- Disabled by default until
enable_idapythonis enabled throughruntime_settings - Python exceptions propagate as SQL errors
sandboxisolates/persists Python globals by sandbox key
Three Python Contexts (Important)
- Host-side Python client (outside IDA): use
requests.post(.../query, data=sql)to send SQL over HTTP. The body may be one statement or a semicolon-separated script; every response uses the canonicalresults[]envelope (a single statement is an array of one — readresults[i].rows). Use this for loops, bulk updates, and automation orchestration. Seeconnectskill HTTP client patterns. - IDAPython via SQL (inside IDA): use
idapython_snippet()/idapython_file()when you need direct IDA SDK APIs in-process. - SQL from IDAPython (inside IDA):
import idasqlin the IDA console, a script, a plugin, or a snippet queries the open database in-process (below). Never call the HTTP server from Python running inside IDA: the request waits for IDA's main thread, which is busy running that Python, and the call deadlocks.
Example contrast:
# Host-side Python (outside IDA): sends SQL over HTTP
import requests
requests.post("http://127.0.0.1:8080/query", data="SELECT COUNT(*) FROM funcs")
-- IDAPython (inside IDA): executes Python in IDA runtime
SELECT idapython_snippet('import idaapi; print(idaapi.get_kernel_version())');
Sandbox Behavior
Each sandbox key creates an isolated Python namespace:
- Variables set in one sandbox are not visible in another
- The same sandbox key reuses its namespace across calls (state persists within a session)
- Without a sandbox key, code runs in the default global namespace
Error Propagation
When a Python script raises an exception, it propagates as a SQL error:
-- This will return an error: "NameError: name 'undefined_var' is not defined"
SELECT idapython_snippet('print(undefined_var)');
Calling idasql from Python (import idasql)
Python that runs inside IDA (the console, a script or plugin, idapython_snippet) can query the open
database directly. idasql injects a small idasql module through IDAPython; idasql itself does not
link Python, and without IDAPython nothing changes.
import idasql
idasql.available() # True when an idasql engine is loaded
n = idasql.scalar("SELECT COUNT(*) FROM funcs") # first cell of the first row, typed, or None
r = idasql.query("SELECT addr, name, size FROM funcs WHERE size > ? ORDER BY size DESC", 100)
for f in r: # Row = tuple with attribute access
print(hex(f.addr), f.name, f.size)
r.columns, r.rows, r.warnings, r.elapsed_ms, r.timed_out, r.partial
r.dicts() # list of dicts
idasql.rows("SELECT * FROM segments") # query(...).dicts()
idasql.query("SELECT ? + ?", [40, 2]) # one list/tuple = the parameter sequence
results = idasql.script("SELECT 1; SELECT 2 AS two") # several statements: one Result each
try:
idasql.query("SELECT * FROM no_such_table")
except idasql.Error as e:
print(e.message, e.sql)
| Value | Python type |
|---|---|
| INTEGER | int (addresses come back as numbers) |
| REAL | float |
| TEXT | str (embedded NULs kept) |
| BLOB | bytes |
| NULL | None |
Parameters (?) are bound by SQLite, never formatted into the SQL: a quote in a name is data.
Python int, float, str, bytes, bool and None are accepted; integers up to 2^64-1 are
passed as their signed 64-bit value (how SQL holds high addresses).
Rules:
- Main thread only. In the GUI a call from another Python thread is forwarded to IDA's main
thread and waits for it. Under idalib (
idasqlCLI,--http,--mcp) nothing services such a request, so it fails at once withidasql.Errorinstead of hanging. - SQL -> Python -> SQL works. Inside
idapython_snippet,import idasqlqueries the same database; the inner query shares the outer statement's deadline and cancellation. - Python -> SQL -> Python is refused.
idapython_snippet/idapython_fileinside SQL issued throughidasqlfail with a clear error: IDAPython is not re-entrant from there. - Writes are writes. Changes made through
idasqlare visible to every later query, roll back with checkpoints (see theannotationsskill), and count as writes for the checkpoint redo guard. - Settings follow transactions.
UPDATE runtime_settingsfrom Python under a read-only statement takes effect at once; under a statement that writes, or insideBEGIN, when that commits. - Lifetime. When the database closes or the plugin unloads, a kept
idasql.queryraisesidasql.Error. A different module already imported asidasqlis never replaced (the bridge module carries_idasql_bridge_version).
Inside a snippet:
UPDATE runtime_settings SET value='1' WHERE key='enable_idapython';
SELECT idapython_snippet('
import idasql
big = idasql.query("SELECT addr, name FROM funcs WHERE size > ? ORDER BY size DESC LIMIT 5", 64)
for f in big:
print(hex(f.addr), f.name)
');
When to Use IDAPython vs SQL
| Use Case | Best Tool | Why |
|---|---|---|
| Query/filter/aggregate data | SQL | JOINs, CTEs, GROUP BY, window functions — SQL is purpose-built for this |
| Cross-table analysis | SQL | JOINing funcs, xrefs, strings, ctree is natural in SQL |
| Reporting and counting | SQL | COUNT, SUM, AVG, GROUP_CONCAT — no Python loop needed |
| Complex algorithms | IDAPython | Graph algorithms, custom pattern matching, ML pipelines |
| IDA SDK APIs not in idasql | IDAPython | Some IDA SDK features aren't exposed as SQL tables/functions |
| UI automation | IDAPython | Opening views, navigating cursor, triggering IDA actions |
| Existing scripts | IDAPython | Reuse existing .py scripts without rewriting in SQL |
General rule: Start with SQL. If you find yourself wanting nested loops, recursive algorithms, or IDA APIs that aren't exposed via idasql, reach for idapython_snippet() as a bridge.
Practical Use Cases
Run a custom analysis script
-- Enable Python execution first
UPDATE runtime_settings SET value='1' WHERE key='enable_idapython';
-- Run a script that collects custom metrics
-- (in SQL this one is SELECT COUNT(*) FROM funcs WHERE flags & 4; prefer SQL when it can)
SELECT idapython_snippet('
import idautils, idc
count = 0
for func_addr in idautils.Functions():
if idc.get_func_attr(func_addr, idc.FUNCATTR_FLAGS) & 0x4: # FUNC_LIB
count += 1
print(f"Library functions: {count}")
');
Access IDA SDK APIs not exposed through idasql
-- Example: get processor-specific register names
SELECT idapython_snippet('
import ida_idp
for i in range(ida_idp.ph_get_regnames().__len__()):
name = ida_idp.ph_get_regnames()[i]
if name:
print(f"{i}: {name}")
');
Bridge pattern: Python produces JSON, SQL processes it
When you need Python's power for extraction but SQL's power for analysis (inside a Python script,
import idasql does the same without the JSON round trip):
-- Python extracts data as JSON
SELECT idapython_snippet('
import json, idautils, idc
result = []
for addr in idautils.Functions():
flags = idc.get_func_attr(addr, idc.FUNCATTR_FLAGS)
if flags & 0x4: # FUNC_LIB
result.append({"addr": addr, "name": idc.get_func_name(addr)})
print(json.dumps(result))
');
-- Then process the JSON output in SQL using json_each()
-- (copy the output from above into the query)
See Also
- Check the relevant SQL skill first (
disassembly,decompiler,types,data,xrefs,annotations,debugger) — fall through to IDAPython only when no SQL surface exists for the task. functions— the SQL function catalog; verify a scalar/helper doesn't already exist before scripting.
How can the creator link this skill?
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/idapython">View idapython on skillZs</a>