REAmon

Analyse anything. Connect the evidence. Understand the system.

REAmon is an AI-assisted reverse-engineering workspace and orchestration platform. It accepts arbitrary targets, profiles what it can, resolves compatible analysis capabilities, coordinates tools and agents, stores connected evidence, and presents the investigation through a live project workspace.

REAmon is for authorised reverse engineering, software analysis, education, and security research only. Analyse targets you own or are explicitly authorised to inspect. You are responsible for complying with applicable law, contracts, and third-party licences.

What REAmon is becoming

REAmon orchestrates reverse-engineering engines such as Ghidra, RetDec, JADX, Vineflower, CFR, Androguard’s Rust DEX decompiler, and ILSpy on the backend, then presents their output in one investigation workspace. Android APKs use isolated JADX and an alternate isolated Rust DEX decompiler; JVM .class/.jar artifacts can also use isolated Vineflower and CFR. Vineflower’s Kotlin plugin is experimental. Managed .NET PE assemblies use isolated ILSpy, and native ELF, PE, and Mach-O files use isolated Ghidra headless analysis with optional RetDec, Glaurung, and Kuna C-like alternatives. These providers publish bounded function or code-unit indexes in the code visualizer. Other formats and dynamic analysis still need matching engines. A workspace can contain multiple related targets and artifacts:

Workspace
├── Targets and artifacts
├── Environments and tools
├── Capabilities and agents
├── Tasks, findings, hypotheses, and evidence
├── Knowledge graph and timeline
└── Reports and live activity

Targets are intentionally open-ended: files, directories, repositories, processes, devices, services, remote hosts, captures, filesystems, debug sessions, custom targets, and unknown inputs. Platform-specific behavior belongs behind capabilities and plugins rather than in the workspace core.

Product direction and documentation

REAmon’s central job is to turn compiled or obfuscated artifacts into evidence-backed, decompiled code that can be understood, edited, reviewed, and maintained. Explanations support that work; they do not replace source recovery. The roadmap prioritizes decomp.wtf’s bounded, evidence-led process—unit-sized work, shared project knowledge, recorded attempts, meaningful validation, and explicit acceptance—then extends it to languages and formats without a reliable byte-for-byte compiler loop.

The decomp.wtf repository was archived on 2026-10-15 and is now a fixed workflow and code reference, not an active upstream. The maintainer cited community opposition to AI-assisted decompilation; REAmon must follow each target project’s rules and never assume that generated contributions are welcome. The reference portfolio also tracks independent analysis, graph, validation, and syntax-aware editing projects, with license and integration constraints documented before adoption.

WIP: language and format support

Language support is still in development and depends on the input format and the available analysis engine. A generated C-like listing or assembly representation is not the original source language, and “supported” does not mean that names, types, control flow, or behavior have been recovered exactly. Treat every decompilation as a starting point for review.

This is a work-in-progress capability matrix, not a compatibility guarantee. The planned rows identify areas to evaluate; they do not promise a release date. Detailed per-language scope is in the language matrix, and cross-workflow status is in the feature matrix. Current engines include JADX, Vineflower and CFR for isolated JVM .class/.jar alternatives, Androguard’s Rust DEX decompiler, ILSpy, Oxidizer through an optional analyzer pinned to angr 10.0.4, Ghidra, and WABT. Python bytecode uses the MIT-licensed pycdc 0.6.0 CLI in an isolated analyzer; its broad version support and reconstruction quality still need REAmon fixture validation. PyLingual remains an alternative for comparison, with a GPL-3.0 license and a larger local ML runtime. JavaScript bundles use the MIT-licensed webcrack 2.16.0 package in an isolated Node.js analyzer. Its AST-based transforms and bundle extraction are a starting point for project-level source recovery, not a claim that original names or behavior have been restored. Standard Lua 5.0–5.4 bytecode uses the MIT-licensed unluac fork in an isolated JVM analyzer. The MIT-licensed unluac-rs 1.4.4 JavaScript/WASM API runs in an isolated worker and adds strict alternate output for Lua 5.1–5.5, LuaJIT, and raw Luau. It returns .lua or .luau source with dialect-specific metadata and bounded prototype/CFG evidence. Luau vector constants use vector.create with three components by default; set REAMON_LUAU_VECTOR_SIZE=4 for four-wide targets, or set REAMON_LUAU_VECTOR_LIBRARY and REAMON_LUAU_VECTOR_CONSTRUCTOR for a host-specific constructor. The target host must expose that constructor. The official Luau compiler 0.742, distributed under MIT, checks saved Luau source in parse-only mode on amd64 agent images; Tree-sitter is the fallback elsewhere. This confirms syntax, not target-host API compatibility or behavior. Versioned decompilation fixture validation remains open. LuaJIT bytecode also uses the MIT-licensed LuaJIT Decompiler v2, built for Linux from its pinned Linux port. REAmon stores each engine’s output separately so it can be reviewed against the same input. Alternate output needs review and has no source-equivalence guarantee. Luau integration is early and only covers raw chunks identified by the profiler; Roblox-wrapped containers and fixture-backed fidelity validation remain future work. Android APK/DEX analysis also has an alternate Java reconstruction and bounded method-level evidence from the Apache-2.0 Androguard dex-decompiler, pinned at commit d458efd. It runs in a separate bounded container; source artifacts retain the engine commit and input hash. Structured Dalvik method observations retain instruction-mnemonic samples, bounded CFG summaries for the function visualizer, and linked per-method instruction artifacts that the AI can use as project evidence. This is an early comparison path, not a replacement for JADX; field reads/writes and direct string literal references are persisted as typed project evidence with capped previews. The visualizer also compares stored Dalvik instruction sequences across completed analyses and opens a matching method in its containing Java source class; similarity is a navigation lead, not proof of equivalent behavior. Fixture-backed accuracy comparisons remain open.

