codebase-audit

name	codebase-audit
description	Audit an inherited or unfamiliar codebase systematically rather than ad-hoc. Covers scope discipline, day-0 triage, SAST and SCA tool recipes (semgrep, CodeQL, gitleaks, trivy), OWASP Top 10 mapped to grep patterns, auth-surface walkthrough, and writing reports that drive remediation. Invoke when inheriting a codebase, accepting an audit engagement, or reviewing AI-generated code before shipping.

Codebase Audit — the Inherited-Code Playbook

This is the skill that binds the others together. Most engagement value from a security review comes from the auditor's process, not from any single check. A junior auditor with a great tool produces a noisy report; a senior auditor with grep and a methodology finds the things that matter.

This skill is the methodology. It walks the audit from "I just got SSH access / a repo URL" through to "here's the prioritized report with owners and deadlines." It cross-links into every hardening skill in this repo as the deep-dive material per finding class.

When to invoke

• Inheriting a codebase — new job, new client, open-source fork, acquisition target
• "Audit my app" engagement — freelancer / consultancy work
• Onboarding to a project — you'll touch the code soon and need to know what's safe to assume
• AI-generated codebase review — before shipping a Claude/Copilot/Cursor-written app
• Periodic re-audit — annual review of a system you already know

Step 0 — Scope before substance

The most common reason audits fail is the auditor trying to look at everything. Scope discipline is the difference between a useful report and a 300-page document nobody reads.

Before starting, write down:

• Why this audit exists — diligence? incident? compliance? onboarding?
• Who reads the report — engineers? CTO? legal? buyer?
• Time budget — 4 hours? 4 days? 4 weeks? This determines depth.
• What's in scope — which repos / services / domains / accounts. Get it confirmed in writing.
• What's explicitly out of scope — third-party SaaS, customer data, anything the client did not authorize. Get this confirmed too.
• Deliverable shape — report? findings spreadsheet? remediation PRs? presentation?

Without these five answers, do not start. Time spent here saves three times that later.

Step 1 — Day-0 triage (the first 30 minutes)

The goal of the first 30 minutes is orientation, not findings. Build a mental model of the system. Findings come later.

# What language(s), what framework(s)?
cd <repo>
ls -la
cat README.md
find . -name 'package.json' -not -path '*/node_modules/*' | head -5
find . -name 'requirements*.txt' -o -name 'pyproject.toml' -o -name 'Gemfile' -o -name 'go.mod' -o -name 'Cargo.toml' 2>/dev/null

Answer in writing (in your notes, not yet the report):

1. Stack — language, framework, DB, cache, queue, deploy target
2. Entry points — what URLs / endpoints does this expose? Background workers? CLIs?
3. Auth story — how do users log in, what session mechanism, are admins separate?
4. Data — what's stored, where (Postgres, Mongo, S3, files on disk, third parties)?
5. Secrets — where are they (env, vault, hardcoded — yes, look)?
6. Deploy — how does code get to production? Who can deploy? CI/CD or manual?
7. Blast radius — if this whole system were compromised tomorrow, what's the worst that happens? Customer data leak? Money lost? Operations halted? Reputation only?

If you cannot answer one of these from a 30-minute look, that's already a finding.

Step 2 — Inventory the surface

Now enumerate everything that matters.

Repositories and branches

git log --oneline | head -20
git log --all --format='%aN' | sort -u           # who has committed
git tag                                          # release cadence
git remote -v                                    # where is it published
ls -la .github/                                  # workflows, codeowners

Routes / endpoints

# Next.js — App Router routes
find app -name 'route.ts' -o -name 'route.js' -o -name 'page.tsx' 2>/dev/null

# Next.js — Pages Router API routes
find pages/api 2>/dev/null

# Express
grep -rE "app\.(get|post|put|delete|patch|use)\(" src 2>/dev/null
grep -rE "router\.(get|post|put|delete|patch)\(" src 2>/dev/null

# Server Actions (Next.js)
grep -rln "'use server'" app 2>/dev/null

# WordPress — REST endpoints
grep -rE "register_rest_route" wp-content/ 2>/dev/null

# OpenAPI / Swagger if present
find . \( -name 'openapi.yaml' -o -name 'openapi.json' -o -name 'swagger.*' \) 2>/dev/null

Build a list of every entry point. For each, you'll later answer "is auth checked? is input validated?"

Dependencies

