Quickstart

Install WARDEN and run the full reverse-engineering pipeline: first on generated samples, then on your own Emscripten module.

WARDEN’s core path is pure Python and the standard library, so a fresh clone runs with no native toolchain (no Ghidra, no Emscripten, no WABT).

Install

1. Clone and create a virtual environment

   git clone https://github.com/purpshell/warden.git
   cd warden
   python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
   
2. Install the package

   The base install is dependency-light (just a CLI shell).

   pip install -e .
   

   Verify it worked: warden version prints the installed version.

Run the whole pipeline (offline)

warden demo

This generates sample modules and walks every stage end-to-end, with no network and no toolchain. You’ll see the Oracle identify runtime functions at score 1.00 and infer the Emscripten version, the agent crew recover a name from a string cross-reference to reach 100% coverage, and a v1 → v2 diff carry annotations forward and print a semantic changelog.

warden demo is the fastest way to understand WARDEN. Run it once, then point the real commands below at your own module.

Reverse-engineer your own module

1. Create a project and ingest the target

   Ingestion parses the .wasm (and optional Emscripten JS glue), fingerprints every function, and seeds names for free from exports, imports, and the name section.

   warden init                                              # creates ./warden.db
   warden ingest app_v1.wasm --glue app_v1.js --label v1
   warden coverage v1                                       # how much is named already?
   warden funcs v1 --unnamed                                # what still needs a name?
   
2. Identify runtime code with the Oracle

   Build a signature corpus from any module that still carries a name section (a debug or --profiling-funcs build), then identify the stripped target against it. This typically collapses a large fraction of a module to known musl/runtime code instantly.

   warden oracle build runtime_debug.wasm --out oracle.json --emver 3.1.55 --opt -O2
   warden oracle identify v1 --store oracle.json
   

   To build a full corpus from the Emscripten toolchain across a version × flag matrix, use the containerized farm in scripts/corpus/. See the Oracle guide.

3. Name the rest with the agent crew

   The crew proposes names for the application-specific remainder, gated by a verifier and the provenance/confidence economy. Runs with an offline heuristic by default; set OPENAI_API_KEY or ANTHROPIC_API_KEY (and pip install -e '.[agents]') for the LLM crew.

   warden agent v1
   
4. Review, lock, and export

   Record verified names (sovereign over agents), then emit a deliverable.

   warden show v1 7
   warden set-name v1 7 verify_license     # provenance=human, locked
   warden export v1 --format pseudo        # or: headers | kb-text | ghidra
   
5. When a new version ships, diff it

   Carry annotations forward automatically and review only the genuine deltas.

   warden ingest app_v2.wasm --label v2
   warden diff v1 v2
   

   The changelog separates real app changes (review these) from runtime/toolchain churn (an Emscripten bump, safely ignored). Read about diffing →

Optional power-ups

The base install is intentionally minimal. Opt into extras as you need them.

LLM agent crew

pip install -e '.[agents]'   # real model-driven naming; set OPENAI_API_KEY or ANTHROPIC_API_KEY

Next: the mental model

Three ideas make every WARDEN command click. Read them before going deeper.