ida-reverse-engineering

name: ida-reverse-engineering description: > Drive IDA Pro through the IDA Pro MCP like a senior reverse engineer: don't just narrate decompiler output, transform the database. Use this whenever the user is reverse engineering, analyzing malware, working a crackme or CTF, or doing binary/firmware analysis with IDA Pro over an MCP connection (mrexodia/ida-pro-mcp or idalib-mcp) — and especially when the agent keeps guessing at raw pseudocode instead of renaming functions and variables, defining structs, fixing types, and adding comments. Covers the iterative cleanup loop, anti-hallucination rules (always use int_convert; read real bytes/strings/xrefs), a triage/deobfuscation/library-resolution pre-pass, a definition-of-done, game-binary reversing (Unity/IL2CPP, Unreal, RTTI, anti-cheat/DRM), and bundled IDAPython scripts. Trigger even if the user only says "reverse engineer this binary", "clean up this IDB", "make this pseudocode readable", "dump the Unity/Unreal SDK", "reverse this game", or names IDA tools, without saying the word "skill".

Senior Reverse Engineering with IDA Pro (MCP)

This skill turns a model connected to IDA Pro via MCP into something that behaves like an experienced reverse engineer instead of a narrator. The single biggest failure mode of an MCP-driven RE agent is treating decompiler output as an answer to explain rather than raw material to transform. A junior reads sub_401000, says "this looks like it validates a license," and moves on. A senior renames the function to validate_license, names every variable, defines the struct behind *(a1 + 0x10), fixes the argument types, comments the algorithm, re-decompiles to confirm the output got cleaner, and only then moves on — leaving the database permanently better than they found it.

Your job is to do the second thing, on every function, using the MCP write tools.

You are a capable model. Use that: reason from evidence, form hypotheses and test them against the binary, and decide where to spend effort. The structure below is a reliable default, not a cage — adapt it when the binary calls for it, but never skip the parts that exist because models specifically fail at them (base conversion, struct recovery, writing findings back).

Scope and ethics. This skill supports legitimate reverse engineering: malware analysis and triage, vulnerability research, interoperability, firmware/protocol analysis, CTFs, and crackmes. It is about understanding and documenting binaries. Do not use it to author malware, build working exploits/payloads, defeat licensing for piracy, or evade detection. Analyzing how a sample works is fine; weaponizing it is not.

When this skill triggers: first three moves

Before any deep work, orient. Skipping this is how analyses go wrong from the start.

1. Confirm the live tool surface. Tool names differ across server versions and forks (older releases use granular names like rename_local_variable; recent main consolidated them into rename, set_type, declare_type). List the server's registered tools once and match by capability, not by the names in this doc. Full mapping and legacy↔current table: references/tool_reference.md.
2. Triage the binary so you know what you're in and where the interesting code is — run scripts/ida_triage.py (see "Binary-level workflow" below).
3. Pick first targets from evidence — entry points, exported APIs, and the functions behind the most interesting strings — not from whichever function has the lowest address.

Reversing a game? Stop and read references/game_re.md before the manual loop. Games carry metadata (IL2CPP global-metadata.dat, Unreal reflection, C++ RTTI) that names thousands of functions at once — fingerprinting the engine and running the right recoverer first saves you from grinding sub_* by hand.

Prime directive: write findings back, don't just describe them

Every conclusion you reach about the code must be persisted into the IDB with a tool call. If you understand something well enough to say it in chat, you understand it well enough to encode it: a rename, a type, a struct, or a comment. Chat-only narration is the failure this skill exists to prevent — a paragraph of prose in the conversation helps no one revisiting the database tomorrow; a rename helps everyone, forever.

So: prefer acting over reporting. The moment you'd write a sentence about what something is, make the edit that says so in the IDB instead.

The core loop (run per function until "done")

Work one function at a time. The loop is iterative on purpose: each edit makes Hex-Rays re-render cleaner pseudocode, which exposes the next thing to fix. Decompiling once and stopping is the mistake — you never see (or get to compound) the readability gains.

