security-review-checklist

Security Review Checklist

Goal

Provide a focused, deep security pass over uncommitted changes, checking them against the checklists below: secrets and obvious exposures, application security, authentication and sessions, client-side and browser, data isolation and lifecycle, messaging and background jobs, resource exhaustion, AI and LLM features, supply chain, infrastructure (Terraform/Atmos on AWS), CI/CD and containers, and optionally compliance and data handling. Every finding must name a real trust boundary and a concrete result, checked against the source; anything that depends on a fact the repository cannot show is reported as a lead to validate, not as a vulnerability. This complements local-code-review, which only covers security at a general level. The report lists security issues the developer should address, and suggests scanners to run.

CRITICAL: MANDATORY FIRST STEP

YOU MUST run git diff HEAD as your ABSOLUTE FIRST action before doing ANYTHING else.

• DO NOT attempt to review code from context or memory
• DO NOT skip this step under any circumstances
• DO NOT proceed to the next step without running this command first
• DO NOT assume you know what changed

If you do not run git diff HEAD first, you are failing to follow instructions.

Process

Follow these steps IN ORDER. DO NOT skip any step:

1. STEP 1 - Get Changes via Git (MANDATORY): Run git diff HEAD in the terminal to retrieve ALL uncommitted changes. This is your primary source of truth for what to review. You can read existing files in the current directory for additional context if needed.
2. STEP 2 - Check Scope: If the diff only changes documentation or formatting, output a single line saying there are no security-relevant changes to check, and stop. Otherwise continue - security applies to almost any code or configuration change.
3. STEP 3 - Map The Change: Before checking items, note for the changed code: the entry points it adds or changes (routes, controller actions, GraphQL resolvers, jobs, webhooks, message consumers, LLM tools, workflows, IAM roles); who can reach each one (anonymous user, signed-in user, another tenant, admin, internal service, fork PR); what it protects (data, money, credentials, code execution, deploy or release authority); and the strongest control already on the path (authentication, authorization, tenant scoping, validation, network rules). Read the surrounding files you need for this. Keep it short: it decides which checklists apply and how severe a finding is, and a one-line summary goes in the report's description.
4. STEP 4 - Decide Which Checklists Apply: Apply a checklist only when the diff touches what it covers. One file can trigger several checklists:
   • Secrets & Credentials and Obvious Exposures - always.
   • Application Security - application code (.rb, .erb, .js, .jsx, .ts, .tsx, controllers, routes, config/).
   • Authentication & Sessions - code or config for login, sessions, cookies, tokens, JWT, OAuth/OIDC/SAML, MFA, passkeys, password reset, account linking, API keys, or trusted-proxy and host settings.
   • Client-Side & Browser - browser code that renders HTML, builds URLs or navigation, handles postMessage or WebSockets, or uses browser storage or service workers, and CORS or framing settings.
   • Data Isolation & Lifecycle - models, queries, scopes and policies, migrations, caches and cache keys, search indexes, object storage keys, exports and imports, and deletion, archiving, or restore code.
   • Messaging, Webhooks & Background Jobs - webhook receivers, background jobs, queue or pub/sub producers and consumers, Action Cable channels, and GraphQL or gRPC services.
   • Resource Exhaustion - code that parses, decompresses, or stores untrusted input, regexes on input, pagination and query parameters, fan-out to jobs or downstream calls, and calls to paid APIs.
   • AI & LLM Features - code that builds prompts, calls a model, retrieves context (RAG), stores agent memory, defines or dispatches tools, implements MCP servers or clients, or renders model output.
   • Supply Chain & Dependencies - Gemfile, Gemfile.lock, package.json, JS lockfiles, registry config (.npmrc, .yarnrc.yml), .github/workflows/, Dockerfile, Terraform required_providers or module sources, .terraform.lock.hcl.
   • Infrastructure - .tf, .tfvars, .hcl, atmos.yaml, and Atmos stack files (usually under stacks/). Apply the service-specific items (ECS, Aurora, ElastiCache, SSM) only when that resource type is touched.
   • CI/CD & Containers - .github/workflows/, Dockerfile, compose files, ECS task definitions.
   • Compliance & Data Handling - only when opted in (see STEP 5).
5. STEP 5 - Determine Compliance Scope: Check whether compliance frameworks were requested, either in the message that invoked this skill (for example soc2 gdpr) or in a Compliance: line in the project's AGENTS.md, CLAUDE.md, or README.md. If SOC 2 and/or GDPR are requested, apply the general items plus those framework items in the Compliance & Data Handling checklist. If none are requested but the diff handles personal data, apply only the general items and make no framework claims.
6. STEP 6 - Choose Review Mode: Check the size of the diff with git diff HEAD --shortstat. If it touches more than 15 files or more than 800 changed lines, or the user asked for subagents, use parallel subagents as described in Large Reviews: Parallel Subagents below. Otherwise, or if the user asked not to use subagents, review it yourself in a single pass.
7. STEP 7 - Review And Verify: In parallel mode, the subagents do sub-steps 1-3 and you do 4 after merging; in single-pass mode, you do all four:
   1. Review the changes against the applicable checklists using the Review Method.
   2. Ask the Wildcard Questions for anything the checklists do not name.
   3. Put every candidate from sub-steps 1 and 2 through Verify Before Reporting.
   4. Run Independent Verification once, for any 🟣 or 🔴 findings.
8. STEP 8 - Generate The Report: Generate the report in markdown format. Only report issues that actually appear in the diff. Rate each finding using the Severity Guide. Do not save the report in the filesystem. You should only output to chat.