Audit Full

Full-Codebase Audit

Single-pass whole-project analysis leveraging Opus 4.8's extended context window. Loads entire codebases (~50K LOC) into context for cross-file vulnerability detection, architecture review, and dependency analysis.

Quick Start

/ork:audit-full                          # Full audit (all modes)
/ork:audit-full security                 # Security-focused audit
/ork:audit-full architecture             # Architecture review
/ork:audit-full dependencies             # Dependency audit

Opus 4.8: Uses complexity: max for extended thinking across entire codebases. 1M context (GA) enables cross-file reasoning that chunked approaches miss. Opus 4.8 defaults to high effort; bump to 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 /ork: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. Opus 4.8 defaults to high (CC 2.1.154) and reserves xhigh for the hardest codebases. Silently falls back to high on other models; /ork: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("${CLAUDE_SKILL_DIR}/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

# 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. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. 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("${CLAUDE_SKILL_DIR}/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:

Over-budget → run the map-reduce workflow (don't punt, don't silently truncate the load):

# 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.mjs",
  "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("${CLAUDE_SKILL_DIR}/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("${CLAUDE_SKILL_DIR}/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("${CLAUDE_SKILL_DIR}/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("${CLAUDE_SKILL_DIR}/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("${CLAUDE_SKILL_DIR}/references/adversarial-refutation.md") (which loads the shared engine ${CLAUDE_PLUGIN_ROOT}/skills/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("${CLAUDE_SKILL_DIR}/assets/audit-report-template.md").

Report structure and severity classification: Read("${CLAUDE_SKILL_DIR}/references/report-structure.md") for finding table format, severity breakdown (CRITICAL/HIGH/MEDIUM/LOW with timelines), and architecture diagram conventions.

Severity matrix: Read("${CLAUDE_SKILL_DIR}/assets/severity-matrix.md") for classification criteria.

Completion Checklist

Before finalizing the report, verify with Read("${CLAUDE_SKILL_DIR}/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.

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

---

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

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("${CLAUDE_SKILL_DIR}/references/<file>"):

Audit Report Template

Use this structure for all audit reports.

Template

# Audit Report: {project-name}

**Date:** {YYYY-MM-DD}
**Auditor:** Claude Opus 4.8 via /ork:audit-full
**Mode:** {Full | Security | Architecture | Dependencies}
**Scope:** {Entire codebase | Directory: path/ | Changed files only}

## Summary

| Metric | Value |
|--------|-------|
| Files loaded | {count} |
| Lines of code | {loc} |
| Estimated tokens | {tokens} |
| Context utilization | {percentage}% |

### Findings Overview

| Severity | Count |
|----------|-------|
| CRITICAL | {n} |
| HIGH | {n} |
| MEDIUM | {n} |
| LOW | {n} |
| **Total** | **{total}** |

**Overall Health Score: {0-10}/10**

## Findings

### CRITICAL

#### F-001: {Finding title}
- **Category:** {Security | Architecture | Dependency}
- **OWASP:** {A01-A10 if applicable}
- **File(s):** `{file:line}`, `{file:line}`
- **Description:** {What the issue is}
- **Impact:** {What could happen if exploited/unfixed}
- **Evidence:**

{relevant code snippet}

- **Remediation:**

{fixed code snippet}

- **Effort:** {Low | Medium | High}

### HIGH

#### F-002: {Finding title}
{same structure as above}

### MEDIUM

#### F-003: {Finding title}
{same structure as above}

### LOW

#### F-004: {Finding title}
{same structure as above}

## Architecture Overview

{ASCII diagram of module dependencies with violations marked}

┌──────────┐ ┌──────────┐ ┌──────────┐ │ routes │────▶│ services │────▶│ repos │ └──────────┘ └──────────┘ └──────────┘ │ ▼ ┌──────────┐ │ domain │ └──────────┘

Violations: {list any dependency direction violations}

## Dependency Summary

| Package | Current | Latest | Status | Risk |
|---------|---------|--------|--------|------|
| {name} | {ver} | {ver} | {Current/Stale/Outdated/EOL} | {severity} |

## Recommendations

### Immediate (This Sprint)
1. {Fix critical findings F-001, F-002}

### Short-term (This Quarter)
1. {Address high findings}
2. {Update outdated dependencies}

### Long-term (Backlog)
1. {Architecture improvements}
2. {Pattern consolidation}

## Appendix

### Files Analyzed
{list of all files loaded into context}

### Methodology
- Single-pass analysis using Opus 4.8 1M context (GA)
- Cross-file data flow tracing
- OWASP Top 10 mapping
- Clean architecture layering check

Report Quality Checklist

Before delivering the report:

• [ ] Every finding has file:line references
• [ ] Every finding has a remediation suggestion
• [ ] Severity classifications match the severity matrix
• [ ] Architecture diagram reflects actual dependencies
• [ ] Recommendations are prioritized by impact and effort
• [ ] No false positives left unverified

Severity Classification Matrix

Consistent severity scoring across all audit domains.

Classification Criteria

Security Domain

Architecture Domain

Dependency Domain

Scoring Formula

Health Score = 10 - (CRITICAL × 2) - (HIGH × 1) - (MEDIUM × 0.3) - (LOW × 0.1)
Minimum: 0, Maximum: 10

Audit Completion Checklist

Verify before finalizing the audit report.

Pre-Report Verification

Coverage

• [ ] All source files in scope were loaded (check file count vs glob count)
• [ ] Entry points identified and traced
• [ ] Configuration files reviewed (env, docker, CI)
• [ ] Lock files checked (package-lock.json, poetry.lock, go.sum)

Security (if applicable)

• [ ] All public endpoints checked for auth middleware
• [ ] Data flow traced from input → storage for at least 3 critical paths
• [ ] Secret detection scan completed (grep for API keys, passwords, tokens)
• [ ] OWASP Top 10 categories all considered (mark N/A if not applicable)
• [ ] Third-party integrations checked for SSRF risk
• [ ] File upload/download paths checked for traversal

Architecture (if applicable)

• [ ] Dependency direction verified (imports flow inward)
• [ ] Circular dependencies checked
• [ ] Pattern consistency evaluated (error handling, validation, data access)
• [ ] Module coupling analyzed (cross-directory import counts)
• [ ] Layer violations identified
• [ ] ASCII architecture diagram generated

Dependencies (if applicable)

• [ ] npm audit / pip-audit / equivalent run
• [ ] License compliance checked (no GPL in proprietary)
• [ ] Outdated packages identified with severity
• [ ] Unused dependencies flagged
• [ ] Transitive dependency risks assessed

Report Quality

• [ ] Every finding has specific file:line references
• [ ] Every finding has a remediation suggestion with code
• [ ] Severity classifications match the severity matrix
• [ ] No duplicate findings (same root cause reported once)
• [ ] False positives verified and removed
• [ ] Recommendations prioritized by impact and effort
• [ ] Executive summary accurately reflects findings
• [ ] Health score calculated correctly

Completeness

• [ ] All selected audit modes completed
• [ ] Context utilization reported (tokens used / available)
• [ ] Files list in appendix matches loaded files
• [ ] Report follows the template structure

Adversarial Refutation — audit-full bindings

Thin adapter. Loads the shared engine, then binds it to audit-full's severity-ranked findings.

Load the engine first: Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/adversarial-refutation.md") — the blindness contract, independent-score-first, citation-verify, quorum, cross-file UPHELD-default, deterministic-exemption, no-auto-flip, spawn-ceiling, ledger schema, and isolated-spawn rules. This file only supplies what's audit-full-specific.

Bindings

Scope filter (which findings get a refuter)

A finding qualifies only if decision-bearing — ANY of:

• CRITICAL or HIGH severity (these drive the report's headline + remediation timeline)
• a finding that asserts exploitability/reachability (a claim, not a tool match)

Skip: MEDIUM/LOW informational findings, and deterministic ground truth — a CVE/CVSS match from a dependency scan, a failing build/test, a type error (engine §6). Only a reachability claim layered on top of a CVE ("this CVE is exploitable because input reaches it") is refutable, and only that claim. Dedup to root-cause BEFORE counting; respect the global spawn ceiling (default 24, engine §8) — rank by severity × distance-from-decision-boundary and flag any un-refuted overflow "manual review required".

Cross-file caution (audit-full-specific)

audit-full's edge is whole-codebase cross-file reasoning (taint flows, auth-boundary gaps spanning modules). A refuter only gets the cited slice, so per engine §5 a "could not reproduce the traced flow" result is UPHELD, never REFUTED — the card MUST carry the producer's full traced file set so the refuter knows what it's missing. A narrow-context refuter must never kill a true cross-file finding it simply couldn't see.

Effort gate (audit-full-specific)

audit-full is already a heavy single-context pass; keep refutation bounded:

• low / medium → skip STEP 3.5 entirely
• high → up-to-ceiling single refuters on CRITICAL/HIGH, advisory only (surfaced, not

auto-applied; a single refuter never demotes a CRITICAL on its own — §7)

• xhigh → quorum (§4): 3-refuter majority for CRITICAL, 2 for HIGH; a kill that would drop

a CRITICAL from the report requires explicit user confirmation (§7)

Isolation note

Refuters are ALWAYS standalone Agent(...) Task spawns with no `team_name`, fed only the serialized claim (category + file:line, NO producer severity/prose). audit-full has no mesh to leak into, but the rule holds: delivery is prompt/additionalContext-only (engine §9).

Architecture Review Guide

Pattern consistency, coupling analysis, and structural health assessment.

Dependency Direction Analysis

Clean Architecture Layers

┌─────────────────────────────┐
│  Presentation (routes, UI)  │  ← Outermost
├─────────────────────────────┤
│  Application (use cases)    │
├─────────────────────────────┤
│  Domain (entities, rules)   │
├─────────────────────────────┤
│  Infrastructure (DB, APIs)  │  ← Outermost
└─────────────────────────────┘

Rule: Dependencies point INWARD only.
Violation: Domain importing from Infrastructure.

Detection Method

1. Map each file to a layer based on directory structure 2. Parse imports/requires in each file 3. Flag imports that point outward (wrong direction)

# VIOLATION EXAMPLE:
# src/domain/user.ts imports from src/infrastructure/db.ts
import { dbPool } from '../infrastructure/db'  // Wrong direction!

# CORRECT:
# src/domain/user.ts defines interface
# src/infrastructure/db.ts implements it

Circular Dependency Detection

What to Look For

# File A imports File B, File B imports File A
// src/auth/service.ts
import { UserRepo } from '../users/repo'

// src/users/repo.ts
import { AuthService } from '../auth/service'  // Circular!

Resolution Patterns

Pattern Consistency Check

Look for the same problem solved differently across the codebase:

Scoring

Coupling Analysis

Metrics to Calculate

Module Boundary Health

# Count imports between directories:
src/auth/ → src/users/    : 5 imports (acceptable)
src/auth/ → src/payments/  : 12 imports (high coupling!)
src/utils/ → src/auth/     : 0 imports (good, utils is generic)

Red Flags

• Module with > 15 external dependents (God module)
• Utility file with > 500 lines (needs splitting)
• Circular import chains > 2 files deep
• Config/env imported in > 20 files (use DI instead)

Layering Violations

Architecture Diagram Output

Generate ASCII diagram showing module dependencies:

┌──────────┐     ┌──────────┐     ┌──────────┐
│  routes   │────▶│ services │────▶│  repos   │
└──────────┘     └──────────┘     └──────────┘
      │                │                │
      ▼                ▼                ▼
┌──────────┐     ┌──────────┐     ┌──────────┐
│middleware│     │  domain  │     │    db     │
└──────────┘     └──────────┘     └──────────┘

Legend: ──▶ = imports from
Violations marked with ✗

Audit Scope Dialog

STEP 0: Verify User Intent with AskUserQuestion

BEFORE creating tasks, clarify audit scope:

AskUserQuestion(
  questions=[
    {
      "question": "What type of audit do you want to run?",
      "header": "Audit mode",
      # multiSelect questions do not render previews (single-select only) — text-only
      "options": [
        {"label": "Full audit (Recommended)", "description": "Security + architecture + dependencies in one pass (Opus 1M context, all files at once)"},
        {"label": "Security audit", "description": "Cross-file vulnerability analysis, data flow tracing, OWASP mapping, secret detection"},
        {"label": "Architecture review", "description": "Pattern consistency, coupling metrics, dependency violations, layer enforcement"},
        {"label": "Dependency audit", "description": "CVE scan, license compliance, version drift, unused/transitive-risk deps"}
      ],
      "multiSelect": true
    },
    {
      "question": "What should be audited?",
      "header": "Scope",
      "options": [
        {"label": "Entire codebase", "description": "Load all source files into context"},
        {"label": "Specific directory", "description": "Focus on a subdirectory (e.g., src/api/)"},
        {"label": "Changed files only", "description": "Audit only files changed vs main branch"}
      ],
      "multiSelect": false
    }
  ]
)

Based on answers, adjust workflow:

• Full audit: All 3 domains, maximum context usage
• Security only: Focus token budget on source + config files
• Architecture only: Focus on module boundaries, imports, interfaces
• Dependency only: Focus on lock files, manifests, import maps
• Changed files only: Use git diff --name-only main...HEAD to scope

Dependency Audit Guide

License compliance, CVE checking, and version currency analysis.

CVE Checking

Automated Scanners

# JavaScript/TypeScript
npm audit --json
npx better-npm-audit audit

# Python
pip-audit --format=json
safety check --json

# Go
govulncheck ./...

# Rust
cargo audit

Manual CVE Check

For dependencies without scanner coverage: 1. Check version in package.json / pyproject.toml / go.mod 2. Search NVD or OSV for package name 3. Compare installed version against affected version ranges 4. Classify by CVSS score

License Compliance

License Risk Tiers

Detection Method

# JavaScript
npx license-checker --json --production

# Python
pip-licenses --format=json --with-urls

# Check for problematic licenses
npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0"

What to Flag

• Any GPL/AGPL dependency in proprietary codebase → CRITICAL
• UNLICENSED dependencies → HIGH (legal risk)
• Dependencies with no license file → MEDIUM
• License changed between versions → LOW (track)

Version Currency

Currency Classification

High-Risk Outdated Patterns

Transitive Dependency Risk

Deep Chains

your-app
  └── package-a@1.0.0
       └── package-b@2.0.0
            └── package-c@3.0.0  ← vulnerability here

Risk: You don't control package-c, and updating package-a may not update it.

Detection

# Show dependency tree
npm ls --all --json | jq '.dependencies'

# Find deep chains (>4 levels)
npm ls --all 2>/dev/null | grep -E "^.{16,}" | head -20

Mitigation

Unused Dependencies

Detection

# JavaScript
npx depcheck

# Python
pip-extra-reqs --ignore-module=tests .

What to Flag

• Installed but never imported → MEDIUM (bloat, attack surface)
• Dev dependency in production deps → LOW (no runtime risk)
• Multiple packages for same purpose → LOW (e.g., both lodash and underscore)

Audit Report Structure

Report Format

# Audit Report: {project-name}
**Date:** {date} | **Mode:** {mode} | **Files loaded:** {count} | **LOC:** {loc}

## Executive Summary
{1-3 sentences: overall health, critical findings count}

## Findings

| # | Severity | Category | File(s) | Finding | Remediation |
|---|----------|----------|---------|---------|-------------|
| 1 | CRITICAL | Security | src/auth.ts:42 | ... | ... |

## Severity Breakdown
- CRITICAL: {n} (must fix before deploy)
- HIGH: {n} (fix within sprint)
- MEDIUM: {n} (fix within quarter)
- LOW: {n} (track and address)

## Architecture Diagram
{ASCII diagram of module dependencies}

## Recommendations
{Prioritized action items}

Severity Classification

Codebase Loading Strategy

1. Glob all source files matching inclusion patterns 2. Sort by priority: entry points -> core modules -> utilities -> config 3. Read files in parallel using multiple Read tool calls per message 4. Track loaded tokens to stay within budget

Inclusion Patterns (by language)

# TypeScript/JavaScript
**/*.ts **/*.tsx **/*.js **/*.jsx
**/package.json **/tsconfig.json

# Python
**/*.py
**/pyproject.toml **/setup.cfg **/requirements*.txt

# Config
**/.env.example **/docker-compose*.yml **/Dockerfile
**/*.yaml **/*.yml (non-lock)

Reading Pattern

Read files in batches of 10-15 per message for efficiency:

# Batch 1: Entry points and config
Read("src/index.ts")
Read("src/app.ts")
Read("package.json")
Read("tsconfig.json")
# ... up to 15 files

# Batch 2: Core modules
Read("src/api/routes.ts")
Read("src/db/connection.ts")
# ... next batch

Security Audit Guide

Cross-file vulnerability analysis patterns for whole-codebase audits.

Data Flow Tracing

Trace user input from entry to storage across file boundaries:

Entry Point → Validation → Processing → Storage
(route.ts)    (middleware)   (service.ts)  (repo.ts)

What to Check at Each Stage

Cross-File Vulnerability Patterns

1. Auth Bypass via Missing Middleware

# PATTERN: Route defined without auth middleware
router.get('/admin/users', getUsersHandler)  # No authMiddleware!

# Compare against protected routes:
router.get('/admin/settings', authMiddleware, getSettingsHandler)

Detection: Glob all route files, check each handler has auth middleware.

2. SQL Injection via String Interpolation

# PATTERN: Variable in SQL string (any file)
query(`SELECT * FROM users WHERE id = '${userId}'`)

# Safe pattern:
query('SELECT * FROM users WHERE id = $1', [userId])

Detection: Grep for template literals containing SQL keywords.

3. Command Injection via Shell Exec

# PATTERN: User input in exec/spawn
exec(`git log --author="${username}"`)

# Safe pattern:
execFile('git', ['log', `--author=${username}`])

Detection: Grep for exec(, execSync(, spawn( with template literals.

4. Secret Leakage

# PATTERN: Hardcoded secrets
const API_KEY = 'sk-live-abc123...'
const password = 'admin123'

# PATTERN: Secrets in error messages
throw new Error(`Auth failed for ${password}`)

# PATTERN: Secrets in logs
console.log(`Connecting with key: ${apiKey}`)

Detection: Grep for common secret patterns (sk-, ghp_, Bearer , password assignments).

5. SSRF via Unvalidated URLs

# PATTERN: User-controlled URL in fetch/axios
const response = await fetch(req.body.url)

# Safe pattern:
const url = new URL(req.body.url)
if (!ALLOWED_HOSTS.includes(url.hostname)) throw new Error('Blocked')

6. Path Traversal

# PATTERN: User input in file path
const filePath = path.join(uploadDir, req.params.filename)
// filename could be '../../etc/passwd'

# Safe pattern:
const resolved = path.resolve(uploadDir, req.params.filename)
if (!resolved.startsWith(uploadDir)) throw new Error('Blocked')

OWASP Top 10 Mapping

Severity Classification

Token Budget Planning

Run Token Estimation

# Use the estimation script
bash ${CLAUDE_SKILL_DIR}/scripts/estimate-tokens.sh /path/to/project

Manual Estimation Rules

Budget Allocation

Auto-Exclusion List

Always exclude from loading:

• node_modules/, vendor/, .venv/, __pycache__/
• dist/, build/, .next/, out/
• *.min.js, *.map, *.lock (read lock files separately for deps audit)
• Binary files, images, fonts
• Test fixtures and snapshots (unless auditing tests)
• Generated files (protobuf, graphql codegen)

If Codebase Exceeds Budget

audit-full owns this case now — it does not punt. The map-reduce tier (workflows/audit-full-mapreduce.mjs, run via the Workflow tool) shards the repo, audits each shard in its own context, then recovers cross-shard edges in a synthesis pass. Prefer it over narrowing scope (which silently drops coverage).

1. Map-reduce tier (recommended): run the workflow with shards derived from the estimate — full coverage, cross-shard boundary pass, same STEP 3.5 refutation. 2. Directory scoping: narrow to specific directories — fast but drops coverage outside the scope; say so. 3. Priority loading: entry points + critical paths only — triage, not a full audit. 4. `/ork:verify`: only if you actually want multi-agent graded verification rather than an audit.

# Over-budget routing
AskUserQuestion(
  questions=[{
    "question": "Codebase exceeds the single-context budget. How to proceed?",
    "header": "Too large",
    "options": [
      {"label": "Map-reduce audit (full coverage)", "description": "Shard → per-shard audit → cross-shard synthesis → refute (workflows/audit-full-mapreduce.mjs)"},
      {"label": "Narrow scope", "description": "Audit specific directories only — drops coverage elsewhere"},
      {"label": "Priority loading", "description": "Entry points + critical paths only (triage)"}
    ],
    "multiSelect": false
  }]
)

Token Estimation Guide

Planning context budget for whole-codebase loading.

Token Ratios by File Type

Quick Estimation Formula

Total tokens ≈ Total LOC × 7.5 (average)

For more precision:

Total tokens ≈ (TS lines × 8) + (Py lines × 7) + (Config lines × 5) + (Other × 7)

Context Budget Planning

Reserved for prompt includes: system prompt, skill content, analysis instructions, and output space.

Exclusion Priority

When codebase exceeds budget, exclude in this order:

1. Always exclude: node_modules/, vendor/, .venv/, dist/, build/, .next/ 2. Exclude first: Test fixtures, snapshots, migration files, generated code 3. Exclude second: Test files (unless auditing test quality) 4. Exclude third: Documentation, README files 5. Keep last: Source files, config, entry points

Loading Priority

When partially loading, prioritize in this order:

1. Entry points: index.ts, main.py, app.ts, server.ts 2. Route definitions: API routes, page routes 3. Middleware/interceptors: Auth, validation, error handling 4. Business logic: Services, use cases, domain models 5. Data access: Repositories, ORM models, migrations 6. Config: Environment config, feature flags, secrets management 7. Utilities: Shared helpers, common functions

Real-World Sizing Examples

Rule Categories

1. Scope Planning (scope) — HIGH — 1 rule

Requires upfront scope declaration before loading files, preventing context window exhaustion on irrelevant content.

• scope-declaration.md — Declare audit mode, inclusion list, exclusion patterns, and token budget before loading any files

2. Finding Classification (severity) — HIGH — 1 rule

Enforces evidence-backed severity levels for every finding to prevent alert fatigue and hidden critical vulnerabilities.

• finding-severity-classification.md — Every finding must include severity level, file path with line number, code snippet, and exploitation scenario

Classify Findings by Severity with Evidence

Why

Without evidence-backed severity classification, findings are either all "CRITICAL" (causing alert fatigue) or uniformly "MEDIUM" (hiding real risks). Both patterns erode trust in audit reports.

Rule

Every finding must include: 1. Severity level (CRITICAL / HIGH / MEDIUM / LOW) 2. File path and line number 3. Code snippet showing the vulnerability 4. Exploitation scenario or impact statement 5. OWASP/CWE classification where applicable

Incorrect — vague findings without evidence

## Findings

| # | Severity | Finding |
|---|----------|---------|
| 1 | HIGH | SQL injection possible |
| 2 | MEDIUM | Auth might be missing |
| 3 | HIGH | Dependencies outdated |

Problems:

• No file paths — developer cannot locate the issue
• No code evidence — finding cannot be verified
• No exploitation scenario — severity is arbitrary
• "might be missing" is not a finding, it is speculation

Correct — evidence-backed severity classification

## Findings

| # | Severity | Category | File(s) | Finding |
|---|----------|----------|---------|---------|
| 1 | CRITICAL | Injection (CWE-89) | src/api/users.ts:42 | SQL injection via string interpolation |

### Finding 1: SQL Injection (CRITICAL)

**Location:** `src/api/users.ts:42`
**OWASP:** A03:2021 Injection | **CWE:** CWE-89

**Vulnerable code:**

const query = SELECT * FROM users WHERE id = ${req.params.id}; await db.execute(query);

**Exploitation:** Attacker sends `id=1; DROP TABLE users--` via
GET /api/users/:id. No parameterization or input validation exists
between the route handler (line 38) and the query execution (line 42).

**Remediation:**

const query = "SELECT * FROM users WHERE id = $1"; await db.execute(query, [req.params.id]);

Severity Classification Criteria

Declare Audit Scope Before Loading

Why

The 1M context window is large but finite. Loading every file without a scope declaration means generated code, test fixtures, and vendor files consume tokens that should go to critical source files.

Rule

Before loading any files, produce a scope declaration that includes: 1. Audit mode (security / architecture / dependency / full) 2. Directory inclusion list 3. File exclusion patterns 4. Estimated token budget vs available budget

Incorrect — audit everything without scoping

## Audit Plan
1. Load all files in the repository
2. Analyze everything
3. Generate report

# Loads everything including generated files
find . -name "*.ts" -o -name "*.js" | xargs cat

Problems:

• Generated files (dist/, plugins/) consume 40%+ of context
• Test fixtures and snapshots add noise
• No priority ordering means entry points may be truncated

Correct — declare scope with budget allocation

## Audit Scope Declaration

**Mode:** Security audit
**Target directories:** src/api/, src/auth/, src/middleware/
**Exclusions:** dist/, node_modules/, *.test.ts, *.spec.ts, __snapshots__/
**Token budget:** ~950K available (1M GA), estimated usage: ~85K (9%)
**Priority order:**
  1. Entry points (src/index.ts, src/app.ts)
  2. Auth boundary (src/auth/*, src/middleware/auth*)
  3. Data access layer (src/db/*, src/repositories/*)
  4. API routes (src/api/*)

# Scoped file discovery with exclusions
find src/api src/auth src/middleware \
  -name "*.ts" \
  ! -name "*.test.ts" \
  ! -name "*.spec.ts" \
  ! -path "*/__snapshots__/*"

Checklist