Security audit for your web app before launch

Security review checklist

Goal: a written review that someone else can check. Every finding has an id, a severity, where it lives, what it lets an attacker do, the fix, and how the fix was verified.

This skill reads code and runs safe, signed-out checks. It does not change application code. It writes only to docs/security-review/. Fixes are a separate change the owner approves.

1. Set the scope

1. Ask what is in scope: web app, API, OAuth or SSO, MCP connector, CLI, background jobs, file upload or install paths, CI.
2. Ask which hosts you may probe live, and confirm you will only use signed-out requests unless the owner gives you a test account.
3. Ask for the date of the last review, if any, so you can mark what is new.

2. Write the architecture notes

Create docs/security-review/architecture.md:

• Components: each deployable piece and what it talks to.
• Identities and credentials: session cookies, personal tokens, OAuth access and refresh tokens, device codes, signing keys, service keys. For each: where it is stored, how long it lives, how it is revoked.
• Data flows: sign-in, sign-up, publish or upload, install or download, export, delete. One short numbered flow each.
• Trust boundaries: every place data from one party reaches code or users of another party.

3. Write the threat model

Create docs/security-review/threat-model.md:

1. Who attacks: for example a malicious uploader, an outsider after accounts, a phisher using your OAuth or device flow, someone burning your budget, a compromised provider or key.
2. What you protect, in order: for example users' machines, integrity of published content, accounts and tokens, private data, availability and spend.
3. A STRIDE table per component (Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege). Columns: threat, what stops it today, risk left.

4. Review, split by area

Do the signed-out live checks yourself. Split the code review into separate passes so each one stays focused. If you can run parallel agents, give each one area and the checklist for that area, and merge their findings.

• Pass A: API, auth, OAuth, SSO, accounts.
• Pass B: paid and private content, sharing, diffs, clones.
• Pass C: upload, scanning, signing, install, CLI, connector.
• Pass D: UI flows that touch auth or money (double submits, lost state, misleading errors).

For each item below, record "fine" with one line of evidence, or open a finding.

Live checks, signed out

• [ ] Security headers on pages: CSP, frame-ancestors or X-Frame-Options, HSTS, nosniff. Consent, approval, token, and delete pages must not be frameable.
• [ ] Every write endpoint refuses a request with no credentials, and refuses a cookie request from another origin.
• [ ] Error bodies do not echo request content, stack traces, or internal messages.
• [ ] OAuth metadata, registration, and authorize endpoints reject bad redirects, missing PKCE, and unknown resources.
• [ ] Unlisted or private paths return the same answer as missing ones.

Auth, sessions, and tokens

• [ ] Session tokens are long, random, hashed at rest, HttpOnly, Secure, SameSite. A new token on every sign-in. Deleted on sign-out and account deletion.
• [ ] Token scopes are checked per route. A narrow scope (for example read-only, or a third-party connector token) cannot reach export, member management, or other sensitive writes.
• [ ] Destructive account actions (delete account, remove members, withdraw invitations, revoke all) need a browser session and a confirmation, not just any bearer token.
• [ ] Revoking an access token also revokes the refresh token family behind it.
• [ ] Token checks tell an outage apart from a bad token. A timeout or 5xx from the auth backend must not be cached or reported as "invalid token, reconnect". Calls to the backend have timeouts.
• [ ] Caches of token checks are short, and the delay before a revoke takes effect is written down.

OAuth, device flow, and SSO

• [ ] PKCE S256 required. Codes single use and bound to client, redirect, and resource. Exact redirect match.
• [ ] Refresh tokens rotate, and reuse revokes the family.
• [ ] The consent page shows where the code will be sent, not only the client's self-declared name.
• [ ] Device flow: codes hashed, approval consumed once, the approval page warns that the user should only approve a code they started.
• [ ] SSO never auto-accepts invitations in the callback. It only signs in or links an existing member, with a confirm step for linking.
• [ ] SSO refuses public mail domains, and only trusts a domain the org has proven it owns.
• [ ] SSO start is not a state-changing GET that a third-party page can trigger (login CSRF).

