Skip to content
Back to search

https://github.com/bkerler/ida_rpc

SkillWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bkerler--ida-rpc/badge.svg)](/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

i

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)

  1. # SKILL.md — ida-rpc
  2. How to use `ida-rpc` as a reverse-engineering skill inside an agent workflow.
  3. ## What This Skill Provides
  4. 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.
  5. ## When to Use This Skill
  6. - You need to **decompile, disassemble, or analyze** a binary.
  7. - You need **cross-references, function lists, imports, exports, or strings**.
  8. - You need to **rename functions, set comments, or create data types** programmatically.
  9. - You need **segment editing, processor context switching (ARM/Thumb), or assembly patching**.
  10. - You are working in an **automation pipeline** or **multi-agent system**.
  11. ## What this skill requires
  12. - Run Unix-socket RPC queries outside the sandbox. `ida-rpc-codex` starts a
  13. loopback TCP session whose RPC commands can run inside the sandbox.
  14. ## Quick Start Workflow
  15. ### 1. Discover capabilities and project path
  16. ```bash
  17. ida-rpc capabilities
  18. ida-rpc find-project /path/to/binary-or-existing.i64
  19. ida-rpc list-loaders /path/to/binary
  20. ```
  21. Use `capabilities` as the stable automation probe. It describes the supported
  22. command groups and the recommended agent workflow. Add `--json` for machine-readable
  23. output.
  24. ### 2. Start the Daemon
  25. ```bash
  26. # Open a binary and start the daemon
  27. ida-rpc open /path/to/binary --arch <arch> --headless --detach
  28. # Open an existing database (.i64 or .idb)
  29. ida-rpc open --project /path/to/existing.i64 --arch <arch> --headless --detach
  30. # For raw binaries, specify architecture and base address
  31. ida-rpc open /path/to/raw.bin --arch arm --base 0x8000 --loader raw --headless --detach
  32. # For custom loaders, first list candidates, then force the loader if needed
  33. ida-rpc list-loaders /path/to/loader.bin
  34. ida-rpc open /path/to/loader.bin --arch arm --loader miniloader --headless --detach
  35. # When opening a system binary (e.g. /usr/bin/ls), specify a writable project path
  36. ida-rpc open /usr/bin/ls --project /tmp/ls_analysis.i64 --arch x86 --headless --detach
  37. ```
  38. ### 3. Set the default project
  39. ```bash
  40. export IDA_RPC_PROJECT=/path/to/binary.i64
  41. ```
  42. ### 4. Check status and list loaded binaries
  43. ```bash
  44. # Check if a daemon is running for a project
  45. ida-rpc status --project /tmp/ls_analysis.i64
  46. # List all currently loaded binaries in a project
  47. ida-rpc list-binaries --project /tmp/ls_analysis.i64
  48. # List all active ida-rpc daemons on this machine
  49. ida-rpc list
  50. ```
  51. ### 5. Run analysis commands
  52. Commands print human-readable text by default. Add `--json` (before the
  53. subcommand) or set `IDA_RPC_JSON=1` when you need structured output for `jq`
  54. or other tools.
  55. ```bash
  56. # List functions (paginated)
  57. ida-rpc functions --limit 20
  58. # Decompile a function
  59. ida-rpc decompile main
  60. # Search for strings containing "password"
  61. ida-rpc strings "password" --limit 20
  62. # Find byte pattern
  63. ida-rpc find-bytes "55 8b ec 83 ec"
  64. # Get cross-references to a function
  65. ida-rpc xrefs-to target_function
  66. # Read raw bytes at an address
  67. ida-rpc read-bytes 0x401000 64
  68. ```
  69. ### 6. Make annotations
  70. ```bash
  71. # Rename a function
  72. ida-rpc rename-function sub_401000 my_awesome_function
  73. # Set a comment
  74. ida-rpc set-comment 0x401020 "This is the entry point"
  75. # Create a struct
  76. ida-rpc create-struct my_struct "int" field1 "char" field2
  77. # Set a bookmark
  78. ida-rpc set-bookmark 0x401000 --type Analysis --comment "Suspicious loop"
  79. ```
  80. ### 7. Save and stop
  81. ```bash
  82. ida-rpc save
  83. ida-rpc stop
  84. ```
  85. ## Command Reference for Agents
  86. ### Lifecycle
  87. | Command | Args | Description |
  88. |---------|------|-------------|
  89. | `capabilities` | | Print agent-discoverable command capabilities |
  90. | `find-project <binary-or-idb>` | | Resolve IDB path, socket path, session state, and recommended start command |
  91. | `list-loaders [binary] [--ida-install-dir DIR]` | | List loader aliases, installed IDA loaders, and file-specific candidates |
  92. | `open <binary-or-idb> --arch <arch> [--project <idb>] [--loader <name>] [--headless] [--detach]` | | Agent-friendly alias for `start` |
  93. | `start <binary> --arch <arch> [--project <idb>] [--base <addr>] [--loader <name>] [--headless] [--detach] [--clean]` | | Open binary and start daemon |
  94. | `start --project <idb> --arch <arch> [--headless] [--detach] [--clean]` | | Open an existing database |
  95. | `stop --project <idb>` | | Stop daemon |
  96. | `status --project <idb>` | | Check health, launch arch, loaded processor/settings, and loaded binary |
  97. | `restart --project <idb> [--headless] [--clean]` | | Restart daemon |
  98. | `list` | | List all active projects/daemons |
  99. | `list-binaries --project <idb>` | | List loaded binaries with arch, bits, endian, format, and base address |
  100. Loader aliases accepted by `--loader` include:
  101. | Alias | IDA loader string |
  102. |-------|-------------------|
  103. | `raw`, `binary`, `bin`, `dump` | `Binary file` |
  104. | `miniloader`, `rk-miniloader`, `rockchip-miniloader` | `Rockchip MiniLoaderAll / LDR` |
  105. | `uboot-fit`, `rk-uboot` | `Rockchip U-Boot FIT image` |
  106. | `rkns` | `Rockchip RKNS IDB/SPL image` |
  107. ### Analysis & Listing
  108. | Command | Args | Description |
  109. |---------|------|-------------|
  110. | `functions [--limit N] [--offset N] [--with-body]` | | List functions with optional pagination |
  111. | `imports` | | List imported symbols |
  112. | `exports` | | List exported symbols |
  113. | `metadata` | | Binary metadata (arch, bits, format, base addr) |
  114. | `relocations [--limit N]` | | List relocation/fixup entries |
  115. | `calling-conventions` | | List valid calling conventions for current processor |
  116. | `strings [query] [--limit N]` | | Search strings (empty query = all) |
  117. | `symbols <query> [--limit N]` | | Search named symbols |
  118. | `find-bytes <pattern> [--limit N]` | | Byte pattern search (supports `??` wildcards) |
  119. | `memory-map` | | List memory segments with RWX permissions |
  120. | `segments` | | Alias for memory-map (explicit segment listing) |
  121. | `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) |
  122. ### Decompilation & Disassembly
  123. | Command | Args | Description |
  124. |---------|------|-------------|
  125. | `decompile <func> [--timeout N]` | | Decompile function to pseudo-C |
  126. | `decompile-all [--limit N] [--function <filter>]` | | Bulk decompile all functions |
  127. | `basic-blocks <func> [--limit N]` | | CFG basic blocks with successors/predecessors |
  128. | `disassemble <address> [--count N]` | | Disassemble instructions (default 20, max 1000) |
  129. | `assemble <address> <instruction>` | | Assemble instruction text (requires Keystone Engine) |
  130. | `read-bytes <address> <length>` | | Hex dump with ASCII |
  131. | `write-bytes <address> <hex>` | | Patch bytes (max 4096) |
  132. ### Cross-References
  133. | Command | Args | Description |
  134. |---------|------|-------------|
  135. | `xrefs-to <target> [--limit N]` | | References **to** target (function name or address) |
  136. | `xrefs-from <target> [--limit N] [--no-stack]` | | References **from** target |
  137. ### Annotations & Modifications
  138. | Command | Args | Description |
  139. |---------|------|-------------|
  140. | `rename-function <target> <new_name>` | | Rename function |
  141. | `rename-symbol <address> <new_name> [--create]` | | Rename symbol at address |
  142. | `create-label <address> <name>` | | Create a named label |
  143. | `set-comment <address> <comment> [--type plate\|pre\|post\|eol\|repeatable]` | | Set comment |
  144. | `set-signature <target> <signature>` | | Set function prototype (C syntax) |
  145. | `set-data-type <address> <type>` | | Set data type (byte, word, dword, qword, string, or C decl) |
  146. | `create-function <address> [--name N]` | | Create function at address |
  147. | `delete-function <target>` | | Delete a function definition |
  148. | `create-instruction <address>` | | Mark bytes at address as an instruction |
  149. | `undefine <address> [length]` | | Undefine instruction or data at address |
  150. | `set-thunk <target> [--thunk-target <addr>] [--clear]` | | Mark/unmark function as thunk |
  151. | `set-calling-convention <target> <convention>` | | Change function calling convention |
  152. | `batch-rename --from-file <json>` | | Bulk rename functions/symbols |
  153. | `batch-set-comment --from-file <json>` | | Bulk set comments |
  154. | `batch --from-file <json>` | | Execute multiple RPC commands in one batch |
  155. ### Lumina
  156. Lumina commands use the primary or secondary Lumina server configured in IDA
  157. (`Options > General > Lumina`) or overridden for the IDA session with
  158. `-Olumina:...` / `-Osecondary_lumina:...`. Credentials are not returned.
  159. | Command | Args | Description |
  160. |---------|------|-------------|
  161. | `lumina-config [--secondary]` | | Report Lumina configuration source and whether a configured client is available |
  162. | `lumina-pull-signatures [target] [--all] [--apply/--no-apply] [--force] [--seen-file] [--secondary]` | | Pull function signatures/metadata from Lumina |
  163. | `lumina-push-signatures [target] [--all] [--mode better\|override\|no-override\|merge] [--min-func-size N] [--secondary]` | | Push function signatures/metadata to Lumina |
  164. ### Data Types
  165. | Command | Args | Description |
  166. |---------|------|-------------|
  167. | `create-struct <name> <fields...> [--if-not-exists] [--or-replace]` | | Fields as `TYPE NAME TYPE NAME ...` pairs |
  168. | `create-union <name> <fields...> [--if-not-exists] [--or-replace]` | | Same pair format as struct |
  169. | `create-enum <name> [values...] [--size 1\|2\|4\|8]` | | Values as `NAME VALUE NAME VALUE ...` pairs |
  170. | `modify-struct <name> --action {rename,retype,delete,set_comment} --field <name>` | | Modify an existing struct field |
  171. | `modify-enum <name> --action {add,remove} --member <name> [--value N]` | | Add/remove enum members |
  172. | `list-data-types [--category all\|struct\|enum\|union] [--query Q] [--limit N]` | | List defined types |
  173. | `list-labels <address> [--end <addr>] [--limit N]` | | List symbols at or near an address |
  174. | `set-equate <address> <operand> <enum> [--clear]` | | Attach enum to instruction operand |
  175. | `list-equates [--address <addr>] [--end <addr>] [--limit N]` | | List all enum operands |
  176. | `clear-data-range <start> [--end <addr> \| --length N]` | | Undefine data in a range |
  177. | `apply-data-type-range <start> <type> [--end <addr> \| --length N]` | | Stamp a type across a range |
  178. ### Segments
  179. | Command | Args | Description |
  180. |---------|------|-------------|
  181. | `add-segment <start> <end> [--name N] [--class C]` | | Create a new segment |
  182. | `edit-segment <start> [--name N] [--class C] [--perm-read/--no-perm-read ...] [--bitness 0\|1\|2]` | | Modify segment name, class, permissions, or bitness |
  183. | `delete-segment <start>` | | Delete a segment |
  184. ### Processor Context
  185. | Command | Args | Description |
  186. |---------|------|-------------|
  187. | `get-processor-context [--address <addr>] [--register <name>]` | | Read processor context registers (e.g., ARM T-bit) |
  188. | `set-processor-context <address> <register> <value> [--end <addr>]` | | Set processor context register over a range |
  189. ### Namespaces
  190. | Command | Args | Description |
  191. |---------|------|-------------|
  192. | `create-namespace <namespace> [--parent <ns>]` | | Validate/create namespace |
  193. | `list-namespaces [--limit N]` | | List all namespaces with symbol counts |
  194. ### Bookmarks
  195. | Command | Args | Description |
  196. |---------|------|-------------|
  197. | `set-bookmark <address> [--type Note\|Warning\|Error\|Info\|Analysis] [--category C] [--comment M]` | | Set bookmark |
  198. | `list-bookmarks [--type T] [--address A] [--limit N]` | | List bookmarks |
  199. | `remove-bookmark <address> [--type T]` | | Remove bookmark |
  200. ### Tags
  201. | Command | Args | Description |
  202. |---------|------|-------------|
  203. | `tag-function <target> <tag>` | | Tag a function |
  204. | `untag-function <target> <tag>` | | Remove tag from function |
  205. | `list-tags` | | List all tags with counts |
  206. | `functions-by-tag <tag> [--limit N]` | | Find functions by tag |
  207. ## Agent Workflow Patterns
  208. ### Pattern 1: Explore → Analyze → Annotate
  209. ```bash
  210. # 1. Discover
  211. ida-rpc functions --limit 50 | jq '.result.functions[].name'
  212. # 2. Deep-dive
  213. ida-rpc decompile suspicious_func | jq '.result.c_code'
  214. ida-rpc xrefs-to suspicious_func | jq '.result.xrefs[]'
  215. # 3. Annotate findings
  216. ida-rpc rename-function suspicious_func decrypt_payload
  217. ida-rpc set-comment 0x401234 "Calls decrypt_payload"
  218. ida-rpc save
  219. ```
  220. ### Pattern 2: Batch String Hunt
  221. ```bash
  222. # Find all strings matching a pattern, then decompile their xrefs
  223. ida-rpc strings "auth" --limit 20 | jq '.result.strings[] | .address'
  224. # For each string address, find xrefs-to, then decompile the referencing functions
  225. ```
  226. ### Pattern 3: Structural Analysis
  227. ```bash
  228. # Get memory map
  229. ida-rpc memory-map | jq '.result.segments[] | select(.execute == true)'
  230. # Find functions in a specific address range
  231. ida-rpc functions --address-min 0x401000 --address-max 0x410000
  232. # Decompile each function in that range
  233. for name in $(ida-rpc functions --address-min 0x401000 --address-max 0x410000 | jq -r '.result.functions[].name'); do
  234. ida-rpc decompile "$name"
  235. done
  236. ```
  237. ### Pattern 4: Find Raw Binary Base Address
  238. When you have a firmware dump or bare-metal image and don't know the load address, use `basefind` before loading:
  239. ```bash
  240. # Scan a raw binary for likely base addresses (no daemon needed)
  241. ida-rpc basefind /path/to/dump.bin --max-results 10
  242. # Example output:
  243. # {
  244. # "candidates": [
  245. # {"base": "0x8000000", "score": 10025, "refs": 25, "string_refs": 0, "source": "early-pointer"},
  246. # {"base": "0x8010000", "score": 18, "refs": 18, "string_refs": 0, "source": "absolute"}
  247. # ]
  248. # }
  249. # Use the best candidate to start IDA
  250. ida-rpc start /path/to/dump.bin --base 0x8000000 --arch arm --headless --detach
  251. ```
  252. **Tuning parameters:**
  253. - `--str-len` (default 10): minimum printable-string length
  254. - `--diff-len` (default 10): string/pointer delta window length
  255. - `--samplerate` (default 20): sparse validation rate for large files
  256. - `--min-abs-refs` (default 4): threshold for absolute-reference candidates
  257. ### Pattern 5: Loading Raw Binaries and Memory Segments
  258. 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.
  259. ```bash
  260. # 1. Start the daemon with a raw binary
  261. # --base is the byte address (not paragraphs)
  262. # --arch selects the processor module and auto-configures the segment
  263. ida-rpc start /path/to/dump.bin \
  264. --project /tmp/firmware.i64 \
  265. --base 0x8200000 \
  266. --arch arm \
  267. --headless --detach
  268. # 2. The segment is auto-configured: class=CODE32, bitness=1, read+exec.
  269. # No manual edit-segment needed when --arch is provided.
  270. # 3. Create functions at known entry points
  271. ida-rpc create-function 0x8211170 --name func_entry
  272. # 4. Disassemble and verify
  273. ida-rpc disassemble 0x8211170 --count 20
  274. ida-rpc functions --limit 20
  275. ```
  276. **Loading a raw binary with explicit file offset, load address, and size:**
  277. ```bash
  278. # Step 1: Create an empty database and start the daemon
  279. # Pass --arch so add-segment auto-configures class/bitnesss/perms.
  280. ida-rpc start --project /tmp/firmware.i64 --arch arm --headless --detach
  281. # Step 2: Create a segment at the target load address
  282. # Class, bitness, and permissions are auto-configured from --arch.
  283. ida-rpc add-segment 0x08000000 0x08020000 --name FLASH
  284. # Step 3: Extract bytes from a specific file offset and load them
  285. # dd: bs=1 skip=<file_offset> count=<size>
  286. dd if=/path/to/dump.bin bs=1 skip=0x2000 count=0x10000 of=/tmp/extracted.bin
  287. python3 -c "import sys; print(open('/tmp/extracted.bin','rb').read().hex())" > /tmp/extracted.hex
  288. ida-rpc write-bytes 0x08000000 "$(cat /tmp/extracted.hex)"
  289. # Step 4: Define functions and analyze
  290. ida-rpc create-function 0x08000000 --name reset_handler
  291. ida-rpc disassemble 0x08000000 --count 10
  292. ida-rpc functions --limit 20
  293. ```
  294. **Supported `--arch` values for raw binary auto-configuration:**
  295. | `--arch` value | Processor | Segment class | Bitness | Notes |
  296. |----------------|-----------|--------------|---------|-------|
  297. | `arm` | ARM 32-bit (ARM mode) | `CODE32` | 1 (32-bit) | A1/T32 instructions |
  298. | `thumb` | ARM 32-bit (Thumb mode) | `CODE16` | 1 (32-bit) | **Use this for Thumb-only or mixed ARM/Thumb firmware** |
  299. | `aarch64` | ARM 64-bit | `CODE64` | 2 (64-bit) | Also accepted: `arm64` |
  300. | `metapc` | Intel x86 | `CODE` | 1 (32-bit) | 32-bit x86 |
  301. | `x86` | Intel x86 | `CODE` | 1 (32-bit) | Alias for `metapc` |
  302. | `x64` | Intel x64 | `CODE64` | 2 (64-bit) | 64-bit x86-64 |
  303. | `mips` | MIPS (little-endian) | `CODE` | 1 (32-bit) | |
  304. | `mipsb` | MIPS (big-endian) | `CODE` | 1 (32-bit) | |
  305. | `mips64` | MIPS 64-bit | `CODE64` | 2 (64-bit) | |
  306. | `ppc` | PowerPC 32-bit | `CODE` | 1 (32-bit) | |
  307. | `ppc64` | PowerPC 64-bit | `CODE64` | 2 (64-bit) | |
  308. **Important notes on architecture selection:**
  309. - **`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).
  310. - 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.
  311. **Segment class values:** `CODE`, `DATA`, `CONST`, `BSS`, `STACK`, `HEAP`, `XTRN`.
  312. ### Pattern 6: ARM/Thumb Mode Switching
  313. ```bash
  314. # Check current processor context at an address
  315. ida-rpc get-processor-context --address 0x8000 --register T
  316. # Switch to Thumb mode (T=1) for a range
  317. ida-rpc set-processor-context 0x8000 T 1 --end 0x9000
  318. ```
  319. ### Pattern 7: Bulk Decompile for Diffing
  320. ```bash
  321. # Decompile all functions matching a pattern
  322. ida-rpc decompile-all --function "parse" --limit 50 | jq '.result.functions[].c_code'
  323. ```
  324. ### Pattern 8: Assembly Patching
  325. ```bash
  326. # Assemble a nop sled at an address (requires Keystone Engine)
  327. ida-rpc assemble 0x401000 "nop"
  328. ida-rpc assemble 0x401001 "jmp 0x401050"
  329. ```
  330. ## JSON Response Structure
  331. Every successful response:
  332. ```json
  333. {
  334. "id": "<uuid>",
  335. "ok": true,
  336. "result": { ... }
  337. }
  338. ```
  339. Every error response:
  340. ```json
  341. {
  342. "id": "<uuid>",
  343. "ok": false,
  344. "error": "ValueError",
  345. "message": "Function 'foo' not found."
  346. }
  347. ```
  348. Parse with `jq .result` to extract the payload, or check `.ok` first.
  349. ## Environment Variables
  350. | Variable | Purpose |
  351. |----------|---------|
  352. | `IDA_RPC_PROJECT` | Default `--project` path |
  353. | `IDA_INSTALL_DIR` | Path to IDA Pro installation (for auto-launch) |
  354. | `IDA_RPC_STATE_DIR` | Directory for session JSON files (default: next to IDB) |
  355. ## Troubleshooting
  356. | Symptom | Fix |
  357. |---------|-----|
  358. | `DaemonNotRunning` | Run `ida-rpc start <binary> --arch <arch> --headless --detach` |
  359. | Socket exists but daemon unresponsive | `ida-rpc stop` then `ida-rpc start <binary> --arch <arch>` |
  360. | Hex-Rays errors | Ensure Hex-Rays decompiler is installed and licensed |
  361. | `Function can be called from the main thread only` | Internal bug — handler forgot `ctx.run_on_main_thread()` |
  362. | Changes lost after stop | Forgot `ida-rpc save` — mutations are auto-saved by most handlers, but explicit save is safest |
  363. | Assembler fails | Install Keystone Engine: `pip install keystone-engine` |
  364. ## Programmatic Use (Python)
  365. ```python
  366. from ida_rpc.client import send_request
  367. from ida_rpc.session import socket_path_for_project
  368. from pathlib import Path
  369. sock = socket_path_for_project("/tmp/test.i64")
  370. resp = send_request(sock, "functions", {"limit": 10})
  371. print(resp["result"]["functions"])
  372. ```
  373. ## Protocol Compatibility Note
  374. 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)

  1. # ida-rpc
  2. ![ida-rpc plugin logo](ida-plugin.png)
  3. (c) B.Kerler 2026
  4. A JSON-RPC daemon for IDA Pro, inspired by [ghidra-rpc](https://github.com/cellebrite-labs/ghidra-rpc).
  5. Exposes IDA Pro reverse engineering capabilities over a local socket for
  6. integration with LLM agents, automation pipelines, and multi-agent setups.
  7. Linux and macOS use Unix domain sockets; Windows uses loopback TCP because
  8. ``socket.AF_UNIX`` is not available in all supported Windows IDA/Python setups.
  9. Set `IDA_RPC_TRANSPORT=tcp` to use loopback TCP on Linux or macOS.
  10. On Windows, the daemon publishes its OS-assigned TCP port in the project endpoint
  11. marker, avoiding ports reserved by virtualization or other local software.
  12. ### Codex sandbox setup
  13. Install this package with `pip install -e .`, then run `ida-rpc-codex` from
  14. the project directory to start a new Codex session. The launcher selects TCP,
  15. permits only `127.0.0.1` command networking, and lets IDA write its user
  16. directory (`$IDAUSR` or `~/.idapro`) in the workspace-write sandbox.
  17. Run `ida-rpc` commands normally in that session. To pass Codex options, append
  18. them to `ida-rpc-codex`.
  19. Stop any existing Unix-socket daemon for an IDB before opening that IDB in the
  20. TCP session. The transport refuses to replace its live socket. Sessions that
  21. use the default Unix transport still need outside-sandbox execution.
  22. ## Features
  23. - **Human-readable CLI output** by default, with `--json` or `IDA_RPC_JSON=1` for structured JSON — faster and more reliable than MCP
  24. - **Headless mode** — run via `ida -A` for CI/automation
  25. - **GUI mode** — works inside the interactive IDA Pro session
  26. - **Protocol compatible** with ghidra-rpc's CLI design
  27. - **Full feature set**: decompile, disassemble, xrefs, rename, types, structs, enums, bookmarks, search, memory maps, patches, segments, processor context, namespaces, tags
  28. ## Quick Start
  29. ### Install
  30. **Via the IDA Plugin Manager (recommended):**
  31. ```bash
  32. hcli plugin install ida-rpc
  33. ```
  34. **Or in the script path:**
  35. ```bash
  36. hcli plugin install .
  37. ```
  38. **Or manually:**
  39. ```bash
  40. pip install -e /path/to/ida-rpc
  41. ln -s /path/to/ida-rpc/ida_rpc_plugin.py $IDAUSR/plugins/ida_rpc_plugin.py
  42. ```
  43. Default `$IDAUSR` paths:
  44. - **Windows:** `%APPDATA%\Hex-Rays\IDA Pro\`
  45. - **macOS:** `~/Library/Application Support/IDA Pro/`
  46. - **Linux:** `~/.idapro/`
  47. ### Start the daemon
  48. For agents and automation, first ask the tool what it can do and which IDB path
  49. to use:
  50. ```bash
  51. ida-rpc capabilities
  52. ida-rpc find-project /path/to/binary-or-existing.i64
  53. ida-rpc list-loaders /path/to/binary
  54. ```
  55. ```bash
  56. # Start headless daemon from a binary (headless is the default)
  57. ida-rpc open /path/to/binary --arch <arch> --detach
  58. # Or open an existing IDB
  59. ida-rpc open --project /path/to/existing.i64 --arch <arch> --detach
  60. # For raw binaries, specify architecture and base address.
  61. # The segment is auto-configured (class, bitness, permissions) based on arch.
  62. ida-rpc open /path/to/raw.bin --arch arm --base 0x8000 --detach
  63. # Open in GUI mode instead
  64. ida-rpc open /path/to/binary --arch <arch> --gui --detach
  65. # Existing IDBs ignore raw import options such as --base and --loader.
  66. # The requested --arch still configures processor/bitness after the IDB opens.
  67. # When opening a system binary (e.g. /usr/bin/ls), specify a writable project path
  68. ida-rpc open /usr/bin/ls --project /tmp/ls_analysis.i64 --arch x86 --detach
  69. # Set default project for subsequent commands
  70. export IDA_RPC_PROJECT=/path/to/binary.i64
  71. # Query functions
  72. ida-rpc functions --limit 10
  73. # Decompile main
  74. ida-rpc decompile main
  75. # Rename a function
  76. ida-rpc rename-function sub_401000 my_func
  77. # List all active daemons
  78. ida-rpc list
  79. ```
  80. ## Command Reference
  81. 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`.
  82. ### Lifecycle
  83. | Command | Description |
  84. |---------|-------------|
  85. | `ida-rpc capabilities` | Print agent-discoverable command capabilities |
  86. | `ida-rpc find-project <binary-or-idb>` | Resolve the IDB path, socket path, and recommended start command |
  87. | `ida-rpc list-loaders [binary] [--ida-install-dir DIR]` | List loader aliases, installed IDA loaders, and file-specific candidates |
  88. | `ida-rpc open <binary> --arch <arch> [--project <idb>] [--base <addr>] [--detach] [--clean]` | Agent-friendly alias for `start` (headless by default) |
  89. | `ida-rpc start <binary> --arch <arch> [--project <idb>] [--base <addr>] [--detach] [--clean]` | Open binary and start daemon; `--base` applies when importing a new IDB |
  90. | `ida-rpc start --project <idb> --arch <arch> [--detach] [--clean]` | Open an existing database |
  91. | `ida-rpc stop --project <idb> [--clean]` | Stop daemon; `--clean` removes IDA companion files (default: false) |
  92. | `ida-rpc status --project <idb>` | Check daemon health, launch arch, loaded processor/settings, and loaded binary |
  93. | `ida-rpc restart --project <idb> [--gui] [--clean]` | Restart daemon (headless by default; `--gui` preserves GUI mode) |
  94. | `ida-rpc list` | List all active projects/daemons |
  95. | `ida-rpc list-binaries --project <idb>` | List loaded binaries with arch, bits, endian, format, and base address |
  96. | `ida-rpc save --project <idb>` | Save the database |
  97. ### Analysis & Listing
  98. | Command | Description |
  99. |---------|-------------|
  100. | `functions [--limit N] [--offset N] [--with-body] [--address-min A] [--address-max A]` | List functions |
  101. | `function <func>` | Show function metadata, signature, and body |
  102. | `function-info <func>` | Rich function summary |
  103. | `function-items <func> [--limit N]` | Instructions/items in a function |
  104. | `function-chunks <func>` | Function chunks/ranges |
  105. | `imports` | List imports |
  106. | `exports` | List exports |
  107. | `add-entry <address> [name] [--ordinal N] [--no-makecode]` | Add an entry point |
  108. | `rename-entry <ordinal> <name>` | Rename an entry point |
  109. | `metadata` | Binary metadata (arch, bits, endian, format, base address) |
  110. | `relocations [--limit N]` | List relocation/fixup entries |
  111. | `calling-conventions` | List valid calling conventions for current processor |
  112. | `strings [query] [--limit N]` | Search strings (empty query = all) |
  113. | `find-string <query> [--limit N] [--address A]` | Find strings matching a query |
  114. | `symbols <query> [--limit N] [--offset N]` | Search named symbols |
  115. | `find-bytes <pattern> [--limit N] [--address A]` | Byte pattern search (supports `??` wildcards) |
  116. | `memory-map` | Memory segments with RWX permissions |
  117. | `list-problems [--type T] [--limit N]` | List IDA analysis problems |
  118. | `file-offset <address>` | Convert EA to file offset |
  119. | `file-offset-to-ea <offset>` | Convert file offset to EA |
  120. | `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) |
  121. | `segments` | Alias for memory-map |
  122. ### Decompilation & Disassembly
  123. | Command | Description |
  124. |---------|-------------|
  125. | `decompile <func> [--timeout N]` | Decompile function to pseudo-C |
  126. | `decompile-all [--limit N] [--function <filter>]` | Bulk decompile all functions |
  127. | `decompile-lvars <func>` | List decompiler local variables |
  128. | `set-lvar-name <func> <lvar> <new_name>` | Rename a decompiler local variable |
  129. | `set-lvar-type <func> <lvar> <type>` | Set a decompiler local variable type |
  130. | `decompile-microcode <func> [--maturity N]` | Dump Hex-Rays microcode |
  131. | `decompiler-xrefs <func> <target>` | Find decompiler-level target references |
  132. | `basic-blocks <func> [--limit N]` | CFG basic blocks with successors/predecessors |
  133. | `function-graph <func>` | Export a function graph |
  134. | `call-graph [--mode callers\|callees\|both] [--title T]` | Export a call graph |
  135. | `get-switch-info <address>` | Inspect switch/jump-table metadata |
  136. | `disassemble <address> [--count N]` | Disassemble instructions (default 20, max 1000) |
  137. | `assemble <address> <instruction>` | Assemble instruction text (requires Keystone Engine) |
  138. | `read-bytes <address> <length>` | Hex dump with ASCII |
  139. | `read-string <address> [--strtype T]` | Read a string |
  140. | `create-string <address> <length> [--strtype T]` | Create a string item |
  141. | `write-bytes <address> <hex>` | Patch bytes (max 4096) |
  142. | `list-patches [--start A] [--end B] [--limit N]` | List patched bytes |
  143. | `revert-patch <start> [--end B]` | Revert patched bytes |
  144. | `patch-byte <address> <value>` | Patch one byte |
  145. | `patch-word <address> <value>` | Patch a 16-bit value |
  146. | `patch-dword <address> <value>` | Patch a 32-bit value |
  147. | `patch-qword <address> <value>` | Patch a 64-bit value |
  148. ### Cross-References
  149. | Command | Description |
  150. |---------|-------------|
  151. | `xrefs-to <target> [--limit N]` | References to target |
  152. | `xrefs-from <target> [--limit N] [--no-stack]` | References from target |
  153. ### Annotations & Modifications
  154. | Command | Description |
  155. |---------|-------------|
  156. | `rename-function <target> <new_name>` | Rename function |
  157. | `rename-symbol <address> <new_name> [--create]` | Rename symbol |
  158. | `create-label <address> <name>` | Create label |
  159. | `set-comment <address> <comment> [--type plate\|pre\|post\|eol\|repeatable]` | Set comment |
  160. | `set-signature <target> <sig>` | Set function prototype |
  161. | `set-data-type <address> <type>` | Set data type |
  162. | `create-function <address> [--name N]` | Create function at address |
  163. | `delete-function <target>` | Delete a function definition |
  164. | `create-instruction <address>` | Mark bytes at address as an instruction |
  165. | `undefine <address> [length]` | Undefine instruction or data at address |
  166. | `set-thunk <target> [--thunk-target <addr>] [--clear]` | Mark/unmark function as thunk |
  167. | `set-calling-convention <target> <convention>` | Change function calling convention |
  168. | `set-function-color <func> <color>` | Set function color |
  169. | `function-frame <func>` | Inspect a function frame |
  170. | `list-stack-vars <func>` | List stack variables |
  171. | `rename-stack-var <func> (--offset N \| --old-name NAME) --new-name NAME` | Rename a stack variable |
  172. | `set-stack-var-type <func> (--offset N \| --name NAME) --type TYPE` | Set stack variable type |
  173. | `list-reg-vars <func>` | List register variables |
  174. | `stack-var-xrefs <func> [--offset N] [--name NAME]` | Find stack variable references |
  175. | `batch-rename --mode {function,symbol} --from-file <json>` | Bulk rename |
  176. | `batch-set-comment --from-file <json>` | Bulk set comments |
  177. | `batch --from-file <json>` | Execute multiple RPC commands in one batch |
  178. ### Lumina
  179. Lumina commands use the primary or secondary Lumina server configured in IDA
  180. (`Options > General > Lumina`) or overridden for the IDA session with
  181. `-Olumina:...` / `-Osecondary_lumina:...`. Credentials are not returned.
  182. | Command | Description |
  183. |---------|-------------|
  184. | `lumina-config [--secondary]` | Report Lumina configuration source and whether a configured client is available |
  185. | `lumina-pull-signatures [target] [--all] [--apply/--no-apply] [--force] [--seen-file] [--secondary]` | Pull function signatures/metadata from Lumina |
  186. | `lumina-push-signatures [target] [--all] [--mode better\|override\|no-override\|merge] [--min-func-size N] [--secondary]` | Push function signatures/metadata to Lumina |
  187. ### Data Types
  188. | Command | Description |
  189. |---------|-------------|
  190. | `create-struct <name> <fields...> [--if-not-exists] [--or-replace]` | Create struct (fields as `TYPE NAME ...` pairs) |
  191. | `create-union <name> <fields...> [--if-not-exists] [--or-replace]` | Create union |
  192. | `create-enum <name> [values...] [--size 1\|2\|4\|8]` | Create enum (values as `NAME VALUE ...` pairs) |
  193. | `modify-struct <name> --action {rename,retype,delete,set_comment} --field <name>` | Modify struct field |
  194. | `modify-enum <name> --action {add,remove} --member <name> [--value N]` | Modify enum |
  195. | `list-data-types [--category all\|struct\|enum\|union] [--query Q] [--limit N]` | List defined types |
  196. | `list-labels <address> [--end <addr>] [--limit N]` | List symbols at or near an address |
  197. | `set-equate <address> <operand> <enum> [--clear]` | Attach enum to instruction operand |
  198. | `list-equates [--address <addr>] [--end <addr>] [--limit N]` | List all enum operands |
  199. | `clear-data-range <start> [--end <addr> \| --length N]` | Undefine data in a range |
  200. | `apply-data-type-range <start> <type> [--end <addr> \| --length N] [--type-size N]` | Stamp a type across a range |
  201. | `import-til <path>` | Import a type library |
  202. | `export-til <path>` | Export type information |
  203. | `delete-type <name>` | Delete a named type |
  204. | `get-type-info <name>` | Show type information |
  205. ### Segments
  206. | Command | Description |
  207. |---------|-------------|
  208. | `add-segment <start> <end> [--name N] [--class C]` | Create a new segment (class defaults to CODE32/CODE16/CODE64 based on `--arch`) |
  209. | `edit-segment <start> [--name N] [--class C] [--perm-read/--no-perm-read ...] [--bitness 0\|1\|2]` | Modify segment |
  210. | `delete-segment <start>` | Delete a segment |
  211. ### Colors, Operands, and Exceptions
  212. | Command | Description |
  213. |---------|-------------|
  214. | `operand-struct-path <address> <operand>` | Inspect operand struct path information |
  215. | `set-color <address> <color>` | Set item color |
  216. | `get-color <address>` | Get item color |
  217. | `del-color <address>` | Remove item color |
  218. | `list-try-blocks [--start A] [--end B]` | List exception/try blocks |
  219. ### Processor Context
  220. | Command | Description |
  221. |---------|-------------|
  222. | `get-processor-context [--address <addr>] [--register <name>]` | Read processor context registers |
  223. | `set-processor-context <address> <register> <value> [--end <addr>]` | Set processor context register |
  224. ### Namespaces
  225. | Command | Description |
  226. |---------|-------------|
  227. | `create-namespace <namespace> [--parent <ns>]` | Validate/create namespace |
  228. | `list-namespaces [--limit N]` | List all namespaces with symbol counts |
  229. ### Bookmarks
  230. | Command | Description |
  231. |---------|-------------|
  232. | `set-bookmark <address> [--type Note\|Warning\|Error\|Info\|Analysis] [--category C] [--comment M]` | Set bookmark |
  233. | `list-bookmarks [--type T] [--address A] [--limit N]` | List bookmarks |
  234. | `remove-bookmark <address> [--type T]` | Remove bookmark |
  235. ### Tags
  236. | Command | Description |
  237. |---------|-------------|
  238. | `tag-function <target> <tag>` | Tag a function |
  239. | `untag-function <target> <tag>` | Remove tag from function |
  240. | `list-tags` | List all tags with counts |
  241. | `functions-by-tag <tag> [--limit N]` | Find functions by tag |
  242. ### Debugger
  243. | Command | Description |
  244. |---------|-------------|
  245. | `debug-select-backend <backend> [--remote]` | Select an IDA debugger backend by internal name |
  246. | `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 |
  247. | `debug-attach <pid> [--backend B] [--remote] [--wait-timeout N]` | Optionally select a backend, then attach and wait for initial suspension |
  248. | `debug-detach`, `debug-exit` | Detach or exit debugger |
  249. | `debug-continue [--wait-timeout N]`, `debug-suspend [--wait-timeout N]` | Continue or suspend execution and wait for the resulting state |
  250. | `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 |
  251. | `debug-status` | Show debugger status |
  252. | `debug-get-registers`, `debug-set-register <reg> <value>` | Read or write registers |
  253. | `debug-read-memory <address> <length>`, `debug-write-memory <address> <hex>` | Read or write debug memory |
  254. | `debug-breakpoints`, `debug-add-breakpoint <address>`, `debug-delete-breakpoint <address>`, `debug-enable-breakpoint <address> --enabled/--disabled` | Manage breakpoints |
  255. | `debug-stack-trace`, `debug-modules`, `debug-threads` | Inspect runtime state |
  256. Use repeated `--register` options to request named registers without returning
  257. the full architecture-specific register set, for example
  258. `ida-rpc debug-get-registers --register RIP --register RCX`.
  259. Backend names are IDA plugin identifiers rather than display labels. For
  260. example, use `win32` for the local Windows debugger, `linux` for the local
  261. Linux debugger, and `mac` for the local macOS debugger. The backend can be
  262. selected separately or atomically with process startup:
  263. ```bash
  264. ida-rpc debug-select-backend win32 --project /path/to/program.i64
  265. ida-rpc debug-start /path/to/program.exe --backend win32 --project /path/to/program.i64
  266. ```
  267. ### Navigation (GUI only)
  268. | Command | Description |
  269. |---------|-------------|
  270. | `goto <target> [function\|address]` | Jump to function or address in IDA UI |
  271. ## Environment Variables
  272. | Variable | Purpose |
  273. |----------|---------|
  274. | `IDA_RPC_PROJECT` | Default `--project` path |
  275. | `IDA_INSTALL_DIR` | Path to IDA Pro installation (for auto-launch) |
  276. | `IDA_RPC_STATE_DIR` | Directory for session JSON files (default: next to IDB) |
  277. ## Agent Usage
  278. Codex, Kimi, and other coding agents should use `ida-rpc` automatically for
  279. IDA-based reverse engineering. The repository includes `AGENTS.md`, `KIMI.md`,
  280. and `SKILL.md` so agents can discover the intended workflow after install.
  281. A complete, progressively disclosed Codex skill is available at
  282. [`skills/idarpc/`](skills/idarpc/). Its compact entrypoint routes agents to
  283. focused references for setup, static analysis, edits, firmware, debugging,
  284. internals, troubleshooting, and common reverse-engineering workflows, so
  285. unrelated documentation does not need to be loaded for every task.
  286. The stable automation probe is:
  287. ```bash
  288. ida-rpc capabilities
  289. ```
  290. The stable project-resolution probe is:
  291. ```bash
  292. ida-rpc find-project /path/to/binary-or-idb
  293. ```
  294. After that, use `open --arch <arch>`, `status`, `functions`, `decompile`, `disassemble`,
  295. `strings`, `xrefs-to`, `xrefs-from`, `rename-function`, `set-comment`, and
  296. `save`. Commands print human-readable text on stdout by default; pass `--json`
  297. (before the subcommand) or set `IDA_RPC_JSON=1` for JSON output. Unexpected
  298. CLI/RPC failures are reported on stderr as `Error: <error>: <message>` (or JSON
  299. with `--json`); set `IDA_RPC_DEBUG=1` to also print tracebacks on stderr.
  300. ## Architecture
  301. ```
  302. ┌─────────────┐ Unix Socket ┌──────────────────────────────┐
  303. │ LLM agent │ ──── JSON/newline ──→ │ ida-rpc daemon │
  304. │ (via CLI) │ ←── JSON/newline ─── │ (IDA Python plugin + server)│
  305. └─────────────┘ └──────────────────────────────┘
  306. ```
  307. ## License
  308. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.