bnsql "<database>" -c "<SQL>"

bnsql "C:/path/to/database.bndb" -c "SELECT ..."

# Query a database
bnsql database.bndb -c "SELECT COUNT(*) FROM funcs"

# Query an existing Binary Ninja database
bnsql database.bndb -c "SELECT name, address FROM funcs LIMIT 10"

# Multiple queries in one session
bnsql program.exe -c "SELECT COUNT(*) FROM funcs" -c "SELECT COUNT(*) FROM strings"

# Start server for a single database (random port)
bnsql database.bndb --http 0

# With specific port
bnsql database.bndb --http 8081

# With authentication token
bnsql database.bndb --http 8081 --token mysecret

# Bind to all interfaces (for remote access)
bnsql database.bndb --http 8081 --bind 0.0.0.0

# Execute SQL query
curl -X POST http://localhost:8081/query -d "SELECT name, size FROM funcs LIMIT 5"

# With authentication
curl -X POST http://localhost:8081/query \
     -H "Authorization: Bearer mysecret" \
     -d "SELECT * FROM funcs"

# Check server status
curl http://localhost:8081/status

{"success": true, "columns": ["name", "size"], "rows": [["main", "500"]], "row_count": 1}

{"success": false, "error": "no such table: bad_table"}

WITH caller_counts AS (
    SELECT to_ea, COUNT(*) as callers
    FROM xrefs WHERE is_code = 1
    GROUP BY to_ea
)
SELECT f.name, printf('0x%X', f.address) as address, c.callers
FROM funcs f
JOIN caller_counts c ON f.address = c.to_ea
ORDER BY c.callers DESC
LIMIT 10;

WITH call_counts AS (
    SELECT to_ea, COUNT(*) as cnt
    FROM xrefs WHERE is_code = 1
    GROUP BY to_ea
)
SELECT f.name, COALESCE(c.cnt, 0) as calls
FROM funcs f
LEFT JOIN call_counts c ON f.address = c.to_ea
WHERE COALESCE(c.cnt, 0) <= 10
ORDER BY calls DESC;

WITH has_callers AS (
    SELECT DISTINCT to_ea FROM xrefs WHERE is_code = 1
)
SELECT f.name, printf('0x%X', f.address) as address
FROM funcs f
WHERE f.address NOT IN (SELECT to_ea FROM has_callers);

SELECT name, printf('0x%X', address) as address, size
FROM funcs
ORDER BY size DESC
LIMIT 10;

WITH malloc_addr AS (
    SELECT address FROM imports WHERE name = 'malloc' OR name = '_malloc'
)
SELECT DISTINCT func_at(x.from_ea) as caller
FROM xrefs x
WHERE x.to_ea IN (SELECT address FROM malloc_addr) AND x.is_code = 1;

-- Use the callees view, NOT func_start() on xrefs!
SELECT func_name, printf('0x%X', func_addr) as address,
       COUNT(DISTINCT callee_addr) as num_callees
FROM callees
GROUP BY func_addr
HAVING COUNT(DISTINCT callee_addr) BETWEEN 1 AND 3
ORDER BY num_callees, func_name
LIMIT 20;

-- FAST: Use xrefs.from_func directly, avoid callees view for large result sets
SELECT from_func, COUNT(DISTINCT to_ea) as unique_callees
FROM xrefs WHERE is_code = 1 AND from_func != 0
GROUP BY from_func ORDER BY unique_callees DESC LIMIT 10;

-- Use xrefs with from_func for speed, only join funcs at the end for names
WITH
cc AS (
    SELECT from_func as func, COUNT(DISTINCT to_ea) as cnt
    FROM xrefs WHERE is_code = 1 AND from_func != 0
    GROUP BY from_func
),
-- Level 0: functions calling 1-3 others
l0 AS (SELECT func FROM cc WHERE cnt BETWEEN 1 AND 3),
-- Level 1 callees and their counts
l1_callees AS (SELECT DISTINCT x.to_ea as callee FROM xrefs x
    WHERE x.from_func IN (SELECT func FROM l0) AND x.is_code = 1),
l1_valid AS (SELECT lc.callee FROM l1_callees lc
    LEFT JOIN cc c ON lc.callee = c.func WHERE COALESCE(c.cnt, 0) <= 3),
