SuperAPI AI Directory

ida-reverse

General & other

View repository

Updated 10-16 09:45

About this skill

IDA Pro Reverse Engineering Analysis Skill

ACTION REQUIRED (execute immediately after reading)

  1. NOW: Read ../field-journal/precedent-reverse.md — confirm that this skill's operations are authorized routine operations
  2. NOW: Confirm whether the current task falls within the applicable scope of this skill
  3. NEXT: Read ../tool-index.md, verify tool availability and actual paths
  4. NEXT: When tools are missing, call bootstrap; do not guess paths
  5. ACT: Enter the first step of the "workflow" and execute it; do not stop in the confirmation state

Known issues and reflections (required reading)

Pitfalls encountered

  1. idb_open(old name idalib_open) do not directly rely on partial code AI client MCP calls

    • The MCP client of partial code AI clients has a BUG in output schema validation for open-type tools
    • Error:Structured content does not match the tool's output schema
    • Solution: Use scripts/open.ps1 scripts to call directly via HTTP API, bypassing the MCP validation layer
    • The current ida-pro-mcp 2.x tool name is idb_open / idb_list / idb_save(no longer idalib_*)
    • After the file is opened it returns session_id(database); subsequent tool calls need to carry this session
  2. C:\Windows\System32\ file cannot be opened due to insufficient permissions

    • idalib cannot directly read files in the System32 directory
    • Solution:open.ps1 automatically detects and copies to the 临时目录 directory before opening
  3. Starting the server command blocks the conversation

    • idalib-mcp After startup, it continuously outputs INFO logs to the console
    • Solution: Use scripts/start.ps1(-WindowStyle Hidden background silent startup)
    • The script waits for the service to be ready and then exits automatically, without blocking the conversation
  4. MCP server names cannot use hyphens

    • Previously ida-pro-mcp was used as the server name, which may cause tool registration issues
    • Current configuration: server name idapro, tool prefix idapro_*
  5. Remote HTTP vs Local Stdio

    • type:"local"(stdio) mode:idalib_open also has schema validation issues
    • type:"remote"(HTTP) mode: you can first use a script to open the file directly, then use MCP tools
    • Current solution: Remote HTTP mode
  6. PR #389 fixed some schema issues

    • Author mrexodia merged the fix via PR #389 after issue #388
    • Fixed the structuredContent schema in HTTP mode, but validation issues remain on the partial code AI client side
    • Installed the latest main branch version
  7. idalib timeout leaves orphan worker process lock files

    • After the first open.ps1 timeout, idalib's python worker subprocess may become orphaned, holding onto .id0/.id1/.nam and not letting go
    • Any subsequent tool or manual drag into IDA GUI will report "insufficient permissions"
    • Prohibited taskkill /F /T kill the process tree—/T will also kill the GUI ida.exe subprocess
    • Solution:start.ps1 Only when no one is listening on the port, or tools/list returns quickly but lacks py_eval(old supervisor), replace the managed supervisor; if the RPC times out and 13337 is still listening, treat it as busy and do not kill it. When opening the database, open.ps1 writes opening.lock, the watchdog must not -Force
    • Deadlock exception:tools/list Continuous failure for more than 3 minutes(based on the last-healthy timestamp, not the process creation time), and there is no in-flight opening.lock, and it is not the GUI holding the port, only then -Force replace the supervisor, still do not kill ida.exe
    • Fallback:open.ps1 When it detects that the old database is locked, automatically copy it to Temp and add a GUID prefix
  8. Opening with automatic analysis looks like it is stuck

    • idalib_open(run_auto_analysis=true) may not respond for a long time, but the backend is actually still opening and analyzing
    • Previously, what the user saw was “PowerShell keeps producing no output,” which is easily mistaken for the script being stuck
    • Current solution:open.ps1 added -TimeoutSeconds, and changed it to background request + foreground polling + periodic progress output
    • When polling detects that the session is ready, it returns early with OK:文件名:session_id, and on timeout returns ERR:open_timeout_xxs
  9. HTTP MCP silently exits after login

    • Cursor/Claude’s type: http will not start the process on its behalf; the old scheduled task only runs once at login
    • pythonw has no console, and when it crashes the Application log is also empty
    • Solution:start.ps1 If healthy by default, reuse it;watchdog.ps1 patrol every minute; logs are in %LOCALAPPDATA%\reverse-skill\ida-mcp\
    • Installation:scripts/install-autostart.ps1. If the port is not up yet when the HTTP client starts, you still need to manually refresh once in the MCP panel
  10. Streamable HTTP GET /mcp will get the single-threaded supervisor stuck

  • Some HTTP MCP clients will send a long-lived GET (SSE) to /mcp . stock idalib_supervisor uses background=False ’s HTTPServer, and handles only one request at a time
  • Result:tools/list times out, and the client marks idapro as error
  • Solution:run-supervisor.py Replace HTTP with ThreadingHTTPServer and accept GET /mcp; if the patch fails, skip it and still start the supervisor. When stuck, use scripts/recover.ps1(immediately -Force)

