Skip to main content
The warden command is a thin shell over the library. Every command takes --db <path> to select the project database (default warden.db, or the WARDEN_DB environment variable).
Run warden --help, or warden <command> --help, for the authoritative, version-specific flag list. This page documents the commands as of the current release.

​
Project lifecycle

Print the installed WARDEN version.
warden version
Create an empty project knowledge base.
warden init [--db warden.db]
Run the entire pipeline end-to-end on generated sample modules. No network or toolchain needed. The fastest way to see what WARDEN does.
warden demo [--dir warden-demo]

​
Ingest and inspect

Parse, fingerprint, and load a module version into the KB. Seeds names from the name section, exports, and imports.
warden ingest <wasm> [--glue <js>] [--label <name>] [--notes <text>] [--db <path>]
  • <wasm>: path to the .wasm file (required).
  • --glue, -g: optional Emscripten .js glue (recovers version, dynCall sigs, pthread shape).
  • --label, -l: version label (defaults to the filename stem).
List all ingested module versions.
warden versions [--db <path>]
Show symbol-coverage statistics for a version (named / by oracle / by human / by agent).
warden coverage <label> [--db <path>]
List functions for a version with their current names and provenance.
warden funcs <label> [--unnamed] [--limit 50] [--db <path>]
  • --unnamed: show only functions that still have no name.
Show everything known about a single function: type, stable id, calls, provenance, and evidence.
warden show <label> <index> [--db <path>]
Set a human-verified name for a function. Human names are sovereign and locked against agent overwrite by default.
warden set-name <label> <index> <name> [--summary <text>] [--lock/--no-lock] [--db <path>]

​
The Oracle

Build (or extend) an Oracle signature store from labeled modules (modules that still carry a name section).
warden oracle build <wasm...> --out <store.json> [--library musl] [--emver <ver>] [--opt <flag>]
  • <wasm...>: one or more labeled .wasm files.
  • --out, -o: signature store path (default oracle.json).
  • --emver: the Emscripten version these were built with (recorded on each signature).
  • --opt: the opt level, e.g. -O2.
Identify runtime/libc functions in a version against a signature store, and infer the Emscripten version from the distribution of matches.
warden oracle identify <label> --store <store.json> [--threshold 0.82] [--indexed] [--db <path>]
  • --indexed: build a MinHash-LSH index over the store before matching, giving sublinear candidate lookup for large signature stores. Produces the same results as the default linear scan at any threshold above 0.82, but is significantly faster when the store exceeds a few thousand signatures.

​
Decompile and execute

Decompile a single function (or every function in a module) to readable pseudo-C using the built-in pure-Python stack-machine lifter.
warden lift <label> [--index N] [--out <file>] [--db <path>]
  • <label>: the version to lift (required).
  • --index, -i: lift only function at index N. Omit to lift the entire module.
  • --out, -o: write output to a file instead of stdout.
The same lifter backs warden export --format pseudo; that command now emits real pseudo-C rather than a mnemonic dump.Example output for parse_token:
i32 parse_token(i32 p0, i32 p1) {
    return ((p0 + p1) * 7);
}
Execute a single function in the built-in mini interpreter and print the return values. Covers the integer instruction subset; no external toolchain is required.
warden exec <label> <index> [args...] [--db <path>]
  • <label>: the version containing the function (required).
  • <index>: function index (required).
  • [args...]: zero or more integer arguments passed to the function.
Raises UnsupportedExecution when an instruction outside the supported subset is encountered. For behavioral comparison across versions use warden diff or call warden.interp.differential_execute from the Python API directly.
Run the concurrency and struct-layout analyzers over a version and persist their findings as KB facts. This populates the thread_model and structs tables that were previously empty.
warden analyze <label> [--db <path>]
The command runs both analyzers in sequence:
  • Concurrency analyzer: detects shared-memory access patterns, atomic sites, and pthread markers; writes facts via kb.add_thread_fact.
  • Struct analyzer: recovers struct layouts (name, field offsets, sizes, and inferred types) from access patterns; writes records via kb.upsert_struct.