-- Level 2
l2_callees AS (SELECT DISTINCT x.to_ea as callee FROM xrefs x
    WHERE x.from_func IN (SELECT callee FROM l1_valid) AND x.is_code = 1),
l2_valid AS (SELECT lc.callee FROM l2_callees lc
    LEFT JOIN cc c ON lc.callee = c.func WHERE COALESCE(c.cnt, 0) <= 3),
-- Level 3 must be terminal (0 callees)
l3_callees AS (SELECT DISTINCT x.to_ea as callee FROM xrefs x
    WHERE x.from_func IN (SELECT callee FROM l2_valid) AND x.is_code = 1),
l3_valid AS (SELECT lc.callee FROM l3_callees lc
    LEFT JOIN cc c ON lc.callee = c.func WHERE COALESCE(c.cnt, 0) = 0)
-- Output L0 functions with names
SELECT f.name, printf('0x%X', l0.func) as addr, cc.cnt as callees
FROM l0 JOIN cc ON l0.func = cc.func JOIN funcs f ON l0.func = f.address
ORDER BY cc.cnt DESC LIMIT 20;

-- First get pseudocode
SELECT decompile(address) FROM funcs WHERE name LIKE '%main%' LIMIT 1;

-- Then get local variables
SELECT name, type, storage FROM hlil_vars
WHERE func_addr = (SELECT address FROM funcs WHERE name LIKE '%main%' LIMIT 1);

-- 10 largest functions
SELECT name, size FROM funcs ORDER BY size DESC LIMIT 10;

-- Functions starting with "sub_" (auto-named, not analyzed)
SELECT name, hex(address) as addr FROM funcs WHERE name LIKE 'sub_%';

-- Find executable segments
SELECT name, hex(start_ea) as start FROM segments WHERE perm & 1 = 1;

-- Imports from kernel32.dll
SELECT name FROM imports WHERE module LIKE '%kernel32%';

-- Find error messages
SELECT content, hex(address) as addr FROM strings WHERE content LIKE '%error%';

-- Longest strings
SELECT hex(address), length, content FROM strings ORDER BY length DESC LIMIT 20;

-- Who calls function at 0x401000?
SELECT hex(from_ea) as caller FROM xrefs WHERE to_ea = 0x401000 AND is_code = 1;

-- Fast: count callees per function using from_func
SELECT from_func, COUNT(DISTINCT to_ea) as num_callees
FROM xrefs WHERE is_code = 1 AND from_func != 0
GROUP BY from_func ORDER BY num_callees DESC LIMIT 10;

-- Functions with most basic blocks
SELECT func_at(func_ea) as name, COUNT(*) as blocks
FROM blocks GROUP BY func_ea ORDER BY blocks DESC LIMIT 10;

-- Instruction profile of a function
SELECT mnemonic, COUNT(*) as count
FROM instructions WHERE func_addr = 0x401330
GROUP BY mnemonic ORDER BY count DESC;

-- Get database info
SELECT * FROM db_info;

-- Who calls function at 0x401000?
SELECT caller_name, printf('0x%X', caller_addr) as from_addr
FROM callers WHERE func_addr = 0x401000;

-- Most called functions
SELECT printf('0x%X', func_addr) as addr, COUNT(*) as callers
FROM callers GROUP BY func_addr ORDER BY callers DESC LIMIT 10;

-- What does main call?
SELECT callee_name, printf('0x%X', callee_addr) as addr
FROM callees WHERE func_name LIKE '%main%';

-- Functions making most calls (total call sites)
SELECT func_name, COUNT(*) as call_count
FROM callees GROUP BY func_addr ORDER BY call_count DESC LIMIT 10;

-- Functions calling the most UNIQUE callees (fan-out)
SELECT func_name, COUNT(DISTINCT callee_addr) as unique_callees
FROM callees GROUP BY func_addr ORDER BY unique_callees DESC LIMIT 10;

-- Functions that call exactly N unique functions (e.g., simple wrappers call 1)
SELECT func_name, COUNT(DISTINCT callee_addr) as callees
FROM callees GROUP BY func_addr HAVING callees = 1;

