xiaoyeuzixi/revlab

What it is

REVLab is a Windows-only (10/11 x64, Python 3.10+) binary analysis workbench with a FastAPI backend, a SQLite store and an MIT licence. It targets generic PE files, Unreal Engine dumps and Unity game directories. The page says it is for self-owned or explicitly authorised samples, and that it is not an antivirus service and will not judge whether a file is safe.

How it works

Each sample moves through stages: identify, unpack, disassemble, decompile and dynamic. Each stage records pending, running, done, error or skipped, with timings and error text. A failed task can resume, and finished stages are reused.

• Identify: pefile parsing plus MD5, SHA1, SHA256, imphash, ssdeep, section entropy, imports, TLS, resources, Rich Header and Authenticode status.
• Unpack: packer detection. UPX unpacking is optional, and PE-sieve is used for memory dumps. Other packers are not assumed unpacked.
• Disassemble: Capstone from the entry point only. The page says it does not recover all function boundaries.
• Decompile: Ghidra Headless exports a limited number of functions. It needs Ghidra and Java 21, otherwise the stage is skipped.
• Dynamic: a local run with process tree, file, registry and DNS observation. Network capture uses Windows pktmon converted to pcap.
• UE: GNames, GObjects, GWorld and GEngine results are candidate RVAs. They count as runtime addresses only after loading a same-build process, checking pointer ranges and decoding FName.
• Unity: it separates Mono from IL2CPP and validates global-metadata.dat. If validation fails, the SDK stage stops and does not produce a Dump.cs.

Workflows are graphs edited in a Vue Flow UI and executed by the backend. They support conditions, failure policies (abort, skip, retry), approval nodes, {{variable}} references and saved workflow snapshots.

The AI and MCP layer

The ai_analyze, pe_ai_assist, ue_ai_assist and unity_ai_assist nodes run a tool loop of up to 6 rounds (max_tool_rounds). The target path is locked by the workflow. A fresh revlab.ai-evidence/v1 bundle is built per sample. If the gateway lacks tools support, the node falls back to reading existing evidence and sets tool_mode=unsupported_fallback.

Evidence carries one of four labels: static, runtime, inferred or blocked. AI output is always ai_inferred, even if the model says confirmed. Only a separate runtime verification node can promote a UE candidate.

Without a configured model, on_fail chooses between external_wait (stop at AI_WAITING), skip and abort. An external agent such as Codex, Claude Code or Cursor then takes over through MCP:

wf_task_outputs(task_id)
get_pe_info / ue_analyze / unity_analyze
wf_resolve_ai(task_id, node_id, ai_result)
wf_retry_node(task_id, node_id)

flowchart TD
    A[AI requests dynamic_run] --> B[blocked_by_policy]
    B --> C[Listed as unverified hypothesis]
    D[User ticks local-execution confirm on a normal dynamic node] --> E[Sample runs on host]

Preconditions

Core static analysis needs only Python. Ghidra with Java 21, pktmon and PE-sieve are optional, and setup does not download them unless REVLAB_AUTO_SETUP=1 is set.

What to do

Quick triage of one exe uses the path sample, PE static analysis, report. It does not run the sample.

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

The UI is at http://127.0.0.1:8000 and OpenAPI at /docs. The MCP server starts with python -m mcp_server.server --port 8765, or --stdio for stdio mode. Tests run with python -m unittest discover -s backend/tests -p "test*.py".

Relevant settings: REVLAB_OUTPUT_DIR, REVLAB_DYNAMIC_BACKEND=local, REVLAB_API_TOKEN and REVLAB_CORS_ORIGINS. Script and command nodes are controlled by REVLAB_ENABLE_UNSAFE_NODES.

Caveats

• Dynamic runs execute on the host with the current user's privileges and network. Only local mode exists, and Sandboxie, Windows Sandbox and VMware backends were removed. Use a dedicated lab machine.
• blocked_by_policy does not mean the sample has no behaviour.
• Entropy, imports and strings are only clues. A well-formed PE can still be malicious.
• The page gives no accuracy figures or version numbers for the project.