Workflow principles

Step What to do What to use
1 Make sure the HTTP server is running scripts/start.ps1(no arguments)
2 Open the target binary file scripts/open.ps1 -Path "xxx.exe"
3 Use the MCP analysis tools Call directly idapro_* / HTTP tools (about 65, depending on version)
4 Analysis complete Tools are automatically available

Script resources

start.ps1 — Start the MCP HTTP server

Path:scripts/start.ps1

  • Automatically resolve IDADIR(environment variable / portable desktop path / common installation path)
  • Prefer IDA’s built-in Python314\python.exe -m ida_pro_mcp.idalib_supervisor
  • By default, probe first http://127.0.0.1:13337/mcp, and if healthy output OK:<n>:reuse and exit
  • 13337 is listening but tools/list times out → WARN:busy / OK:busy:reuse,do not kill(cannot respond when opening the database or when the GUI is occupying it)
  • tools/list Continuous failure for more than 3 minutes(last-healthy timestamp) and no opening.lock → considered a deadlock, output INFO:deadlock and -Force replace supervisor. In-progress idb_open and GUI will not take this path
  • Only when no one is listening on the port, missing py_eval, or the aforementioned deadlock, is the managed supervisor replaced;never kill ida.exe, do not use taskkill /T
  • When the GUI occupies 13337, output WARN:gui_busy and exit, without starting another supervisor
  • On success, output OK:<工具数>(currently about 66), on failure output ERR:timeout
  • supervisor log:%LOCALAPPDATA%\reverse-skill\ida-mcp\supervisor.log
  • The server runs in the background without blocking the conversation

How to invoke:

powershell -File "<skill-root>\ida-reverse\scripts\start.ps1"

watchdog.ps1 / recover.ps1 / install-autostart.ps1 — keep-alive

  • watchdog.ps1: probe 13337; healthy reuse (and refresh last-healthy); GUI / open.ps1 open database lock / last-healthy not yet 3 minutes busy → reuse; only tools/list after more than 3 minutes of consecutive failures do start.ps1 -Force
  • recover.ps1: immediately start.ps1 -Force(without killing ida.exe). Use this when the HTTP client marks idapro as error
  • install-autostart.ps1: register scheduled task reverse-skill-ida-mcp(logon + every minute)
  • Log:%LOCALAPPDATA%\reverse-skill\ida-mcp\watchdog.log

open.ps1 — open a binary file

Path:scripts/open.ps1

  • Call directly via the HTTP API idb_open, bypassing MCP schema validation
  • Automatically detect the System32 path and copy it to a temporary directory
  • Automatically clean up old database files with the same name (.id0/.id1/.nam/.til/.i64)
  • When the old database is locked, automatically degrade: copy to Temp with a GUID prefix and open it, without reporting an error
  • Execute the open request in the background to avoid the script becoming unresponsive due to a long synchronous wait
  • Support -TimeoutSeconds, return after timeout ERR:open_timeout_xxs, will not hang indefinitely
  • Output once every 10 seconds INFO:opening:已用时/超时秒数, to help determine that analysis is still in progress
  • On success, output OK:文件名:session_id, when degraded add (temp copy) marker
  • On failure, automatically retry using the Temp copy

How to invoke:

