xiaoyeuzixi/revlab

What it claims

REVLab is an MIT-licensed reverse-engineering workbench that runs locally on Windows 10/11 x64 with Python 3.10 or later. It splits analysis of a sample into stages: identify, unpack, disassemble, decompile and dynamic. Each stage's result is stored in a SQLite sample record, so a file can be re-run, compared across workflows, and traced back to raw evidence. The README positions it for reverse-engineering study, internal software investigation and lab sample triage. It says the tool is not an antivirus service and does not judge whether a file is safe.

How it works

The quickest path is sample, then PE static analysis, then report. That path does not run the sample and needs neither Ghidra nor dynamic components.

• identify uses pefile. It computes MD5, SHA1, SHA256, imphash and ssdeep, and reads headers, ASLR/DEP/CFG/SEH flags, section entropy, imports, exports, TLS callbacks, Rich Header, PDB paths, Authenticode status and filtered strings.
• unpack detects common packers. UPX unpacking is optional. Other protectors are never assumed unpacked. PE-sieve handles memory dumps.
• disassemble runs Capstone from the entry point and collects basic call and jump targets. It does not recover full function boundaries.
• decompile calls Ghidra Headless and exports pseudocode for a limited number of functions. It needs Java 21 and is marked skipped if Ghidra or Java is missing.
• dynamic runs the sample on the local host only. Sandboxie, Windows Sandbox and VMware backends are no longer supported. The sample starts only after the user ticks a per-run local-execution confirmation. Without it the stage returns blocked_by_policy and creates no process. It collects the process tree, file, registry and DNS changes. Network capture uses Windows pktmon converted to pcap.

The UE module reports GNames, GObjects, GWorld and GEngine as candidate RVAs. Treat them as runtime addresses only after loading a same-build process, checking pointer ranges and decoding FName. The Unity module separates Mono from IL2CPP and validates global-metadata.dat. If validation fails it stops the SDK stage rather than emit an unusable Dump.cs.

Stage states are pending, running, done, error and skipped. A failed task can resume with completed stages reused. Graph tasks support conditional branches, approval nodes, {{variable}} references, and per-node fail policies (terminate, skip, retry).

AI nodes use an OpenAI-compatible endpoint (base_url, api_key, model). They receive a per-sample revlab.ai-evidence/v1 package. An AI-requested dynamic_run always returns blocked_by_policy. If a model returns "confirmed" for a UE address, normalisation downgrades it to AI inferred. Only a separate runtime verification node can promote a candidate.

flowchart TD
  A[AI node starts] --> B{Model configured?}
  B -- yes --> C{Gateway supports tools?}
  C -- yes --> D[Tool loop, max_tool_rounds]
  C -- no --> E[Read-only fallback, warning]
  B -- no --> F{on_fail}
  F -- skip --> G[Continue workflow]
  F -- abort --> H[Task error]
  F -- external_wait --> I[AI_WAITING]
  I --> J[MCP agent: wf_resolve_ai]
  J --> K[wf_retry_node]

The MCP sequence is: wf_task_outputs reads evidence and tool_trace, the agent runs PE/UE/Unity tools, wf_resolve_ai submits a JSON conclusion, and wf_retry_node reruns the node. Submitted results stay labelled ai_inferred.

How to use it

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1
scripts\start.bat

The UI runs at http://127.0.0.1:8000 and the OpenAPI docs at /docs. External tools are not downloaded automatically. Automatic dependency setup needs REVLAB_AUTO_SETUP=1. Configuration starts from Copy-Item .env.example .env. The keys are REVLAB_OUTPUT_DIR, REVLAB_DYNAMIC_BACKEND=local, REVLAB_API_TOKEN (needed only for remote access) and REVLAB_CORS_ORIGINS. Script and command nodes are gated by REVLAB_ENABLE_UNSAFE_NODES.

MCP server, for Codex, Claude Code, Cursor and similar agents:

python -m mcp_server.server --port 8765
python -m mcp_server.server --stdio

Tests and build:

python -m unittest discover -s backend/tests -p "test*.py"
python -m compileall -q backend mcp_server
cd frontend\workflow
npm run build

Limits

Dynamic analysis runs with the current host's privileges, file system and live network, with no sandbox or VM. The risk is the user's. blocked_by_policy means no runtime evidence was collected, not that the sample showed no behaviour. Ghidra and pktmon availability depends on local setup and permissions. Input and output paths outside the allowed directories are rejected. The README restricts use to owned or explicitly authorised samples. It states the project does not bypass licensing, anti-cheat or access controls and does not guarantee results across all builds. Static and AI results need manual review before any production or forensic conclusion.