API Audit

zuvo:api-audit — API and Endpoint Integrity Audit

Standalone audit of how the application exposes, consumes, and validates data across API boundaries. Evaluates endpoints through 10 weighted dimensions, builds an auth matrix, and runs cross-cutting analysis on contract consistency, money field representation, and payload efficiency.

When to use: Periodic health check of the API layer, before major releases, after adding new endpoints, when investigating overfetching or waterfall issues. Out of scope: Single-file code review (use zuvo:review), refactoring (use zuvo:refactor), security posture analysis (use zuvo:security-audit), feature development (use zuvo:build).

Argument Parsing

Mandatory File Loading

Read these files from disk before starting. Print the checklist. Do not proceed from memory.

CORE FILES LOADED:
  1. ../../rules/cq-checklist.md            -- READ/MISSING
  2. ../../rules/security.md                -- READ/MISSING
  3. ../../shared/includes/env-compat.md    -- READ/MISSING
  4. ../../shared/includes/codesift-setup.md -- READ/MISSING
  5. ../../shared/includes/run-logger.md    -- READ/MISSING
  6. ../../shared/includes/retrospective.md    -- READ/MISSING

If any file is missing: Stop. The audit requires the full rule set to score correctly.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking.

CodeSift Integration

Read ../../shared/includes/codesift-setup.md for the full initialization sequence.

Summary: Run the CodeSift setup from codesift-setup.md at skill start. Use CodeSift tools for endpoint discovery and handler inspection when available. If unavailable, fall back to grep/find scripts.

CodeSift Optimizations

Degraded Mode (CodeSift unavailable)

All endpoint discovery falls back to grep/find scripts (Phase 0.3). Handler analysis requires full file reads. Auth chain verification loses transitive analysis (only direct callers visible).

Safety Gates (NON-NEGOTIABLE)

GATE 1 -- HTTP Request Policy

Default (no environment confirmed): treat as production. REFUSE all requests until user clarifies.

GATE 2 -- PII and Credential Censorship

When logging API responses, headers, or payloads:

• Replace Bearer tokens: Bearer ***
• Replace API keys: x-api-key: ***
• Replace emails: ***@***.***
• Replace passwords: ***
• Strip AWS signatures, session tokens, cookies

All output files and reports must be scrubbed before writing.

GATE 3 -- Script Execution

Discovery scripts >20 lines MUST be saved to file first, then chmod +x, then executed. No pasting long scripts into the terminal.

CQ Integration

This audit extends (not duplicates) the CQ checklist:

If zuvo:review already scored these CQs, focus on what CQ self-eval misses: cross-endpoint consistency, client-side waterfall patterns, caching strategy, and system-wide contract drift.

Phase 0: Detection and Scope

0.1 Stack Detection

Save as script, chmod +x, execute:

#!/bin/bash
set -euo pipefail
SRC="${1:-.}"
echo "=== API STACK DETECTION ==="
NEST_CTRL=$(find "$SRC" -name "*.controller.ts" 2>/dev/null | wc -l)
[ "$NEST_CTRL" -gt 0 ] && echo "NestJS: $NEST_CTRL controllers"
WRANGLER=$(find "$SRC" -name "wrangler.toml" 2>/dev/null | wc -l)
[ "$WRANGLER" -gt 0 ] && echo "Cloudflare Workers: $WRANGLER configs"
FASTAPI=$(grep -rl "APIRouter\|FastAPI()" "$SRC" --include="*.py" 2>/dev/null | wc -l || true)
[ "$FASTAPI" -gt 0 ] && echo "FastAPI: $FASTAPI routers"
REACT_QUERY=$(grep -rl "useQuery\|useMutation" "$SRC" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l || true)
[ "$REACT_QUERY" -gt 0 ] && echo "React Query: $REACT_QUERY files"
RAW_FETCH=$(grep -rl "fetch(\|axios\." "$SRC" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l || true)
[ "$RAW_FETCH" -gt 0 ] && echo "Raw fetch/axios: $RAW_FETCH files"
ZOD=$(grep -rl "z\.object\|z\.string" "$SRC" --include="*.ts" 2>/dev/null | wc -l || true)
CLASS_VAL=$(grep -rl "@IsString\|@IsNotEmpty\|ValidationPipe" "$SRC" --include="*.ts" 2>/dev/null | wc -l || true)
echo "Validation: Zod=$ZOD, ClassValidator=$CLASS_VAL"
echo "=== DETECTION COMPLETE ==="

0.2 Tier Selection

Risk signals that force DEEP tier:

• Payment/money endpoints
• Auth/permission endpoints
• Multi-tenant data isolation
• External API integrations
• File upload/download endpoints

