audit-full

# Full-Codebase Audit Single-pass whole-project analysis leveraging Opus 5.5's extended context window. Loads entire codebases (~50K LOC) into context for cross-file vulnerability detection, architecture review, and dependency analysis. ## Quick Start ```bash audit-full # Full audit (all modes) audit-full security # Security-focused audit audit-full architecture # Architecture review audit-full dependencies # Dependency audit ``` > **Opus 5.5**: Uses `complexity: max` for extended thinking across entire codebases. 1M context (default and maximum on Opus 5.5) enables cross-file reasoning that chunked approaches miss. Set effort explicitly: Opus 5.5's own default is `medium` (one level below Opus 5's `high`), and CC 2.1.280+ starts a newly released model at its default rather than an older saved `/effort` level. Run audits at `high`; use `xhigh` for one additional cross-file pattern sweep on the hardest codebases. > **1M Context Required:** If `CLAUDE_CODE_DISABLE_1M_CONTEXT` is set, audit-full cannot perform full-codebase analysis. Check: `echo $CLAUDE_CODE_DISABLE_1M_CONTEXT` — if non-empty, either unset it (`unset CLAUDE_CODE_DISABLE_1M_CONTEXT`) or use `verify` for chunked analysis instead. > **Effort (CC 2.1.111+):** `xhigh` adds a second pass that re-reads cross-module boundaries specifically looking for patterns the first pass normalized over. Reserve `xhigh` for the hardest codebases (see the Opus 5.5 note above for the default). Silently falls back to `high` on other models; `doctor` warns on mismatch. > **Switching to Opus (CC 2.1.144+):** `/model` now affects the current session only — pick Opus for this audit without it persisting. Press `d` in the picker only if you want it as the default for new sessions too. --- ## STEP 0: Verify User Intent with AskUserQuestion **BEFORE creating tasks**, clarify audit scope using the interactive dialog. Load: `Read("references/audit-scope-dialog.md")` for the full AskUserQuestion dialog with mode options (Full/Security/Architecture/Dependencies) and scope options (Entire codebase/Specific directory/Changed files). --- ## CRITICAL: Task Management is MANDATORY ```python # 1. Create main task IMMEDIATELY TaskCreate( subject="Full-codebase audit", description="Single-pass audit using extended context", activeForm="Running full-codebase audit" ) # 2. Create subtasks for each phase TaskCreate(subject="Estimate token budget and plan loading", activeForm="Estimating token budget") # id=2 TaskCreate(subject="Load codebase into context", activeForm="Loading codebase") # id=3 TaskCreate(subject="Run audit analysis", activeForm="Analyzing codebase") # id=4 TaskCreate(subject="Generate audit report", activeForm="Generating report") # id=5 # 3. Set dependencies for sequential phases TaskUpdate(taskId="3", addBlockedBy=["2"]) # Loading needs budget estimate TaskUpdate(taskId="4", addBlockedBy=["3"]) # Analysis needs codebase loaded TaskUpdate(taskId="5", addBlockedBy=["4"]) # Report needs analysis done # 4. Update status as you progress TaskUpdate(taskId="2", status="in_progress") # When starting TaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask ``` --- ## STEP 1: Estimate Token Budget Before loading files, estimate whether the codebase fits in context. Load: `Read("references/token-budget-planning.md")` for estimation rules (tokens/line by file type), budget allocation tables, auto-exclusion list, and fallback dialog when codebase exceeds budget. Run estimation: `bash ${CLAUDE_SKILL_DIR}/scripts/estimate-tokens.sh /path/to/project` ### Two tiers — pick by the estimate audit-full has **two execution tiers**. The estimate decides which: | Estimate vs budget | Tier | Path | |--------------------|------|------| | **Fits** (~≤125K LOC / ≤1M tokens) | **Single-context** (default — the skill's edge: whole-codebase cross-file reasoning in one window) | continue to STEP 2 | | **Exceeds** budget | **Map-reduce** (scale tier — shard → per-shard audit → cross-shard boundary synthesis → refute) | invoke the workflow below; STEP 2–3.5 run *inside* it | **Over-budget → run the map-reduce workflow** (don't punt, don't silently truncate the load): ```python # Derive shards from STEP 1 (top-level modules/dirs by size: src, apps/api, apps/web, packages/*). Workflow({ "scriptPath": "${CLAUDE_SKILL_DIR}/workflows/audit-full-mapreduce.js", "args": { "shards": ["<repo-relative dirs>"], "mode": "<full|security|architecture|dependencies>", "effort": "<high|xhigh>" } }) ``` It preserves cross-file reasoning *within* each shard and recovers cross-*shard* edges (taint/auth/dep-direction that span modules) in a dedicated synthesis pass, then runs the same STEP 3.5 adversarial refutation. Its return (merged findings + refutation ledger) feeds STEP 4. The single-context tier remains the default because it's cheaper and loses no boundaries when the repo fits — only reach for map-reduce when it genuinely doesn't. --- ## STEP 2: Load Codebase into Context Load: `Read("references/report-structure.md")` for loading strategy, inclusion patterns by language (TS/JS, Python, Config), and batch reading patterns. --- ## STEP 3: Audit Analysis With codebase loaded, perform the selected audit mode(s). ### Security Audit Load: `Read("references/security-audit-guide.md")` for the full checklist. Key cross-file analysis patterns: 1. **Data flow tracing**: Track user input from entry point → processing → storage 2. **Auth boundary verification**: Ensure all protected routes check auth 3. **Secret detection**: Scan for hardcoded credentials, API keys, tokens 4. **Injection surfaces**: SQL, command, template injection across file boundaries 5. **OWASP Top 10 mapping**: Classify findings by OWASP category ### Architecture Review Load: `Read("references/architecture-review-guide.md")` for the full guide. Key analysis patterns: 1. **Dependency direction**: Verify imports flow inward (clean architecture) 2. **Circular dependencies**: Detect import cycles across modules 3. **Layer violations**: Business logic in controllers, DB in routes, etc. 4. **Pattern consistency**: Same problem solved differently across codebase 5. **Coupling analysis**: Count cross-module imports, identify tight coupling ### Dependency Audit Load: `Read("references/dependency-audit-guide.md")` for the full guide. Key analysis patterns: 1. **Known CVEs**: Check versions against known vulnerabilities 2. **License compliance**: Identify copyleft licenses in proprietary code 3. **Version currency**: Flag significantly outdated dependencies 4. **Transitive risk**: Identify deep dependency chains 5. **Unused dependencies**: Detect installed but never imported packages ### Progressive Output (CC 2.1.76) Output findings **incrementally** as each audit mode completes — don't batch until the report: 1. **Security findings first** — show critical/high vulnerabilities immediately, don't wait for architecture review 2. **Architecture findings** — show dependency direction violations, circular deps as they surface 3. **Dependency findings** — show CVE matches, license compliance issues For multi-mode audits (Full), each mode's findings appear as they complete. This lets users act on critical security findings while architecture analysis is still running. --- ## STEP 3.5: Adversarial Refutation (effort-gated) Before the report, a separate **blind refuter** verifies CRITICAL/HIGH findings — the structural fix for self-preferential bias (a single-context pass grading its own findings anchors on its own reasoning). `low`/`medium` skip this step; `high` runs single advisory refuters; `xhigh` runs the engine's quorum (3 for CRITICAL, 2 for HIGH). Load the protocol + audit-full bindings: `Read("references/adversarial-refutation.md")` (which loads the shared engine `${CLAUDE_PLUGIN_ROOT}/shared/rules/adversarial-refutation.md`). These refuters are audit-full's **only** sub-agent spawns (the producer is single-context), always isolated `Agent(...)` with no `team_name`, fed only a neutral claim (category + `file:line`). **Deterministic ground truth is exempt** — CVE/CVSS matches, failing build/test, type errors are never refuted; only a *reachability claim* on top of a CVE is. Cross-file findings the refuter can't reproduce from its narrow slice stay **UPHELD** (engine §5). Refutation never silently drops a CRITICAL — the ledger (`refutation-ledger.json`) records survived/killed/downgraded, and removing a CRITICAL/HIGH from the report needs user confirmation. --- ## STEP 4: Generate Report Load the report template: `Read("assets/audit-report-template.md")`. Report structure and severity classification: `Read("references/report-structure.md")` for finding table format, severity breakdown (CRITICAL/HIGH/MEDIUM/LOW with timelines), and architecture diagram conventions. Severity matrix: `Read("assets/severity-matrix.md")` for classification criteria. ### Completion Checklist Before finalizing the report, verify with `Read("checklists/audit-completion.md")`. ### PushNotification on Completion (CC 2.1.110+) A full-codebase 1M-context audit typically runs 15–60 minutes on medium projects and can exceed that on large ones. **After the report file is written and the completion checklist passes, call `PushNotification`** so the finding counts are visible even if the user walked away. ```python PushNotification( message=f"ork:audit-full complete — {SCOPE}: {critical}C/{high}H/{medium}M/{low}L · {report_path}", status="proactive" ) ``` Full rule: `Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/rules/push-notification-on-completion.md")`. --- ## When NOT to Use | Situation | Use Instead | |-----------|-------------| | Small targeted check (1-5 files) | Direct Read + analysis | | CI/CD automated scanning | `security-scanning` skill | | Multi-agent graded verification | `verify` | | Exploring unfamiliar codebase | `explore` | | Codebase > 125K LOC (exceeds 1M) | **stay here** — STEP 1 routes to the map-reduce tier (`workflows/audit-full-mapreduce.js`); `verify` only if you want multi-agent *graded* verification instead of an audit | --- ## Notes for whole-codebase passes > **Oversized reads (CC 2.1.144+):** When loading large files, Read returns a `[PARTIAL view]` truncated first page instead of a hard error if the whole-file read exceeds the token limit. Detect that notice and re-read with explicit `offset`/`limit` to page through the rest — a partial read silently omits code an audit must not miss. > **When context fills (CC 2.1.141+):** Use the rewind menu's "Summarize up to here" to compress earlier turns while keeping recent findings, instead of restarting the audit. Reactive compaction (CC 2.1.142+) sizes the first summarize to the actual overflow, so a wasted second pass mid-turn is now rare. --- ## Running unattended with /goal Set a completion condition with `/goal` (CC 2.1.139+) and this skill will keep working across turns until the condition is met. Works in interactive, `-p`, and Remote Control. The overlay panel shows live elapsed / turns / tokens. **Example completion condition for this skill:** ``` /goal until findings.critical == 0 OR no_new_critical_for_3_turns, or stop after 30 turns ``` Stops when: zero critical issues remain across 3 consecutive passes, or a structural anti-pattern budget is reached. Compatible with claude.ai Remote Control runs. --- ## Related Skills - `security-scanning` — Automated scanner integration (npm audit, Semgrep, etc.) - `ork:security-patterns` — Security architecture patterns and OWASP vulnerability classification - `ork:architecture-patterns` — Architectural pattern reference - `ork:quality-gates` — Quality assessment criteria - `ork:verify` — Multi-agent verification (fallback for codebases exceeding 1M context) ## References Load on demand with `Read("references/<file>")`: | File | Content | |------|---------| | `references/security-audit-guide.md` | Cross-file vulnerability patterns | | `references/architecture-review-guide.md` | Pattern and coupling analysis | | `references/dependency-audit-guide.md` | CVE, license, currency checks | | `references/adversarial-refutation.md` | Blind-refuter bindings (STEP 3.5) — loads the shared engine | | `references/token-estimation.md` | File type ratios and budget planning | | `assets/audit-report-template.md` | Structured output format | | `assets/severity-matrix.md` | Finding classification criteria | | `checklists/audit-completion.md` | Pre-report verification | | `scripts/estimate-tokens.sh` | Automated LOC to token estimation | | `workflows/audit-full-mapreduce.js` | Scale tier — shard→audit→synthesize→refute for repos that exceed 1M context (run via the Workflow tool) |