Haseeb Heaven
a84c61e8ba
Preserve authenticated application graph evidence through checkpoint save/reopen, bind application artifacts by canonical path and digest, and retain legacy checkpoint compatibility. Current-head CI passed; real Electron runtime launch remains unverified.
RE-Agent
Reverse Engineering Agent for Legacy Software Maintenance
Investigate unsupported software. Recover documented behavior. Verify repairs and independent ports.
RE-Agent is a local-first, evidence-driven reverse-engineering toolkit for maintainers of authorized legacy desktop applications, command-line software, and games. It connects coding agents to static analysis, controlled runtime observation, memory evidence, and bounded reconstruction/verification workflows through existing CLI and MCP interfaces.
Status: Active development. RE-Agent does not automatically recreate arbitrary applications or prove whole-program equivalence. Scope, platform support, execution permissions, and available observations determine what can be verified.
What it is built for
| Workstream | Intended outcome | Evidence required |
|---|---|---|
| Legacy maintenance | Reproduce a failure, identify dependencies and platform assumptions, repair an authorized implementation | Original binary identity, reproducer, before/after regression |
| Native software analysis | Investigate PE/ELF/Mach-O code paths and binary interfaces | Function inventory, call references, provider identity and limitations |
| Runtime and memory investigation | Correlate observed behavior with static hypotheses | Authorized process/trace identity, bounded capture, reproducible conditions |
| Independent application porting | Reimplement a declared behavior slice on a new platform | Matching original/replica scenarios and explicit unsupported behavior |
| Game preservation engineering | Examine script formats, asset pipelines, engine interactions and gameplay behavior | File-format evidence, state/input traces, asset and frame comparisons where applicable |
| Verification | Detect regressions and expose unknown behavior | Raw original/candidate observations, explicit comparison rules and coverage |
Real-world investigation record
Project I.G.I. 2 — GConv / QVM tooling (2003 Windows PE32)
This is the project's primary documented legacy investigation, not a completed legacy-game port.
| Component | Evidence and result | Remaining work |
|---|---|---|
| Executable and DLL inventory | Hash-bound examination of gconv.exe, gconvapi.dll and vqdll.dll; function/import/export records |
Link native exports and calls to verified runtime semantics |
| QVM format work | Header/strings and partial instruction-format recovery; independently implemented qvmtool |
Full QVM execution, native registration and error/edge semantics |
| Behavioral comparison | Historical 120-script error-message comparison receipt | Reproducible replay corpus and fresh verification on supported worker |
| Porting / compatibility | Analysis and limited independent tooling | Full DLL ABI, codec compatibility, app/game port and release rights not verified |
Evidence: GConv case study · static inventory · rights-screened target catalog
Do not infer: a repaired original application, full IGI engine recreation, complete QVM execution, or unrestricted rights to original binaries/assets.
Evidence gallery
Screenshots are shown only when their provenance and capture scope are documented. An identical screenshot alone does not prove input replay or state equivalence.
- Retained native/game capture evidence and limitations — contains captured images and manifests; several images are fixture comparisons rather than legacy-port proofs.
- Game behavior verification contract — outlines state, input and frame requirements.
- Complete experimental benchmark inventory — contains development fixtures and partial reconstructions, clearly separated from actual legacy-maintenance case studies.
No verified end-to-end legacy application port with a complete original-versus-replica screenshot series is currently documented. That is an engineering gap, not something to cover with illustrative screenshots.
Analysis and reconstruction architecture
flowchart LR
T[Authorized original binary and assets] --> S[Static investigation]
T --> R[Controlled runtime and memory evidence]
S --> E[Canonical evidence and bounded hypotheses]
R --> E
E --> A[Host coding agent and reconstruction workspace]
A --> C[Candidate build]
C --> V[Independent differential verification]
T --> V
V -->|Mismatch and counterexample| E
V --> O[Scoped report: pass, mismatch, unknown]
Existing foundations: Ghidra/IDA/Hopper providers and other artifact workflows; Frida/LLDB/process observations; authenticated Evidence records; persistent investigation checkpoints; bounded build/test/repair loops; selected conditional Z3 expression proofs.
Important limits: Semantic heap recovery, generalized algorithm reconstruction, broad differential fuzzing, universal binary equivalence, and complete native Windows/GUI-worker acceptance are not established. Tools discovered on disk are not necessarily installed, integrated, or verified for a target.
Read architecture and autonomous reconstruction, runtime observation, verification scope, and open engineering issues.
Maintenance workflow
- Authorize and bind the target. Record original hashes, rights and support status. Preserve originals.
- Reproduce the defect or behavior. Capture inputs, dependencies, environment and failures.
- Correlate static and runtime evidence. Separate observed facts from inferred hypotheses.
- Repair or port in a separate workspace. Do not modify the original binary by default.
- Compare independently. Preserve mismatches as regression inputs.
- Report scope and limitations. A passing finite suite proves only its declared observations.
The nine documented maintenance modules cover provenance, triage, static diagnosis, runtime/memory observation, repair, porting, verification and release review. For the current branch's actual installed catalog, run:
node scripts/rea.mjs maintenance-skills
The module additions are tracked separately in PR #23; the catalog on develop may contain fewer modules until those changes merge. Community skill discovery reads metadata and instructions; it does not execute discovered code.
See maintenance workflow and community skill format.
Build and connect a coding agent
Requires a supported Node.js release and appropriate external analyzers for the target.
git clone https://github.com/heaven-hm/re-agent.git
cd re-agent
npm ci
npm run build:cached
node scripts/rea.mjs --help
node scripts/print-mcp-config.mjs /absolute/path/to/target --local
Use the generated MCP configuration with a supported host. Consult installation, CLI, and MCP contracts. The npm identity is re-agent; legacy command names exist for compatibility. Do not assume an upstream rea release contains fork-specific code.
See the MCP-tool_catalog, supported agents, and MCP registry references for current integration details.
Validation and development fixtures
The repository retains arithmetic, UI, managed-program, and small open-source application/game benchmarks because they test specific components and regressions. They are not showcased as professional legacy-support deliverables. Their scoped results, unverified cases, capture files, and test commands remain in benchmarks and validation reports.
A serious preservation case study should provide: independently identified original artifact; rights and environment; real reproducer; static/runtime evidence; candidate implementation and build instructions; replayable original/candidate comparisons; failure samples; platform matrix; and visual evidence where relevant. Until these exist, mark the target PARTIAL or UNVERIFIED.
Project map
| Location | Purpose |
|---|---|
src/ |
Providers, runtime capture, Evidence, maintenance and autonomy implementations |
maintenance-skills/ |
Modular, bounded agent workflows |
bridge/ |
Native/tool-specific bridges |
scripts/ |
CLI entrypoints, build and verification scripts |
tests/ |
Automated regression and contract testing |
benchmarks/ |
Engineering fixtures, source-hidden experiments, case-study artifacts |
docs/ |
Architecture, provider contracts, investigations and platform guides |
Documentation and governance
Legacy maintenance · Native investigation · Ghidra provider · Agent workflow · Evidence and MCP · Testing · Roadmap
Use RE-Agent only for authorized analysis, maintenance, preservation and independent porting. Software, assets, and optional tools keep their respective licenses. See usage policy, license and third-party notices.
Contribution standard: reproducible original/candidate evidence and truthful limits are more important than screenshots, target counts, or claimed reconstruction percentages.
Acknowledgments
RE-Agent builds on the original REA project. Dryxio/ReAgent informed the dependency-aware reconstruction scheduling design; no Dryxio source code was incorporated. See the integration review and third-party notices.