cat package.json | jq '.dependencies, .devDependencies'
wc -l package-lock.json                          # rough sense of transitive surface
find . -name 'node_modules' -prune -o -name 'package.json' -print | wc -l

Infrastructure-as-code

find . \( -name '*.tf' -o -name 'Dockerfile*' -o -name 'docker-compose*' -o -name 'k8s*.yaml' \) -not -path '*/node_modules/*' 2>/dev/null
ls .github/workflows/ 2>/dev/null

Where data lives

# Database connection strings — environment variables only, never hardcoded
grep -rE 'DATABASE_URL|MONGO_URL|REDIS_URL|postgres://|mongodb://' --include='*.{js,ts,py,rb,go,env,yml,yaml}' . 2>/dev/null | grep -v node_modules

# File storage paths
grep -rE 'multer|formidable|busboy|fs\.write|writeFile|S3|R2|Bucket' --include='*.{js,ts}' . 2>/dev/null | grep -v node_modules | head -20

Step 3 — Tool-assisted scanning

Run automated tools early, parse their output later. The tools give you a haystack of candidates; the manual review (Step 4–6) figures out which are real.

SAST — static code analysis

# Semgrep — fast, language-aware, good default rules
brew install semgrep
semgrep --config=auto --json -o /tmp/semgrep.json . 2>/dev/null
semgrep --config=auto . 2>&1 | grep -E '(WARNING|ERROR|^Findings:|^\s*severity:)' | head -30

# More targeted — security-focused rules only
semgrep --config=p/security-audit --config=p/owasp-top-ten .

# For JavaScript/TypeScript specifically
semgrep --config=p/javascript --config=p/typescript .

# Language-specific
semgrep --config=p/python   # Python — bandit-equivalent rules
semgrep --config=p/php      # PHP including WordPress patterns

Secret scanning

# gitleaks — across history too
brew install gitleaks
gitleaks detect --source . --report-format json --report-path /tmp/gitleaks.json
gitleaks detect --source . --log-opts="--all"   # scan all branches + history

# trufflehog — different ruleset, often catches things gitleaks misses
trufflehog git file://. --json --only-verified > /tmp/trufflehog.json

Dependency / SCA

# npm
npm audit --omit=dev --audit-level=high

# Better — Socket for behavior-level signals
# (https://socket.dev — runs in CI on PRs)

# OSV-Scanner — broader than npm audit
osv-scanner --recursive .

# pip-audit for Python
pip-audit --strict -r requirements.txt

Container scanning

# Trivy — image scanning, IaC scanning, secret scanning
trivy fs --severity HIGH,CRITICAL .
trivy image myapp:latest --severity HIGH,CRITICAL
trivy config .   # Dockerfile + k8s + terraform misconfigs

GitHub CodeQL (if hosted on GitHub)

Enable in repo Settings → Code security → CodeQL analysis. It's free for public repos and worth its quotas for private. The results land in the Security tab; treat them as candidates, not verdicts.

What each tool catches, what it misses

Tool	Catches	Misses
Semgrep	Pattern-shaped vulns (SQL string-concat, unsafe deserialization, missing CSRF)	Logic bugs, broken access control, business-logic issues
Gitleaks	Token-shape secrets in code/history	Custom secret formats, encrypted-at-rest values
npm audit	Known CVEs against pinned versions	Malicious-by-design packages, unreported issues
Socket	Behavior changes (sudden network calls, install scripts)	Pre-existing issues in established packages
Trivy	Image CVEs, misconfigured IaC, secrets in images	Application logic, runtime behavior
CodeQL	Dataflow-level vulns (taint analysis)	Issues outside its rule set, recent CVEs not yet ruled

No tool finds broken access control. That is the single most common high-severity finding in real audits, and it requires manual review. Plan time accordingly.

Step 4 — Manual review — Auth surface

Auth surface is where the highest-impact findings cluster. Walk every entry point and answer:

1. Is auth checked? Server-side, in the handler itself — not just at middleware.
2. Is authorization checked? Auth says "you are X"; authz says "X may do this." They are not the same check.
3. Are object IDs resolved against the requester? GET /invoices/:id must verify the invoice belongs to the requesting user.
4. What happens on auth failure? Generic error (good) or detailed enumeration ("user not found" vs "wrong password" — bad)?
5. Where are session cookies issued? HttpOnly, Secure, SameSite=Lax?
6. Password reset and email change flows? Single-use token, expiring, invalidates sessions on success?