Current bootstrap

The REAmon workspace foundation is implemented and running:

• Create a reverse-engineering workspace without inventing a domain or network scope.
• Import a complete browser-selected folder in bounded batches, preserving its relative directory tree as workspace context. Single-file import remains available.
• Compare a selected folder with the latest completed snapshot before upload, then store an authoritative SHA-256 refresh delta after finalization.
• Cancel an in-flight import safely, keep its partial state visible, and resume the remaining paths or select a replacement snapshot later.
• Persist a directory root target, logical artifact paths, and candidate analysis targets in PostgreSQL.
• Compute SHA-256 identity and a basic magic/extension/header profile.
• Keep unknown inputs valid instead of rejecting them.
• Resolve compatible built-in capabilities from typed plugin manifests.
• Queue a reviewed capability proposal as an idempotent analysis task without executing providers in the request path.
• Show targets, artifacts, detected metadata, capabilities, progress, findings, hypotheses, evidence, and activity in a real data-backed dashboard.
• Run JADX 1.5.6 in an isolated backend service for APK decompilation; store bounded Java source outputs separately and publish class-sized code-unit observations.
• Detect managed PE assemblies from their CLR data directory and run pinned ILSpyCmd in an isolated backend service; store bounded C# type outputs and publish browsable code-unit observations without routing native PE files through the managed provider.
• Run Ghidra 12.1.4 headless in an isolated backend service for ELF, PE, and Mach-O decompilation; store bounded C-like function outputs separately and publish address-aware code-unit observations.
• Run pycdc for Python bytecode and webcrack for JavaScript bundles in isolated analyzers; store reconstructed source as derived artifacts and index module units.
• Draw a searchable size/coverage treemap from provider code-unit observations and open source only through an authenticated, active-workspace artifact route.
• Run bounded strings and readelf process providers against stored source and ELF artifacts, capture stable observations, and terminate the process on cancellation or timeout.
• Inspect generic file metadata and bounded JSON configuration documents through the same typed provider boundary, with stable observations and fail-closed size limits.
• Converge observations with explicit provider-independent identity hints before graph projection, including explicit relationship endpoint hints while retaining source-specific keys for provenance.
• Reconcile completed graph replays against the relational observation source, fencing overlapping project replays so stale nodes and relationships are removed without allowing concurrent workers to delete each other’s writes.
• Persist worker dispatch health, show stale-worker status, and surface an operator alert when a worker is stale or reports a failed dispatch.
• Preserve the PostgreSQL, Neo4j, agent, authentication, and event infrastructure needed by the REAmon workspace.

The current provider set covers profiling, source strings, ELF headers, generic file identification, bounded JSON inspection, APK-to-Java decompilation through JADX, managed .NET PE decompilation through ILSpy, and native ELF, PE, and Mach-O decompilation through Ghidra. Runtime instrumentation, additional executable formats, resource extraction, and broader language-specific workflows remain future work.

Long-term product progress

40% 40%

Weighted estimate: 39.7% (rounded for the bar). Refreshed from the workstream weights at pushed commit 568199b.

The weights describe REAmon’s full reverse-engineering goal, not the narrower bootstrap release. Each push to main regenerates this block from the progress ledger. Update a workstream estimate only when committed implementation or fixture evidence changes its basis; the score is a roadmap estimate, not a line-count or test-count metric.

Bootstrap release readiness

100% 100%

