ExploitLens

Differential exploit replay and evidence-backed fix verification.

ExploitLens takes a supplied Solidity exploit, replays it against a vulnerable commit and a patched commit under identical frozen inputs, aligns the two call trees semantically, and identifies the first causal divergence that explains the missing prohibited effect. The result is a Fix Receipt: a scoped, independently verifiable claim about what the patch actually blocked — never a generic "secure" badge.

Status: Phase 1. The workspace foundation is in place and the pinned, deterministic demo exploit fixture (fixtures/demo-exploit/) is complete. No runner, executor, or UI behavior is implemented yet.

Requirements

Tool	Version	Notes
Node.js	24.18.1 (.node-version)	>=22.11.0 is supported.
pnpm	11.18.0 (packageManager)	corepack enable picks this up automatically.
Foundry	pinned in Phase 1	Only needed once the demo fixture exists.

Setup

corepack enable
pnpm install

Commands

Run these from the repository root.

Command	What it does
pnpm lint	ESLint across every workspace.
pnpm format / pnpm format:check	Prettier write / verify.
pnpm typecheck	Root config plus every workspace's tsc project.
pnpm test	Vitest across tests/, packages, and the runner.
pnpm test:coverage	Vitest with V8 coverage.
pnpm build	Topological build: TypeScript packages, then the web bundle.
pnpm verify	lint → typecheck → test → build. Use this before opening a PR.
pnpm clean	Remove build output from every workspace.

Scope a command to one workspace with a filter:

pnpm --filter @exploitlens/manifest test
pnpm --filter @exploitlens/web dev

Layout

apps/
  web/                React workbench (Vite, static-deployable)
  runner/             Local Fastify API and execution coordinator
packages/
  manifest/           Exploit Bundle schema, canonicalization, hashing
  executor/           Workspaces, Foundry commands, timeouts, capture
  trace-ir/           Versioned canonical call and effect types
  trace-normalizer/   Raw Foundry output to Trace IR
  effects/            Native, token, event, and storage effect extraction
  aligner/            Semantic tree alignment and first causal divergence
  invariants/         Security and legitimate-control gate logic
  variants/           Deterministic candidate generation and scoring
  receipt/            Receipt creation and evidence references
  verifier/           Offline hash and consistency verification
  ui-contracts/       Frontend-safe artifact view models
fixtures/demo-exploit/  Pinned vulnerable, patched, exploit, and control case
schemas/              Generated and reviewed JSON Schemas
artifacts/demo/       Committed fallback evidence bundle
scripts/              reproduce-demo.sh, verify-demo.sh
tests/                Cross-workspace structural tests
docs/                 Feature list, PRD, architecture, task plan

Conventions

• ESM everywhere. Every workspace is "type": "module" and TypeScript is strict with verbatimModuleSyntax.
• Packages publish dist/, never src/. Cross-package imports resolve to built declarations at build time and to source during typecheck and test, so neither depends on the other having run first.
• No shell strings. Foundry is invoked through spawn with argument arrays; a lint rule enforces this.
• Artifacts are the source of truth. Evidence bundles are versioned, hashable JSON. Any database is a discovery index, never authoritative.

Documentation

• docs/01_MVP_FEATURE_LIST.md
• docs/02_HACKATHON_PRD.md
• docs/03_SYSTEM_ARCHITECTURE.md
• docs/04_ORDERED_DEVELOPMENT_TASKS.md

License

MIT