English ｜ 简体中文
Give any AI agent the workflow of a real reverse engineer for any unknown file: identify → fingerprint → static → dynamic → targeted breakthrough → model & verify → document.
- Zero third-party dependencies — pure Python standard library, works the
moment you unpack it. No
pip install, no build, no virtualenv. - Targets every major platform — Windows PE / Linux ELF / macOS–iOS Mach-O / Android APK / iOS IPA / .NET / Java / Python pyc / Web·WASM·Electron / firmware / private formats / SQLite.
- Bounded memory, speed first — streaming scans; string extraction on a 100 MB file takes roughly one second.
- Read-only analysis — never writes to the target, never patches it, never generates registration codes.
- Ships with its own test harness — 146 self-test cases + 76 end-to-end integration checks; all must pass before a commit is allowed.
⚠️ Authorized use only. Only reverse-engineer targets you own or have written authorization to analyze. See USE-POLICY.md for the authorization policy and LICENSE (MIT) for the legal terms.
中文文档： README.zh.md ・ INSTALL.md ・ CONTRIBUTING.md ・ SECURITY.md ・ USE-POLICY.md ・ CODE_OF_CONDUCT.md ・ PUBLISHING.md
- Install into your AI runtime
- Quick start
- Commands
- Concepts worth knowing
- Self-testing and gates
- Symbol recovery (MSVC / Itanium / Rust)
- Repository layout
- Compliance
- Contributing
This skill follows the Agent Skills open standard — a single SKILL.md with
YAML frontmatter. The same file drops into Claude Code / Codex CLI / Hermes /
OpenClaw / Cursor / Gemini CLI without modification. Only the skills
directory differs between runtimes:
cd scripts
python _dev/_install.py --auto --verify # detect which runtimes exist locally
python _dev/_install.py --auto # install into all detected runtimes| Runtime | Personal scope | Project scope |
|---|---|---|
| Claude Code | ~/.claude/skills/ |
.claude/skills/ |
| Codex CLI | $CODEX_HOME/skills/ (default ~/.codex/skills/) |
.codex/skills/ |
| Hermes | ~/.hermes/skills/ |
— |
| OpenClaw | ~/.openclaw/skills/ |
.openclaw/skills/ |
| Cursor | — (project scope only) | .cursor/skills/ |
| Gemini CLI | ~/.gemini/skills/ |
.gemini/skills/ |
On Windows, ~ means %USERPROFILE%. Full instructions, manual installation and
a troubleshooting table live in INSTALL.md.
The toolkit is pure Python stdlib (3.10+), so every runtime runs on every OS — no compile step, no binary wheels:
| OS \ Runtime | Claude Code | Codex CLI | Hermes | OpenClaw | Cursor | Gemini CLI |
|---|---|---|---|---|---|---|
| Windows | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| macOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Verified paths: os.path.join / os.sep throughout (no hardcoded C:\),
streaming I/O with no mmap tricks, and every format parser tested against
byte-level synthetic fixtures on Windows (the other two OSes share the same
stdlib surface; PE/ELF/Mach-O fixtures are OS-independent).
After installing, start a new session. Most runtimes scan skills at session startup, so a skill installed mid-session will not load until the next one.
# Python 3.10+ is the only requirement. Nothing to install.
cd reverse-engineering/scripts # the scripts/ directory at the repository root
python re.py doctor --json # which external tools are available here
python re.py triage some-unknown-file --json # first thing to run on an unknown target
python re.py plan some-unknown-file --json # what to do next
python re.py report some-unknown-file --out report.md # Markdown reportJust
cd scriptsand run — no installation, no build step, no virtualenv. If you got the project viagit clone, enterscripts/after cloning.
When an agent calls this tool, always pass --json. Exit codes 0 / 2 / 3 / 4
mean success / usage error / target unreadable / analysis error. Under --json
every subcommand emits a top-level ok field, and a self-test case guards that
contract.
A note on exit code 1. It is never a legal outcome of this CLI — it means
an uncaught exception escaped. That is a bug, not a result. The same philosophy
runs through the whole codebase: a failure must never be reported as a success.
There are 50 subcommands in three layers: 39 analysis commands (the
table below, schedulable by the orchestration layer), 3 platform/contract
commands (provider unknowns bundle — cross-cutting evidence-contract
capabilities) and 5 orchestration/state commands (require flow case
result toolgraph, used by an agent for routing and caching).
| Command | Purpose |
|---|---|
doctor |
Probe the local toolchain (83 external tools) |
identify |
Format identification + structural parsing (PE/ELF/Mach-O/DEX/ZIP/pyc/WASM/SQLite/class/firmware headers) |
strings |
Streaming string extraction (filter by category/regex, UTF-16 aware) |
entropy |
Overall entropy + block entropy curve (locate encrypted/compressed regions) |
imports |
Import table / dependent libraries (the behaviour map) |
info |
Deep structural parsing |
triage |
One-shot first pass (identify + entropy + strings + IOCs + packer detection) |
carve |
Carve embedded files by magic number (firmware / overlay analysis) |
apk |
Android APK reverse engineering (AXML manifest semantics: package/version/permissions/components/exported surface/signing, DEX summary, native libs) |
dexmap |
DEX method-level interface map (api_surface call graph, JNI symbol mapping, component entry points, code-embedded URLs) |
ipa |
iOS IPA reverse engineering (Info.plist / bundle / frameworks / provisioning) |
iso |
ISO9660 disc image inventory & extraction (incl. Joliet, UDF probe) |
fsx |
Firmware / embedded-filesystem signature scan & extraction (binwalk-style) |
replica |
System replication (deterministic manifest / reproducible pack / verify & tamper detection) |
endpoints |
In-application interfaces (API paths / IPC / Intent actions / COM ProgIDs / gRPC / SOAP) |
ports |
Port interfaces (explicit ports + protocol default-port pairing, observed vs derived confidence) |
netaddr |
Network addresses (URL / IPv4 / IPv6 / domain / email / UNC, with scope annotation) |
diff |
Byte-level diff of two files (version comparison / reversing private formats) |
plan |
Generate a step-by-step analysis plan, trimmed to the local toolchain |
report |
Produce a Markdown analysis report |
magic |
Magic-number lookup |
disasm |
Disassembly (x86 / x86-64 / ARM64 / Thumb) |
funcs |
Function identification + fingerprints + XREF |
cfg |
Control-flow graph for a single function |
struct |
Control-flow structuring (if / loop / switch + pseudocode skeleton) |
ir |
Per-instruction lightweight IR (assign / load / store / branch semantics) |
fundeep |
Function deep-dive (full dossier + call-chain expansion + similar functions) |
xref |
Cross references (who calls whom) |
sim |
Function-level similarity diff between two binaries |
semantics |
Per-function semantic summary (which APIs it calls, what it does) |
capability |
Capability detection (capa-style rule library → behaviour + ATT&CK mapping) |
symbols |
Symbol recovery (C++/MSVC/Rust demangle + Go pclntab) |
obfstr |
Obfuscated string recovery (stack strings + XOR decryption loops) |
evidence |
Wrap findings as traceable evidence + register residual unknowns (evidence contract layer) |
layout |
Binary layout + static mitigations (ELF program headers / PE DllCharacteristics) |
peres |
PE resource tree (type / name / language) |
archs |
Mach-O / universal-binary architecture list |
plist |
Apple plist parsing (XML / binary) |
dotnet |
.NET managed-assembly metadata (CLR header, metadata streams, assembly name) |
goinfo |
Go binary buildinfo (compiler version, modules, build settings) |
evm |
EVM bytecode dispatch selector table |
demangle |
Symbol demangling (C++/Rust/Swift) |
provider |
Analysis provider selection & probing (deterministic, never fails over) |
unknowns |
Residual-unknown governance (record / update / adjudicate / optimistic concurrency) |
bundle |
Evidence bundle export / import / compare (canonical bytes, tamper-evident, replayable) |
require |
Look up which subcommands fit an intent (the agent's routing entry point) |
flow |
Staged workflow: what to run now (parallelizable batches shown together) |
case |
Analysis state directory: persist results, reuse them, detect staleness |
result |
Result summary + error classification (prevents useless retries) |
toolgraph |
Tool transition graph: what to run after this one |
Three design decisions shape everything above.
1. Never report a failure as a success. This is the single most important rule
in the project, and defects in this class are treated as vulnerabilities. A
malformed PE that fails to parse must not come back as ok: true with zero
imports; a truncated scan must not look like a completed one; a stat that was
never computed must not be printed as 0. Where a value genuinely cannot be
computed, the field is reported as null with an explanation — never as a
plausible-looking wrong number.
2. A gate that never blocks is not a gate. Every check tool is judged by its
exit code, not by its prose. A self-test that silently runs zero cases is a
failure, not a pass. The tool-matrix harness in scripts/_dev/_matrix.py carries
an explicit guard for this: if it manages to run zero groups, it fails loudly
instead of reporting "no problems".
3. Verify by evidence, not by assertion. Every claim about behaviour in this repository is expected to be backed by an actual file path and line number, or by a runnable check. Recommendations are not accepted because they sound right.
python selftest.py # full self-test (146 cases, ~3 min)
python selftest.py --only 性能 # run one category only
python _dev/_lint.py # static audit (syntax / swallowed exceptions / hardcoded paths)
python _dev/_e2e.py # end-to-end: all 50 subcommands against real PE files
python _dev/_ossaudit.py # open-source compliance self-auditCoverage runs along three axes: correctness (synthetic samples plus real
system files), robustness (empty files, truncation, bit-flip mutation, garbage
input) and performance (100 MB streaming scan). Two further hard constraints
are enforced: zero third-party dependencies and the ok field contract
for --json.
| Command | Exit code | Meaning |
|---|---|---|
selftest.py |
0 all green / 1 failures present / 2 --only matched nothing |
Silently running zero cases is an error, not a pass |
_dev/_lint.py |
0 zero findings in production files / 1 findings present |
Warnings in _dev/ scaffolding are listed separately and do not affect the exit code |
_dev/_undefined.py |
0 clean / 1 problems |
A zero-dependency pyflakes |
_dev/_ossaudit.py |
0 no high-severity items / 1 high-severity items present |
Open-source compliance self-audit |
Where make exists (Linux / macOS / WSL):
make check # lint + undefined names + full self-test (required before every commit)
make all # check + end-to-end + compliance audit (required before a release)
make help # list every targetNative Windows environments usually lack make; just run the corresponding
python xxx.py commands above. The Makefile contains no logic — only command
aliases.
lib_symbols.py implements three demanglers with no external dependencies:
| Dialect | Prefix | Coverage |
|---|---|---|
| Itanium C++ ABI | _Z |
GCC/Clang: nested names, templates, substitution tables, member CV/ref qualifiers, operators, thunks, typeinfo/vtable/guard/TLS |
| MSVC | ? |
Windows C++ / drivers / COM: full LLVM grammar, back-references, thunks, RTTI, C++/CX hat pointers |
| Rust legacy / v0 | _ZN…17h / _R |
legacy hash stripping; v0 punycode idents, generics, lifetimes, const generics |
The MSVC path is aligned character-for-character against
dbghelp!UnDecorateSymbolName and measured on 61,248 real exported symbols
from system DLLs:
valid samples 61205
exact character match 51337 (83.88%)
including dbghelp quirks 61138 (99.89%)
still mismatched 67 (0.11%)
gave up 0 (0.00%)
correct rate (w/ quirks) 99.89%
end-to-end coverage 99.82% (of all input)
"dbghelp quirks" are defects in dbghelp itself, each confirmed with a minimal
reproducing case (no space before CV, duplicated trailing __ptr64 on
variables, dropped const on pointer return values, and so on). The complete
list with minimal cases lives in scripts/_quirk.py (reference documentation;
no code imports it). All 67 mismatches are attributable to dbghelp defects
rather than grammar gaps in this engine — this project deliberately does not
"align to a defect", and the reasoning is recorded in that file's module
docstring.
C++/CX hat pointers (
^), the$AA–$ADextensions, do not exist in LLVM at all. They were reverse-engineered for this project as a 2-bit CV ladder. Seereferences/research.md.
reverse-engineering/
├── SKILL.md # skill entry point (this is what the AI reads; Chinese)
├── INSTALL.md / INSTALL.en.md # installation into each AI runtime (zh / en)
├── README.md # English README (primary, this file)
├── README.zh.md # 简体中文 README
├── PUBLISHING.md / .en.md # open-source publishing guide (maintainer manual, zh / en)
├── CONTRIBUTING.md / .en.md # contribution guide (zh / en)
├── SECURITY.md / SECURITY.en.md # vulnerability disclosure (zh / en)
├── USE-POLICY.md / .en.md # usage policy (zh / en; explicitly NOT a license)
├── CODE_OF_CONDUCT.md / .en.md # code of conduct (zh / en)
├── LICENSE # MIT (standard text, no additional restrictions)
├── CHANGELOG.md # changelog
├── Makefile # command entry points (make test / lint / check)
├── .editorconfig # editor configuration
├── .github/
│ ├── workflows/ci.yml # CI: three platforms × multiple Python versions
│ ├── ISSUE_TEMPLATE/
│ └── PULL_REQUEST_TEMPLATE.md
├── references/
│ ├── workflow.md # general methodology: five-layer model / hypothesis-driven / SOP / ABI / anti-debugging
│ ├── playbooks.md # 13 target classes: pressure points, toolchains, pitfalls
│ ├── toolchain.md # tool matrix, install sources, learning path
│ ├── ecosystem.md # open-source ecosystem map: four-layer stack / project comparison / decision tree
│ ├── research.md # paper index, organised by "where you're stuck"
│ ├── ai-calling-protocol.md # how an AI picks tools: intent lookup / summary layer / orchestration
│ ├── top-tier-tools.md # tools and habits of top reverse engineers, with an "AI reachability" column
│ ├── open-source-survey.md # open-source survey (2120 repos) + capability matrix behind the new commands
│ └── legal.md # compliance red lines (CN / US / EU + self-check list)
├── rules/ # capability rule library (capa-style, loaded by `capability`)
│ └── imported/ # 910 rules translated from capa-rules (Apache-2.0, see NOTICE.md)
│ ├── anti-analysis.yml # anti-debugging / anti-analysis
│ ├── crypto.yml # AES and similar crypto constants and APIs
│ ├── network.yml # HTTP / network communication
│ └── process.yml # process creation / WMI / shell
├── assets/
│ ├── frida-templates.js # Frida hook templates (native / Android / iOS / plaintext capture / unpacking)
│ └── notes-template.md # analysis notes template
└── scripts/
├── re.py # CLI entry point (50 subcommands)
├── lib_formats.py # magic-number library + per-format parsers
├── lib_analyze.py # strings / entropy / IOCs / diffing / carving
├── lib_disasm.py # disassembly dispatcher
├── lib_x86.py # x86 / x86-64 decoder
├── lib_arm.py # ARM64 / Thumb decoder
├── lib_code.py # function identification / CFG / XREF
├── lib_ir.py # lightweight IR lifting + control-flow structuring
├── lib_fundeep.py # function deep-dive (dossier + call chain + similar)
├── lib_semantics.py # function semantic profiling
├── lib_libscan.py # library-function and crypto-constant identification
├── lib_symbols.py # MSVC / Itanium / Rust demangling engine
├── lib_names.py # symbol recovery (Go pclntab / symbol table / exports)
├── lib_obfstr.py # obfuscated string recovery (stack strings + XOR loops)
├── lib_rules.py # capability rule engine (built-in YAML subset parser + matcher)
├── lib_agent.py # orchestration: intent→command lookup / workflow / state / transition graph
├── lib_evidence.py # evidence contract layer: evidence model + residual-unknown governance
├── lib_contracts.py # platform contracts: error contract + provider abstraction + stage closure
├── lib_bundle.py # evidence bundle export/import/compare + snapshot reuse
├── lib_inspect.py # extra inspectors: layout / PE resources / Mach-O / plist / .NET / Go / EVM
├── lib_apk.py # APK / IPA reverse engineering (AXML manifest semantics, DEX summary, Info.plist)
├── lib_dexmap.py # DEX method-level interface map (api_surface / JNI mapping / entry points / URLs)
├── lib_iso.py # ISO9660 disc image parsing / inventory / safe extraction
├── lib_paths.py # 路径安全裁决点（提取类命令共用的穿越防护 + 最终路径断言）
├── lib_fsx.py # firmware signature scan, embedded extraction, deterministic replication
├── lib_tools.py # toolchain probing + analysis plans
├── _quirk.py # known dbghelp defects (reference doc, not a runtime module)
├── selftest.py # self-test suite (146 cases, incl. 5 installation cases)
└── _dev/ # development scaffolding (not shipped in releases)
└── _install.py # cross-runtime installer (--auto detect / --verify re-check)
Only reverse-engineer targets you own or have written authorization to analyze. Analyze malware in an isolated environment. Decompiled output, recovered source code and extracted keys must never be redistributed.
- Legal terms: LICENSE (standard MIT, no field-of-use restriction)
- Authorization and compliance policy: USE-POLICY.md (not a license)
- Compliance red lines (CN / US / EU + self-check list):
references/legal.md - Vulnerability disclosure: SECURITY.md
Read CONTRIBUTING.md first. Two constraints are non-negotiable:
- Zero third-party dependencies. Python 3.10+, standard library only. The
t_no_third_partytest will reject a pull request that breaks this. - Never disguise a failure as a success, and never disguise a skip or a truncation as a pass. A new check must be able to go red; adding a guard requires showing that withdrawing the fix makes the test fail.
Every fix is expected to come with a regression case in selftest.py, and commit
messages must answer three questions: what changed, why the original code was
wrong, and what the blast radius is.