-- Find functions using error strings
SELECT func_name, string_value
FROM string_refs
WHERE string_value LIKE '%error%' OR string_value LIKE '%fail%';

-- Functions with most string references
SELECT func_name, COUNT(*) as string_count
FROM string_refs WHERE func_name IS NOT NULL
GROUP BY func_addr ORDER BY string_count DESC LIMIT 10;

-- Get pseudocode for a function
SELECT line FROM pseudocode WHERE func_addr = 0x401000 ORDER BY line_num;

-- Find functions containing "password" in decompiled code
SELECT DISTINCT func_at(func_addr) FROM pseudocode WHERE line LIKE '%password%';

-- Variables in a function
SELECT name, type, storage FROM hlil_vars WHERE func_addr = 0x401000;

-- Find functions with "buffer" variables
SELECT DISTINCT func_at(func_addr) FROM hlil_vars WHERE name LIKE '%buffer%';

-- What does a function call?
SELECT DISTINCT callee_name FROM hlil_calls WHERE func_addr = 0x401000;

-- Find functions calling malloc
SELECT DISTINCT func_at(func_addr) FROM hlil_calls WHERE callee_name = 'malloc';

-- WRONG: 8000 API calls on a binary with 8000 xrefs
SELECT func_start(from_ea), to_ea FROM xrefs WHERE is_code = 1;

-- CORRECT: Pure SQL join, milliseconds
SELECT func_addr, callee_addr FROM callees;

-- Find all matches for a pattern
SELECT search_bytes('48 8B ?? 00');

-- Parse JSON results
SELECT json_extract(value, '$.address') as addr
FROM json_each(search_bytes('48 89 ??'))
LIMIT 10;

-- First match only
SELECT printf('0x%X', search_first('CC CC CC'));

-- Count unique functions containing RDTSC (opcode: 0F 31)
SELECT COUNT(DISTINCT func_start(json_extract(value, '$.address'))) as count
FROM json_each(search_bytes('0F 31'))
WHERE func_start(json_extract(value, '$.address')) IS NOT NULL;

-- List those functions with names
SELECT DISTINCT
    func_start(json_extract(value, '$.address')) as func_ea,
    name_at(func_start(json_extract(value, '$.address'))) as func_name
FROM json_each(search_bytes('0F 31'))
WHERE func_start(json_extract(value, '$.address')) IS NOT NULL;

-- Direct JOIN is now efficient (uses filter_eq with GetCodeReferences)
SELECT f.name, COUNT(*) as callers
FROM funcs f
JOIN xrefs x ON x.to_ea = f.address
WHERE x.is_code = 1
GROUP BY f.address
ORDER BY callers DESC
LIMIT 10;

-- GOOD: Pre-aggregate with CTE (~800ms)
WITH call_counts AS (
    SELECT to_ea, COUNT(1) as cnt
    FROM xrefs
    WHERE is_code = 1
    GROUP BY to_ea
)
SELECT f.name, COALESCE(c.cnt, 0) as calls
FROM funcs f
LEFT JOIN call_counts c ON c.to_ea = f.address
WHERE COALESCE(c.cnt, 0) <= 10
ORDER BY calls DESC;

-- BAD: Correlated subquery (O(n×m) = very slow, will timeout!)
-- SELECT name, (SELECT COUNT(*) FROM xrefs WHERE to_ea = funcs.address) as calls FROM funcs;

SELECT s.content, func_at(x.from_ea) as used_by
FROM strings s
JOIN xrefs x ON s.address = x.to_ea
WHERE s.content LIKE '%password%';

SELECT func_at(func_ea) as name, COUNT(*) as block_count
FROM blocks
GROUP BY func_ea
ORDER BY block_count DESC
LIMIT 10;

-- Which modules are used
SELECT module, COUNT(*) AS cnt FROM imports GROUP BY module ORDER BY cnt DESC;

-- Find dangerous/suspicious imports
SELECT module, name FROM imports
WHERE name LIKE '%Shell%'
   OR name LIKE '%WinExec%'
   OR name LIKE '%CreateProcess%'
   OR name LIKE '%VirtualAlloc%'
   OR name IN ('strcpy', 'strcat', 'sprintf', 'gets');

