dappwalker

DAPPWALKER - AI Offchain/dApp auditor

by @0xluk3

A Claude Code skill for multi-pass dApp security audits. Runs a pure-AI instant mode (recon, generalist sweep, and detector match) and an extended mode that additionally orchestrates semgrep (static analysis) and npm audit. Outputs a single deduplicated report in two formats: Markdown and HTML.

---

Install

git clone git@github.com:0xluk3/dappwalker.git ~/.claude/skills/dappwalker

Skills in ~/.claude/skills/<name>/SKILL.md are auto-discovered by Claude Code.

Use

In any Claude Code session at the root of a dApp repo:

run dappwalker

Or:

audit this dapp

Claude will ask:

1. Mode - instant (no downloads) or extended (installs + runs semgrep, npm audit).
2. Target path - defaults to CWD.

It runs the passes, writes intermediate outputs to .dappwalker/<timestamp>/, and emits the audit report in both Markdown and styled HTML at the target root (filenames described under Output).

Modes

Mode	Passes	External tools
instant	0, 1, 2, 3, 5, 6	none
extended	0-6	semgrep (auto-installed via pipx), npm audit

Extended mode confirms installs with you before running.

Scope

Right after you pick the mode, dappwalker runs a Scope Scout that classifies every file in the target and proposes an audit scope. You see a proposal summary, then a three-option picker:

Scope ready: 63 files included, 102 excluded. How do you want to proceed?

  ❯ Proposed scope       — Use the scout's recommendation (recommended)
    All files (override) — Include every file except vendor/generated/binary.
                           Scans docs, whitepapers, PDFs.
    Edit scope           — Customize include/exclude paths via a quick
                           back-and-forth.

• Proposed scope - use the scout's recommendation. Covers the 90% case.
• All files (override) - audit every file except vendor dirs (node_modules/, dist/, etc.), lockfiles, and binaries. Use this when you specifically want whitepapers, docs, or marketing copy audited too (e.g. looking for leaked endpoints in a README). Warning: PDFs, whitepapers, and markdown content will be audited.
• Edit scope - small REPL: reply with +<path> to include a path or -<path> to exclude a path, one per token, then done. Good for custom include/exclude beyond what the heuristics caught.

The scout always excludes vendor/generated/binary paths (node_modules, dist, lockfiles, images, fonts, etc.) and prior dappwalker audit artifacts (AUDIT_REPORT.*, *-0xluk3_dappwalker*.{md,html}) regardless of mode - auditing its own output is a footgun we guard against.

The resulting scope.md is authoritative for every downstream pass: recon, generalist, detectors, verifier, and merger all restrict Grep/Glob/Read to the included globs. The verifier (Pass 5) is allowed one level of out-of-scope imports to complete a taint trace, and must note doing so.

Passes

0. passes/0_scout.md - scope scout. Classifies files (code / config / markup / docs / whitepaper / vendor / binary), proposes scope, writes scope.md. Runs in main context.
1. passes/1_recon.md - architecture & auth matrix (pasted verbatim into final report). Runs in the main context.
2. passes/2_generalist.md - bias-resistant generalist audit using recon as the Context Report. Dispatched as a parallel subagent.
3. passes/3_detectors.md - per-category shard. One subagent per detectors/<cat>.md file dispatched in parallel with Pass 2; each shard sweeps the target for its own detectors and writes 03_detectors_<cat>.md.
4. passes/4_external.md - extended only. The underlying script scripts/run_external_tools.sh runs as a background process concurrently with the Pass 2/3 subagents; a follow-up agent then normalizes the raw output.
5. passes/5_verifier.md - adversarial verifier. Always on. Takes every raw candidate from Passes 2/3/4, splits them into batches of up to 3, and dispatches one parallel subagent per batch. Each batch gets: the 3 candidates + the Pass 1 recon output + read access to the target code. Each subagent judges valid / valid_downgraded / false_positive per finding with a cited reason. This is the quality gate.
6. passes/6_merger.md - consumes verifier output plus raw pass outputs, dedupes the surviving findings, normalizes severity, and renders the final reports.

Execution order:

Pass 1 (main)
  ↓
Parallel: Pass 2 || Pass 3 shards (|| Pass 4 background, extended)
  ↓
Pass 5 verifier batches (parallel, up to 3 candidates each)
  ↓
Pass 6 merger (main)

The fan-out at Pass 2/3 shards and again at Pass 5 is what keeps wall-clock manageable. Adding Pass 5 trades ~2-4 min of verifier wall-clock for a noticeably cleaner main report - false positives, overstated findings, and name-matched-without-logic claims get filtered out before dedup.

Detectors

detectors/ holds detector specs organized by category: frontend/, web/, blockchain/, auth/ (incl. auth/jwt/), logic/, deps/. Add your own following detectors/README.md.

Layout

dappwalker/
├── SKILL.md                      # orchestrator
├── README.md
├── passes/                       # the 5 prompt passes
├── detectors/                    # one .md per detector
├── scripts/run_external_tools.sh # extended-mode runner
└── templates/
    ├── final_report.md           # markdown output skeleton
    └── final_report.html         # dark-navy HTML output skeleton

Output

At the target root, four files per audit (same stem):

• <target>-<YYYYMMDD>-0xluk3_dappwalker.md - main report (markdown). Only findings that survived verification, deduped, severity-adjusted.
• <target>-<YYYYMMDD>-0xluk3_dappwalker.html - main report (HTML), same content in the dark-slate theme.
• <target>-<YYYYMMDD>-0xluk3_dappwalker-candidates.md - candidates companion report (markdown). Every raw candidate from Passes 2/3/4 grouped by verifier verdict (Valid / Valid (downgraded) / False positive / Unverified), with the verifier's reason and cited evidence per candidate. This is the transparency trail so you can see what got filtered and why.
• <target>-<YYYYMMDD>-0xluk3_dappwalker-candidates.html - candidates companion (HTML).

Plus intermediate files in the scratch dir (not meant to be read by humans but useful for debugging):

• .dappwalker/<timestamp>/scope.md - the authoritative scope manifest produced by Pass 0.
• .dappwalker/<timestamp>/0{1..4}_*.md - per-pass raw outputs (Pass 2, Pass 3 shards, Pass 4).
• .dappwalker/<timestamp>/verified_batch_*.md - one file per Pass 5 verifier batch with verdicts + reasons.
• .dappwalker/<timestamp>/_recon_prompt_verbatim.md - recon prompt, unaltered.

<target> is the final path component of the audited directory; <YYYYMMDD> is the audit date. Example: auditing /home/joe/docs/dev-proj/example on 2026-04-22 produces:

• example-20260422-0xluk3_dappwalker.md
• example-20260422-0xluk3_dappwalker.html
• example-20260422-0xluk3_dappwalker-candidates.md
• example-20260422-0xluk3_dappwalker-candidates.html

---

Disclaimer

dappwalker identifies potential issues. Exploitability and real-world impact assessment require manual analysis and knowledge about deployment conditions. The tool is provided as-is, use at your own risk.

---

Known limitations

dappwalker works best with small to medium codebases. Large codebases may take significantly longer and have decreased accuracy as findings spread across more files than the detector shards are shaped for.

If you require a review of a complex codebase, get in touch - @0xluk3 on X

---

License

Licensed under AGPL-3.0-or-later.

---

Author

Built by @0xluk3 · luk3.tech