0.3 Endpoint Inventory

Build a complete endpoint list before auditing.

When CodeSift is available: get_file_tree(repo, name_pattern="route.ts") + get_file_outline per route file. Use search_text(repo, query="@Get|@Post|@Put|@Delete", regex=true) for NestJS.

When unavailable, per stack:

NestJS: grep -rn "@Get\|@Post\|@Put\|@Patch\|@Delete" --include="*.controller.ts" Workers: grep -rn "request.method\|router\.\(get\|post\)" --include="*.ts" FastAPI: grep -rn "@router\.\(get\|post\|put\|patch\|delete\)" --include="*.py" Frontend: grep -rn "useQuery\|useMutation\|fetch(\|axios\." --include="*.ts" --include="*.tsx"

Discovery must return ALL results. No truncation via head -N. If output exceeds 200 lines, save to audits/artifacts/endpoints-raw.txt.

OpenAPI layer: If an OpenAPI/Swagger spec exists, use it as primary inventory. Grep-based discovery becomes the fallback. Endpoints found by grep but missing from spec = undocumented (flag for D10).

Completeness check: Cross-check grep results against module imports/exports, Swagger spec if present, and test files hitting unlisted endpoints.

Output:

ENDPOINT INVENTORY
Stack: [detected]
Tier: [LIGHT/STANDARD/DEEP]
Total endpoints: [N]
Risk signals: [list or "none"]
Completeness: [high/medium]

Phase 1: Dimension Analysis (D1-D11)

For EACH dimension, evaluate all endpoints in scope and assign a score.

D11 activation: Only if OpenAPI spec exists. If no spec -> D11=N/A.

N/A-aware scoring: Dimensions not applicable to the tier or codebase context are excluded from both score sum and max denominator.

max = sum of weights for all non-N/A dimensions
score = sum of dimension scores
percentage = score / max x 100

Evidence ratio scoring: For each dimension, compute violating_endpoints / eligible_endpoints:

Always report ratio alongside score: D1: 11/15 (3/18 endpoints lack validation = 17%).

Health grades:

• = 80%: HEALTHY

• 60-79%: NEEDS ATTENTION
• 40-59%: AT RISK
• < 40%: CRITICAL

Critical gate: D9<8 (auth gaps on mutations), D1=0 (no validation), D3<3 with >10K records, D11=0 (critical breaking change) -> auto-fail regardless of total.

Execution

Split endpoints into batches by controller/module. Each batch covers one controller and all its endpoints.

Parallel (Claude Code with Task tool): spawn one agent per batch, max 6 concurrent. Sequential (Cursor, Codex, no Task tool): evaluate one batch at a time inline.

Each Task agent dispatch:

Agent: API Dimension Auditor (per batch)
  model: "sonnet"
  type: "Explore"
  instructions: evaluate endpoints in batch against D1-D11 dimensions
  input: batch endpoint list (one controller/module), detected stack, CODESIFT_AVAILABLE

Phase 2: GET-Only Probing (STANDARD+ tier)

Skip if: --static flag set, or LIGHT tier, or no running server.

Prerequisites (HARD GATE)

All variables must be confirmed before any HTTP request:

Environment gate:

1. User confirms target (localhost/staging/sandbox)
2. Production domains -> REFUSE
3. Auth token from user (never auto-extract from code)

Probing Protocol

For each list endpoint:

CURL_OPTS="--connect-timeout 5 --max-time 15 --retry 2 --retry-delay 1 --fail-with-body"

curl -s -w "\n%{size_download} %{http_code} %{time_total}" $CURL_OPTS \
  -H "Authorization: Bearer $TOKEN" "$BASE_URL$ENDPOINT?limit=10"

curl -s -I $CURL_OPTS -H "Authorization: Bearer $TOKEN" "$BASE_URL$ENDPOINT" | \
  grep -i "cache-control\|etag\|vary\|x-ratelimit\|content-type"

Rate limiting: Max 5 req/s. 3 consecutive 429s -> pause 30s, resume at 2 RPS. 3 consecutive 5xx -> STOP, report "target unhealthy".

Scrub ALL responses before recording (Gate 2).

Phase 3: Cross-Cutting Analysis (STANDARD+ tier)

3.1 Contract Consistency

• Same entity from different endpoints -- identical shape?
• Frontend expects field X, backend returns field Y?
• Pagination format consistent across list endpoints?
• Error shape consistent across stacks?

3.2 Money Field Audit

• List ALL fields with money values across all endpoints
• Same representation everywhere (number OR integer-cents, never both)?
• Currency always travels with amount (never implicit)?