# Find every route + look for the auth check
grep -rEn "app\.(get|post|put|delete|patch)\(['\"]" src | head -40
# Then for each, check the handler for: session lookup, role check, owner check

See auth-hardening for the deep dive and the checklist.

Step 5 — Manual review — Input handling

Every place untrusted input enters the system:

# SQL — anything that concatenates user input
grep -rEn "(\\.query\\(|\\.execute\\(|raw\\().*\\+.*req\\." --include='*.{js,ts,py}' . | head
grep -rEn 'f"SELECT.*\\{|f"INSERT.*\\{' --include='*.py' .

# HTML rendering — anything that dangerouslySetInnerHTML, v-html, .innerHTML
grep -rEn 'dangerouslySetInnerHTML|v-html|\\.innerHTML\\s*=' --include='*.{tsx,jsx,vue,ts,js}' .

# Shell execution
grep -rEn 'child_process|execSync|spawn|popen|os\\.system|subprocess\\.(run|call|Popen)' --include='*.{js,ts,py}' . | head

# Eval and friends
grep -rEn '\\beval\\(|new Function\\(|exec\\(' --include='*.{js,ts,py}' . | head

# File path joining with user input
grep -rEn 'path\\.join.*req\\.|os\\.path\\.join.*request' --include='*.{js,ts,py}' . | head

Every hit is a candidate. Read the surrounding code. Most are fine; some are critical.

Step 6 — OWASP Top 10 mapped to grep recipes

A quick checklist with concrete searches for each Top-10 category (Web Apps, 2021 edition):

A01 — Broken Access Control (most common, hardest to grep)

• Read every handler. Does it check the user owns the resource?
• grep -rEn ":id|:slug" src/routes — every parameterized route is a candidate

A02 — Cryptographic Failures

grep -rEn 'md5|sha1|DES|crypto\.createCipher\b' --include='*.{js,ts,py}' .   # deprecated/weak
grep -rEn 'http://' --include='*.{js,ts,py,html}' . | grep -v 'w3.org\|example\.com\|localhost'

A03 — Injection

• See SQL / shell / HTML grep above
• Plus: grep -rEn 'LDAP|ldap_search' . if LDAP is in scope
• Plus: NoSQL injection patterns — grep -rEn '\$where|\$regex' --include='*.{js,ts}' .

A04 — Insecure Design — by inspection, not grep

A05 — Security Misconfiguration

grep -rEn 'NODE_ENV.*development|DEBUG\s*=\s*True|app\.debug\s*=\s*True' --include='*.{js,ts,py}' .
grep -rE 'cors.*\*|Access-Control-Allow-Origin.*\*' --include='*.{js,ts,py}' .

A06 — Vulnerable and Outdated Components — npm audit, osv-scanner (Step 3)

A07 — Identification and Authentication Failures — auth surface walkthrough (Step 4)

A08 — Software and Data Integrity Failures

• Lockfile present?
• Third-party dependencies pinned?
• Deserialization of untrusted data — grep -rE 'pickle\\.loads|yaml\\.load(\\(|\\s)' .

A09 — Security Logging and Monitoring Failures

• Is there logging at all? See log-strategy.
• Are failures logged? Auth events?

A10 — Server-Side Request Forgery (SSRF)

grep -rEn 'fetch\\(.*req\\.|axios.*req\\.|requests\\.(get|post)\\(.*request' --include='*.{js,ts,py}' . | head

Step 7 — Dependency-surface review

See dependency-supply-chain for the deep workflow. Specifically for audit:

• Is there a lockfile? Is it committed?
• Are direct deps tightly pinned (no caret on critical libs)?
• Any deps with single-digit weekly downloads? Investigate each.
• Any deps with maintainer transferred in the last 90 days?
• Install scripts on transitive deps — enumerate them.
• Has npm audit --audit-level=high been run recently? What does it say?

Step 8 — Infra & deploy review

• Where does code run? VPS, container platform, serverless, Kubernetes?
• Who can deploy? CI service account? Multiple humans?
• Where are production secrets? Env vars at the platform? A secret manager? .env on disk?
• Is there a way for an attacker to influence the build? (Pull-request runs that get prod secrets, etc.)
• Are images / artifacts pinned by SHA?
• What's the rollback story?

See vps-hardening, docker-container-security, github-actions-security, cloudflare-hardening, backend-architecture.

