> ## Documentation Index
> Fetch the complete documentation index at: https://warden-re.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WARDEN

> Living reverse-engineering for Emscripten WebAssembly: a versioned, agent-populated symbol knowledge base that survives binary updates.

Today's WebAssembly reverse engineering is a pile of disconnected tools, and every annotation
you make **dies when the vendor ships a new `.wasm`**. You re-do the work. That's the real
pain. Not the first decompile, but the *second through hundredth*.

WARDEN treats RE as a **living, versioned knowledge base** keyed to *stable function
identities* rather than file offsets, so your names, types, and notes **carry across binary
updates automatically**.

<CardGroup cols={3}>
  <Card title="The Emscripten Oracle" icon="telescope">
    Emscripten, musl, dlmalloc, and libc++ are open source, so WARDEN compiles its *own*
    ground truth and auto-identifies runtime functions in a target, attaching the real upstream
    name. You stop reversing code that already has public source.
  </Card>

  <Card title="A persistent symbol KB" icon="database">
    Every name, type, struct, and comment lives in a database keyed to a content identity, with
    provenance and a confidence score. It survives rebuilds instead of dying with the file.
  </Card>

  <Card title="Cross-version carry-over" icon="git-compare-arrows">
    When a new `.wasm` drops, WARDEN diffs it, ports annotations to unchanged and moved
    functions, and surfaces *only the genuine deltas*. Reversing becomes incremental.
  </Card>
</CardGroup>

## See the whole thing in one command

The core path is **pure Python + standard library**. No Ghidra, no Emscripten, no native
toolchain required to fork and run.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/purpshell/warden.git
cd warden
python -m venv .venv && source .venv/bin/activate
pip install -e .

warden demo            # runs the entire pipeline, offline
```

`warden demo` generates sample modules and walks the system end-to-end: ingest, Oracle
identification, agent crew, ship a new version, diff and carry-over. You watch coverage climb
to 100% and a `v1 → v2` semantic changelog get produced with zero manual work.

<CardGroup cols={2}>
  <Card title="Start here: the 60-second quickstart" icon="rocket" href="/quickstart">
    Install WARDEN and run the full loop on your own module.
  </Card>

  <Card title="The reverse-engineering loop" icon="repeat" href="/workflow">
    The practical guide: ingest, identify, decompile, understand, review, and iterate together.
  </Card>
</CardGroup>

## How it works

<CardGroup cols={2}>
  <Card title="Stable identity" icon="fingerprint">
    Each function gets a content identity (structural skeleton + call-neighborhood + type
    signature) that stays constant across rebuilds even when its table index shifts. Annotations
    attach to *that*, not to an offset. [Read the concepts →](/concepts)
  </Card>

  <Card title="One engine, two jobs" icon="recycle">
    The same fingerprint/similarity engine powers both the Oracle (match against compiled ground
    truth) and the diff carry-over (match against the previous version).
  </Card>

  <Card title="A provenance economy" icon="scale">
    Every write records who made it: `human`, `oracle`, `export`, `agent`, or `diff-carry`,
    along with a confidence score. Human edits are sovereign; agents only overwrite lower-confidence agent
    output. That's what makes it safe to re-run the whole crew on every update.
  </Card>

  <Card title="Agents do the labor" icon="bot">
    A propose, verify, write-back crew fills the KB without proportional human time. Runs with
    zero dependencies via an offline heuristic, or upgrades to a real LLM crew.
    [Read about agents →](/pipeline/agents)
  </Card>
</CardGroup>

## What "100% reverse engineered" means here

Perfect source recovery is impossible. The compiler destroyed that information. WARDEN targets
a rigorous, *achievable* 100% along three axes.

<AccordionGroup>
  <Accordion title="100% symbol coverage" icon="tags">
    Every function has *some* binding: an Oracle-confirmed real name, a recovered name, or an
    agent proposal with a confidence score. No anonymous `func_412` ever remains.
  </Accordion>

  <Accordion title="100% behavioral equivalence (verifiable)" icon="circle-check">
    Reconstructions are differentially executed against the original until outputs match.
    Determinism verification runs today; the wasm2c differential harness activates when a C
    toolchain is present. [Read about verification →](/pipeline/verify)
  </Accordion>

  <Accordion title="100% change accountability" icon="list-checks">
    Across versions, every byte-level delta is mapped to a function and a semantic explanation.
    Nothing changes silently. [Read about diffing →](/pipeline/diff)
  </Accordion>
</AccordionGroup>

<Note>
  WARDEN is **alpha**. The core loop runs today: ingestion, the knowledge base, stable identity,
  diff and carry-over, Oracle matching, the decompiler, the agent crew and the per-function deep
  engine, exporters, determinism verification, the read-only UI, and the MCP surface. The deeper
  integrations (the Ghidra round-trip, the full emsdk corpus farm, and the wasm2c verifier) are
  scaffolded with clear interfaces. See [the reverse-engineering loop](/workflow) for how it all
  fits together, the [roadmap](/project/roadmap) for status, and [honest limits](/project/limitations).
</Note>