English · 简体中文

Capabilities · Structure · Install · Requirements · Failure catalogue · Scope · Maintenance

exe-reverse

An Agent Skill for Windows x86/x64 local-software reverse engineering: triage, byte-level patching, signature work, debugging, injection, dump repair, licensing-mechanism classification, algorithm recovery, packers and code virtualisation, managed assemblies, kernel drivers, and the hardware-observation layer — instruction tracing, hardware breakpoints, and hypervisor-assisted observation — that software tooling cannot substitute for.

It is a skill, not a tutorial: it is written to be loaded by an agent while it works, so it is organised for progressive disclosure — a short decision-oriented skills/exe-reverse/SKILL.md, detailed references loaded only when a step needs them, and parameterised scripts you can run directly.

How an agent is expected to consume this

SKILL.md is written as a procedure with gates, not as advice, because the observed failure mode is not ignorance — it is a model reading the whole thing, agreeing with it, and then reasoning from first principles anyway.

Four things in it are meant to be acted on:

• Five operating rules (O1–O5). Where they conflict with the current plan, they win until evidence overrides them.
• A symptom index. Each row is a failure that has already been paid for. A matching row is a stop signal: load that file before running another command, not after a few more attempts.
• Five gates (G1–G5), each an action with a pass criterion. "I understand the idea" does not clear a gate. They exist so that classification, host truth and a control build happen before the first patch, not after the third failure.
• A two-strike rule and stop conditions. Two failures of the same shape mean the model is wrong, not the parameters.

And one thing at the end that is meant to be withheld: "done" has a definition (six items). A clean log is not one of them. Anything short of all six is a checkpoint, and should be reported as a checkpoint with what remains.

The cheapest possible first command is python skills/exe-reverse/scripts/doctor.py. It answers three questions in one pass: which capabilities this host actually supports and what to install for the ones it does not, whether every script in the kit is runnable as-is, and which host facts would silently poison an experiment. python skills/exe-reverse/scripts/hwprobe.py is the deeper hardware-level probe beneath it, and python skills/exe-reverse/scripts/capabilities.py --verbose prints the next action for anything blocked.

What it is good at

• Deciding fast whether a request is achievable by changing the client at all, instead of burning hours on a decision the server owns.
• Establishing which host you actually have before a plan depends on it: a debugger installed, an elevated session, test signing, a second machine, or a hypervisor that intercepts the very mechanism the plan relies on.
• Patching without breaking the file: equal-length edits first, the checksum recomputed, the written bytes re-read from disk, and a length change reported as the structural edit it is.
• Making a signature honest about itself: how many sites a pattern matched, whether that count changed between builds, and whether the pattern is a locator or a coin flip.
• Separating "the bytes are in the file" from "the code runs" — the most common way a patch is reported as working while nothing changed.
• Classifying a licence decision before touching it: client-verified, client-rendered server data, or server-authoritative — three problems with three different answers, only two of which a binary change can reach.
• Working through a target that fights analysis: recognising which anti-analysis mechanism actually fired, and which layer can still observe the target when every hook is detected.
• Reaching for the hardware layer when a debugger cannot: hardware breakpoints that do not modify the bytes they watch, instruction tracing that records control flow without executing hooks, and an honest statement of what each of those requires and what it still cannot see.
• Keeping a long session honest: a live record, graded conclusions, bounded waits calibrated from a measurement, and a control build for every claim.
• Publishing what it learns without publishing the target — a scanner that reports identity shapes with their context, and an explicit list of what must not be redacted because redacting it destroys the reusable part.

Structure

SKILL.md, references/ and scripts/ live inside the skill directory, skills/exe-reverse/. Everything at the repository root is maintenance tooling shared across skills, not part of an installed skill.

skills/exe-reverse/SKILL.md     a procedure with gates, not background reading:
                                five moves -> five override rules (O1-O5)
                                symptom index (a matching row is a stop signal)
                                five gates (G1-G5, actions with pass criteria)
                                thirteen classification questions
                                target routing table
                                the tool/context budget rules
                                the workflow -> what "done" means -> stop conditions -> constraints
skills/exe-reverse/references/  loaded on demand, one topic each; the inventory with when to load
                                each one is skills/exe-reverse/references/routing.md
skills/exe-reverse/scripts/     parameterised and path-agnostic; runnable on a bare Python 3.10+
skills/exe-reverse/evals/       the with-skill / without-skill cases, and how to run them
skills/exe-reverse/evidence/    the machine-readable companions to the evidence summary
docs/tool-verification/         the evidence record for measurement passes (not shipped)
tests/                          the executable regression suite

The reference library is indexed, not memorised: skills/exe-reverse/references/routing.md carries every reference file with when to load it and every script with what it does, and it is the file to read once a route has been chosen.

Install

This repository is a skills repository: the skill lives at skills/exe-reverse/, which is the layout the skills CLI resolves, and it is installed by name rather than by copying a directory:

npx skills add <owner>/exe-reverse                 # install every skill in the repo
npx skills add <owner>/exe-reverse --list          # list what is here, install nothing
npx skills add <owner>/exe-reverse --skill exe-reverse -y
npx skills use  <owner>/exe-reverse@exe-reverse    # use it once, without installing

