Chief Wiggum

Chief Wiggum - Ralph Wiggum-style Vulnerability Hunter

Iterative vulnerability discovery using four-phase explore/deep-dive methodology, built on Ralph Wiggum's self-referential loop pattern.

Quick Start

# Install the plugin (symlink to Claude Code plugins)
ln -s /path/to/chief-wiggum ~/.claude/plugins/chief-wiggum

# Start a hunt (sequential, single session)
/vuln-hunt --profile ./profiles/chrome-sandbox-escape.yaml \
           --target /path/to/chromium/src \
           --max-iterations 50

# Start a hunt with Agent Teams (parallel teammates)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
/vuln-hunt --profile ./profiles/chrome-sandbox-escape.yaml \
           --target /path/to/chromium/src \
           --team 3

How It Works

Chief Wiggum combines the simplicity of Ralph Wiggum's self-referential loops with proven vulnerability hunting methodology. It supports two modes: sequential (default) and team (parallel via Agent Teams).

Sequential Mode (default)

A single session loops through four phases using the Stop hook:

┌──────────────────────────────────────────────────────────────────┐
│                     Four-Phase Hunt Loop                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────┐  ┌───────────┐  ┌───────────┐  │
│  │ CONTEXT-     │─▶│ EXPLORE  │─▶│ DEEP-DIVE │─▶│ SCRUTINIZE│  │
│  │ BUILD        │  │          │  │           │  │           │  │
│  └──────────────┘  └──────────┘  └───────────┘  └───────────┘  │
│                          │              │              │         │
│                          ▼              ▼              ▼         │
│                   ┌──────────────────────────────────────────┐   │
│                   │       Filesystem Memory                  │   │
│                   │  • hunt-plan.json  (attack surface map) │   │
│                   │  • candidates/     (potential vulns)     │   │
│                   │  • findings/       (confirmed)           │   │
│                   │  • explored.log    (search history)      │   │
│                   └──────────────────────────────────────────┘   │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Team Mode (--team N)

A lead session coordinates N independent teammates via Agent Teams:

┌──────────────────────────────┐
│ Lead session                 │
│ CONTEXT-BUILD                │
│   ↓ (stop hook)             │
│ TEAM-LEAD                    │
│   Create tasks from plan     │
│   Spawn N teammates          │
│   Wait + synthesize          │
└──────────────────────────────┘
  │         │         │
  ▼         ▼         ▼
Teammate1  Tm2       Tm3
AS-001     AS-002    AS-003
EXPLORE    EXPLORE   EXPLORE
DEEP-DIVE  ...       ...
SCRUTINIZE
(parallel, independent)

Each teammate runs a full EXPLORE → DEEP-DIVE → SCRUTINIZE cycle on its assigned attack surface area. Area-ID prefixing prevents file conflicts between teammates.

Requirements: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var must be set. Without it, --team gracefully falls back to sequential mode.

Phases

CONTEXT-BUILD — Maps the codebase, identifies attack surfaces, creates hunt-plan.json

EXPLORE — Picks the highest-priority unexplored area, searches for vulnerability patterns, creates candidate files

DEEP-DIVE — Validates candidates using Vulnhalla-style guided questions with evidence from actual code

SCRUTINIZE — Devil's advocate analysis, test-based verification, PoC generation, vulnerability report

TEAM-LEAD (team mode only) — Creates tasks per attack surface, spawns teammates, delegates and waits

TEAM-SYNTHESIS (team mode only) — Merges teammate results, creates synthesis report

Commands

Command	Description
/vuln-hunt --profile <yaml> --target <path>	Start a sequential hunt
/vuln-hunt --profile <yaml> --target <path> --team [N]	Start a team hunt with N teammates (default: 3)
/hunt-status	Show status of all active hunts
/cancel-hunt	Stop the current hunt (preserves data)
/review-hunt	Review hunt results
/resume-hunt	Resume a stopped hunt

Profile Format

Profiles define what you're hunting for:

name: "My Vulnerability Hunt"
description: >
  Detailed description of what vulnerabilities you're looking for,
  including patterns, examples, and context.

language: "cpp"

scope:
  include_paths:
    - "src/**/*"
  exclude_paths:
    - "tests/**/*"
  focus_keywords:
    - "dangerous_function"
    - "unchecked_input"

constraints:
  - "REJECT: False positive pattern X"
  - "REQUIRE: Must be reachable from attack surface"

checklist:
  - "□ Is input validated?"
  - "□ Are bounds checked?"
  - "□ Is this exploitable?"

File Structure

.claude/
├── vuln-hunt-{profile}.local.md       # Hunt state (active during hunt)
└── vuln-hunt-data-{profile}/
    ├── hunt-plan.json                  # Attack surface map (from CONTEXT-BUILD)
    ├── hunt-config.json                # Hunt configuration
    ├── candidates/                     # Potential vulnerabilities
    │   └── 001-example.md              # Sequential mode
    │   └── AS001-001-example.md        # Team mode (area-prefixed)
    ├── findings/                       # Confirmed vulnerabilities
    │   └── confirmed-001-example.md
    ├── rejected/                       # Investigated and dismissed
    │   └── 001-false-positive.md
    ├── review-queue/                   # Low-confidence rejections for human review
    ├── poc/                            # Proof-of-concept exploits and tests
    ├── reports/                        # Vulnerability reports
    │   └── team-synthesis.md           # Team mode: merged results
    ├── agents/                         # Per-teammate learnings (team mode)
    │   └── learnings-{teammate}.md
    ├── explored.log                    # Search history
    └── learnings.md                    # Accumulated security patterns

Completion Signals

Signal	Meaning
<promise>VULNERABILITY_CONFIRMED</promise>	Found and confirmed a vulnerability
<promise>HUNT_EXHAUSTED</promise>	Explored all scope areas, no findings
<transition>TEAM-SYNTHESIS-COMPLETE</transition>	Team mode: all teammates done, results synthesized

Agent Teams Hooks

When using --team, two additional hooks provide quality gates:

Hook	Purpose
TeammateIdle	Prevents teammates from going idle while tasks remain; guides them to check the task list
TaskCompleted	Validates teammate work before allowing task completion: checks explored.log, hunt-plan.json, and ensures no orphaned candidates

References

• Ralph Wiggum — Self-referential AI loops using filesystem as memory
• SLICE — Three-stage SAST→Enrichment→LLM pipeline for systematic vulnerability discovery
• Vulnhalla — Guided question methodology for filtering false positives from CodeQL results

License

MIT