SQL interface to DWARF debug information via SQLite virtual tables.

Query DWARF debug information from ELF (Linux) and Mach-O (macOS) binaries using SQL. dwarfsql exposes compilation units, functions, variables, types, structures, enumerations, and line number information through virtual tables.

# Query functions in a binary
dwarfsql a.out "SELECT name, low_pc, high_pc FROM functions LIMIT 10"

# Interactive mode
dwarfsql a.out -i

# HTTP REST server
dwarfsql a.out --http 8080

# MCP server (for Claude Desktop / AI tools)
dwarfsql a.out --mcp 9000

SELECT name, (high_pc - low_pc) AS size
FROM functions
WHERE high_pc > 0
ORDER BY size DESC
LIMIT 10;

SELECT name, comp_dir, producer
FROM compilation_units;

SELECT s.name AS struct_name, m.name AS member, m.type, m.offset
FROM structs s
JOIN struct_members m ON s.id = m.struct_id
ORDER BY s.name, m.offset;

SELECT file, line
FROM line_info
WHERE address <= 0x401234
ORDER BY address DESC
LIMIT 1;

With AI agent support, you can query in natural language:

dwarfsql> Find all functions that start with 'init'
dwarfsql> What are the largest structures?
dwarfsql> Show me the enum values for error codes

The AI agent requires one of these CLI tools installed and authenticated:

Important: You must be logged in before using AI features.

.agent provider claude    # or copilot
.agent byok enable
.agent byok key sk-your-key

• CMake 3.20+
• C++17 compiler
• libdwarf (DWARF parsing library)

Ubuntu/Debian:

apt install libdwarf-dev libelf-dev

macOS:

brew install libdwarf

Fedora:

dnf install libdwarf-devel elfutils-libelf-devel

# From a parent project root
cmake -B build -DBUILD_WITH_DWARFSQL=ON
cmake --build build

# With AI agent support
cmake -B build -DBUILD_WITH_DWARFSQL=ON -DDWARFSQL_WITH_AI_AGENT=ON
cmake --build build

cd dwarfsql
cmake -B build
cmake --build build

Usage:
  dwarfsql <binary> "<query>"       Execute query and exit
  dwarfsql <binary> -i              Interactive mode
  dwarfsql <binary> --http [port]   Start HTTP REST server (default: 8080)
  dwarfsql <binary> --mcp [port]    Start MCP server (default: random 9000-9999)

Options:
  -i, --interactive   Interactive REPL mode
  -q, --query <sql>   Execute query
  --http [port]       Start HTTP REST server
  --mcp [port]        Start MCP server (Model Context Protocol)
  --bind <addr>       Bind address (default: 127.0.0.1)
  --token <token>     Authentication token
  -v, --verbose       Verbose output
  -h, --help          Show help

When started with --http, dwarfsql exposes a REST API:

Example:

curl -X POST http://localhost:8080/query -d "SELECT name FROM functions LIMIT 5"

Response format — all /query responses use the canonical script envelope (single statement = array of one entry):

{
  "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
}

Bodies can be multi-statement (semicolon-separated); each results[i] has its own columns/rows/row_count/error. Fail-fast is the default; pass ?continue_on_error=1 to run every statement regardless of earlier failures.

When started with --mcp, dwarfsql provides an MCP server for integration with AI tools like Claude Desktop.

# Start MCP server
dwarfsql a.out --mcp 9000

Add to Claude Desktop config:

{
  "mcpServers": {
    "dwarfsql": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}

Available MCP tools:

• dwarfsql_query - Execute SQL queries directly
• dwarfsql_agent - Ask natural language questions (requires AI agent build)

.tables         List all tables
.schema <table> Show table schema
.info           Show database info
.clear          Clear session
.quit / .exit   Exit
.help           Show help

.agent help     AI agent commands
.agent provider Show/set provider
.agent byok     BYOK configuration

dwarfsql is part of a family of tools that expose different binary-analysis and debug-information platforms through the same SQL surface, all built on the shared libxsql virtual-table framework. A query you learn against one tool largely carries over to the others.

Reverse-engineering platforms

• idasql — IDA Pro databases as SQL.
• bnsql — Binary Ninja databases as SQL.
• ghidrasql — Ghidra databases as SQL.

Debug info & compiler data

• pdbsql — Windows PDB symbol files as SQL.
• clangsql — Clang AST as SQL.

Core

• libxsql — the C++ SQLite virtual-table framework every tool above is built on.

Elias Bachaalany (@0xeb)

This project is licensed under the Mozilla Public License 2.0.