1. Decompile. decompile(addr) to get current pseudocode. Read it as a hypothesis to test, not a transcript.
2. Orient with ground truth, not guesses. Determine the function's real purpose from the API calls it makes, the strings it references, the constants it uses, and who calls it (xrefs_to, callees). A suggestive auto-name proves nothing; being called from the TLS callback proves a lot. Resolve any numeric value with int_convert.
3. Rename for meaning. rename the function and every default-named local, global, and stack variable to a descriptive name. No vN, aN, sub_*, dword_*, loc_* should survive in code you've analyzed. A slightly-wrong name you fix later beats v14 forever.
4. Recover types and structs — the highest-leverage step. Wherever you see *(x + offset) arithmetic, define the structure with declare_type and apply it with set_type (use infer_types as a starting point). Hex-Rays will rewrite the offset math into x->field_name across the whole function at once. Fix pointer/array/signedness mistakes the decompiler made. This single habit accounts for most of the difference between sludge and readable code — this is the step to slow down and think on.
5. Comment the non-obvious. set_comments on the algorithm, the why behind tricky branches, decoded constants, and anything that took effort to understand. Comments land in both disassembly and pseudocode. Don't comment the obvious — comment what the next analyst would otherwise have to re-derive.
6. Re-decompile and verify. Decompile again. Confirm your edits took effect and the output is genuinely more readable. If a type made things worse, revert it. Then move to the next function.

Definition of done (per function)

A function is "done" when:

• it has a descriptive name reflecting its actual purpose (not sub_*);
• zero default-named identifiers remain (vN/aN/dword_*/etc.);
• pointer-offset arithmetic has been replaced by struct field access wherever a struct fits;
• argument and return types are correct;
• the core logic and any non-obvious behavior are commented.

Use scripts/re_progress.py to measure this across the whole database and find what's left.

Anti-hallucination: the operations you are worst at

Be honest about where models fail. RE depends heavily on exactly the operations you are least reliable at — base conversion, byte order, pointer arithmetic — and you will produce confident, fluent, wrong answers if you do them in your head. The fix is not "try harder"; it's "don't do them in your head at all."

Self-check: before you state any numeric fact, address, offset, decoded constant, or byte interpretation, ask — did I read or convert this with a tool, or did I compute it mentally? If mentally, stop and route it through a tool before it enters your analysis. One transposed nibble silently invalidates everything downstream.

• Never convert number bases by hand. Always use int_convert for hex ↔ decimal ↔ bytes ↔ ASCII ↔ binary. If math beyond conversion is needed, say so explicitly rather than computing it inline (consider a math MCP for heavy arithmetic).
• Read real data instead of assuming it. Use get_bytes, get_int (with explicit width/endianness like u32le), get_string, read_struct, and get_global_value to read what's actually in the binary. Do not invent values.
• Derive purpose from evidence. Base claims on xrefs_to, callees, imports, and strings — not on an auto-generated name.
• Trust the binary over old comments. Stale or wrong pre-existing comments are common; verify against the actual code before relying on them.

Binary-level workflow (the phases around the loop)

Don't start renaming function #1 blindly. Orient, remove noise, then go deep. Full detail and worked patterns live in references/methodology.md; the short version:

1. Recon / triage. Run scripts/ida_triage.py (or read its sections via py_eval) to inventory entry points, segments and their entropy, imports (with commonly-abused APIs flagged), strings, and anti-analysis indicators. This tells you what kind of binary you're in and where the interesting code is.
2. Deobfuscation pre-pass. You perform badly on obfuscated code and will narrate nonsense with full confidence — so neutralize string encryption, import/API hashing, control-flow flattening, and anti-decompilation tricks before deep analysis. If the binary is heavily obfuscated, fix that first; everything downstream depends on it.
3. Resolve library code. Apply FLIRT signatures (and/or Lumina) so the C runtime, STL, and known library functions are identified automatically. This stops you from wasting effort renaming std::vector internals and sharply improves accuracy on the code that's actually the author's.
4. Systematic cleanup. Now run the core loop in a sensible order: start from entry points, exported/imported API usage, and string cross-references, then follow xrefs_to outward. Analyzing callees before their callers often lets you name the parent correctly. Let the database's improving state guide what to tackle next.
5. Document. Maintain a running report.md (or RE/*.md) capturing what each major function does, recovered structures, the overall control/data flow, and any IOCs. When you finish, the report plus the cleaned IDB are the deliverable.

MCP tool quick-map

Confirm names against the live tool list (see "first three moves"). Grouped by what you reach for:

• Read code: decompile, disasm, analyze_funcs, basic_blocks, callgraph
• Find things: lookup_funcs, list_funcs, list_globals, imports, xrefs_to, xrefs_to_field, callees, find_regex, find_bytes, find_insns, search_structs
• Read data (ground truth): get_bytes, get_int, get_string, get_global_value, read_struct, int_convert
• Write (the important part): rename (funcs/locals/globals/stack), set_type / infer_types, declare_type, set_comments, define_func, define_code, undefine, declare_stack / delete_stack, patch_asm
• Dynamic (extension, enable with ?ext=dbg): dbg_start, dbg_run_to, dbg_step_*, breakpoints, registers, dbg_read/dbg_write, dbg_stacktrace
• Escape hatch: py_eval(code) runs arbitrary IDAPython in IDA's context — use it for anything the dedicated tools don't cover, including running the bundled scripts.

Full mapping, batch payload shapes, and the legacy↔current name table: references/tool_reference.md.

Operating the MCP tools well

Knowing which tool to call isn't enough; most wasted effort comes from mis-operating the tools themselves. These habits compound — getting them right makes every loop faster and your "done" checks actually trustworthy.

• Batch your writes. The API is batch-first: rename takes all four namespaces (func/data/local/stack) in one call, and set_type / set_comments take lists. Collect every edit for a function, then send one batch per tool — not twenty calls for twenty variables. It's faster and keeps your context clean.
• Check the per-item error field, then retry. A batch returns a parallel list where each item is {..., "error": null | "message"}. A call that "succeeded" can still have half its items rejected (invalid type, Hex-Rays refused a prototype). Read every item's error, fix the cause, and re-send the failures. Don't mark anything done off a return you didn't inspect.
• Verify the write actually landed — don't trust the return. set_type can be silently rejected or only partly applied. The proof is the re-decompile: after applying a struct, confirm *(a1 + 0x10) actually became a1->length. If it didn't, the type didn't take — fix it rather than moving on.
• Follow pagination to completeness. Search/listing tools (xrefs_to, list_funcs, find_*) paginate via a cursor ({next: offset} until {done: true}). Stopping at page one gives you a subset of xrefs — and "called from one place" when it's actually forty leads to a wrong parent name. Drain the cursor before drawing conclusions about callers or references.
• Spend context wisely. For orientation, analyze_funcs bundles decompile + asm + xrefs + callees + strings + constants in a single call — cheaper than six separate ones. For pure read-only state (segments, structs, imports), read the MCP resources (ida://idb/segments, ida://structs, ida://import/{name}) instead of issuing tool calls.
• Treat any prior decompile as stale after a write. A rename or set_type changes the pseudocode. If you keep reasoning over the listing already in your context, you'll reference names that no longer exist. Re-decompile before the next analytical step, not just at loop's end.
• Declare dependent types in order. declare_type parses C — a struct that references another type needs that type (or a forward declaration) first; pad fields you don't understand yet with char field_N[size]; so offsets stay aligned. Nested structs and vtables fail to parse otherwise.
• Use py_eval as a last resort, and capture its value. Prefer the typed, dedicated tools (they're safer and validated). Reach for py_eval only for bulk operations or APIs with no wrapper, and remember it returns the last expression's value — return it explicitly rather than relying on stdout.
• In headless idalib, target the right database. With multiple DBs open, pass database= (session id / path) on each call. Omitting it writes your renames into whatever DB is current — a silent, painful mix-up.

A worked pass (what the tool calls actually look like)

Cleaning one function sub_401000 that decrypts a config blob:

1. lookup_funcs(["sub_401000"]) → resolve the address.
2. analyze_funcs(["0x401000"]) → one call for pseudocode + xrefs + callees + strings + constants.
3. See *(a1 + 0x10) and a constant 0x6C616D66. int_convert(["0x6C616D66"]) → it's the ASCII tag "flam" (never decode this in your head).
4. declare_type the layout: struct Config { unsigned int magic; char* name; unsigned int length; };
5. set_type([{func:"0x401000", local:"a1", type:"Config*"}]).
6. decompile("0x401000") again → verify *(a1+0x10) is now a1->length. (If not, the type was rejected — fix and repeat.)
7. One batched rename: func → decrypt_config, plus the local/stack vars; one set_comments for the algorithm and the decoded tag.
8. Check each returned item's error; re-send any that failed. Move to the next function.

When to drop to disassembly or dynamic analysis

The decompiler is the default lens; reach lower when it's lying or missing:

• Disassembly (disasm) when the decompiler output looks wrong, the function involves heavy SIMD/intrinsics, calling conventions are non-standard, or you need exact instruction-level behavior (flags, alignment, jump tables).
• Dynamic analysis (debugger extension) when static analysis stalls: self-modifying or packed code, runtime-computed values, encrypted strings decrypted in memory, or you simply want to confirm a hypothesis by watching it run. Enable ?ext=dbg, set breakpoints at the interesting addresses, read memory/registers — then feed what you learn back into renames, types, and comments. Run untrusted samples only in an isolated, disposable VM.

Bundled scripts

Run these inside IDA (File ▸ Script file) or paste their bodies into py_eval. They are analysis/cleanup aids — they read and report, or help you build structures; none changes program behavior. See each script's header for usage and its heuristics/limits.

Recon & finding the interesting code (do these early):

• scripts/ida_triage.py — The recon pass; run first on any new sample. Metadata, segments with Shannon entropy (flags packed/encrypted regions), imports with commonly-abused APIs highlighted, notable strings, and anti-analysis indicators.
• scripts/function_capabilities.py — Lightweight capa-style ranking: attributes imported APIs to the functions that call them and ranks functions by how many behavior categories (net/crypto/inject/persist/anti/…) they touch, so you know where to start.
• scripts/string_xref_map.py — The "follow the strings" pivot: maps notable strings (URLs/IPs/paths/registry/mutexes) to the functions that reference them.
• scripts/crypto_const_scan.py — Findcrypt-style scan for known crypto constants (AES S-box, SHA/MD5 tables, Blowfish P-array, CRC32 table, Base64 alphabets, ChaCha sigma) and the functions that use them. Won't catch table-less ciphers like RC4 — find those behaviorally.

Deobfuscation pre-pass:

• scripts/stackstring_recover.py — Reconstructs strings built on the stack via immediate stores (a common way to hide strings from strings), so you can comment the real literals.

Type recovery (step 4 of the loop):

• scripts/struct_recovery.py — For a chosen function, collects [base + displacement] accesses, infers field widths, and emits a C struct skeleton to hand to declare_type and then set_type onto the base pointer.

Progress & documentation:

• scripts/re_progress.py — Operationalizes the definition-of-done: percentage of functions still auto-named, functions lacking comments, and (with DEEP = True) the functions with the most default-named variables. Keeps you honest about what's left.
• scripts/export_report.py — Harvests renamed functions, their comments, and declared structs/enums and writes a report.md skeleton in the methodology.md template, with TODO placeholders for the prose.

Comparison & dynamic analysis (situational):

• scripts/function_fingerprint.py — Exports relocation-independent per-function fingerprints (normalized mnemonics + operand types) to JSON; run in two databases to diff samples/versions/patches, or to spot duplicated code within one binary.
• scripts/dump_region.py — Debugger helper to dump a memory region or segment to disk (e.g. an unpacked payload after a breakpoint) and report its entropy. Needs the debugger extension (?ext=dbg); run untrusted samples only in an isolated VM.

References

• references/tool_reference.md — Complete MCP tool → RE-action mapping, batch payload formats, and the legacy↔current name table. Read this when you need exact tool names/arguments.
• references/methodology.md — The deeper playbook: triage checklist, naming conventions, struct/type recovery technique, calling-convention cheats, common code patterns (loops, switch tables, crypto, string ops), and per-platform notes (Windows/Linux/macOS/embedded). Read this when you want the "how a senior actually thinks" detail.
• references/game_re.md — The game-binary playbook. Read this first whenever the target is a game: fingerprinting the engine (Unity/IL2CPP, Unreal, Source, etc.) and middleware, recovering names wholesale via IL2CPP dumpers / Unreal SDK generators / RTTI, typing math+SIMD and the entity struct, recognizing DRM/anti-cheat, and building update-resilient signatures. Games reverse very differently from malware — metadata names the world before you touch the manual loop.
• references/reading_list.md — Curated RE books (with what each is good for) plus high-quality online references, practice sites, and primary architecture/ABI documentation. Point the user here when they ask how to get better at RE.

Common pitfalls (the short list)

Most reduce to one of these. If you're stuck or producing confident sludge, check here first:

• Narrating instead of editing — the cardinal sin. Prose without tool calls means nothing landed in the IDB. Write it back.
• Skipping struct recovery — leaving *(a1 + N) everywhere is the fastest way to keep pseudocode unreadable.
• Mental hex math — guaranteed to eventually corrupt an analysis. Route through int_convert.
• Trusting auto-names and stale comments — sub_* and old comments are leads, not facts.
• Turning the model loose on obfuscated or unsignatured binaries — deobfuscate and apply FLIRT/Lumina first, or expect confident garbage.