3.3 Auth Matrix

Build endpoint x role matrix:

| Endpoint | Public | User | Admin | Manager | Evidence |

3.4 Payload Size Analysis (if probing done)

• Flag endpoints returning >100KB for list views
• Flag nested relations >3 levels deep
• Flag dual fields in responses (*_id + *_name for same entity)

Phase 4: Report

Save to: audits/api-audit-[date].md

REQUIRED: emit the Tool Availability Block (template in ../../shared/includes/codesift-setup.md) at the top of the report, after the title and before findings. Auditing degraded runs depends on this — do NOT skip it.

# API and Endpoint Integrity Audit

## Metadata
| Field | Value |
|-------|-------|
| Project | {name} |
| Date | {date} |
| Tier | {LIGHT/STANDARD/DEEP} |
| Stacks | {detected} |
| Total Endpoints | {N} |
| Probing | {Static only / Static + GET on {env}} |

## Score Summary

| Dimension | Score | Max |
|-----------|-------|-----|
| D1. Input Validation | {X} | 15 |
| D2. Payload Efficiency | {X} | 15 |
| D3. Pagination | {X} | 12 |
| D4. Error Standardization | {X} | 12 |
| D5. Caching | {X} | 8 |
| D6. HTTP Semantics | {X} | 8 |
| D7. API Waterfall | {X} | 5 |
| D8. Rate Limiting | {X} | 5 |
| D9. Auth | {X} | 15 |
| D10. Documentation | {X} | 5 |
| D11. Contract Stability | {X or N/A} | 5 |
| **TOTAL** | **{X}** | **{max}** | **{grade} ({%})** |

## Critical Findings
## All Findings (by dimension)
## Cross-Cutting Analysis
## Recommendations (top 5 by effort + impact)
## CQ Overlap

Issue Format

### API-{N}: {Title}
Dimension: D{X} -- {name}
Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: {X}/100
Endpoint: {METHOD} {path}
Stack: {NestJS/Worker/FastAPI/Frontend}
File: {path} -> {handler}()
Evidence: {code quote or response excerpt, max 15 lines, SCRUBBED}
Problem: {specific}
Impact: {user/security/performance}
Fix: {complete code for MEDIUM+}
CQ Overlap: {CQ IDs or "none -- cross-endpoint only"}

Phase 5: Backlog Persistence

Default: off. Activate with --persist-backlog flag or explicit user request.

When active, persist findings (confidence 26+) to memory/backlog.md:

1. Read memory/backlog.md. If missing, create with template.
2. Fingerprint: file|dimension|endpoint-signature. Dedup: existing = increment Seen.
3. Delete resolved items. Confidence 0-25 = DISCARD.

Full protocol: ../../shared/includes/backlog-protocol.md.

Phase 6: Next-Action Routing

Phase 6b: Adversarial Review on Audit Report (MANDATORY — do NOT skip)

After the audit report is generated, run cross-model validation to catch score inflation and gate inconsistency.

adversarial-review --mode audit --files "[audit report path]"

If adversarial-review is not in PATH: ~/.claude/plugins/cache/zuvo-marketplace/zuvo/*/scripts/adversarial-review.sh

Wait for complete output. Then:

• CRITICAL (FAIL gate not in verdict, severity mismatch) → fix in report before delivery
• WARNING (N/A abuse, skipped check) → append to Known Gaps section
• INFO → ignore

Completion Gate Check

Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.

COMPLETION GATE CHECK
[ ] Endpoint inventory printed with total count
[ ] Auth matrix built: every endpoint classified
[ ] Adversarial review ran on audit report
[ ] Cross-cutting analysis ran
[ ] Report saved to audits/
[ ] Run: line printed and appended to log

API-AUDIT COMPLETE

Score: [N] / [max] -- [grade] Tier: [LIGHT/STANDARD/DEEP] Dimensions: [N scored] | Critical gates: [PASS/FAIL] Findings: [N critical] / [N total] Run: api-audit - -dimensions

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

After printing this block, append the Run: line value (without the Run: prefix) to the log file path resolved per run-logger.md.

VERDICT: PASS (0 critical findings), WARN (1-3 critical), FAIL (4+ critical).

Execution Notes

• Use Sonnet for LIGHT/STANDARD tiers
• Use Opus for DEEP tier
• Process controllers sequentially. Claude Code may parallelize with up to 6 Task agents.
• Read the project's AGENTS.md or CLAUDE.md first for stack-specific conventions
• Estimated durations: LIGHT ~3-5 min, STANDARD ~8-10 min, DEEP ~15-20 min