Quickstart

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

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

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

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?

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.

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

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

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.

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

pip install -e '.[mcp]'      # drive the KB from any MCP-capable agent
warden mcp

pip install -e '.[dev]'      # pytest, ruff, mypy, pre-commit

pip install -e '.[all]'

Next: the mental model

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

The reverse-engineering loop

The practical, command-by-command guide to reverse-engineering a real module as a loop.

Getting started

The pipeline

Reference

Project

Install

Run the whole pipeline (offline)

Reverse-engineer your own module

Optional power-ups

Next: the mental model

The reverse-engineering loop

​Install

​Run the whole pipeline (offline)

​Reverse-engineer your own module

​Optional power-ups

Next: the mental model

The reverse-engineering loop

Install

Run the whole pipeline (offline)

Reverse-engineer your own module

Optional power-ups