powershell -File "<skill-root>\ida-reverse\scripts\open.ps1" -Path "C:\path\to\file.exe"

Optional parameters:

# 指定 SessionId
powershell -File "scripts\open.ps1" -Path "file.exe" -SessionId "my_session"

# 跳过自动分析(大文件推荐)
powershell -File "scripts\open.ps1" -Path "large.exe" -NoAutoAnalysis

# 设置超时,避免带自动分析时长时间无返回
powershell -File "scripts\open.ps1" -Path "file.exe" -TimeoutSeconds 600

Output conventions:

# 分析进行中(每 10 秒输出一次)
INFO:opening:11/600s

# 成功打开
OK:sample.exe:abcd1234

# 成功打开,但因锁文件降级到 Temp 副本
OK:1234abcd-sample.exe:abcd1234 (temp copy)

# 达到超时上限
ERR:open_timeout_600s

Measured notes:

  • Snipaste.exe with automatic analysis actually takes about 324s before returning success; this is "analysis takes a long time" rather than "script deadlock"
  • Therefore, when encountering GUI programs or more complex samples, it is recommended to first explicitly set -TimeoutSeconds 600

Core tool list

Overview analysis (first step)

  • idapro_survey_binary(detail_level="minimal") — quick overview: function count, strings, segments, entry point, import categories (crypto/network/file IO)
  • idapro_list_funcs(queries) — list functions (paged, filter by name)
  • idapro_list_globals(queries) — list global variables
  • idapro_entity_query(kind, filter) — unified query: functions/globals/imports/strings/names

Decompilation and disassembly

  • idapro_decompile(addr) — decompile to pseudocode
  • idapro_disasm(addr, max_instructions=N) — disassemble
  • idapro_analyze_function(addr, include_asm=false) — comprehensive analysis (pseudocode + strings + constants + callers + callees + blocks)
  • idapro_func_profile(queries) — function summary metrics

Cross-references and data flow

  • idapro_xrefs_to(addrs) — find who references the target address
  • idapro_xref_query(addr, direction) — advanced xref query (direction/type filtering)
  • idapro_callees(addrs) — subfunction list
  • idapro_callgraph(roots, max_depth) — call graph
  • idapro_trace_data_flow(addr, direction, max_depth) — data flow tracing (forward/backward)

Search

  • idapro_find_regex(pattern, limit) — Regex string search
  • idapro_search_text(pattern) — Search text in the disassembly listing
  • idapro_find_bytes(patterns, limit) — Byte pattern search (supports ?? wildcards)
  • idapro_find(type, targets) — Advanced search (immediates/strings/references)

Memory and Data

  • idapro_get_bytes(addrs) — Read raw bytes
  • idapro_get_string(addrs) — Read string
  • idapro_get_int(queries) — Read integer value
  • idapro_get_global_value(queries) — Read global variable value
  • idapro_read_struct(queries) — Read struct field value
  • idapro_search_structs(filter) — Search structs

Modification Operations

  • idapro_set_comments(items) — Add comment (bidirectionally synced between disassembly and decompilation)
  • idapro_append_comments(items) — Append comment
  • idapro_rename(batch) — Batch rename (functions/globals/locals/stack variables)
  • idapro_patch_asm(items) — Patch assembly instructions
  • idapro_patch(patches) — Patch bytes
  • idapro_define_func(items) — Define function
  • idapro_undefine(items) — Undefine
  • idapro_define_code(items) — Convert bytes to code

Type System

  • idapro_declare_type(decls) — Declare C struct/union/enum
  • idapro_set_type(edits) — Apply type to function/global/local
  • idapro_infer_types(addrs) — Infer type
  • idapro_type_query(queries) — Query declared types
  • idapro_type_inspect(queries) — View type details

Stack Frame

  • idapro_stack_frame(addrs) — View stack frame variables
  • idapro_declare_stack(items) — Declare stack variable
  • idapro_delete_stack(items) — Delete stack variable

Signatures

  • idapro_make_signature(addrs) — Generate a unique byte signature for an address
  • idapro_make_signature_for_function(addrs) — Generate a signature for a function
  • idapro_find_xref_signatures(addrs) — Generate a signature for code that references an address

