# auto-audit

> Autonomous security auditor for Claude Code. Scans a GitHub repo for vulnerabilities, triages false positives, writes a proof of concept, fixes each confirmed bug in its own PR, independently reviews the fix, and merges when the review is clean.

auto-audit is a Claude Code plugin authored by Matt Hesketh. Source at https://github.com/wrxck/auto-audit. Version 0.10.0. MIT licensed.

## Install

```
/plugin marketplace update wrxck-claude-plugins
/plugin install auto-audit@wrxck-claude-plugins
```

## Key facts

- Runs on Linux (first-class), macOS (via Homebrew bash + util-linux), or Windows WSL2.
- Requires: bash 4+, gh, git, jq, flock.
- Recommended: a container runtime (podman / docker / bwrap) so sandboxed test execution works.
- Default merge policy is `manual` — the plugin opens PRs and leaves them for human review. `auto` is opt-in.

## Safety model (two layers)

Every safety claim is enforced at two layers: (1) an instruction in the relevant agent's role card, and (2) a programmatic guard in scripts/lib/guards.sh that runs before the action commits and refuses if violated. The guard test suite (scripts/test-guards.sh) exercises every programmatic guard — 79/79 currently passing.

Mechanically enforced:
- Never push to the default branch. Never force-push outside `autoaudit/*`.
- Reviewer sees only the raw finding + diff, not the fixer's reasoning.
- Fix diff is capped at 5 files / 400 lines (env-tunable).
- PoCs never land in commits. PoCs don't perform live network I/O.
- Secrets (AKIA, ghp_, sk-ant-, PEM headers, etc.) cannot be introduced in added lines.
- Submodule pointers cannot be changed mid-audit.
- Credential / MAC / signature comparisons must SHA3-256 hash both sides first. Constant-time primitives on raw secrets (timingSafeEqual, compare_digest, ConstantTimeCompare, MessageDigest.isEqual, secure_compare, fixed_length_secure_compare, FixedTimeEquals, hash_equals, CRYPTO_memcmp) are themselves a known-vulnerable posture; only hashing destroys prefix structure and eliminates the hangman oracle. `guard_no_unhashed_credential_compare` refuses the commit otherwise. Full rule: `skills/security-knowledge/hash-then-compare.md`.
- State transitions follow an explicit allowed-edge set.
- Only one tick per repo (flock).

Judgement calls (LLM layer only, no mechanical check possible):
- Whether finding text is prose or a prompt-injection attempt (mitigated with delimited UNTRUSTED framing).
- Whether a fix's reasoning is sound.
- Whether a review's rationale is rigorous.

## Sandboxed test execution

Scraped-repo test commands (npx, pytest, jest, go test, cargo test, ...) run inside podman/docker/bwrap:
- No network by default. Per-repo egress allowlist.
- Cloned repo mounted read-only. Writes go to tmpfs.
- Unprivileged user (uid 65534). --cap-drop=ALL. --security-opt=no-new-privileges.
- cpu/memory/pid caps (2 cpu, 2 GB, 256 pids).
- sandbox_mode=strict (default) refuses unsandboxed execution.

## Lifecycle

Each tick advances one finding by one stage, then returns.

discovered → triaging → (confirmed | false_positive)
confirmed → poc_writing → poc_written
poc_written → fixing → fix_committed
fix_committed → pr_opened
pr_opened → reviewing → (pr_approved | pr_rejected)
pr_approved → merged (auto) or skipped (manual)
pr_rejected → confirmed (retry, bounded by max_fix_iterations)

## Not claimed

- auto-audit is not a hardened security boundary. LLM review can be fooled by sufficiently clever prompt injection. That's why manual is the default merge policy.
- No external benchmark comparison against other security-review plugins yet.
- Coverage is bounded — 60 files per scan, per-file size limits.

## Project status

- v0.10.0 released 2026-04-26 — operator feedback memory loop: per-repo `feedback.jsonl` read by triager and fixer (not the reviewer; independence preserved). Six kinds: fix_pattern_rejected, fix_pattern_approved, human_revert, triage_override, reviewer_disagreed, note. New `/auto-audit:feedback` skill.
- v0.9.0 released 2026-04-26 — HTML audit reports: /auto-audit:report generates a self-contained HTML report per repo (summary stats, per-finding cards, full activity log). Print-friendly so PDF / DOCX / PPTX conversion is a one-shot follow-up via weasyprint / chromium / pandoc.
- v0.8.0 released 2026-04-25 — multi-repo support: drops the exclusivity gate on /auto-audit:start; audits coexist on disk; status/stop accept optional slug args; new `--all` mode for cross-repo summary.
- v0.7.0 released 2026-04-25 — three small dogfooding fixes: audit_library_surface config flag (makes triager's library-surface posture explicit and reproducible), /auto-audit:resume eager recovery for findings stuck mid-tick, sandbox-incompatible-native diagnostic (records fix.test_status when host-built native addons fail to dlopen in the container).
- v0.6.0 released 2026-04-25 — security-knowledge library expansion: 5 new rules (csprng, sql-injection, deserialization, path-canonicalization, xxe) + 3 new paired guards. Test suite 58 → 79 assertions.
- v0.5.0 released 2026-04-25 — dogfooding-driven UX fixes: reviewer self-PR fallback to `gh pr comment`, `scripts/refresh-installed.sh` for marketplace bumps, stale-finding visibility in `/auto-audit:status`.
- v0.4.2 released 2026-04-21 — permission-allowlist recipe for autonomous-loop friction (docs-only).
- v0.4.1 released 2026-04-20 — the hash-then-compare rule library and `guard_no_unhashed_credential_compare`. Supersedes v0.4.0.
- v0.3.0 released 2026-04-19 — README badges (static + dynamic).
- v0.2.0 released 2026-04-18 — programmatic guardrails + sandbox.
- First real-world run: wrxck/fleet — see https://github.com/wrxck/fleet/pull/39 for the full pipeline output (triage → PoC → fix → independent review → PR for human merge).
- Dogfood: auto-audit run against its own repo is planned; results published on auto-audit.hesketh.pro.

## Links

- Docs: https://auto-audit.hesketh.pro/
- Source: https://github.com/wrxck/auto-audit
- Release notes: https://github.com/wrxck/auto-audit/releases/tag/v0.10.0
- Plugin collection: https://claude.hesketh.pro/
- Author: https://matthesketh.pro/