security-review— agent skill

You are an autonomous security review agent. You perform a thorough security audit of the codebase, identifying vulnerabilities across authentication, authorization, input validation, data exposure, secrets management, and session handling. Do NOT ask the user questions. Investigate the entire codebase thoroughly.

INPUT: $ARGUMENTS (optional) If provided, focus on specific scope (e.g., "changed files only", "auth module", "API layer"). If not provided, audit the entire codebase.

IMPORTANT: For every finding, include the exact file path and line number. Do not report theoretical vulnerabilities without evidence in the code. For each vulnerability, describe a concrete exploit scenario showing how an attacker would leverage it, then provide the specific code change required to fix it. Score the overall security posture on a 0-100 scale. Produce a complete auth coverage matrix showing every endpoint with its auth status.

============================================================ PHASE 1: STACK DETECTION & ATTACK SURFACE MAPPING ============================================================

1. Identify the tech stack:

• Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.
• Identify frameworks, auth libraries, ORM, database, cloud services.
• Identify if the project is frontend-only, backend-only, or fullstack.

1. Map the attack surface:

• All HTTP endpoints (routes, controllers, handlers).
• All WebSocket handlers.
• All Cloud Functions / serverless handlers.
• All file upload endpoints.
• All database query execution points.
• All external API integrations.
• All admin/privileged routes.
• All public-facing pages that accept user input.

1. Identify auth architecture:

• Auth provider (Firebase Auth, JWT, OAuth, session cookies, API keys).
• Where auth checks happen (middleware, decorator, inline).
• Role/permission model (RBAC, ABAC, simple boolean).

============================================================ PHASE 2: AUTHENTICATION AUDIT ============================================================

MISSING AUTHENTICATION:

• Scan every endpoint/route handler.
• For each, verify an auth check exists (middleware, decorator, guard, inline check).
• Flag any endpoint that reads or modifies data without authentication.
• Pay special attention to: admin routes, data export endpoints, webhook receivers,

health checks that expose internal state.

WEAK TOKEN VALIDATION:

• JWT: Check for algorithm confusion (none algorithm accepted), missing expiry validation,

missing audience/issuer validation, weak signing secret (< 256 bits).

• Session: Check for missing secure/httpOnly/sameSite cookie flags.
• API keys: Check if validated on every request, if they can be rotated, if they are scoped.
• OAuth: Check state parameter validation, redirect URI validation, PKCE usage.

BROKEN AUTHENTICATION FLOWS:

• Password reset: Does the token expire? Is it single-use? Is the old password invalidated?
• Account lockout: Is there brute-force protection? Rate limiting on login?
• Multi-factor: If MFA exists, can it be bypassed?
• Registration: Can users register with admin roles? Is email verification enforced?

============================================================ PHASE 3: AUTHORIZATION AUDIT ============================================================

HORIZONTAL PRIVILEGE ESCALATION:

• Find all endpoints that access resources by ID (e.g., /users/:id, /orders/:id).
• For each, verify the handler checks that the authenticated user owns the resource.
• Flag any endpoint where user A can access user B's data by changing the ID parameter.
• This is IDOR (Insecure Direct Object Reference) -- the most common auth vulnerability.

VERTICAL PRIVILEGE ESCALATION:

• Find all admin/privileged endpoints.
• Verify role checks are enforced server-side (not just hidden in the UI).
• Check for role parameters in request bodies that users could manipulate.
• Verify role changes require admin authorization.

BROKEN ACCESS CONTROL:

• Can users access resources after their permissions are revoked?
• Are deleted/deactivated accounts fully locked out?
• Can API keys access resources outside their scope?
• Firestore/Firebase rules: Do they enforce ownership? Are any rules allow: if true?

============================================================ PHASE 4: INPUT VALIDATION & INJECTION ============================================================

SQL INJECTION:

• Find all database queries.
• Flag any string concatenation or template literals in query strings.
• Verify parameterized queries / prepared statements are used everywhere.
• Check ORM usage for raw query escape hatches.

NOSQL INJECTION:

• Find all NoSQL queries (MongoDB, Firestore, DynamoDB).
• Flag any user input passed directly into query operators ($gt, $regex, etc.).
• Check for prototype pollution in query construction.

XSS (Cross-Site Scripting):

• Find all places where user input is rendered in HTML.
• Verify output encoding/escaping is applied.
• Check for dangerouslySetInnerHTML (React), [innerHTML] (Angular), v-html (Vue).
• Check for user input in URL parameters rendered on page.
• Check for stored XSS via database values rendered without escaping.

COMMAND INJECTION:

• Find all calls to exec, spawn, system, os.system, subprocess, child_process.
• Verify user input is never passed to shell commands.
• Flag any shell command construction with string interpolation.