Paid and private content

• [ ] Paid or private files never leak through a side door: diffs, suggestions, comparison views, clones, forks, exports, previews, search snippets, or error messages.
• [ ] Unlisted content gets the same copy and access checks as public content.
• [ ] Saving a private copy as public or unlisted runs the full publish path, including checks.
• [ ] Download links are short lived, bound to one object, and stop working after a takedown or a revoke within a known time.
• [ ] One-time links (upload, invite, reset, magic link) really are single use, and their lifetime matches the token that created them.

Upload, scanning, and install

Treat every user-supplied file as hostile, including its name.

• [ ] Install commands never put file names, titles, or other user text into a shell string. Pass them as arguments or refuse names with shell characters ($, backticks, quotes, ;, |, newlines).
• [ ] Binary detection is based on content, not on extension or one bad byte. A file that claims to be an image but is not gets flagged. A file marked binary is still checked, not skipped.
• [ ] Hidden Unicode is flagged: bidi controls, zero-width characters, variation selectors, invisible operators, soft hyphens, combining joiners, filler characters.
• [ ] Download-and-run is caught in every spelling, not just a pipe into a bare shell name. Test a full shell path, a shell behind sudo, env, or command, eval of a command substitution, and sourcing a process substitution. Keep these samples in test fixtures, not in docs.
• [ ] Archives with duplicate paths (exact, case-folded, or Unicode-normalized) are refused, so the checker and the installer cannot see different files.
• [ ] Symlinks, absolute paths, and .. are refused.
• [ ] Frontmatter or manifest fields that grant access (allowed tools, permission modes, hooks) are shown to the user before install, or refused.
• [ ] Declared permissions are narrow. Bare interpreters, package runners, inline code flags, and wrappers are refused as shell grants. Write access to code-running config (git hooks, editor or agent settings, env files, package manifests, **) is refused or warned.
• [ ] Update never overwrites the user's own files without an explicit force flag.
• [ ] Asking for an exact version fails if the server returns a different one.

Signing and keys

• [ ] The verifier recomputes the key id from the key bytes. It never trusts the id the server lists.
• [ ] Trusted keys are pinned or fetched from a different origin than the content they verify.
• [ ] There is a revoked-key list, and the client checks already-installed content against it.
• [ ] There is a written, scripted way to rotate a key and re-sign published content.

Platform hygiene

• [ ] No secrets, tokens, prompts, or user file content in logs. Errors log a class or code only.
• [ ] Inputs that become URL paths for outbound calls are validated against dot segments (SSRF).
• [ ] Rate limits key on a client address the proxy actually sets.
• [ ] CI runs dependency and secret scanning. Third-party CI actions are pinned by commit hash.
• [ ] Audit events exist for sign-in, token create and revoke, approvals, and sensitive writes, and never contain secrets.

5. Record findings

Copy templates/findings.md to docs/security-review/findings.md and fill one row per finding.

Severity:

• Critical: exploitable now, broad harm (code runs on users' machines, account takeover).
• High: exploitable, real harm to users or integrity.
• Medium: needs conditions, or harm is limited.
• Low: defense in depth.
• Info: worth knowing, no action needed.

Rules for each finding:

• Number findings in order (R-01, R-02, ...). Never reuse an id. A later review continues the numbering.
• "Where" names the file, function, or endpoint precisely enough to find it.
• "Impact" says what an attacker gets, in one or two plain sentences.
• "Verified how" is a test name, a command and its output, or a live check. "Looks right" is not verification.
• Also fill "Checked and fine" so the next reviewer knows what was covered.

6. Hand off

1. Summarize: counts by severity, open versus fixed, and the top three risks.
2. List each open item with the fix you propose. Ask before changing any code.
3. When fixes land, update each row with the fix and how it was verified, and move it to fixed.

Rules

• Never run destructive requests against a live host. Signed out and read only, unless the owner says otherwise.
• Never paste secrets, tokens, or user content into the review docs.
• Review docs describe weak points. Keep them private until every High and Critical item is fixed.
• One finding per issue. If two areas share a root cause, link them instead of merging.