This is a release-gate snapshot, reviewed 2026-10-03 against repository, hosted workflow, production-image, and staging evidence. The score measures readiness for a dependable self-hosted production release, not the number of UI screens or lines of code.

This rating covers the bootstrap release scope only. It does not measure readiness for REAmon’s broader product goal of reverse-engineering arbitrary programs from import through decompilation, navigation, AI-assisted analysis, and runtime work. That broader goal remains in progress. The WIP support matrix above describes capability additions that are outside this historical bootstrap release score.

The 100% score is justified for the current production release scope. The product boundary is release-gated independently: no native workspace depends on a retired scanner, pentest, or upstream-update surface.

Weighted result: 100%.

The production release gate is complete. The remaining roadmap items are capability expansion and migration cleanup, not unverified deployment prerequisites. String extraction is now available through the shared provider for every imported file format. ELF artifacts also expose dynamic dependencies and imported/exported symbols as graph observations.

Evidence recorded for this review:

• .github/workflows/reamon-quality.yml runs the full web suite, type-check, lint, npm production-dependency audit, Python unit gate, Trivy image scan, and a live Compose release gate against the production image.
• The live gate runs authenticated acceptance, browser import/approval/analysis/ recovery controls, PostgreSQL restore, artifact extraction, and Neo4j dump/load/query recovery. It also scales the worker service to two replicas, kills one container, crosses the configured stale threshold, and requires one recovered completion.
• .github/workflows/reamon-release.yml validates VERSION against semver tags, requires a green quality workflow for the exact tagged commit, and publishes a checksum-backed source archive as a GitHub release. The reviewed release is v6.23.0.
• tooling/scripts/reamon-release-preflight.sh --live --acceptance --backup reproduces the same operational checks for self-hosted release operators.
• The authenticated acceptance flow imports representative JSON and C artifacts, exercises approvals and both built-in providers, proves distinct concurrent task claims, projects and reconciles the graph, and verifies the workspace snapshot.
• Two Compose worker replicas recover a controlled stale lease and complete the task exactly once; the isolated backup drill restores PostgreSQL into a disposable database and extracts the artifact archive successfully. A bounded four-task, two-replica load/soak run then verifies stable containers without restart churn.

For production alerting, set REAMON_WORKER_ALERT_WEBHOOK_URL and optionally REAMON_WORKER_ALERT_WEBHOOK_TOKEN. Failed provider dispatches send a bounded worker.degraded JSON event with a five-second timeout; missing or failing alert delivery never fails the dispatch request. The dashboard remains the source of truth for stale workers, including workers that stop reporting entirely.

Architecture

The target-to-workflow boundary is:

Target import
    ↓
Target Profiler → TargetProfile / ArtifactProfile
    ↓
Capability Resolver
    ↓
Native analysis providers · generic process adapters
    ↓
Tasks and analysis plans
    ↓
Evidence, findings, hypotheses, activity, and knowledge graph

The initial typed contracts live in webapp/src/lib/reamon:

• TargetProfile describes observable target facts.
• ToolPluginManifest describes accepted inputs, capabilities, requirements, and produced entities.
• ToolPlugin provides the execution boundary without naming a specific platform.
• resolveCapabilities() chooses compatible providers from installed manifests.
• buildProgressModel() derives progress from persisted lifecycle state.

Read the full design in docs/REAMON_ARCHITECTURE.md and the migration inventory in docs/REAMON_MIGRATION.md.

Quick start

Prerequisites

• Docker Engine or Docker Desktop
• Docker Compose v2
• At least 4 GB RAM for the REAmon stack
• A local checkout of this repository

Node.js, Python, and reverse-engineering tools run inside containers for the normal workflow. Do not commit .env or real target data.

Local install

git clone https://github.com/xdCloudy/REAmon.git
cd REAmon

./reamon.sh install

The installer creates the local .env, generates deployment secrets, builds the configured services, starts PostgreSQL/Neo4j/the webapp and supporting workers, and offers to create the first administrator. Open after the webapp is healthy.

For an existing installation:

./reamon.sh up
./reamon.sh status
./reamon.sh logs webapp
./reamon.sh down

Existing PostgreSQL/Neo4j data and stable Compose volume identifiers can be retained when upgrading an installation; retired scanner services are not started.

First REAmon workflow

1. Sign in and choose New Project.
2. Enter a workspace name or choose a project folder; the folder name is used as the default workspace name.
3. Review the preflight inventory, then choose Create and import workspace.
4. REAmon creates one DIRECTORY root target, uploads files through bounded requests, hashes and profiles each artifact, and retains paths such as bin/x64/app.dll.
5. Review the workspace inventory, file tree, detected logical targets, capabilities, deterministic progress, and activity timeline.