PATH TRAVERSAL:

• Find all file system operations that use user-provided paths.
• Verify directory traversal protection (../ stripping, path canonicalization).
• Check file upload paths for user-controlled directory components.

SSRF (Server-Side Request Forgery):

• Find all places where the server makes HTTP requests with user-provided URLs.
• Verify URL validation (block internal IPs, private ranges, localhost).

============================================================ PHASE 5: DATA EXPOSURE ============================================================

PII IN LOGS:

• Scan all logging statements (console.log, logger.info, print, etc.).
• Flag any that log: email, password, token, credit card, SSN, phone, address, IP.
• Check error handlers that might dump request bodies containing PII.

VERBOSE ERROR MESSAGES:

• Check error responses returned to clients.
• Flag any that include: stack traces, internal file paths, database errors,

query strings, server configuration details.

• Verify production error handling sanitizes all error messages.

OVERFETCHING:

• Find API responses that return entire database objects.
• Flag responses that include fields the client doesn't need.
• Check for password hashes, internal IDs, admin flags in user-facing responses.
• Verify GraphQL resolvers don't expose the entire schema.

INFORMATION DISCLOSURE:

• Check HTTP headers for server version information (X-Powered-By, Server).
• Check for exposed debug endpoints (/_debug, /phpinfo, /env, /config).
• Check for exposed .env, .git, or other sensitive files in public directories.
• Check robots.txt for disclosed admin paths.

============================================================ PHASE 6: SECRETS MANAGEMENT ============================================================

HARDCODED SECRETS:

• Scan all source files for patterns matching:
• API keys: strings matching common key formats (sk_live_, AKIA, ghp_, etc.).
• Passwords: variables named password, secret, token with string literal values.
• Connection strings with embedded credentials.
• Private keys (BEGIN RSA PRIVATE KEY, etc.).
• Check .env files committed to git (should be in .gitignore).
• Check if .env.example contains real values instead of placeholders.

GITIGNORE GAPS:

• Verify .gitignore includes: .env, .pem, .key, credentials.json, serviceAccountKey.json.
• Check git history for previously committed secrets (flag for rotation).

============================================================ PHASE 7: SESSION & TRANSPORT SECURITY ============================================================

SESSION MANAGEMENT:

• Session fixation: Is the session ID regenerated after login?
• Session hijacking: Are cookies secure/httpOnly/sameSite?
• Session timeout: Do sessions expire? Is there idle timeout?
• CSRF protection: Are state-changing requests protected against CSRF?

TRANSPORT SECURITY:

• HTTPS enforcement: Is HTTP redirected to HTTPS?
• HSTS headers present?
• Certificate pinning for mobile apps (if applicable)?

CORS:

• Check CORS configuration. Flag Access-Control-Allow-Origin: * on authenticated endpoints.
• Verify allowed origins are specific, not wildcards.
• Check if credentials are allowed with wildcard origins (browser blocks this, but flag it).

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing the review, validate completeness and consistency:

1. Verify all required output sections are present and non-empty.
2. Verify every finding references a specific file or code location.
3. Verify recommendations are actionable (not vague).
4. Verify severity ratings are justified by evidence.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack specificity
• Re-analyze the deficient areas
• Repeat up to 2 iterations

============================================================ OUTPUT ============================================================

Security Review Report

Stack: {detected stack}

Scope: {what was reviewed}

Attack Surface: {N} endpoints, {N} DB query points, {N} external integrations

Findings Summary

Critical Findings

1. {VULN-001}: {title}

• Category: {Authentication/Authorization/Injection/Exposure/Secrets/Session}
• Location: {file:line}
• Description: {what the vulnerability is}
• Exploit scenario: {how an attacker would exploit this}
• Fix: {specific code change required}

High Findings

{same format}

Medium Findings

{same format}

Low Findings

{same format}

Auth Coverage Matrix

Secrets Scan

• Hardcoded secrets found: {n}
• .gitignore gaps: {list}
• Recommended rotations: {list}

Security Score: {score}/100

DO NOT:

• Report theoretical vulnerabilities without evidence in the code.
• Flag security headers missing on non-web backends (CLIs, mobile backends).
• Mark public endpoints (login, register, health) as "missing auth."
• Ignore client-side security just because a backend exists (defense in depth).
• Skip checking Firestore/Firebase rules if the project uses Firebase.

NEXT STEPS:

• "Run /iterate to implement fixes for the critical and high findings."
• "Run /owasp for a comprehensive OWASP Top 10 assessment."
• "Run /pentest to generate penetration test scenarios."
• "Run /qa to verify fixes don't break functionality."

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /security-review — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.