SELECT module, name FROM imports
WHERE name LIKE '%Crypt%'
   OR name LIKE '%Hash%'
   OR name LIKE '%AES%'
   OR name LIKE '%RSA%';

SELECT module, name FROM imports
WHERE name LIKE '%socket%'
   OR name LIKE '%connect%'
   OR name LIKE '%send%'
   OR name LIKE '%recv%'
   OR name LIKE '%WSA%'
   OR name LIKE '%Http%';

WITH caller_counts AS (
    SELECT to_ea as func_addr, COUNT(DISTINCT from_func) as caller_cnt
    FROM xrefs WHERE is_code = 1 AND from_func != 0 GROUP BY to_ea
),
callee_counts AS (
    SELECT from_func as func_addr, COUNT(DISTINCT to_ea) as callee_cnt
    FROM xrefs WHERE is_code = 1 AND from_func != 0 GROUP BY from_func
)
SELECT f.name, COALESCE(cr.caller_cnt, 0) as callers, COALESCE(ce.callee_cnt, 0) as callees
FROM funcs f
LEFT JOIN caller_counts cr ON cr.func_addr = f.address
LEFT JOIN callee_counts ce ON ce.func_addr = f.address
WHERE COALESCE(cr.caller_cnt, 0) >= 5 AND COALESCE(ce.callee_cnt, 0) >= 5
ORDER BY (cr.caller_cnt * ce.callee_cnt) DESC LIMIT 20;

-- Optimized pattern: pre-filter strings, then use EXISTS on cached xrefs
-- (Avoid string_refs view which iterates all strings)
WITH error_addrs AS (
    SELECT address FROM strings
    WHERE content LIKE '%error%' OR content LIKE '%fail%' OR content LIKE '%invalid%'
),
funcs_with_errors AS (
    SELECT DISTINCT x.from_func as func_addr
    FROM xrefs x
    WHERE x.from_func != 0
      AND EXISTS (SELECT 1 FROM error_addrs e WHERE e.address = x.to_ea)
),
caller_counts AS (
    SELECT to_ea as func_addr, COUNT(*) as caller_cnt
    FROM xrefs WHERE is_code = 1 GROUP BY to_ea
)
SELECT f.name, COALESCE(cr.caller_cnt, 0) as callers
FROM funcs_with_errors fwe
JOIN funcs f ON f.address = fwe.func_addr
LEFT JOIN caller_counts cr ON cr.func_addr = f.address
WHERE COALESCE(cr.caller_cnt, 0) >= 5
ORDER BY cr.caller_cnt DESC LIMIT 15;

WITH write_funcs AS (
    SELECT address FROM imports
    WHERE name LIKE '%write%' OR name LIKE '%send%' OR name LIKE '%fwrite%'
),
caller_coverage AS (
    SELECT x.from_func as func_addr, COUNT(DISTINCT x.to_ea) as write_targets
    FROM xrefs x
    WHERE x.to_ea IN (SELECT address FROM write_funcs) AND x.from_func != 0
    GROUP BY x.from_func
)
SELECT f.name, cc.write_targets
FROM caller_coverage cc JOIN funcs f ON f.address = cc.func_addr
ORDER BY cc.write_targets DESC LIMIT 10;

SELECT hex(address) as addr, name FROM funcs;

-- Entry points
SELECT * FROM entries;

-- Imported APIs (hints at functionality)
SELECT module, name FROM imports ORDER BY module, name;

-- Interesting strings
SELECT content FROM strings WHERE length > 10 ORDER BY length DESC LIMIT 20;

-- Dangerous string functions
SELECT module, name FROM imports
WHERE name IN ('strcpy', 'strcat', 'sprintf', 'gets');

-- Crypto-related
SELECT * FROM imports WHERE name LIKE '%Crypt%' OR name LIKE '%Hash%';

-- Network-related
SELECT * FROM imports WHERE name LIKE '%socket%' OR name LIKE '%connect%';

-- Basic info
SELECT * FROM funcs WHERE address = 0x401000;

-- What calls it
SELECT hex(from_ea) as caller FROM xrefs WHERE to_ea = 0x401000 AND is_code = 1;

-- Decompile it
SELECT decompile(0x401000);

-- Or with line limit
SELECT decompile(0x401000, 30);