The CLI symlinks the skill into your agent's skills directory by default (--copy makes independent copies instead), -g installs for every project rather than the current one, and -a targets specific agents. With one skill in the repository, --skill exe-reverse is redundant today; it is written out because it is what selects a single skill once a second one exists.

Once installed, the agent loads SKILL.md when a task matches its description and pulls in references/* only as needed. No global state, no machine-specific paths, and no build step.

Requirements

Nothing is mandatory; each script checks what it needs, and skills/exe-reverse/scripts/hwprobe.py reports which of these are present here and which routes are therefore available — including the routes that are not available on a virtualised host.

If your toolchain lives outside PATH (a project-local tools directory, a versioned SDK folder), set EXEREV_TOOLS to one or more directories and the probes will find them:

set EXEREV_TOOLS=<dir>;<dir>                     # Windows
export EXEREV_TOOLS=<dir>:<dir>                  # POSIX

Tool	Used for
Python 3.10+	every script; the PE reader, patcher, host probe, capability registry and doctor are dependency-free
A disassembler/decompiler (IDA, Ghidra, Binary Ninja, Cutter)	reading code; several are GUI-only, and a GUI-only tool is a request for a human, not a reason to substitute a weaker one
A debugger (x64dbg, WinDbg)	locating runtime behaviour and watching values
dumpbin / link (MSVC toolchain)	header and import inspection when you have the SDK
An installer extractor (innoextract, 7-Zip, expand)	getting at a payload without running the installer. Extract first and re-triage what came out: it is a new unknown
Frida	runtime instrumentation where a hook is acceptable
Procmon / ETW tooling (wpr, logman)	file, registry and system event evidence
A .NET toolchain	managed assemblies are a different artifact with a different toolchain
A solver or emulator (Z3, Triton, angr, Unicorn, Qiling)	reducing a trace or a condition instead of reading it; skills/exe-reverse/references/symbolic-execution.md records which default of each will change your answer
An isolated VM	the analysis host is part of the experiment
A second machine	kernel debugging on a current Windows host
A CPU that reports the trace feature, plus a capture path	the hardware-observation routes; the probe reports what this host has, and on this platform the capture path is the open question rather than the decoding

None of these need to be on PATH: the scripts accept explicit paths for the tools they shell out to, and a runnable archive or a script counts as installed. skills/exe-reverse/scripts/capabilities.py carries the same list as a probed registry, with an executable next step and a cost estimate for each entry. ls skills/exe-reverse/scripts/ is the authoritative list; skills/exe-reverse/references/routing.md describes each one.

Read this first

Published for learning, research and authorized security testing only. It ships no exploit payloads, no target data and no third-party binaries — it is a method, a set of scripts and an evidence record.

Then read skills/exe-reverse/references/pitfalls.md. It is the most valuable file here — every entry is a failure that produced a working-looking artifact. Read it before building.

Scope

Built for working on your own software, samples you are authorized to analyse, and competition sandboxes. It contains no vendored third-party binaries and no target-specific data.

What it covers, and what it deliberately does not, is stated in the skill itself (skills/exe-reverse/references/coverage-and-limits.md). The short version: Windows PE on x86 and x64, deep on the layers that have been worked through — triage, patching, signatures, licensing classification, protectors, managed code, and the hardware-observation route map. Defeating a server-side authority, a fully automated general-purpose devirtualiser, defeating a named commercial protector as a product claim, and any guarantee on a Windows build this repository has not measured are not covered, and the skill is written to say so and stop rather than apply the nearest documented procedure to a target it was not written for.

Repository maintenance

Six tools live at the root and are not part of the installed skill:

check_repo.py      every skill discovered, frontmatter valid, scripts runnable, documented paths
                   resolve, README paths explicit and existing, and -- on the tracked surface only
                   -- no target identity (delegates the rules to scan_leaks.py)
check_refs.py      every cross-reference that names a section of another document reaches a real
                   heading in that document
check_routing.py   the on-demand inventory still matches the entry point: the symptom mirror agrees
                   with SKILL.md, and every reference file and every script is named in routing.md
check_commands.py  every command a document tells you to run is checked against the script's own
                   argparse table -- a documented flag that does not exist is drift the anchor
                   checks cannot see
check_budget.py    keep the always-loaded part from creeping: SKILL.md measured in lines and
                   tokens, index-row length, long files with no navigable head, hedged rules
build_scripts.py   audit for machine-specific leftovers (absolute paths, credentials)

Consistency has a natural counter-pressure — a broken path fails loudly and someone fixes it. Bloat has none, which is why the budget gate exists.

tests/benchmark.md holds the regression matrix: dimension → public target → the scripts the row exercises → measured result → strength label. docs/tool-verification/ is the evidence record for the measurement passes: what each script actually did, which independent method confirmed it, and which scenarios the target could not exercise. It exists so the coverage claims can be checked against runs instead of trusted.

---

Disclaimer

For learning, research and authorized security testing only. Every script, reference and recorded result in this repository exists to explain how Windows application analysis works, so that practitioners can reason about the tools they already own. Nothing here is a service, a product, or an endorsement of any particular use.

The material is provided as is, without warranty of any kind. Results are recorded as they were measured on one machine at one time; nothing here promises that a route will work on your target, your host or your toolchain. Verify before you trust, and work on copies.

Names of tools, libraries, file formats and hardening products appear only to make the material reusable; they belong to their respective owners, and this project is not affiliated with any of them.