idasql v0.0.18 - SQL interface to IDA databases

Usage: idasql -s [-q ] [-f ] [-i] [--export ]

Options: -s 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 Auth token for HTTP/MCP server mode (if server requires it) -q Execute SQL query or semicolon-separated script -f Execute SQL from file -i Interactive REPL mode -w, --write Save database on exit (persist changes) --export 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 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 -q "SELECT * FROM binary; SELECT COUNT(*) FROM funcs;" 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

Thank you for using IDA. Have a nice day!

Legacy input `.idb` a 32 bit vengono aggiornati da idalib a un `.i64` associato. Quando ciò accade, idasql termina prima di servire SQL, restituisce il codice di uscita `3` e stampa un oggetto JSON su stdout con `status:"upgraded"` e `reopen_with`. Ripeti la stessa operazione con `-s <reopen_with>`.

</details>

### Compilazione dai Sorgenti

#### Prerequisiti

- CMake 3.20+
- compilatore C++20
- IDA SDK 9.0+ (imposta la variabile d'ambiente `IDASDK`)```bash
cmake -S . -B build -DIDASQL_WITH_MCP=ON -DIDASQL_BUILD_EXAMPLES=OFF
cmake --build build --config Release

Opzioni CMake utili:

Note:

• Il supporto Hex-Rays è sempre compilato e rilevato a runtime. Se Hex-Rays non è disponibile, le tabelle/funzioni basate sul decompilatore semplicemente non vengono registrate.
• Il supporto HTTP REST è sempre compilato; usa --http dalla CLI oppure .http start dalla CLI REPL/plugin.
• L'esecuzione SQL IDAPython è compilata ma disabilitata per impostazione predefinita a runtime. Abilitala per sessione con PRAGMA idasql.enable_idapython = 1;.
• IDASQL_WITH_MCP=ON recupera fastmcpp; OFF rimuove il supporto MCP e i comandi --mcp / .mcp.
• XSQL_WITH_THINCLIENT è forzato a ON e HTTPLIB_USE_OPENSSL_IF_AVAILABLE è forzato a OFF perché IDASQL usa HTTP locale in chiaro.

Tabelle disponibili

30+ tabelle virtuali che coprono funzioni, stringhe, tipi, riferimenti incrociati, disassemblaggio, decompilazione e altro.

Core

Stringhe e Byte

Decompilatore

Tipi

Annotazioni

Ricerca

Info Database

Archiviazione

Analisi

Funzioni SQL

Ricerca entità unificata

Usa la tabella grep per ricerche SQL componibili su funzioni nominate, etichette, segmenti, tipi e membri.```sql -- Search anything starting with "Create" SELECT name, kind, printf('0x%X', addr) as addr FROM grep WHERE pattern = 'Create%' LIMIT 20;

-- Search anywhere in name (plain text performs a contains search) SELECT name, kind, full_name FROM grep WHERE pattern = 'File' AND kind IN ('function', 'import') LIMIT 20;

-- Find struct members SELECT name, parent_name, full_name FROM grep WHERE pattern = 'dw%' AND kind = 'member';

-- Pagination SELECT name, kind, full_name FROM grep WHERE pattern = 'Create%' ORDER BY kind, name LIMIT 20 OFFSET 20;

## Integrazione

### HTTP REST API

Server HTTP stateless per una semplice integrazione. Nessun overhead di protocollo.```bash
idasql -s database.i64 --http 8080

The input content is empty — no source text was provided to translate. Please supply the chunk text.```bash curl http://localhost:8080/status curl -X POST http://localhost:8080/query -d "SELECT name FROM funcs LIMIT 5" curl -X POST http://localhost:8080/query -d "SELECT * FROM binary; SELECT COUNT(*) FROM funcs;"

Tutte le risposte `/query` utilizzano l'involucro dello script canonico — singola istruzione = array di un elemento:```
{
  "success": true,
  "statement_count": <N>,
  "results": [
    { "statement_index": 0, "success": true, "columns": [...], "rows": [...], "row_count": <N>, "elapsed_ms": <ms>, "error": null },
    ...
  ],
  "row_count_total": <N>,
  "elapsed_ms_total": <ms>,
  "first_error_index": null
}

Il fail-fast è il comportamento predefinito; passa continue_on_error=true (ad es. ?continue_on_error=1) per eseguire ogni istruzione indipendentemente dai fallimenti precedenti. Ogni results[i].error è canonico per i fallimenti delle singole istruzioni; first_error_index indica il primo fallimento o è null. In caso di errore dello splitter (ad es. una virgoletta non chiusa) la risposta è success:false, statement_count:0, results:[], oltre a un parse_error di livello superiore.

Per più database, esegui istanze separate:```bash idasql -s malware.i64 --http 8080 idasql -s kernel.i64 --http 8082

Endpoints: `/status`, `/help`, `/query`, `/shutdown`

#### Server HTTP dalla REPL

Avvia un server HTTP interattivamente dalla REPL o dalla CLI del plugin IDA:```
idasql -s database.i64 -i
idasql> .http start
HTTP server started on port 8142
URL: http://127.0.0.1:8142
...
Press Ctrl+C to stop and return to REPL.

Nel plugin IDA (non bloccante):``` idasql> .http start HTTP server started on port 8142 idasql> .http stop HTTP server stopped

Il server utilizza una porta casuale (8100-8199) per evitare conflitti con `--http`.

### Avvio automatico (Pinning)

`.pin` salva in modo persistente una preferenza del server nell'IDB (netnode `$ idasql config`) così che il **plugin IDA avvii automaticamente** un server HTTP o MCP ogni volta che quel database viene aperto — comodo per configurazioni multi-istanza in cui ogni database mantiene una porta stabile e nota.```
idasql> .pin set http 8080        # pin HTTP at 127.0.0.1:8080 (autostart on)
idasql> .pin set mcp 0.0.0.0 9500 # bind override + port (port optional; omit or 0 = fresh random port each launch)
idasql> .pin list                 # show pinned config
idasql> .pin off http             # disable autostart but keep host/port
idasql> .pin clear all            # remove all pins

Dopo il pinning, riaprire il database avvia automaticamente il server — lo vedrai nella finestra di output di IDA al caricamento:``` IDASQL v0.0.18: Query engine initialized IDASQL CLI: Installed IDASQL: autostart -> IDASQL HTTP server: http://127.0.0.1:8099 Type '.http stop' to stop the server.

`.pin` (oppure `.pin list`) mostra la configurazione attuale per entrambi i servizi:```
idasql> .pin
Autostart pins:
  http 127.0.0.1:8099  (autostart: on)
  mcp  (not set)

• L'avvio automatico al caricamento avviene solo nel plugin IDA. Il comando .pin stesso funziona sia nella CLI che nel plugin (la CLI si limita a leggere/scrivere il pin).
• .http start / .mcp start senza porta esplicita riutilizzano l'host/porta salvati.
• Dalla CLI, le modifiche .pin persistono solo quando si avvia con -w/--write (come qualsiasi altra modifica IDB).

Server MCP

Per client compatibili MCP (Model Context Protocol, uno standard per l'integrazione di strumenti AI):

--mcp e .mcp sono disponibili quando si compila con -DIDASQL_WITH_MCP=ON, che è l'impostazione predefinita. Compila con -DIDASQL_WITH_MCP=OFF per omettere il supporto MCP.```bash

Standalone mode

idasql -s database.i64 --mcp idasql -s database.i64 --mcp 9500 # specific port

Or in interactive mode

idasql -s database.i64 -i .mcp start

Configura il tuo client MCP:```json
{
  "mcpServers": {
    "idasql": { "url": "http://127.0.0.1:<port>/sse" }
  }
}

Tools: idasql_query (query SQL diretta o script separato da punto e virgola)

La famiglia xsql

IDASQL fa parte di una famiglia di strumenti che espongono diverse piattaforme di analisi binaria e informazioni di debug attraverso la stessa superficie SQL, tutti basati sul framework condiviso di tabelle virtuali libxsql. Una query che impari su uno strumento si trasferisce in gran parte agli altri — ad es. la stessa SELECT name, size FROM funcs ORDER BY size DESC LIMIT 10 funziona ovunque.

Piattaforme di reverse-engineering

• bnsql — Database di Binary Ninja come SQL.
• ghidrasql — Database di Ghidra come SQL.

Dati di debug e compilatore

• pdbsql — File di simboli PDB di Windows come SQL.
• dwarfsql — Informazioni di debug DWARF come SQL.
• clangsql — AST di Clang come SQL.

Core

• libxsql — il framework C++ di tabelle virtuali SQLite su cui sono costruiti tutti gli strumenti sopra.

Realizzato con

• libxsql - Libreria C++17 header-only per esporre strutture dati C++ come tabelle virtuali SQLite. Fornisce l'API builder fluente per definire tabelle, pushdown dei vincoli e supporto client HTTP thin.

• fastmcpp - Implementazione opzionale del server MCP usata quando si compila con -DIDASQL_WITH_MCP=ON.

Licenza e condizioni d'uso

In breve: puoi leggere, compilare, valutare, fare benchmark, impacchettare e usare idasql non modificato, anche a livello commerciale, se conservi le note e rispetti i termini della licenza. Puoi fare fork o applicare patch per preparare correzioni di bug, ottimizzazioni, funzionalità, test o miglioramenti alla documentazione da contribuire, nel rispetto delle regole sullo scopo dei contributi della licenza.

Non puoi mantenere un fork privato divergente, porting, rebranding, clone, sostituto compatibile con l'API, implementazione concorrente, né usare idasql come input per AI per ricreare o migliorare un'implementazione derivata senza previa autorizzazione scritta di Elias Bachaalany. Le implementazioni indipendenti che non sono copiate, materialmente derivate o sostanzialmente informate da idasql nel senso definito dalla licenza non sono vietate.

Richieste di permesso: apri un issue GitHub su allthingsida/idasql/issues.

Se idasql informa materialmente un progetto distribuito, preserva l'origine umana: accredita visibilmente idasql ed Elias Bachaalany nel tuo README/docs e nella UI About/credits quando applicabile. La licenza include una sezione esempi/FAQ per gli usi comuni consentiti e quelli che richiedono permesso. Le dipendenze di terze parti (libxsql, l'IDA SDK e le loro dipendenze transitive) rimangono soggette alle proprie licenze.

Vedi la Human-Origin Source License v1.0 completa.