Step 9 — Write the report

The report exists to drive action. Optimize for "can a different engineer fix this in a sprint?"

Per finding

## [CRITICAL] Broken access control on /api/invoices/:id

### Summary
Any authenticated user can read any invoice by ID. No owner check.

### Evidence
- File: src/api/invoices/[id]/route.ts:12
- Reproduction: as user A, fetch /api/invoices/<an id belonging to user B>
  $ curl -H "Cookie: $A_SESSION" https://app.example.com/api/invoices/$B_INVOICE_ID
  → 200 OK with B's data

### Impact
Cross-tenant data exposure. Any logged-in user reads every invoice.

### Remediation
Add owner check in the handler:
  const invoice = await db.invoices.findFirst({ where: { id, userId: session.userId }});
  if (!invoice) return NextResponse.json({ error: 'not found' }, { status: 404 });

### Severity reasoning
CRITICAL — affects all customer data, exploitable by any logged-in user, no
detection in current monitoring.

### Suggested owner: <name>
### Suggested deadline: <date — typically 7 days for critical>

Severity classes

Use a small scale, consistently applied:

• CRITICAL — exploitable without auth, or with low-effort auth, affects all users or money / data integrity
• HIGH — exploitable with some pre-condition (specific user role, specific data), affects sensitive data
• MEDIUM — exploitable but limited blast radius, or requires significant attacker effort
• LOW — defense-in-depth, hygiene improvement, not directly exploitable
• INFO — observation, no action required

Aggressive severity inflation kills the report's usefulness. If everything is HIGH, nothing is HIGH.

Group by severity, then by area

A reader skims for CRITICALs and HIGHs first. Make that easy. Within severity, group by area (auth, data handling, infra) so an owner can take their slice.

Include a one-page summary

Decision-makers read the summary, not the report. Cover:

• How many findings, by severity
• The top 3 to fix this week
• The systemic patterns (e.g. "auth checks are inconsistent across handlers — not a finding-per-handler problem")
• Suggested timeline / sprint allocation

Step 10 — Anti-patterns junior auditors fall into

• Boil the ocean — trying to audit everything in scope to the same depth. Time-box per area; go deep where impact is highest.
• Tool output is the report — pasting npm audit output without synthesis or prioritization. Tool output is candidates, not findings.
• No reproduction steps — "I think this might be vulnerable" is not a finding. Either prove it or downgrade to INFO.
• Severity inflation — calling everything CRITICAL because the auditor wants attention. Kills credibility.
• Wrong audience — writing for engineers when the buyer is the CTO, or vice versa. Match the language.
• No remediation — listing problems without "do this to fix" leaves the recipient stuck.
• Adversarial tone — "the developers clearly did not understand security" is unproductive. Frame as observations + fixes.
• Missing the systemic — listing 30 instances of the same pattern, instead of "this pattern occurs throughout the codebase; fix here is to introduce a shared helper / linter rule."
• Auditing without authorization — never audit a system you do not have written permission for, even if you think you're being helpful.

Step 11 — After delivery

• Walk through the report with the team if possible. A 30-minute call beats a 50-page document for getting buy-in.
• Offer to retest specific findings after fixes — closes the loop.
• Document what's been fixed in the report itself, or in a follow-up appendix.
• Note what's deferred with the reasoning. "Accepted risk: X, until Y date, owner Z" is fine; "ignored" is not.

When you find a critical mid-audit

Stop. Notify the client / stakeholder same-day if the finding affects customer data, money, or trust. Holding a CRITICAL for a final report on Friday when you found it on Monday is itself a finding.

Quick checklist — am I done?

• Scope was agreed in writing
• Day-0 triage notes exist (stack, auth, secrets, data, deploy, blast radius)
• Surface inventory exists (routes, deps, infra)
• SAST/SCA/secret/container scans ran; output triaged
• Auth surface walked manually
• OWASP Top 10 grep recipes run
• Each finding has reproduction, impact, remediation, owner, deadline, severity
• Severity scale was applied consistently
• One-page summary written for decision-makers
• Critical findings communicated to client same-day they were discovered

What this skill will not do

• Help audit a system you do not have written authorization for
• Provide exploitation techniques for findings — the report describes the issue and the fix, not the attack
• Replace a full penetration test for systems where regulatory or contractual obligations require one
• Generate a "your app is secure" certificate — audits find issues; they do not prove absence