AGENTS.md — Secure code review

Read every change the way an attacker would, so injection, broken access control and leaked secrets are caught before merge instead of after an incident.

How to do it

1. Map what changed and what it touches — List the new or changed entry points (routes, handlers, queue consumers, CLI flags, webhooks) and the sinks they reach (SQL, shell, file system, HTML output, outbound HTTP, deserialisers). Write the list in the review comment; anything not on it is out of scope.
2. Trace untrusted input to every sink — For each entry point, follow request bodies, headers, query strings, cookies and uploaded files to each sink. Confirm the input is validated against an allow-list schema on the server and that each sink uses a safe API: parameterised queries, argument arrays instead of shell strings, context-aware output encoding, and safe deserialisers.
3. Check authentication and authorisation on every action — For each handler, find the line that proves who the caller is and the line that proves they may act on this specific record (object-level check, not just role). Missing either is a blocking finding. Confirm the default is deny when no rule matches.
4. Inspect outbound requests for SSRF — Any URL, host or redirect target that a user can influence must be resolved and checked against an allow-list of hosts and schemes before the request is made; block private, loopback and link-local ranges and metadata addresses, and disable automatic redirects or re-check each hop.
5. Look for secrets and sensitive data — Search the diff for keys, tokens, passwords, connection strings and private keys, including in tests, fixtures and config. Confirm secrets come from the environment or a secret store and that tokens, passwords and personal data are not written to logs, error messages or analytics.
6. Review new and upgraded dependencies — For each added or bumped package, check the audit output, maintenance activity and install scripts, and confirm the lockfile changed in the same commit. Question any dependency that replaces a few lines of code.
7. Record findings with severity and a fix — Write each finding as: location, what an attacker can do, severity (critical, high, medium, low), and the concrete fix. Block merge on critical and high; open tracked issues for the rest.
8. Verify fixes with a failing test — For every blocking finding, ask for a test that reproduces the exploit input (for example a second user reading the first user's record) and fails before the fix and passes after.

Checklist (before a pull request)

• Every new entry point and sink is listed in the review
• All server-side input is validated against an allow-list schema
• Every query, shell call and template uses a parameterised or encoding API
• Each protected action has an authentication check and an object-level authorisation check
• User-influenced outbound URLs are checked against a host allow-list with private ranges blocked
• No secrets or personal data appear in code, fixtures, logs or error responses
• Dependency audit shows no new high or critical findings
• Each blocking finding has a regression test

Rules

• Treat every value from outside the process as hostile until a server-side schema has accepted it, including headers, cookies and data from your own other services. (Trust boundaries move; validation at the point of use is the one that cannot be bypassed.)
• Never build SQL, shell commands, file paths or HTML by string concatenation with untrusted values. (Concatenation is the root of injection; safe APIs remove the whole class.)
• Check authorisation against the specific record being read or changed, not only the caller's role. (Broken object-level access is the most common way one user reads another user's data.)
• Return generic error messages to clients and log the detail server-side without secrets or tokens. (Stack traces and verbose errors hand attackers a map of the system.)
• Fail closed: when a permission lookup, signature check or token parse throws, deny the request. (Exceptions that fall through to success turn outages into breaches.)

Checks

Generated from the Celestial engineering practice “Secure code review”.