Results are visible in warden show and in the HTML report produced by warden report.
Generate a self-contained HTML reverse-engineering report for a version. The file has inline CSS and requires no server to view.
warden report <label> [--out <file>] [--db <path>]
  • --out, -o: output path (default <label>-report.html).
The report includes:
  • A coverage summary (named / oracle / human / agent / unnamed).
  • A confidence heatmap: every function colored by provenance and confidence score.
  • A thread and memory model section (populated after warden analyze).
  • The diff changelog from all prior warden diff runs against this version.

​
Agents, diff, verify, export

Run one propose → verify → write-back sweep over unnamed functions. Auto-selects the OpenAI backend when OPENAI_API_KEY is set and the SDK is installed, then Anthropic when ANTHROPIC_API_KEY is set, otherwise the deterministic offline backend.
warden agent <label> [--strategy call-graph|flat] [--backend offline|openai|codex|oai|anthropic] [--db <path>]
--strategy controls how functions are ordered and processed (default: call-graph).call-graph (default): walks the call graph bottom-up.
  1. Builds the intra-module call graph. Direct calls are exact. Indirect calls (call_indirect / dynCall) are over-approximated to table targets of the matching type, so the graph is a static skeleton.
  2. Condenses strongly-connected components (mutual recursion) and sorts them into bottom-up layers. Every function in a layer has all of its defined callees in earlier layers.
  3. Runs the concurrency and struct analyzers first and routes their findings into per-function notes (atomic sites, struct layouts).
  4. Processes layers bottom-up. Each function is named with its callees’ recovered names already in view, carried in FunctionFacts.callee_names and FunctionFacts.notes. This is the main quality win over a flat pass.
  5. Functions in the same layer are independent and are proposed concurrently via asyncio (blocking LLM backends run in worker threads, capped by --concurrency, default 8). Writes still go through the provenance and confidence economy, so concurrent branches that share a callee cannot clobber each other.
flat: the original single-pass, leaves-first ordering. Available for comparison or when call-graph analysis is not needed.
List agent backends, availability, required credentials, and default models. Use this before a provider-backed run to confirm what auto-selection will see.
warden agent-backends
Diff two versions, carry annotations forward, and print the semantic changelog.
warden diff <from_label> <to_label> [--no-carry] [--db <path>]
  • --no-carry: classify only; do not port annotations forward.
Export a deliverable. All formats are deterministic so they diff cleanly in git.
warden export <label> --format headers|pseudo|kb-text|ghidra [--out <file>] [--db <path>]
FormatOutput
headersA C header of recovered function prototypes.
pseudoReadable per-function listings with names and summaries.
kb-textA stable, git-diffable dump of every symbol.
ghidraA Python script that renames functions in the Ghidra WASM plugin.
Verify ingestion determinism and report differential-equivalence readiness (whether a wasm2c/w2c2 + C toolchain is present).
warden verify <wasm>
Serve the knowledge base over the Model Context Protocol (stdio). Requires pip install -e '.[mcp]'. See the MCP reference.
warden mcp [--db <path>]

​
A full session

warden init
warden ingest app_v1.wasm --glue app_v1.js -l v1
warden oracle build runtime_debug.wasm -o oracle.json --emver 3.1.55 --opt -O2
warden oracle identify v1 --store oracle.json --indexed
warden agent v1
warden set-name v1 7 verify_license
warden analyze v1
warden lift v1 --index 7          # inspect the decompiled pseudo-C for a single function
warden export v1 --format pseudo --out v1.pseudo.txt
warden report v1 --out v1_report.html

# next release:
warden ingest app_v2.wasm -l v2
warden diff v1 v2
warden report v2 --out v2_report.html
Last modified on June 7, 2026