A lightweight Codex/Claude skill for professional security review of blockchain node implementations: execution clients, consensus clients, app-chain SDKs, bridges, relayers, and codebases with P2P networking, consensus logic, RPC handlers, or state transition code. This is a coordination layer for security review, not an autonomous full-audit platform.

What it does

The orchestrator coordinates agents and runs cheap inline Bash gates; subagents read code and write scoped outputs to audit/. Every finding lives in its own markdown file with YAML frontmatter — there is no mega-inventory file as the authority.

The pipeline is split into three explicit commands. Each one stops after its own completion gate. Do not silently chain them.

  1. /client-auditor start [path] — setup, recon, hunt drafts, optional cross-subsystem pass, inventory promotion to canonical findings, coverage. Stops after the inventory gate passes.
  2. /client-auditor verify [path] [deep] — builds verification_queue.md, verifies queued findings (each verifier edits its assigned finding file in place — frontmatter verification_* fields + a ## Verification body section). deep adds at most four depth lenses (consensus / network / state-resource / memory-concurrency) plus an adversarial review pass.
  3. /client-auditor report [path] — renders report.md from existing finding files. Does not run tests, source validation, verifier re-checks, or deep lenses.

start does not accept deep. Depth lenses and adversarial review run only during verify deep.

Design philosophy

  • Per-finding files are authority. Each canonical finding is audit/findings/{C|H|M|L|I}-{NNN}-{slug}.md with YAML frontmatter. The findings_inventory.md file is a derived view, regenerated by inventory on every run.
  • Stable id, mutable filename. The frontmatter id: F-NNN is globally unique, never reused, never renumbered. Severity changes rename the file (mv to new PREFIX-) but id stays — cross-references in queue / report / adversarial all use F-NNN.
  • Drafts → canonical via promotion. Hunt / cross-subsystem / depth agents write drafts to findings/_drafts/{focus}-NN-{slug}.md. Inventory promotes via mv with calibrated severity and id.
  • Verification lives on the finding. Verifier edits its assigned finding file in place (frontmatter verification_* fields + a ## Verification body section).
  • Append-only audit trail. Merge → loser becomes superseded, file kept. REFUTED → mv to _false-positives/FP-NNN-*.md, file kept. Nothing is deleted.
  • Cardinal Rule on gates. If a Bash gate complains an artifact is “extra” or “no longer required,” the gate is wrong — fix the gate, not the artifact. Never delete verifier work to pass a gate.
  • Main context stays lean. The orchestrator does not read source files, pattern files, lens files, large analysis references, or finding body text. Subagents do.
  • Observable phases. Every phase writes audit/progress/{phase}-{owner}.md as its first action and updates at checkpoints. The orchestrator polls these to detect stalls.
  • Honest uncertainty. Recon records discovery confidence, miss risk, unresolved entry-point questions, and triggered deep lenses.
  • Report is cheap. Report generation is rendering only and discloses stale or inconsistent inputs under Report Input Gaps rather than fixing them.

Usage

/client-auditor start [target-path]
/client-auditor verify [target-path] [deep]
/client-auditor report [target-path]
CommandMeaning
startDiscover scope, run hunt agents, write drafts, promote to canonical findings, build coverage.
verifyBuild verification queue and verify Medium+ findings (and depth promotions if deep). deep adds 4 lenses + adversarial review.
reportRender the final report from existing artifacts only.

If no command is supplied, the skill treats the request as start and states that assumption.

Output

audit/
  metadata.md
  manifest.md
  spawn_manifest.md
  progress/                              # per-phase progress, agent-created
  findings/                              # AUTHORITY for every vulnerability claim
    _drafts/                             # hunt/xsub/depth output (pre-promotion)
      {focus}-{NN}-{slug}.md
    {C|H|M|L|I}-{NNN}-{slug}.md          # canonical findings; PREFIX = current severity
    _false-positives/
      FP-{NNN}-{slug}.md                 # REFUTED findings, file kept as audit trail
  findings_inventory.md                  # auto-generated derived view (not authoritative)
  verification_queue.md                  # orchestrator-built from frontmatter
  depth/{lens}.md                        # depth lens scratch output
  adversarial_review.md                  # severity recommendations table
  coverage.md
  report.md

audit/progress/ is the live control plane. Required files vary by command phase: progress/recon.md, progress/hunt-{focus}.md, progress/xsub.md, progress/inventory.md, progress/verification_queue.md, progress/verify-{ID}.md, progress/depth-{lens}.md, progress/adversarial.md, progress/report.md.

Agents create their own progress file as their first file-write action — the orchestrator does not pre-create skeletons. Completion gates reject phases whose progress files are not terminal (complete | skipped | blocked).

Gates

Each phase ends with an inline Bash snippet (in SKILL.md) that the orchestrator runs to verify required artifacts exist and have valid frontmatter. Snippets are written for bash; invoke them with bash -lc '<snippet>' or an equivalent bash runner.

The most important gate invariants:

  • spawn_manifest.md has at least one Required = YES row
  • every required hunt has a terminal progress/hunt-{focus}.md (zero drafts is OK with Findings Touched: 0)
  • every canonical finding has frontmatter id, status, severity, confidence, and filename PREFIX equals severity[0]
  • every queued verification id has a finding file with verification_status set after verify

Knowledge base

  • 20 vulnerability pattern families in references/patterns/ (PAT-01 through PAT-20)
  • Routing and discovery references in references/routing/ (entry points, trust boundaries 1-7, pattern routing, discovery playbook)
  • Client-native deep lenses in references/lenses/ (consensus-invariant, network-surface, state-resource, memory-concurrency)
  • Audit artifact, finding, inventory-view, and progress schemas in references/specs/
  • 7-lens analysis checklist, heuristics, severity judging rules, and Red/Blue/Judge adversarial review protocol in references/

Contributing

  • New pattern: add to the appropriate references/patterns/client-attack-patterns-N.md (use PAT-NN id) and references/routing/pattern-routing.md.
  • New artifact shape: update references/specs/finding-format.md (the schema authority) first, then the matching gate snippet in SKILL.md and any agent prompts that consume that shape.
  • New agent: add references/agents/{name}-agent.md with explicit Inputs / First Action (progress write) / Method / Output / Scope / Self-Check / Return sections, and wire from SKILL.md with explicit artifact ownership and a close-after-stage instruction.
  • New gate: add it inline in SKILL.md at the relevant Stage end. Prefer shell-variable names such as st= over names that commonly collide with interactive shell built-ins. Pin column indices in inline comments if you parse tables.