-- Find a medium-sized function and decompile it
SELECT name, size, decompile(address, 40) FROM funcs
WHERE size BETWEEN 500 AND 2000 ORDER BY size LIMIT 1;

-- Get variables
SELECT name, type, storage FROM hlil_vars WHERE func_addr = 0x401000;

-- Get function calls made
SELECT DISTINCT callee_name FROM hlil_calls WHERE func_addr = 0x401000;

-- BAD: Iterates all functions, decompiles each one - WILL HANG!
SELECT COUNT(*) FROM pseudocode;
SELECT COUNT(*) FROM hlil_vars;
SELECT * FROM hlil_calls LIMIT 10;  -- Still iterates from start!

-- GOOD: First get a function address, then query that function
SELECT address FROM funcs WHERE size > 100 LIMIT 1;  -- Get: 0x401000
SELECT * FROM pseudocode WHERE func_addr = 0x401000;
SELECT * FROM hlil_vars WHERE func_addr = 0x401000;
SELECT * FROM hlil_calls WHERE func_addr = 0x401000;

-- Search requires iteration but filter early
SELECT DISTINCT func_at(func_addr) FROM pseudocode WHERE line LIKE '%password%';
-- Still iterates all, but finds matches. Use for targeted searches, not counts.

-- SLOW: Executes subquery for EACH function (O(n×m))
SELECT name, (SELECT COUNT(*) FROM xrefs WHERE to_ea = funcs.address) FROM funcs;

-- FAST: Single pass over xrefs, then hash join (O(n+m))
WITH counts AS (SELECT to_ea, COUNT(*) as n FROM xrefs GROUP BY to_ea)
SELECT f.name, COALESCE(c.n, 0) FROM funcs f LEFT JOIN counts c ON c.to_ea = f.address;

# Default port 8081
bnsql database.bndb --http

# Custom port and bind address
bnsql database.bndb --http 9000 --bind 0.0.0.0

# With authentication
bnsql database.bndb --http 8081 --token mysecret

# Get API documentation
curl http://localhost:8081/help

# Execute SQL query
curl -X POST http://localhost:8081/query -d "SELECT name, size FROM funcs LIMIT 5"

# With authentication
curl -X POST http://localhost:8081/query \
     -H "Authorization: Bearer mysecret" \
     -d "SELECT * FROM funcs"

# Check status
curl http://localhost:8081/status

{"success": true, "columns": ["name", "size"], "rows": [["main", "500"]], "row_count": 1}

{"success": false, "error": "no such table: bad_table"}

bnsql database.bndb --server 13337
bnsql database.bndb --server 13337 --token mysecret

bnsql --remote localhost:13337 -c "SELECT name FROM funcs LIMIT 5"
bnsql --remote localhost:13337 -i

import socket, struct, json

def bnsql_query(sql, host="localhost", port=13337, token=None):
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.connect((host, port))
    req = {"sql": sql}
    if token: req["token"] = token
    payload = json.dumps(req).encode()
    s.sendall(struct.pack(">I", len(payload)) + payload)
    resp_len = struct.unpack(">I", s.recv(4))[0]
    return json.loads(s.recv(resp_len))

-- BAD: Will iterate all functions and generate MANY rows per function
SELECT COUNT(*) FROM _hlil_ast;

-- GOOD: Always filter by specific function
SELECT * FROM _hlil_ast WHERE func_addr = 0x401000;

-- Get a function address first
SELECT address FROM funcs WHERE size > 500 LIMIT 1;  -- e.g., 0x401330

-- Query loops in that function
SELECT op_name, hex(ea) as addr, cond_id, body_id
FROM _hlil_ast_loops
WHERE func_addr = 0x401330;

SELECT op_name, hex(ea) as addr, cond_id, true_id, false_id
FROM _hlil_ast_ifs
WHERE func_addr = 0x401330;

int64_t sub_401000() {
    void* ptr = malloc(0x100);
    for (int i = 0; i < 10; i++) {
        process(ptr, i);
    }
    return 0;
}

## Function: sub_401000 (500 bytes)

### Pseudocode:
\`\`\`c
int64_t sub_401000(int64_t arg1) {
    if (arg1 == 0) return -1;
    ...actual code here...
}
\`\`\`

### Analysis:
- This function validates the input argument...