https://github.com/bkerler/ida_rpc
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bkerler/ida_rpc with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bkerler/ida_rpc'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/bkerler--ida-rpc)HTML
<a href="/listings/bkerler--ida-rpc"><img src="/api/listings/bkerler--ida-rpc/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install
**Via the IDA Plugin Manager (recommended):**
hcli plugin install ida-rpc
**Or in the script path:**
hcli plugin install .
**Or manually:**
pip install -e /path/to/ida-rpc ln -s /path/to/ida-rpc/ida_rpc_plugin.py $IDAUSR/plugins/ida_rpc_plugin.py
Default `$IDAUSR` paths: - **Windows:** `%APPDATA%\Hex-Rays\IDA Pro\` - **macOS:** `~/Library/Application Support/IDA Pro/` - **Linux:** `~/.idapro/`
Start the daemon
For agents and automation, first ask the tool what it can do and which IDB path to use:
ida-rpc capabilities ida-rpc find-project /path/to/binary-or-existing.i64 ida-rpc list-loaders /path/to/binary
# Start headless daemon from a binary (headless is the default) ida-rpc open /path/to/binary --arch <arch> --detach # Or open an existing IDB ida-rpc open --project /path/to/existing.i64 --arch <arch> --detach # For raw binaries, specify architecture and base address. # The segment is auto-configured (class, bitness, permissions) based on arch. ida-rpc open /path/to/raw.bin --arch arm --base 0x8000 --detach # Open in GUI mode instead ida-rpc open /path/to/binary --arch <arch> --gui --detach # Existing IDBs ignore raw import options such as --base and --loader. # The requested --arch still configures processor/bitness after the IDB opens. # When opening a system binary (e.g. /usr/bin/ls), specify a writable project path ida-rpc open /usr/bin/ls --project /tmp/ls_analysis.i64 --arch x86 --detach # Set default project for subsequent commands export IDA_RPC_PROJECT=/path/to/binary.i64 # Query functions ida-rpc functions --limit 10 # Decompile main ida-rpc decompile main # Rename a function ida-rpc rename-function sub_401000 my_func # List all active daemons ida-rpc list
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 494 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # SKILL.md — ida-rpc
- How to use `ida-rpc` as a reverse-engineering skill inside an agent workflow.
- ## What This Skill Provides
- Direct, structured access to IDA Pro's analysis engine without GUI interaction. Commands print human-readable text by default; pass `--json` (before the subcommand) or set `IDA_RPC_JSON=1` for JSON. No screen scraping, no MCP protocol overhead. Works in both interactive (GUI) and automation (headless) modes.
- ## When to Use This Skill
- - You need to **decompile, disassemble, or analyze** a binary.
- - You need **cross-references, function lists, imports, exports, or strings**.
- - You need to **rename functions, set comments, or create data types** programmatically.
- - You need **segment editing, processor context switching (ARM/Thumb), or assembly patching**.
- - You are working in an **automation pipeline** or **multi-agent system**.
- ## What this skill requires
- - Run Unix-socket RPC queries outside the sandbox. `ida-rpc-codex` starts a
- loopback TCP session whose RPC commands can run inside the sandbox.
- ## Quick Start Workflow
- ### 1. Discover capabilities and project path
- ```bash
- ida-rpc capabilities
- ida-rpc find-project /path/to/binary-or-existing.i64
- ida-rpc list-loaders /path/to/binary
- ```
- Use `capabilities` as the stable automation probe. It describes the supported
- command groups and the recommended agent workflow. Add `--json` for machine-readable
- output.
- ### 2. Start the Daemon
- ```bash
- # Open a binary and start the daemon
- ida-rpc open /path/to/binary --arch <arch> --headless --detach
- # Open an existing database (.i64 or .idb)
- ida-rpc open --project /path/to/existing.i64 --arch <arch> --headless --detach
- # For raw binaries, specify architecture and base address
- ida-rpc open /path/to/raw.bin --arch arm --base 0x8000 --loader raw --headless --detach
- # For custom loaders, first list candidates, then force the loader if needed
- ida-rpc list-loaders /path/to/loader.bin
- ida-rpc open /path/to/loader.bin --arch arm --loader miniloader --headless --detach
- # When opening a system binary (e.g. /usr/bin/ls), specify a writable project path
- ida-rpc open /usr/bin/ls --project /tmp/ls_analysis.i64 --arch x86 --headless --detach
- ```
- ### 3. Set the default project
- ```bash
- export IDA_RPC_PROJECT=/path/to/binary.i64
- ```
- ### 4. Check status and list loaded binaries
- ```bash
- # Check if a daemon is running for a project
- ida-rpc status --project /tmp/ls_analysis.i64
- # List all currently loaded binaries in a project
- ida-rpc list-binaries --project /tmp/ls_analysis.i64
- # List all active ida-rpc daemons on this machine
- ida-rpc list
- ```
- ### 5. Run analysis commands
- Commands print human-readable text by default. Add `--json` (before the
- subcommand) or set `IDA_RPC_JSON=1` when you need structured output for `jq`
- or other tools.
- ```bash
- # List functions (paginated)
- ida-rpc functions --limit 20
- # Decompile a function
- ida-rpc decompile main
- # Search for strings containing "password"
- ida-rpc strings "password" --limit 20
- # Find byte pattern
- ida-rpc find-bytes "55 8b ec 83 ec"
- # Get cross-references to a function
- ida-rpc xrefs-to target_function
- # Read raw bytes at an address
- ida-rpc read-bytes 0x401000 64
- ```
- ### 6. Make annotations
- ```bash
- # Rename a function
- ida-rpc rename-function sub_401000 my_awesome_function
- # Set a comment
- ida-rpc set-comment 0x401020 "This is the entry point"
- # Create a struct
- ida-rpc create-struct my_struct "int" field1 "char" field2
- # Set a bookmark
- ida-rpc set-bookmark 0x401000 --type Analysis --comment "Suspicious loop"
- ```
- ### 7. Save and stop
- ```bash
- ida-rpc save
- ida-rpc stop
- ```
- ## Command Reference for Agents
- ### Lifecycle
- | Command | Args | Description |
- |---------|------|-------------|
- | `capabilities` | | Print agent-discoverable command capabilities |
- | `find-project <binary-or-idb>` | | Resolve IDB path, socket path, session state, and recommended start command |
- | `list-loaders [binary] [--ida-install-dir DIR]` | | List loader aliases, installed IDA loaders, and file-specific candidates |
- | `open <binary-or-idb> --arch <arch> [--project <idb>] [--loader <name>] [--headless] [--detach]` | | Agent-friendly alias for `start` |
- | `start <binary> --arch <arch> [--project <idb>] [--base <addr>] [--loader <name>] [--headless] [--detach] [--clean]` | | Open binary and start daemon |
- | `start --project <idb> --arch <arch> [--headless] [--detach] [--clean]` | | Open an existing database |
- | `stop --project <idb>` | | Stop daemon |
- | `status --project <idb>` | | Check health, launch arch, loaded processor/settings, and loaded binary |
- | `restart --project <idb> [--headless] [--clean]` | | Restart daemon |
- | `list` | | List all active projects/daemons |
- | `list-binaries --project <idb>` | | List loaded binaries with arch, bits, endian, format, and base address |
- Loader aliases accepted by `--loader` include:
- | Alias | IDA loader string |
- |-------|-------------------|
- | `raw`, `binary`, `bin`, `dump` | `Binary file` |
- | `miniloader`, `rk-miniloader`, `rockchip-miniloader` | `Rockchip MiniLoaderAll / LDR` |
- | `uboot-fit`, `rk-uboot` | `Rockchip U-Boot FIT image` |
- | `rkns` | `Rockchip RKNS IDB/SPL image` |
- ### Analysis & Listing
- | Command | Args | Description |
- |---------|------|-------------|
- | `functions [--limit N] [--offset N] [--with-body]` | | List functions with optional pagination |
- | `imports` | | List imported symbols |
- | `exports` | | List exported symbols |
- | `metadata` | | Binary metadata (arch, bits, format, base addr) |
- | `relocations [--limit N]` | | List relocation/fixup entries |
- | `calling-conventions` | | List valid calling conventions for current processor |
- | `strings [query] [--limit N]` | | Search strings (empty query = all) |
- | `symbols <query> [--limit N]` | | Search named symbols |
- | `find-bytes <pattern> [--limit N]` | | Byte pattern search (supports `??` wildcards) |
- | `memory-map` | | List memory segments with RWX permissions |
- | `segments` | | Alias for memory-map (explicit segment listing) |
- | `basefind <path> [--max-results N] [--min-abs-refs N] [--str-len N] [--diff-len N] [--samplerate N] [--no-filename-hints]` | | Scan a flat 32-bit binary to determine its load base (runs locally, no daemon needed) |
- ### Decompilation & Disassembly
- | Command | Args | Description |
- |---------|------|-------------|
- | `decompile <func> [--timeout N]` | | Decompile function to pseudo-C |
- | `decompile-all [--limit N] [--function <filter>]` | | Bulk decompile all functions |
- | `basic-blocks <func> [--limit N]` | | CFG basic blocks with successors/predecessors |
- | `disassemble <address> [--count N]` | | Disassemble instructions (default 20, max 1000) |
- | `assemble <address> <instruction>` | | Assemble instruction text (requires Keystone Engine) |
- | `read-bytes <address> <length>` | | Hex dump with ASCII |
- | `write-bytes <address> <hex>` | | Patch bytes (max 4096) |
- ### Cross-References
- | Command | Args | Description |
- |---------|------|-------------|
- | `xrefs-to <target> [--limit N]` | | References **to** target (function name or address) |
- | `xrefs-from <target> [--limit N] [--no-stack]` | | References **from** target |
- ### Annotations & Modifications
- | Command | Args | Description |
- |---------|------|-------------|
- | `rename-function <target> <new_name>` | | Rename function |
- | `rename-symbol <address> <new_name> [--create]` | | Rename symbol at address |
- | `create-label <address> <name>` | | Create a named label |
- | `set-comment <address> <comment> [--type plate\|pre\|post\|eol\|repeatable]` | | Set comment |
- | `set-signature <target> <signature>` | | Set function prototype (C syntax) |
- | `set-data-type <address> <type>` | | Set data type (byte, word, dword, qword, string, or C decl) |
- | `create-function <address> [--name N]` | | Create function at address |
- | `delete-function <target>` | | Delete a function definition |
- | `create-instruction <address>` | | Mark bytes at address as an instruction |
- | `undefine <address> [length]` | | Undefine instruction or data at address |
- | `set-thunk <target> [--thunk-target <addr>] [--clear]` | | Mark/unmark function as thunk |
- | `set-calling-convention <target> <convention>` | | Change function calling convention |
- | `batch-rename --from-file <json>` | | Bulk rename functions/symbols |
- | `batch-set-comment --from-file <json>` | | Bulk set comments |
- | `batch --from-file <json>` | | Execute multiple RPC commands in one batch |
- ### Lumina
- Lumina commands use the primary or secondary Lumina server configured in IDA
- (`Options > General > Lumina`) or overridden for the IDA session with
- `-Olumina:...` / `-Osecondary_lumina:...`. Credentials are not returned.
- | Command | Args | Description |
- |---------|------|-------------|
- | `lumina-config [--secondary]` | | Report Lumina configuration source and whether a configured client is available |
- | `lumina-pull-signatures [target] [--all] [--apply/--no-apply] [--force] [--seen-file] [--secondary]` | | Pull function signatures/metadata from Lumina |
- | `lumina-push-signatures [target] [--all] [--mode better\|override\|no-override\|merge] [--min-func-size N] [--secondary]` | | Push function signatures/metadata to Lumina |
- ### Data Types
- | Command | Args | Description |
- |---------|------|-------------|
- | `create-struct <name> <fields...> [--if-not-exists] [--or-replace]` | | Fields as `TYPE NAME TYPE NAME ...` pairs |
- | `create-union <name> <fields...> [--if-not-exists] [--or-replace]` | | Same pair format as struct |
- | `create-enum <name> [values...] [--size 1\|2\|4\|8]` | | Values as `NAME VALUE NAME VALUE ...` pairs |
- | `modify-struct <name> --action {rename,retype,delete,set_comment} --field <name>` | | Modify an existing struct field |
- | `modify-enum <name> --action {add,remove} --member <name> [--value N]` | | Add/remove enum members |
- | `list-data-types [--category all\|struct\|enum\|union] [--query Q] [--limit N]` | | List defined types |
- | `list-labels <address> [--end <addr>] [--limit N]` | | List symbols at or near an address |
- | `set-equate <address> <operand> <enum> [--clear]` | | Attach enum to instruction operand |
- | `list-equates [--address <addr>] [--end <addr>] [--limit N]` | | List all enum operands |
- | `clear-data-range <start> [--end <addr> \| --length N]` | | Undefine data in a range |
- | `apply-data-type-range <start> <type> [--end <addr> \| --length N]` | | Stamp a type across a range |
- ### Segments
- | Command | Args | Description |
- |---------|------|-------------|
- | `add-segment <start> <end> [--name N] [--class C]` | | Create a new segment |
- | `edit-segment <start> [--name N] [--class C] [--perm-read/--no-perm-read ...] [--bitness 0\|1\|2]` | | Modify segment name, class, permissions, or bitness |
- | `delete-segment <start>` | | Delete a segment |
- ### Processor Context
- | Command | Args | Description |
- |---------|------|-------------|
- | `get-processor-context [--address <addr>] [--register <name>]` | | Read processor context registers (e.g., ARM T-bit) |
- | `set-processor-context <address> <register> <value> [--end <addr>]` | | Set processor context register over a range |
- ### Namespaces
- | Command | Args | Description |
- |---------|------|-------------|
- | `create-namespace <namespace> [--parent <ns>]` | | Validate/create namespace |
- | `list-namespaces [--limit N]` | | List all namespaces with symbol counts |
- ### Bookmarks
- | Command | Args | Description |
- |---------|------|-------------|
- | `set-bookmark <address> [--type Note\|Warning\|Error\|Info\|Analysis] [--category C] [--comment M]` | | Set bookmark |
- | `list-bookmarks [--type T] [--address A] [--limit N]` | | List bookmarks |
- | `remove-bookmark <address> [--type T]` | | Remove bookmark |
- ### Tags
- | Command | Args | Description |
- |---------|------|-------------|
- | `tag-function <target> <tag>` | | Tag a function |
- | `untag-function <target> <tag>` | | Remove tag from function |
- | `list-tags` | | List all tags with counts |
- | `functions-by-tag <tag> [--limit N]` | | Find functions by tag |
- ## Agent Workflow Patterns
- ### Pattern 1: Explore → Analyze → Annotate
- ```bash
- # 1. Discover
- ida-rpc functions --limit 50 | jq '.result.functions[].name'
- # 2. Deep-dive
- ida-rpc decompile suspicious_func | jq '.result.c_code'
- ida-rpc xrefs-to suspicious_func | jq '.result.xrefs[]'
- # 3. Annotate findings
- ida-rpc rename-function suspicious_func decrypt_payload
- ida-rpc set-comment 0x401234 "Calls decrypt_payload"
- ida-rpc save
- ```
- ### Pattern 2: Batch String Hunt
- ```bash
- # Find all strings matching a pattern, then decompile their xrefs
- ida-rpc strings "auth" --limit 20 | jq '.result.strings[] | .address'
- # For each string address, find xrefs-to, then decompile the referencing functions
- ```
- ### Pattern 3: Structural Analysis
- ```bash
- # Get memory map
- ida-rpc memory-map | jq '.result.segments[] | select(.execute == true)'
- # Find functions in a specific address range
- ida-rpc functions --address-min 0x401000 --address-max 0x410000
- # Decompile each function in that range
- for name in $(ida-rpc functions --address-min 0x401000 --address-max 0x410000 | jq -r '.result.functions[].name'); do
- ida-rpc decompile "$name"
- done
- ```
- ### Pattern 4: Find Raw Binary Base Address
- When you have a firmware dump or bare-metal image and don't know the load address, use `basefind` before loading:
- ```bash
- # Scan a raw binary for likely base addresses (no daemon needed)
- ida-rpc basefind /path/to/dump.bin --max-results 10
- # Example output:
- # {
- # "candidates": [
- # {"base": "0x8000000", "score": 10025, "refs": 25, "string_refs": 0, "source": "early-pointer"},
- # {"base": "0x8010000", "score": 18, "refs": 18, "string_refs": 0, "source": "absolute"}
- # ]
- # }
- # Use the best candidate to start IDA
- ida-rpc start /path/to/dump.bin --base 0x8000000 --arch arm --headless --detach
- ```
- **Tuning parameters:**
- - `--str-len` (default 10): minimum printable-string length
- - `--diff-len` (default 10): string/pointer delta window length
- - `--samplerate` (default 20): sparse validation rate for large files
- - `--min-abs-refs` (default 4): threshold for absolute-reference candidates
- ### Pattern 5: Loading Raw Binaries and Memory Segments
- When IDA cannot auto-detect the file format (e.g., firmware dumps, bare-metal images), load the raw binary, fix segment bitness/permissions, and then define functions.
- ```bash
- # 1. Start the daemon with a raw binary
- # --base is the byte address (not paragraphs)
- # --arch selects the processor module and auto-configures the segment
- ida-rpc start /path/to/dump.bin \
- --project /tmp/firmware.i64 \
- --base 0x8200000 \
- --arch arm \
- --headless --detach
- # 2. The segment is auto-configured: class=CODE32, bitness=1, read+exec.
- # No manual edit-segment needed when --arch is provided.
- # 3. Create functions at known entry points
- ida-rpc create-function 0x8211170 --name func_entry
- # 4. Disassemble and verify
- ida-rpc disassemble 0x8211170 --count 20
- ida-rpc functions --limit 20
- ```
- **Loading a raw binary with explicit file offset, load address, and size:**
- ```bash
- # Step 1: Create an empty database and start the daemon
- # Pass --arch so add-segment auto-configures class/bitnesss/perms.
- ida-rpc start --project /tmp/firmware.i64 --arch arm --headless --detach
- # Step 2: Create a segment at the target load address
- # Class, bitness, and permissions are auto-configured from --arch.
- ida-rpc add-segment 0x08000000 0x08020000 --name FLASH
- # Step 3: Extract bytes from a specific file offset and load them
- # dd: bs=1 skip=<file_offset> count=<size>
- dd if=/path/to/dump.bin bs=1 skip=0x2000 count=0x10000 of=/tmp/extracted.bin
- python3 -c "import sys; print(open('/tmp/extracted.bin','rb').read().hex())" > /tmp/extracted.hex
- ida-rpc write-bytes 0x08000000 "$(cat /tmp/extracted.hex)"
- # Step 4: Define functions and analyze
- ida-rpc create-function 0x08000000 --name reset_handler
- ida-rpc disassemble 0x08000000 --count 10
- ida-rpc functions --limit 20
- ```
- **Supported `--arch` values for raw binary auto-configuration:**
- | `--arch` value | Processor | Segment class | Bitness | Notes |
- |----------------|-----------|--------------|---------|-------|
- | `arm` | ARM 32-bit (ARM mode) | `CODE32` | 1 (32-bit) | A1/T32 instructions |
- | `thumb` | ARM 32-bit (Thumb mode) | `CODE16` | 1 (32-bit) | **Use this for Thumb-only or mixed ARM/Thumb firmware** |
- | `aarch64` | ARM 64-bit | `CODE64` | 2 (64-bit) | Also accepted: `arm64` |
- | `metapc` | Intel x86 | `CODE` | 1 (32-bit) | 32-bit x86 |
- | `x86` | Intel x86 | `CODE` | 1 (32-bit) | Alias for `metapc` |
- | `x64` | Intel x64 | `CODE64` | 2 (64-bit) | 64-bit x86-64 |
- | `mips` | MIPS (little-endian) | `CODE` | 1 (32-bit) | |
- | `mipsb` | MIPS (big-endian) | `CODE` | 1 (32-bit) | |
- | `mips64` | MIPS 64-bit | `CODE64` | 2 (64-bit) | |
- | `ppc` | PowerPC 32-bit | `CODE` | 1 (32-bit) | |
- | `ppc64` | PowerPC 64-bit | `CODE64` | 2 (64-bit) | |
- **Important notes on architecture selection:**
- - **`thumb` vs `arm`:** For 32-bit ARM firmware that is primarily Thumb code (common in Cortex-M/MCU binaries), use `--arch thumb`. This sets the segment class to `CODE16`, which tells IDA to disassemble in Thumb mode by default. If you later encounter ARM-mode functions, use `set-processor-context` to switch the T-bit (see Pattern 5).
- - For raw binaries, IDA may default to 64-bit addressing even for 32-bit processors. `--arch` is mandatory and auto-configures the segment with the correct bitness and class.
- **Segment class values:** `CODE`, `DATA`, `CONST`, `BSS`, `STACK`, `HEAP`, `XTRN`.
- ### Pattern 6: ARM/Thumb Mode Switching
- ```bash
- # Check current processor context at an address
- ida-rpc get-processor-context --address 0x8000 --register T
- # Switch to Thumb mode (T=1) for a range
- ida-rpc set-processor-context 0x8000 T 1 --end 0x9000
- ```
- ### Pattern 7: Bulk Decompile for Diffing
- ```bash
- # Decompile all functions matching a pattern
- ida-rpc decompile-all --function "parse" --limit 50 | jq '.result.functions[].c_code'
- ```
- ### Pattern 8: Assembly Patching
- ```bash
- # Assemble a nop sled at an address (requires Keystone Engine)
- ida-rpc assemble 0x401000 "nop"
- ida-rpc assemble 0x401001 "jmp 0x401050"
- ```
- ## JSON Response Structure
- Every successful response:
- ```json
- {
- "id": "<uuid>",
- "ok": true,
- "result": { ... }
- }
- ```
- Every error response:
- ```json
- {
- "id": "<uuid>",
- "ok": false,
- "error": "ValueError",
- "message": "Function 'foo' not found."
- }
- ```
- Parse with `jq .result` to extract the payload, or check `.ok` first.
- ## Environment Variables
- | Variable | Purpose |
- |----------|---------|
- | `IDA_RPC_PROJECT` | Default `--project` path |
- | `IDA_INSTALL_DIR` | Path to IDA Pro installation (for auto-launch) |
- | `IDA_RPC_STATE_DIR` | Directory for session JSON files (default: next to IDB) |
- ## Troubleshooting
- | Symptom | Fix |
- |---------|-----|
- | `DaemonNotRunning` | Run `ida-rpc start <binary> --arch <arch> --headless --detach` |
- | Socket exists but daemon unresponsive | `ida-rpc stop` then `ida-rpc start <binary> --arch <arch>` |
- | Hex-Rays errors | Ensure Hex-Rays decompiler is installed and licensed |
- | `Function can be called from the main thread only` | Internal bug — handler forgot `ctx.run_on_main_thread()` |
- | Changes lost after stop | Forgot `ida-rpc save` — mutations are auto-saved by most handlers, but explicit save is safest |
- | Assembler fails | Install Keystone Engine: `pip install keystone-engine` |
- ## Programmatic Use (Python)
- ```python
- from ida_rpc.client import send_request
- from ida_rpc.session import socket_path_for_project
- from pathlib import Path
- sock = socket_path_for_project("/tmp/test.i64")
- resp = send_request(sock, "functions", {"limit": 10})
- print(resp["result"]["functions"])
- ```
- ## Protocol Compatibility Note
- The wire format (`{"id", "cmd", "args"}` → `{"id", "ok", "result/error"}`) is designed to be compatible with ghidra-rpc. If you have existing clients built for Ghidra, point them at the IDA socket path and most read-only commands will work with minimal or no changes.
README.md · README · 390 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # ida-rpc
- 
- (c) B.Kerler 2026
- A JSON-RPC daemon for IDA Pro, inspired by [ghidra-rpc](https://github.com/cellebrite-labs/ghidra-rpc).
- Exposes IDA Pro reverse engineering capabilities over a local socket for
- integration with LLM agents, automation pipelines, and multi-agent setups.
- Linux and macOS use Unix domain sockets; Windows uses loopback TCP because
- ``socket.AF_UNIX`` is not available in all supported Windows IDA/Python setups.
- Set `IDA_RPC_TRANSPORT=tcp` to use loopback TCP on Linux or macOS.
- On Windows, the daemon publishes its OS-assigned TCP port in the project endpoint
- marker, avoiding ports reserved by virtualization or other local software.
- ### Codex sandbox setup
- Install this package with `pip install -e .`, then run `ida-rpc-codex` from
- the project directory to start a new Codex session. The launcher selects TCP,
- permits only `127.0.0.1` command networking, and lets IDA write its user
- directory (`$IDAUSR` or `~/.idapro`) in the workspace-write sandbox.
- Run `ida-rpc` commands normally in that session. To pass Codex options, append
- them to `ida-rpc-codex`.
- Stop any existing Unix-socket daemon for an IDB before opening that IDB in the
- TCP session. The transport refuses to replace its live socket. Sessions that
- use the default Unix transport still need outside-sandbox execution.
- ## Features
- - **Human-readable CLI output** by default, with `--json` or `IDA_RPC_JSON=1` for structured JSON — faster and more reliable than MCP
- - **Headless mode** — run via `ida -A` for CI/automation
- - **GUI mode** — works inside the interactive IDA Pro session
- - **Protocol compatible** with ghidra-rpc's CLI design
- - **Full feature set**: decompile, disassemble, xrefs, rename, types, structs, enums, bookmarks, search, memory maps, patches, segments, processor context, namespaces, tags
- ## Quick Start
- ### Install
- **Via the IDA Plugin Manager (recommended):**
- ```bash
- hcli plugin install ida-rpc
- ```
- **Or in the script path:**
- ```bash
- hcli plugin install .
- ```
- **Or manually:**
- ```bash
- pip install -e /path/to/ida-rpc
- ln -s /path/to/ida-rpc/ida_rpc_plugin.py $IDAUSR/plugins/ida_rpc_plugin.py
- ```
- Default `$IDAUSR` paths:
- - **Windows:** `%APPDATA%\Hex-Rays\IDA Pro\`
- - **macOS:** `~/Library/Application Support/IDA Pro/`
- - **Linux:** `~/.idapro/`
- ### Start the daemon
- For agents and automation, first ask the tool what it can do and which IDB path
- to use:
- ```bash
- ida-rpc capabilities
- ida-rpc find-project /path/to/binary-or-existing.i64
- ida-rpc list-loaders /path/to/binary
- ```
- ```bash
- # Start headless daemon from a binary (headless is the default)
- ida-rpc open /path/to/binary --arch <arch> --detach
- # Or open an existing IDB
- ida-rpc open --project /path/to/existing.i64 --arch <arch> --detach
- # For raw binaries, specify architecture and base address.
- # The segment is auto-configured (class, bitness, permissions) based on arch.
- ida-rpc open /path/to/raw.bin --arch arm --base 0x8000 --detach
- # Open in GUI mode instead
- ida-rpc open /path/to/binary --arch <arch> --gui --detach
- # Existing IDBs ignore raw import options such as --base and --loader.
- # The requested --arch still configures processor/bitness after the IDB opens.
- # When opening a system binary (e.g. /usr/bin/ls), specify a writable project path
- ida-rpc open /usr/bin/ls --project /tmp/ls_analysis.i64 --arch x86 --detach
- # Set default project for subsequent commands
- export IDA_RPC_PROJECT=/path/to/binary.i64
- # Query functions
- ida-rpc functions --limit 10
- # Decompile main
- ida-rpc decompile main
- # Rename a function
- ida-rpc rename-function sub_401000 my_func
- # List all active daemons
- ida-rpc list
- ```
- ## Command Reference
- Commands print human-readable text by default. Pass `--json` (before the subcommand) or set `IDA_RPC_JSON=1` to get structured JSON. Commands that operate on an open database accept `--project <idb>` or read `IDA_RPC_PROJECT`.
- ### Lifecycle
- | Command | Description |
- |---------|-------------|
- | `ida-rpc capabilities` | Print agent-discoverable command capabilities |
- | `ida-rpc find-project <binary-or-idb>` | Resolve the IDB path, socket path, and recommended start command |
- | `ida-rpc list-loaders [binary] [--ida-install-dir DIR]` | List loader aliases, installed IDA loaders, and file-specific candidates |
- | `ida-rpc open <binary> --arch <arch> [--project <idb>] [--base <addr>] [--detach] [--clean]` | Agent-friendly alias for `start` (headless by default) |
- | `ida-rpc start <binary> --arch <arch> [--project <idb>] [--base <addr>] [--detach] [--clean]` | Open binary and start daemon; `--base` applies when importing a new IDB |
- | `ida-rpc start --project <idb> --arch <arch> [--detach] [--clean]` | Open an existing database |
- | `ida-rpc stop --project <idb> [--clean]` | Stop daemon; `--clean` removes IDA companion files (default: false) |
- | `ida-rpc status --project <idb>` | Check daemon health, launch arch, loaded processor/settings, and loaded binary |
- | `ida-rpc restart --project <idb> [--gui] [--clean]` | Restart daemon (headless by default; `--gui` preserves GUI mode) |
- | `ida-rpc list` | List all active projects/daemons |
- | `ida-rpc list-binaries --project <idb>` | List loaded binaries with arch, bits, endian, format, and base address |
- | `ida-rpc save --project <idb>` | Save the database |
- ### Analysis & Listing
- | Command | Description |
- |---------|-------------|
- | `functions [--limit N] [--offset N] [--with-body] [--address-min A] [--address-max A]` | List functions |
- | `function <func>` | Show function metadata, signature, and body |
- | `function-info <func>` | Rich function summary |
- | `function-items <func> [--limit N]` | Instructions/items in a function |
- | `function-chunks <func>` | Function chunks/ranges |
- | `imports` | List imports |
- | `exports` | List exports |
- | `add-entry <address> [name] [--ordinal N] [--no-makecode]` | Add an entry point |
- | `rename-entry <ordinal> <name>` | Rename an entry point |
- | `metadata` | Binary metadata (arch, bits, endian, format, base address) |
- | `relocations [--limit N]` | List relocation/fixup entries |
- | `calling-conventions` | List valid calling conventions for current processor |
- | `strings [query] [--limit N]` | Search strings (empty query = all) |
- | `find-string <query> [--limit N] [--address A]` | Find strings matching a query |
- | `symbols <query> [--limit N] [--offset N]` | Search named symbols |
- | `find-bytes <pattern> [--limit N] [--address A]` | Byte pattern search (supports `??` wildcards) |
- | `memory-map` | Memory segments with RWX permissions |
- | `list-problems [--type T] [--limit N]` | List IDA analysis problems |
- | `file-offset <address>` | Convert EA to file offset |
- | `file-offset-to-ea <offset>` | Convert file offset to EA |
- | `basefind <path> [--max-results N] [--min-abs-refs N] [--str-len N] [--diff-len N] [--samplerate N] [--no-filename-hints]` | Scan a flat 32-bit binary to determine its load base (runs locally) |
- | `segments` | Alias for memory-map |
- ### Decompilation & Disassembly
- | Command | Description |
- |---------|-------------|
- | `decompile <func> [--timeout N]` | Decompile function to pseudo-C |
- | `decompile-all [--limit N] [--function <filter>]` | Bulk decompile all functions |
- | `decompile-lvars <func>` | List decompiler local variables |
- | `set-lvar-name <func> <lvar> <new_name>` | Rename a decompiler local variable |
- | `set-lvar-type <func> <lvar> <type>` | Set a decompiler local variable type |
- | `decompile-microcode <func> [--maturity N]` | Dump Hex-Rays microcode |
- | `decompiler-xrefs <func> <target>` | Find decompiler-level target references |
- | `basic-blocks <func> [--limit N]` | CFG basic blocks with successors/predecessors |
- | `function-graph <func>` | Export a function graph |
- | `call-graph [--mode callers\|callees\|both] [--title T]` | Export a call graph |
- | `get-switch-info <address>` | Inspect switch/jump-table metadata |
- | `disassemble <address> [--count N]` | Disassemble instructions (default 20, max 1000) |
- | `assemble <address> <instruction>` | Assemble instruction text (requires Keystone Engine) |
- | `read-bytes <address> <length>` | Hex dump with ASCII |
- | `read-string <address> [--strtype T]` | Read a string |
- | `create-string <address> <length> [--strtype T]` | Create a string item |
- | `write-bytes <address> <hex>` | Patch bytes (max 4096) |
- | `list-patches [--start A] [--end B] [--limit N]` | List patched bytes |
- | `revert-patch <start> [--end B]` | Revert patched bytes |
- | `patch-byte <address> <value>` | Patch one byte |
- | `patch-word <address> <value>` | Patch a 16-bit value |
- | `patch-dword <address> <value>` | Patch a 32-bit value |
- | `patch-qword <address> <value>` | Patch a 64-bit value |
- ### Cross-References
- | Command | Description |
- |---------|-------------|
- | `xrefs-to <target> [--limit N]` | References to target |
- | `xrefs-from <target> [--limit N] [--no-stack]` | References from target |
- ### Annotations & Modifications
- | Command | Description |
- |---------|-------------|
- | `rename-function <target> <new_name>` | Rename function |
- | `rename-symbol <address> <new_name> [--create]` | Rename symbol |
- | `create-label <address> <name>` | Create label |
- | `set-comment <address> <comment> [--type plate\|pre\|post\|eol\|repeatable]` | Set comment |
- | `set-signature <target> <sig>` | Set function prototype |
- | `set-data-type <address> <type>` | Set data type |
- | `create-function <address> [--name N]` | Create function at address |
- | `delete-function <target>` | Delete a function definition |
- | `create-instruction <address>` | Mark bytes at address as an instruction |
- | `undefine <address> [length]` | Undefine instruction or data at address |
- | `set-thunk <target> [--thunk-target <addr>] [--clear]` | Mark/unmark function as thunk |
- | `set-calling-convention <target> <convention>` | Change function calling convention |
- | `set-function-color <func> <color>` | Set function color |
- | `function-frame <func>` | Inspect a function frame |
- | `list-stack-vars <func>` | List stack variables |
- | `rename-stack-var <func> (--offset N \| --old-name NAME) --new-name NAME` | Rename a stack variable |
- | `set-stack-var-type <func> (--offset N \| --name NAME) --type TYPE` | Set stack variable type |
- | `list-reg-vars <func>` | List register variables |
- | `stack-var-xrefs <func> [--offset N] [--name NAME]` | Find stack variable references |
- | `batch-rename --mode {function,symbol} --from-file <json>` | Bulk rename |
- | `batch-set-comment --from-file <json>` | Bulk set comments |
- | `batch --from-file <json>` | Execute multiple RPC commands in one batch |
- ### Lumina
- Lumina commands use the primary or secondary Lumina server configured in IDA
- (`Options > General > Lumina`) or overridden for the IDA session with
- `-Olumina:...` / `-Osecondary_lumina:...`. Credentials are not returned.
- | Command | Description |
- |---------|-------------|
- | `lumina-config [--secondary]` | Report Lumina configuration source and whether a configured client is available |
- | `lumina-pull-signatures [target] [--all] [--apply/--no-apply] [--force] [--seen-file] [--secondary]` | Pull function signatures/metadata from Lumina |
- | `lumina-push-signatures [target] [--all] [--mode better\|override\|no-override\|merge] [--min-func-size N] [--secondary]` | Push function signatures/metadata to Lumina |
- ### Data Types
- | Command | Description |
- |---------|-------------|
- | `create-struct <name> <fields...> [--if-not-exists] [--or-replace]` | Create struct (fields as `TYPE NAME ...` pairs) |
- | `create-union <name> <fields...> [--if-not-exists] [--or-replace]` | Create union |
- | `create-enum <name> [values...] [--size 1\|2\|4\|8]` | Create enum (values as `NAME VALUE ...` pairs) |
- | `modify-struct <name> --action {rename,retype,delete,set_comment} --field <name>` | Modify struct field |
- | `modify-enum <name> --action {add,remove} --member <name> [--value N]` | Modify enum |
- | `list-data-types [--category all\|struct\|enum\|union] [--query Q] [--limit N]` | List defined types |
- | `list-labels <address> [--end <addr>] [--limit N]` | List symbols at or near an address |
- | `set-equate <address> <operand> <enum> [--clear]` | Attach enum to instruction operand |
- | `list-equates [--address <addr>] [--end <addr>] [--limit N]` | List all enum operands |
- | `clear-data-range <start> [--end <addr> \| --length N]` | Undefine data in a range |
- | `apply-data-type-range <start> <type> [--end <addr> \| --length N] [--type-size N]` | Stamp a type across a range |
- | `import-til <path>` | Import a type library |
- | `export-til <path>` | Export type information |
- | `delete-type <name>` | Delete a named type |
- | `get-type-info <name>` | Show type information |
- ### Segments
- | Command | Description |
- |---------|-------------|
- | `add-segment <start> <end> [--name N] [--class C]` | Create a new segment (class defaults to CODE32/CODE16/CODE64 based on `--arch`) |
- | `edit-segment <start> [--name N] [--class C] [--perm-read/--no-perm-read ...] [--bitness 0\|1\|2]` | Modify segment |
- | `delete-segment <start>` | Delete a segment |
- ### Colors, Operands, and Exceptions
- | Command | Description |
- |---------|-------------|
- | `operand-struct-path <address> <operand>` | Inspect operand struct path information |
- | `set-color <address> <color>` | Set item color |
- | `get-color <address>` | Get item color |
- | `del-color <address>` | Remove item color |
- | `list-try-blocks [--start A] [--end B]` | List exception/try blocks |
- ### Processor Context
- | Command | Description |
- |---------|-------------|
- | `get-processor-context [--address <addr>] [--register <name>]` | Read processor context registers |
- | `set-processor-context <address> <register> <value> [--end <addr>]` | Set processor context register |
- ### Namespaces
- | Command | Description |
- |---------|-------------|
- | `create-namespace <namespace> [--parent <ns>]` | Validate/create namespace |
- | `list-namespaces [--limit N]` | List all namespaces with symbol counts |
- ### Bookmarks
- | Command | Description |
- |---------|-------------|
- | `set-bookmark <address> [--type Note\|Warning\|Error\|Info\|Analysis] [--category C] [--comment M]` | Set bookmark |
- | `list-bookmarks [--type T] [--address A] [--limit N]` | List bookmarks |
- | `remove-bookmark <address> [--type T]` | Remove bookmark |
- ### Tags
- | Command | Description |
- |---------|-------------|
- | `tag-function <target> <tag>` | Tag a function |
- | `untag-function <target> <tag>` | Remove tag from function |
- | `list-tags` | List all tags with counts |
- | `functions-by-tag <tag> [--limit N]` | Find functions by tag |
- ### Debugger
- | Command | Description |
- |---------|-------------|
- | `debug-select-backend <backend> [--remote]` | Select an IDA debugger backend by internal name |
- | `debug-start [path] [--args A] [--sdir D] [--backend B] [--remote] [--suspend-at start\|entry\|none] [--wait-timeout N]` | Optionally select a backend, then start and wait for initial suspension |
- | `debug-attach <pid> [--backend B] [--remote] [--wait-timeout N]` | Optionally select a backend, then attach and wait for initial suspension |
- | `debug-detach`, `debug-exit` | Detach or exit debugger |
- | `debug-continue [--wait-timeout N]`, `debug-suspend [--wait-timeout N]` | Continue or suspend execution and wait for the resulting state |
- | `debug-step-into [--wait-timeout N]`, `debug-step-over [--wait-timeout N]`, `debug-run-to <address> [--wait-timeout N]` | Step or run to an address, waiting for suspension or exit |
- | `debug-status` | Show debugger status |
- | `debug-get-registers`, `debug-set-register <reg> <value>` | Read or write registers |
- | `debug-read-memory <address> <length>`, `debug-write-memory <address> <hex>` | Read or write debug memory |
- | `debug-breakpoints`, `debug-add-breakpoint <address>`, `debug-delete-breakpoint <address>`, `debug-enable-breakpoint <address> --enabled/--disabled` | Manage breakpoints |
- | `debug-stack-trace`, `debug-modules`, `debug-threads` | Inspect runtime state |
- Use repeated `--register` options to request named registers without returning
- the full architecture-specific register set, for example
- `ida-rpc debug-get-registers --register RIP --register RCX`.
- Backend names are IDA plugin identifiers rather than display labels. For
- example, use `win32` for the local Windows debugger, `linux` for the local
- Linux debugger, and `mac` for the local macOS debugger. The backend can be
- selected separately or atomically with process startup:
- ```bash
- ida-rpc debug-select-backend win32 --project /path/to/program.i64
- ida-rpc debug-start /path/to/program.exe --backend win32 --project /path/to/program.i64
- ```
- ### Navigation (GUI only)
- | Command | Description |
- |---------|-------------|
- | `goto <target> [function\|address]` | Jump to function or address in IDA UI |
- ## Environment Variables
- | Variable | Purpose |
- |----------|---------|
- | `IDA_RPC_PROJECT` | Default `--project` path |
- | `IDA_INSTALL_DIR` | Path to IDA Pro installation (for auto-launch) |
- | `IDA_RPC_STATE_DIR` | Directory for session JSON files (default: next to IDB) |
- ## Agent Usage
- Codex, Kimi, and other coding agents should use `ida-rpc` automatically for
- IDA-based reverse engineering. The repository includes `AGENTS.md`, `KIMI.md`,
- and `SKILL.md` so agents can discover the intended workflow after install.
- A complete, progressively disclosed Codex skill is available at
- [`skills/idarpc/`](skills/idarpc/). Its compact entrypoint routes agents to
- focused references for setup, static analysis, edits, firmware, debugging,
- internals, troubleshooting, and common reverse-engineering workflows, so
- unrelated documentation does not need to be loaded for every task.
- The stable automation probe is:
- ```bash
- ida-rpc capabilities
- ```
- The stable project-resolution probe is:
- ```bash
- ida-rpc find-project /path/to/binary-or-idb
- ```
- After that, use `open --arch <arch>`, `status`, `functions`, `decompile`, `disassemble`,
- `strings`, `xrefs-to`, `xrefs-from`, `rename-function`, `set-comment`, and
- `save`. Commands print human-readable text on stdout by default; pass `--json`
- (before the subcommand) or set `IDA_RPC_JSON=1` for JSON output. Unexpected
- CLI/RPC failures are reported on stderr as `Error: <error>: <message>` (or JSON
- with `--json`); set `IDA_RPC_DEBUG=1` to also print tracebacks on stderr.
- ## Architecture
- ```
- ┌─────────────┐ Unix Socket ┌──────────────────────────────┐
- │ LLM agent │ ──── JSON/newline ──→ │ ida-rpc daemon │
- │ (via CLI) │ ←── JSON/newline ─── │ (IDA Python plugin + server)│
- └─────────────┘ └──────────────────────────────┘
- ```
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.