Related Skills

• security-patterns
• architecture-patterns
• quality-gates

Full-Codebase Audit

Single-pass whole-project analysis leveraging Opus 4.6'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.6: Uses complexity: max for extended thinking across entire codebases. 1M context (beta, Tier 4+) enables cross-file reasoning that chunked approaches miss.

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.

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",
      "options": [
        {"label": "Full audit (Recommended)", "description": "Security + architecture + dependencies in one pass"},
        {"label": "Security audit", "description": "Cross-file vulnerability analysis, data flow tracing, OWASP mapping"},
        {"label": "Architecture review", "description": "Pattern consistency, coupling analysis, dependency violations"},
        {"label": "Dependency audit", "description": "License compliance, CVE checking, version currency"}
      ],
      "multiSelect": false
    },
    {
      "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

CRITICAL: Task Management is MANDATORY

TaskCreate(
  subject="Full-codebase audit",
  description="Single-pass audit using extended context",
  activeForm="Running full-codebase audit"
)

# Phase subtasks
TaskCreate(subject="Estimate token budget and plan loading", activeForm="Estimating token budget")
TaskCreate(subject="Load codebase into context", activeForm="Loading codebase")
TaskCreate(subject="Run audit analysis", activeForm="Analyzing codebase")
TaskCreate(subject="Generate audit report", activeForm="Generating report")

STEP 1: Estimate Token Budget

Before loading files, estimate whether the codebase fits in context.

Run Token Estimation

# Use the estimation script
bash ${CLAUDE_PLUGIN_ROOT}/src/skills/audit-full/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

1. Priority loading: Entry points first, then imported modules
2. Directory scoping: Ask user to narrow to specific directories
3. Fallback: Recommend /ork:verify for chunked multi-agent approach

# Fallback suggestion
AskUserQuestion(
  questions=[{
    "question": "Codebase exceeds context window. How to proceed?",
    "header": "Too large",
    "options": [
      {"label": "Narrow scope", "description": "Audit specific directories only"},
      {"label": "Use /ork:verify instead", "description": "Chunked multi-agent approach (works with any context size)"},
      {"label": "Priority loading", "description": "Load entry points + critical paths only"}
    ],
    "multiSelect": false
  }]
)

STEP 2: Load Codebase into Context

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

STEP 3: Audit Analysis

With codebase loaded, perform the selected audit mode(s).

Security Audit

See 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

See 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

See 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

STEP 4: Generate Report

Use the report template from assets/audit-report-template.md.

Report Structure

# 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

See assets/severity-matrix.md for classification criteria.

Completion Checklist

Before finalizing the report, verify with checklists/audit-completion.md.

When NOT to Use

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 — Chunked multi-agent verification (fallback for large codebases)

References

• Security Audit Guide — Cross-file vulnerability patterns
• Architecture Review Guide — Pattern and coupling analysis
• Dependency Audit Guide — CVE, license, currency checks
• Token Estimation — File type ratios and budget planning
• Audit Report Template — Structured output format
• Severity Matrix — Finding classification criteria
• Audit Completion Checklist — Pre-report verification
• Token Estimation Script — Automated LOC → token estimation

References (4)

Architecture Review Guide

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 ✗

Dependency Audit Guide

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)

Security Audit Guide

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 Estimation

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

Checklists (1)

Audit Completion

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