Debugger (requires ?ext=dbg)

  • idapro_open_file(file_path) — Open file in a GUI IDA instance
  • Debugger tools are hidden by default; they can be enabled via the URL parameter ?ext=dbg Enable

Session Management (ida-pro-mcp 2.x)

  • idapro_idb_open / HTTP idb_open — ⚠️ Recommended to use open.ps1 to open
  • idapro_idb_list / HTTP idb_list — List all sessions
  • idapro_idb_save / HTTP idb_save — Save database
  • Most analysis tools require the database=<session_id> parameter (the session output by open.ps1)

Other

  • idapro_int_convert(inputs) — Base conversion (you must use this, don't compute bases yourself!)
  • idapro_export_funcs(addrs, format) — Export functions (json/c_header/prototypes)
  • idapro_py_eval(code) — Execute Python in the IDA context
  • idapro_server_health() — Server health check
  • idapro_server_warmup() — Warm up subsystems (string cache, Hex-Rays, etc.)

Complete Reverse Engineering Analysis Workflow

Step 1: Start the server

Path A — Headless idalib (requires a valid license)

powershell -File "scripts/start.ps1"

Output OK:<工具数>(currently about 65) indicates ready.

Path B — GUI + plugin (when the idalib license fails or interactive analysis is needed)

powershell -File "scripts/start-gui.ps1" -Path "C:\目标.exe"

Or double-click the portable Launch-IDA-Pro.cmdand open the sample in IDA.

After confirming that the Output window shows [MCP] ... port=13337 the MCP tools are available.

For general integration steps see LOCAL-SETUP.md。

Step 2: Open the file

Headless:

powershell -File "scripts/open.ps1" -Path "C:\目标.exe" -TimeoutSeconds 600

Output OK:文件名:session_id indicates success (followed by (temp copy) indicates automatic fallback to a temporary copy).

If ERR:idalib_license:...appears, switch to Path B (GUI mode) and do not repeatedly retry open.ps1.

GUI mode: simply open the sample directly in IDA; open.ps1 is not needed.

Step 3: Global overview (including the import table hard gate)

idapro_survey_binary(detail_level="minimal")

Focus on:

  • architecture (x86/x64/ARM)
  • Entry points (main/WinMain/DllMain)
  • Interesting strings (URLs, paths, error messages)
  • Import classification (MUST): encryption functions / network APIs / file operations / process injection / registry — must be recorded as Evidence (suggested id:E-imports), available idapro_entity_query(kind="imports") or the imports section in the survey output
  • DLL/SYS: export table in parallel with import table (Evidence E-exports)
  • .NET: when there is no traditional IAT, use module/metadata/managed-reference summaries as equivalent anchors and write them into the E-imports semantic slot
  • Clean import table: note dynamic-loading suspicion and drive dynamic API breakpoint verification
  • Hot functions (functions with high xref counts are usually key logic)

Hard gate: before the imports view/classification summary (or a legitimate equivalent anchor) is written into Evidence, MUST NOT proceed to Step 4 deep-dive conclusions, MUST NOT claim survey is complete. If the import table is empty or the query fails, still MUST record the failure symptom. If packed IAT repair fails, MUST record E-iat-repair-fail and switch to dynamic debugging to capture APIs; static grinding is forbidden. When the user requests redoing the import table/IAT check, MUST redo the named steps (when blocked, feasibility gate: explain + confirm; if forced, mark quality=unreadable); switching to unrelated steps is forbidden.

Step 4: Deep dive into key functions

idapro_analyze_function(addr="关键函数名")

Or:

idapro_decompile(addr="函数名")
idapro_disasm(addr="函数名", max_instructions=50)

Step 5: Data flow and cross-references

idapro_xrefs_to(addrs="关键地址/字符串")
idapro_callgraph(roots=["关键函数"], max_depth=3)
idapro_trace_data_flow(addr="关键地址", direction="backward", max_depth=5)

Step 6: Record and optimize

idapro_set_comments(items=[{"addr": "0x140001000", "comment": "你的理解"}])
idapro_rename(batch={"func": [{"addr": "函数地址", "name": "有意义的名字"}]})

Step 7: Output report

After analysis is complete, generate report.md to record findings and steps.

Prompt engineering guidelines

  1. Do not calculate bases manually — whenever you need to convert numbers, use idapro_int_convert
  2. Survey first, then deep dive — look at the overview first, then perform targeted analysis
  3. Continuously add comments and rename — keep updating function names and variable names during analysis to improve the accuracy of subsequent analysis
  4. Track cross-references — when you find interesting data/strings, use xrefs_to to see who references it
  5. When encountering obfuscated code — first perform preprocessing such as string decryption, import hash removal, and control-flow flattening removal
  6. C++ STL code — after identifying library functions with FLIRT/Lumina, then analyze the business logic
  7. Do not brute force — analysis should derive solutions from the disassembly, using simple Python to assist calculations
  8. When encountering "No database bound" — no binary file has been opened yet; first execute open.ps1
  9. When encountering "Failed to open database" — possibly an old database file is locked,open.ps1 will automatically fall back to a Temp copy (output contains the (temp copy) marker)
  10. When opening the GUI/complex samples with auto-analysis — by default add -TimeoutSeconds 600, do not misjudge a long INFO:opening:... as the script being stuck

Routing context

Upstream entry: skills/SKILL.md(master control),routing.md Upstream alternate: radare2/(if you do not want to open IDA, you can first do quick reconnaissance with r2) Downstream exit:

  • Needs Frida dynamic verification → reverse-engineering/tools-dynamic.md
  • Needs symbolic execution/angr → reverse-engineering/tools-dynamic.md
  • Needs general reverse-engineering methodology → reverse-engineering/SKILL.md

Sibling related modules: radare2/(Alternative when IDA is unavailable)


On-Demand Bootstrap

This skill's entry script is already integrated with the unified bootstrap system.

Automation capability boundaries

Tool Can be installed automatically Installation method Description
idalib-mcp ✓ pip install (from GitHub) start.ps1 automatically installed when missing
IDA Pro itself ✗ Commercial software, requires manual installation Set the IDADIR environment variable to point to the installation directory

Installation steps (verified)

# 1. 设置 IDA 路径(替换为你的实际 IDA 安装目录)
setx IDADIR "<你的IDA安装目录>"

# 2. 从 GitHub 安装 ida-pro-mcp(PyPI 上的 ida-mcp 是另一个项目,不要装错!)
pip install git+https://github.com/mrexodia/ida-pro-mcp.git

# 3. 安装 IDA 插件(选择 Streamable HTTP + Global + 全选客户端)
ida-pro-mcp --install

# 4. 重启 IDA Pro,打开目标文件
# 插件自动监听 127.0.0.1:13337

# 5. 验证
ida-pro-mcp --config

⚠️ Note: the ida-mcp package on PyPI (author jtsylve) is a different project, not the one we need. It must be installed from GitHub mrexodia/ida-pro-mcp。

Bootstrap trigger point

  • scripts/start.ps1: when idalib-mcp is missing, automatically call bootstrap-reverse.ps1
  • MCP registration: bootstrap will automatically write idapro into the Claude MCP configuration

Prerequisites

  • IDA Pro is installed and the IDADIR environment variable is set (or the default path in the script is correct)
  • It is recommended to use the ida-pro-mcpin IDA's bundled Python314 (already included in the portable version)
  • Common local configuration:
    • User env IDADIR → IDA installation directory (including ida.exe)
    • Optional ~\Tools\bin\idalib-mcp.cmd / ida-pro-mcp.cmd wrapper
    • For the client MCP server name, keep only idapro → http://127.0.0.1:13337/mcp

Task completion self-check (MUST pass before claiming completion)

  • Did I execute every step in the workflow (rather than just reading it)?
  • Have survey/imports been written into Evidence (E-imports or equivalent)? Do DLL/SYS include E-exports? If IAT fails, is E-iat-repair-fail recorded?
  • If the user asks to redo the import table/IAT, was the same step redone?
  • Did I base this on tool-index and use real tool paths?
  • Did I produce reproducible evidence (commands/scripts/screenshots/reports)?
  • Did I complete and write back the Checklist items required by RULES?