SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsida-reverse

ida-reverse

Security & auditing

View repository

Updated 10-16 08:49

About this skill

IDA Pro Reverse Engineering Analysis Skill

Known Issues and Reflections (Must Read)

Pitfalls Encountered

  1. idalib_open Cannot be called directly through some code AI client MCP

    • Some code AI client's MCP client has issues with idalib_open 's output schema validation has a BUG
    • Error:Structured content does not match the tool's output schema
    • Solution: Use the scripts/open.ps1 script to call directly via HTTP API, bypassing the MCP validation layer
    • After the file is opened, the database is bound to the shared context, and all other idapro_* tools can be used directly

  2. C:\Windows\System32\ File has no permission to open

    • idalib cannot directly read files in the System32 directory
    • Solution：open.ps1 Automatically detect and copy to the 临时目录 directory before opening

  1. 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 silent background startup)
    • The script will wait for the service to be ready and then exit automatically, without blocking the conversation

  2. MCP server names cannot use hyphens

    • Previously used ida-pro-mcp as the server name, which may cause tool registration issues
    • Current configuration: server name idapro, tool prefix idapro_*

  3. Remote HTTP vs Local Stdio

    • type:"local"(stdio) mode:idalib_open Also has schema validation issues
    • type:"remote"(HTTP) mode: you can first use the script to open the file directly, then use MCP tools
    • Current solution: Remote HTTP mode

  4. 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 some code AI client-side validation still has issues
    • Latest main branch version installed

  5. idalib timeout leaves orphan worker process lock files

    • First open.ps1 After the timeout, idalib's python worker child process becomes an orphan process, holding onto .id0/.id1/.nam and not letting go
    • Any subsequent tool or manually dragging into IDA GUI will report "insufficient permissions"
    • Solution：start.ps1 Switch to taskkill /F /T to kill the process tree, no longer leaving orphans
    • Fallback：open.ps1 Added automatic degradation; when it detects the old database is locked, it automatically copies to Temp and adds a GUID prefix

  6. 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 continuing to open and analyze
    • Previously what users saw was "PowerShell has no output all along", making it easy to misjudge it as the script being stuck
    • Current solution：open.ps1 Added -TimeoutSeconds, and changed to background request + foreground polling + periodic progress output
    • When polling detects that the session is ready, it returns early OK:文件名:session_id; on timeout, returns ERR:open_timeout_xxs

Workflow Principles

Step What to do What to use
1 Ensure the HTTP server is running scripts/start.ps1(no parameters)
2 Open the target binary file scripts/open.ps1 -Path "xxx.exe"
3 Use all 72 MCP tools Directly call the idapro_* tool
4 Analysis complete Tools are automatically available

Script Resources

start.ps1 — Start the MCP HTTP server

Path:scripts/start.ps1

  • Use taskkill /F /T to kill the old process tree (cleaning up worker child processes as well) → start in the background idalib-mcp → wait until ready (up to 15 seconds)
  • On success output OK:72, on failure output ERR:timeout
  • The server runs in the background without blocking the conversation

How to call：

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

open.ps1 — Open the binary file

Path:scripts/open.ps1

  • Call directly via the HTTP API idalib_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 then open, without reporting an error
  • Run the open request in the background to avoid the script becoming unresponsive due to a long synchronous wait
  • Supports -TimeoutSeconds, after timeout returns ERR:open_timeout_xxs, and will not hang indefinitely
  • Output INFO:opening:已用时/超时秒数every 10 seconds, making it easy to tell that analysis is still in progress
  • On success output OK:文件名:session_id, when degraded add the (temp copy) marker
  • On failure automatically retry using the Temp copy

How to call：

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 takes about 324s before returning success; this is “long analysis” rather than “script deadlock”
  • Therefore, for GUI programs or more complex samples, it is recommended to 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 classification (encryption/network/file IO)
  • idapro_list_funcs(queries) — List functions (pagination, 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 search for strings
  • idapro_search_text(pattern) — Search for 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 struct

Modification operations

  • idapro_set_comments(items) — Add comment (disassembly + decompilation bidirectional sync)
  • 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/enum/union
  • 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

Signature

  • idapro_make_signature(addrs) — Generate unique byte signature for address
  • idapro_make_signature_for_function(addrs) — Generate signature for function
  • idapro_find_xref_signatures(addrs) — Generate signature for code referencing address

Debugger (requires ?ext=dbg)

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

Session management

  • idapro_idalib_open(input_path) — ⚠️ Has a schema validation BUG, use instead open.ps1 script
  • idapro_idalib_list() — List all sessions
  • idapro_idalib_current() — Session bound to current context
  • idapro_idalib_switch(session_id) — Switch to another session
  • idapro_idalib_close(session_id) — Close session
  • idapro_idalib_save(path) — Save database
  • idapro_idalib_health(session_id) — Check worker health status

Other

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

Complete reverse engineering workflow

Step 1: Start the server

Ensure the HTTP service is running in the background.

powershell -File "scripts/start.ps1"

Output OK:72 indicates ready.

Step 2: Open file

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 analysis takes a long time, it will periodically output INFO:opening:...; if the timeout is reached, it outputs ERR:open_timeout_xxs。

Step 3: Global overview

idapro_survey_binary(detail_level="minimal")

Focus on:

  • Architecture (x86/x64/ARM)
  • Entry points (main/WinMain/DllMain)
  • Interesting strings (URLs, paths, error messages)
  • Import categories (crypto functions? network APIs? file operations?)
  • Hot functions (functions with high xref counts are usually key logic)

Step 4: 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 refine

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. Don't calculate bases manually — anytime you need to convert numbers, use idapro_int_convert
  2. Survey first, then dive deep — First look at the overview, then analyze in a targeted way
  3. Continuously add comments and rename — Continuously update 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 the solution from the disassembly, using simple Python to assist with 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" — The old database file may be locked,open.ps1 will automatically fall back to a Temp copy (the output contains the (temp copy) marker)
  10. When opening the GUI/complex samples with auto-analysis enabled — By default add -TimeoutSeconds 600, do not mistake a long INFO:opening:... for a stuck script

Routing context

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

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

Peer related modules: radare2/(alternative when IDA is unavailable)

On-Demand Bootstrap

The entry script of this skill is already connected to the unified bootstrap system.

Automation capability boundaries

Tool Can be installed automatically Installation method Description
idalib-mcp ✓ pip install (from GitHub) start.ps1 Automatically install 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 another 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)
  • Python is installed (idalib-mcp depends on Python)