Browser folder selection is a snapshot: the server never receives the absolute local filesystem path and cannot watch the directory after the browser selection ends. The import includes everything selected by default; refresh comparisons use manifest facts before upload and authoritative hashes after upload.

Artifacts are stored in the named reamon_artifacts volume. The default per-file limit is 512 MiB and the default import limit is 50,000 files / 8 GiB. Process providers are bounded to a 60-second execution window and 2 MiB of captured output by default. Set REAMON_MAX_ARTIFACT_BYTES, REAMON_MAX_IMPORT_FILES, or REAMON_MAX_IMPORT_BYTES in .env before starting the webapp to change import limits; use REAMON_PROCESS_TIMEOUT_MS and REAMON_MAX_PROCESS_OUTPUT_BYTES to tune provider limits. Keep the artifact volume backed up with the PostgreSQL and Neo4j data volumes.

Production deployment

The default Compose file is suitable for a trusted local network and development environments. For an internet-facing deployment, use the hardened single-host deployment under tooling/deploy/single-host, which adds TLS termination, firewall/SSH hardening, and keeps internal services private.

Before exposing a deployment:

• Set unique, high-entropy values for POSTGRES_PASSWORD, NEO4J_PASSWORD, AUTH_SECRET, and INTERNAL_API_KEY.
• Set TRUST_PROXY=true only when every request reaches the app through a trusted proxy that overwrites forwarding headers.
• Set AGENT_WS_PUBLIC_URL to the deployment origin when using a reverse proxy.
• Back up postgres_data, neo4j_data, and reamon_artifacts before upgrades.
• Review THIRD-PARTY-LICENSES.md before redistribution.
• Do not upload real target data to a development or shared environment.

The webapp entrypoint synchronises the Prisma schema on startup. Take a database backup and inspect schema changes before upgrading a production instance. Startup refuses destructive Prisma schema drift by default; set REAMON_DB_PUSH_ACCEPT_DATA_LOSS=true only for a planned, backed-up upgrade after reviewing the schema change. /api/health is a lightweight liveness check; /api/health/ready verifies both the PostgreSQL connection and writable REAmon artifact storage, and is the endpoint used by the Compose healthcheck. Follow docs/REAMON_RELEASE_RUNBOOK.md for backup, upgrade, smoke-test, rollback, and restore procedures.

Development

The repository is a Docker-orchestrated monorepo. The webapp is Next.js 16, React 19, TypeScript, Prisma, and Vitest; the analysis agent, worker, and supporting services are containerized.

# Validate the Compose model without starting services.
docker compose config --quiet

# Build the webapp image.
docker compose build webapp

# Start the lightweight development stack.
docker compose up -d postgres neo4j webapp

# Validate the REAmon foundation inside the webapp environment.
docker compose exec webapp npm run test -- src/lib/reamon
docker compose exec webapp npm run type-check

The repository test policy is documented in docs/readmes/README.TESTING.md and skills/redamon-testing/SKILL.md. The normal gate is containerized; do not run host Python tests against the service code.

Useful top-level commands:

./reamon.sh install       Build and start the stack
./reamon.sh update        Disabled; install reviewed REAmon releases explicitly
./reamon.sh up            Start already-built services
./reamon.sh status        Show service status
./reamon.sh test unit     Run the unit gate
./reamon.sh create-admin  Create or reset an administrator
./reamon.sh down          Stop services without deleting data

Repository map

webapp/src/lib/reamon/     REAmon domain, profiler, capabilities, and progress
webapp/src/app/projects/   Workspace dashboard, import, and project flows
webapp/prisma/             PostgreSQL schema and REAmon foundation migration
agentic/                   Analysis agent and bounded provider runtime
graph_db/                  Neo4j access and knowledge graph infrastructure
services/reamon_worker/    Durable queued-task worker
docs/REAMON_*.md           Current architecture and product-boundary decisions

Roadmap

1. Expand specialist binary/process providers beyond shared string extraction and run the staging multi-worker drill around the existing ownership, retry, and process-cancellation path. The generic provider and contention scripts are already available for extension and validation.
2. Ingest universal code/data/runtime entities and relationships into Neo4j.
3. Extend approval policy reporting and richer recovery UX for target-agnostic analysis workflows.
4. Add specialist binary, runtime, and data providers behind the capability boundary.
5. Add capability-specific dashboards and reports while retaining one workspace framework for every target type.

Provenance and licence

REAmon was derived from an MIT-licensed upstream codebase. Required attribution, copyright notices, and third-party licences are retained. The maintained product is the REAmon workspace at ; retired upstream features are not part of its runtime contract. The bundled component inventory is documented in THIRD-PARTY-LICENSES.md.