AGENTS.md — Backend Security Audit Skill

This file tells any AI coding agent (Claude Code, Cursor, Windsurf, Antigravity, Cline, or any agent-based IDE) how to behave when the backend-security-audit skill is active. Read it together with SKILL.md.

Scope: The backend / server / API of a web or mobile app — secrets, databases, auth, authorization, payments, PII, and production hardening. This is an audit-fix-verify skill and is not a replacement for professional penetration testing.

Core Behavior When This Skill Is Active

1. Find the real, exploitable weakness — don't blindly bolt on controls. Every fix must trace to a concrete, named risk (a hardcoded key, a route with no ownership check, a client-trusted price, a raw SQL concat). Don't add security middleware "for coverage" if it breaks the app or doesn't address a real hole.
2. Never print a discovered secret's value. Report the location (file:line) and type (e.g. "Stripe secret key"), redacted. If a secret is exposed or lives in git history, tell the user to rotate it immediately — moving it to an env var does not un-leak it.
3. Separate Confirmed from Potential. Label each finding Confirmed (you saw the exploitable code path) or Potential (needs verification). Do not inflate uncertain findings into confirmed vulnerabilities.
4. Never claim the app is "secure." State what was checked, what was fixed, and what still needs human review. For apps handling real money or sensitive PII at scale, explicitly recommend a professional security review before launch.
5. Verify fixes — don't assume. Re-read the fixed code path, and re-run tools where available (gitleaks, npm audit, semgrep, bearer, plus typecheck/lint/tests). Mark anything you couldn't run as "unverified until run" with the exact command.
6. Do no harm during the audit. Do not exfiltrate data, call third-party or production systems, run destructive commands, or weaken/remove existing security controls to "make it work." Read and analyze; only edit to fix.
7. Make surgical, behavior-preserving edits. Move secrets to env, add ownership/role checks, parameterize queries, verify webhook signatures, scrub logs, add rate limits/headers/CORS, remove debug endpoints, add startup env validation. Match project conventions. Call out any change that alters product behavior.

Files To Read Before Editing

package.json | lockfile | tsconfig.json
.env* | .env.example | .gitignore
next.config.* | vercel.json | netlify.toml | Dockerfile
src/** app/** pages/api/** server/** api/** functions/** routes/** controllers/**
middleware.ts | auth/** | guards | session/JWT helpers
prisma/schema.prisma | migrations | model files | raw query call sites
supabase/** (RLS policies) | firestore.rules | storage.rules
webhook handlers (payments, auth providers)
logging / error-handling setup

Audit Order (Always)

1. Understand the app + risk: does it handle MONEY or sensitive PII? framework, DB, auth, payments.
2. Secrets & credentials         (scan code AND git history; never print values)
3. PII data flow                 (logs, third-party payloads, deletion path)
4. Passwords & sessions          (bcrypt/argon2; httpOnly cookies, not localStorage)
5. Authentication                (JWT signing/expiry/alg-pin, reset tokens, rate limits, no default admin)
6. Authorization & IDOR          (ownership on every ID; server-side role checks; tenant scoping)
7. Input & injection             (parameterized queries, XSS, command, file uploads, validation)
8. Payments & business logic     (server-side totals, webhook signatures, abuse vectors, idempotency)
9. API / transport / errors      (CORS, helmet/security headers, generic errors + correlation ID, TLS)
10. Production hardening          (debug/test endpoints, env fail-fast, DB security, npm audit)
11. Attacker's-perspective pass   (ID tampering, login bypass, priv-esc, abuse, injection, internal exposure)
12. Fix plan → safe fixes → verify → client-ready report (SKILL.md Output Format).

Present the fix plan before editing. Do the attacker's pass last.

Tool / Environment Specific Guidance

• Claude Code: Read/Grep files before editing. Run gitleaks, npm audit, semgrep, bearer, typecheck, lint, test via Bash so the report's Verification section is real. Use plan-first (EnterPlanMode) before broad changes.
• Cursor / Windsurf / Antigravity / Cline: Open and read every file in "Files To Read" before proposing edits. Present a diff plus the verification commands in the same response. Use the matching file in prompts/.
• Agents without shell access: Produce exact edits + copy-paste scan/verify commands, and mark results "needs user verification."

Hard Rules (Do Not Violate)

• Do not print a discovered secret's value; report location/type redacted and recommend rotation.
• Do not claim the app is "secure"; report what was checked/fixed and what needs human review.
• Do not present uncertain findings as confirmed; label Confirmed vs Potential.
• Do not weaken or remove existing security controls to make something work.
• Do not exfiltrate data, hit third-party/production systems, or run destructive commands during the audit.
• Do not change auth/payment/data behavior in ways that alter product behavior without calling it out.
• Do not add heavy security libraries without a clear reason and a trade-off note.
• Do proceed with best-practice assumptions when info is sufficient; ask only blocking questions.
• Do recommend a professional human security review for apps handling real money or sensitive PII at scale.

Definition of Done

Complete only when:

• The audit ran through all ten areas plus the attacker's-perspective pass, in order, and
• Findings are labeled with severity and Confirmed/Potential status, with no secret values printed, and
• Fixes are surgical, behavior-preserving, and verified (tools re-run where possible, or flagged "unverified until run"), and
• The report includes Summary, Issues Found, Fixes Applied, Files Changed, Verification, Secrets To Rotate, Remaining Risks, and Next Steps — is client-ready, and recommends human review where warranted.