Secure Skills

Changelog

• 1.0.0, 22 October 2026: first release

Secure Skills

Version 1.0.0

Security checklists, configs and scripts for the jobs that sit between "we wrote the code" and "we sleep at night": catching secrets before they're committed, auditing dependencies every week, rolling out a Content Security Policy with real reports, reviewing sign-in and upload code, and knowing exactly what to do in the first hour after a leak. Every config is ready to copy into a repository, and every decision is explained in the Markdown next to it.

Who it's for

• Developers who own security for a small team or a side project, without a dedicated security engineer
• Teams setting up CI for a new repository and wanting sensible security checks from day one
• Reviewers who need a concrete checklist for auth, sessions and file uploads
• Anyone who has had a key leak once and doesn't want to improvise next time

It assumes you're comfortable with git, a terminal and your CI system. It goes further than a pre-launch checklist: each area has working files plus the reasoning behind them.

How to use it in 5 minutes

1. Copy secrets/.gitleaks.toml to your repository root and run gitleaks git --redact . to see what's already in your history.
2. Copy secrets/secret-scan.yml and dependencies/dependency-audit.yml into .github/workflows/, and dependencies/scripts/audit-deps.sh into scripts/.
3. Run sh scripts/audit-deps.sh locally and look at what it reports.
4. Print incident/first-hour-checklist.md and fill in the contacts table now, while nothing is on fire.
5. Put headers/csp-rollout.md and the two checklists in checklists/ on your list for the next sprint.

File map

A note on limits

These files reduce common risks and make your response faster. They can't make a system secure on their own, and they don't replace a professional review or penetration test for high-risk systems. Scanners only find known patterns and known advisories. The legal notes in the incident files are general; get advice for your own situation.

Licence

MIT License. See LICENSE.txt.

Auth and session checklist

For apps that handle their own sign-in, or that wrap a hosted auth provider with their own session logic. If you use a hosted provider for everything, most of the password items are its job, but the session, authorisation and recovery items are still yours.

Mark each item done, not applicable, or "risk accepted" with a reason.

Passwords

• Passwords are hashed with a slow, salted algorithm built for passwords: Argon2id, scrypt or bcrypt. Never plain SHA-256, MD5 or encryption.
• Hashing parameters are reviewed yearly and raised as hardware gets faster. Old hashes are upgraded when users next sign in.
• Minimum length is at least 8 characters, with 12 or more encouraged. Long passphrases are allowed (at least 64 characters).
• No composition rules (one capital, one symbol) and no forced periodic changes. These lead to weaker, predictable passwords.
• New passwords are checked against a list of known breached or common passwords.
• Paste is allowed in password fields, so password managers work.
• Passwords are never logged, emailed back or shown in an admin panel.

Sign-in

• The error message is the same for "no such user" and "wrong password": "Email or password is incorrect."
• Response time is similar for both cases, so attackers can't tell which emails have accounts.
• Sign-in is rate limited per account and per IP address, with increasing delays after failures.
• Repeated failures trigger extra checks (a delay, a challenge, an email to the account owner) rather than a hard lockout that attackers can use to lock real users out.
• Sign-in from a new device or location can notify the user.
• Credentials are only ever sent over HTTPS, in a POST body, never in a URL.

Multi-factor authentication

• MFA is available to all users and required for admins and staff accounts.
• Passkeys (WebAuthn) or authenticator apps are offered. SMS codes are a fallback only, because SIM swaps defeat them.
• Recovery codes are shown once, stored hashed, and each works only once.
• Turning MFA off, or changing the MFA device, requires a recent sign-in and sends an email to the account.
• MFA codes are rate limited and expire quickly.

Sessions

• Session IDs come from a secure random generator with at least 128 bits of entropy.
• A new session ID is issued at sign-in and on any privilege change, to prevent session fixation.
• Session cookies are Secure, HttpOnly, SameSite=Lax or Strict, and use the __Host- prefix where possible.
• Sessions have an idle timeout and an absolute lifetime. Pick values for your risk: for example 30 minutes idle and 12 hours absolute for an admin panel, longer for a low-risk consumer app with "remember me".
• Sign-out destroys the session on the server, not just the cookie in the browser.
• Users can see their active sessions and sign out of all other devices.
• Changing the password or email signs out every other session.
• Session data stored on the server doesn't include secrets that would be harmful if the session store leaked.

Tokens (JWT and similar)

• Tokens are verified on every request: signature, exp, nbf, iss and aud.
• The accepted algorithm is fixed on the server. Tokens claiming alg: none, or a different algorithm, are rejected.
• Access tokens are short-lived (minutes). Refresh tokens are longer-lived, stored server-side or rotated on each use, and can be revoked.
• Refresh token reuse is detected: if an old refresh token is used again, the whole token family is revoked.
• Tokens aren't stored in localStorage when a cookie would do. Any script running on the page can read localStorage.
• Tokens never contain sensitive data. JWT payloads are only encoded, not encrypted; anyone holding one can read it.
• Signing keys can be rotated without downtime (a key ID in the header, and the server accepting the old and new keys for a short overlap).

Authorisation

• Every server route and API endpoint checks who is calling and whether they may act on this record. Hiding a button is not access control.
• Object IDs from the client are always checked against the signed-in user's rights. Changing /invoices/1041 to /invoices/1042 must not show someone else's invoice.
• Admin routes check for an admin role on the server, on every request.
• Role and permission changes take effect straight away, not at next sign-in.
• Mass assignment is blocked: users can't set fields like role, isAdmin, ownerId or price by adding them to a request body.
• There is a test for at least one "user A tries to read user B's data" case per resource type.

Account recovery

• Password reset links are single-use, expire within an hour, and are invalidated when the password changes.
• Reset tokens are random, at least 128 bits, and stored hashed.
• The reset page sets Referrer-Policy: no-referrer so the token doesn't leak to third-party scripts or links.
• Requesting a reset shows the same message whether or not the email has an account.
• Reset requests are rate limited per email and per IP.
• After a reset, the user is told by email, and all sessions are ended.
• Security questions are not used.
• Support staff follow a written process before changing an account's email or turning off MFA, and every change is logged.

Email change

• Changing email requires the current password or a recent sign-in.
• A confirmation link goes to the new address, and a notice goes to the old address with a way to undo the change.
• The change only takes effect when the new address is confirmed.

Sign-up

• Email addresses are verified before the account can do anything that matters.
• Sign-up is rate limited and protected against scripted mass sign-ups where that matters for your costs.
• Sign-up doesn't reveal whether an email is already registered. Send the existing user an email instead of showing an error.

OAuth and social sign-in

• The state parameter is used and checked to prevent cross-site request forgery.
• PKCE is used for public clients (single-page and mobile apps).
• Redirect URIs are registered exactly, with no wildcards.
• Accounts are linked by a verified email from the provider only. An unverified email claim must not take over an existing account.
• Scopes requested are the minimum needed.

Logging and monitoring

• Sign-ins, failures, MFA changes, password resets, email changes, role changes and admin actions are logged with time, user, IP and user agent.
• Logs never contain passwords, tokens, reset links or full session IDs.
• Alerts fire on spikes in failed sign-ins or reset requests, and on admin sign-ins from new locations.

Sign-off

File upload checklist

File uploads let strangers put content on your systems. Each item below closes one way that goes wrong: running code on your server, serving malware from your domain, filling your storage bill, or leaking one user's files to another.

Decide what you accept

• There is a written allowlist of file types for each upload feature (for example: avatars accept JPEG, PNG and WebP; documents accept PDF only). Anything else is rejected.
• There is a maximum file size per feature, enforced at the edge or proxy and in the app.
• There is a maximum number of files per request and per user per day.
• There is a storage quota per user or account, so one account can't fill your storage.

Validate on the server

• File type is checked from the file contents (magic bytes), not from the extension or the Content-Type the browser sent. Both are set by the client.
• The extension is also checked against the allowlist, and must agree with the detected type.
• Double extensions (invoice.pdf.exe, photo.php.jpg) and trailing dots or spaces are rejected.
• Images are decoded and re-encoded with a maintained image library. This strips embedded scripts, malformed data and metadata.
• Image dimensions are capped before decoding, to stop decompression bombs (a small file that expands to gigabytes in memory).
• Archives (.zip and similar) are only accepted if you need them. If you extract them, cap the total extracted size and file count, and reject entries with ../ or absolute paths.
• SVG uploads are rejected, or sanitised with a dedicated SVG sanitiser and served only as images. SVG can contain scripts.
• HTML, JavaScript and other active content are never accepted as uploads unless the feature is literally for hosting them.
• Office documents and PDFs are scanned for malware if other users will download them.

Store safely

• Uploaded files go to object storage or a folder outside the web root, never into a folder the web server executes code from.
• Files are stored under a name you create (a random ID), never the user's file name. Keep the original name in the database if you need to show it.
• The original file name, when shown, is escaped. File names can contain HTML.
• Storage buckets are private by default. Public access is granted per file, only for content meant to be public.
• Metadata such as GPS location in photos is stripped before files are made visible to others.
• Files are encrypted at rest (most object storage does this by default; confirm it is on).

Serve safely

• User files are served from a separate domain (for example example-usercontent.com) or a dedicated subdomain with no cookies, so a malicious file can't run in your main site's origin.
• Responses for user files send X-Content-Type-Options: nosniff and the stored, validated Content-Type.
• Files that should download rather than display send Content-Disposition: attachment.
• A restrictive CSP is sent with user files: default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox.
• Private files are served through short-lived signed URLs or an authenticated route that checks the user may see this file.
• Signed URLs expire in minutes, not days, and are not logged in full.

Direct-to-storage uploads

If the browser uploads straight to object storage with a pre-signed URL or form:

• The pre-signed request fixes the exact object key, the content type and a maximum size (a content-length range condition).
• The URL expires quickly (a few minutes).
• The file is treated as untrusted until a server-side job validates it. Keep it in a "pending" location and move it only after checks pass.
• The app records which user requested each upload, and rejects attempts to attach someone else's upload to a record.

Processing

• Processing (resizing, conversion, scanning) runs in a separate worker or sandbox with limited permissions and no access to secrets it doesn't need.
• Processing has timeouts and memory limits.
• Image and document libraries used for processing are kept up to date. They are a common source of serious vulnerabilities.
• Failed or rejected files are deleted, not left in storage.

Abuse and cost

• Uploads require a signed-in user, unless there is a strong reason otherwise.
• Upload endpoints are rate limited.
• There is a way to report and remove abusive content, and a person who handles reports.
• Storage and bandwidth spending alerts are set with your provider.
• Files are deleted when the owning account or record is deleted, in line with your privacy policy.

Tests to run

• Upload a file with a valid extension but the wrong contents (a text file renamed .png). It is rejected.
• Upload a file over the size limit. It is rejected before it is fully stored.
• Upload an SVG with a script inside. It is rejected or sanitised.
• Upload a file named <img src=x onerror=alert(1)>.png. The name displays as text.
• As user A, request user B's private file URL. Access is denied.
• Wait past the signed URL expiry and try again. Access is denied.

Sign-off

Dependency audit

Most of the code in a modern app was written by someone else. A dependency audit checks your locked package versions against public vulnerability databases and tells you which ones have known problems. This folder gives you a script that runs the right audit tool for each language it finds, a weekly CI job and a policy for how fast to act.

Files in this folder

Set it up

1. Copy scripts/audit-deps.sh to scripts/audit-deps.sh in your repository.
2. Run it locally from the repository root:

   sh scripts/audit-deps.sh

1. Copy dependency-audit.yml to .github/workflows/dependency-audit.yml.
2. Read update-policy.md with your team and agree the response times.

What the script does

It exits with:

• 0 when every audit that ran passed
• 1 when any audit found something at or above the threshold, or failed to run
• 2 for a bad argument or setting

Settings

Set these as environment variables.

Pass a folder as the first argument to audit a sub-project: sh scripts/audit-deps.sh services/api. For a monorepo, call it once per package folder that has its own lockfile.

Things to know

• pip-audit doesn't filter by severity. Most Python advisories don't carry a consistent severity score, so any known vulnerability fails the run. Use update-policy.md to decide how fast to act on each one.
• --strict on pip-audit fails when a package can't be audited at all, for example a private package not on PyPI. If you have private packages, either remove --strict from the script or list them with --ignore-vuln or a private index setting.
• Poetry and uv projects: export a requirements file first (poetry export -f requirements.txt -o requirements.txt or uv export --format requirements-txt > requirements.txt) so the audit sees exact locked versions.
• Yarn: the script doesn't run Yarn. Yarn Classic uses yarn audit --level high, which reports through a bitmask exit code. Yarn Berry uses yarn npm audit --severity high. Add a block for the one you use, in the same pattern as the npm block.
• Dev dependencies count. Build tools run on your machine and in CI with access to your source and secrets. Only turn on AUDIT_PROD_ONLY if you have a reason, and audit dev dependencies separately on a slower schedule.
• No lockfile, no audit. Without a lockfile you are auditing whatever version happens to resolve today. Commit your lockfile.

Why a weekly schedule

Vulnerabilities are published against versions you already shipped. A pull request check only catches problems in new changes. The weekly run catches new advisories against code that hasn't changed. Pick a time when someone will read the result, and route failures to a channel people watch.

What it can't do

• It only finds known vulnerabilities in public advisory databases.
• It doesn't tell you whether your code actually calls the vulnerable function. Many findings won't be reachable in your app; some will. update-policy.md covers how to decide.
• It doesn't catch malicious packages that have no advisory yet. Lockfiles, careful review of new dependencies and an update delay (see the policy) help there.

Dependency update policy

Copy this into your repository or team handbook and change the numbers to suit you. A written policy turns "we should update that" into a decision with an owner and a date.

Team: [Team name] Policy owner: [Name] Last reviewed: [Date]

1. Response times for security findings

Times start when the finding is first reported to the team (the weekly audit, a bot pull request or an advisory email).

"Mitigate" means the risk is removed even if the package isn't updated yet: a feature turned off, an input blocked at the edge, a config change. Record the mitigation in the exception register (section 4).

Treat a finding as critical and reachable regardless of score if:

• there is a public exploit and the package handles untrusted input (parsers, upload handling, template engines, auth libraries), or
• the advisory is for a package that has been taken over or published with malicious code.

2. How to judge reachability

Spend no more than 15 minutes on this per finding. When unsure, treat it as reachable.

1. Is the package in production code, or only used to build, test or lint?
2. Does our code call the affected function or feature named in the advisory?
3. Can an outside user influence the input that reaches it?
4. Is it behind a login, an admin role or an internal network?

Write the answer in the pull request or ticket, so the next person doesn't redo the work.

3. Fixing a finding

1. Try the smallest update that fixes it: a patch or minor version.
2. If the fix is only in a new major version, read the changelog, update, run the full test suite and test the affected feature by hand.
3. If the vulnerable package is a transitive dependency (a dependency of a dependency):

• First update the direct dependency that pulls it in.
• If that has no fixed release, use an override: overrides in package.json for npm, pnpm.overrides for pnpm, a constraints file for pip. Remove the override once the direct dependency catches up.

1. If no fixed version exists, mitigate and add an exception.
2. Never fix by deleting the lockfile and regenerating it. That updates everything at once and hides what changed.

4. Exceptions

Some findings can't be fixed in time. Record each one:

Rules:

• Every exception has an owner and a review date no more than 30 days away.
• An expired exception is treated as a new finding.
• Use the audit tool's own ignore option (pip-audit --ignore-vuln <ID>, npm overrides, or a reviewed allowlist file) so the exception is visible in code, not only in a spreadsheet.

5. Routine updates

Security fixes are much easier when you are only a few versions behind.

• Turn on an update bot (Dependabot, Renovate or your host's equivalent). Group minor and patch updates into one weekly pull request per ecosystem.
• Set a short delay before new versions are proposed (for example 3 days). Malicious releases are often caught and pulled within that window.
• Merge routine updates weekly when tests pass. Don't let them pile up.
• Review major updates one at a time, with someone who knows the affected area.
• Once a quarter, list dependencies that have had no release for two years or have been marked deprecated, and decide whether to replace them.

6. Adding a new dependency

Before adding a package, the person adding it checks:

• We need it. A few lines of our own code wouldn't do the job.
• It is maintained: recent releases, issues answered, more than one maintainer if possible.
• The name is spelled correctly. Typo-squatted packages copy popular names with one letter changed.
• It doesn't run install scripts we don't expect.
• Its licence is compatible with ours.
• Its size and number of transitive dependencies are reasonable for what it does.

7. Who does what

Content Security Policy rollout

A Content Security Policy (CSP) tells the browser which scripts, styles, frames and connections a page may use. A good one turns most cross-site scripting bugs from "attacker runs code in your users' browsers" into "browser blocks it and sends you a report". A careless one breaks your checkout on a Friday evening.

This guide takes you from no policy to an enforced one in five stages, with reports collected the whole way.

Stage 1: collect reports before you write a policy

You need somewhere for browsers to send violation reports. Use csp-report-endpoint/ in this folder, or a hosted reporting service.

Both endpoint files:

• accept the older report-uri format and the newer Reporting API (report-to) format
• reject bodies over 64 KB and anything that isn't JSON
• strip query strings and fragments from URLs before logging, because those often carry tokens and personal data
• write one JSON line per violation to the log, which most log tools can search and group
• answer CORS preflight requests only for origins you list in ALLOWED_ORIGINS

Settings (environment variables for Node, variables or secrets for the worker):

Run the Node version with node node-server.mjs. It has no dependencies.

Reports can be sent by anyone, so treat the data as untrusted. Add a rate limit at your proxy or edge if the endpoint is public, and don't display report contents in an admin page without escaping them.

Stage 2: deploy a report-only policy

Content-Security-Policy-Report-Only makes the browser report violations without blocking anything. Start with a strict policy in this mode so the reports show you everything that would break.

Reporting-Endpoints: csp="https://example.com/csp-report"
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; report-uri https://example.com/csp-report; report-to csp

Include both report-uri and report-to. Browsers that support report-to ignore report-uri; older ones only understand report-uri.

Leave it running for at least a week, or one full release cycle, so you see traffic from every page and every browser your users have.

Stage 3: read the reports and decide

Group reports by directive and blockedUrl. For each group, decide one of three things:

Keep a short list of every source you add and why. When a provider is removed from your app, remove its host from the policy too.

Stage 4: replace inline scripts with nonces or hashes

Allowing 'unsafe-inline' in script-src removes most of the protection a CSP gives you. There are two clean alternatives.

Nonce (best for server-rendered pages)

The server creates a fresh random value for every response, puts it in the header and adds it to each <script> tag it renders. An attacker who injects a script can't guess the value.

Content-Security-Policy: script-src 'nonce-R4nd0mValueFromServer' 'strict-dynamic'; object-src 'none'; base-uri 'none'

<script nonce="R4nd0mValueFromServer" src="/app.js"></script>

Rules for nonces:

• At least 128 bits of randomness from a secure random generator, base64 encoded. In Node: crypto.randomBytes(16).toString("base64").
• New value for every response. A nonce in a cached page is the same for everyone, which defeats the point. Don't let a CDN cache HTML that carries a nonce, or move to hashes.
• Never echo a nonce from the request, and never put it in a URL.
• 'strict-dynamic' lets a trusted (nonced) script load further scripts, which is how most bundlers and tag managers work. With it, host lists in script-src are ignored by modern browsers.

A minimal Express example:

import crypto from "node:crypto";

app.use((req, res, next) => {
  const nonce = crypto.randomBytes(16).toString("base64");
  res.locals.cspNonce = nonce;
  res.setHeader(
    "Content-Security-Policy",
    `script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'`
  );
  next();
});

Then render nonce="<%= cspNonce %>" (or your template's equivalent) on every script tag. Next.js, Nuxt, SvelteKit, Rails and Django all have documented ways to do this; use your framework's method rather than rolling your own.

Hash (best for static sites)

For a fixed inline script, put the SHA-256 hash of its exact contents in the policy. Static hosts can't create a nonce per response, so hashes are the usual choice there.

printf '%s' 'document.documentElement.classList.add("js")' | openssl dgst -sha256 -binary | openssl base64

Content-Security-Policy: script-src 'self' 'sha256-<the base64 output>'

The hash covers the exact characters between <script> and </script>, including spaces and line breaks. Any change, even reformatting, needs a new hash. Your browser's console prints the expected hash when it blocks an inline script, which is the quickest way to get it right.

Hashes don't cover onclick= and other inline event handlers. Move those into a script file with addEventListener.

Stage 5: enforce, and keep reporting

1. When a week of reports shows only noise (extensions, single users), copy the report-only policy to a Content-Security-Policy header.
2. Keep the report-only header too, with a stricter candidate policy. This lets you test the next tightening without risk.
3. Keep report-uri and report-to on the enforced policy, so you hear about breakage straight away.
4. Watch reports closely for the first day after each release.

Common directives

Notes:

• frame-ancestors, report-uri and report-to don't work in a <meta http-equiv> CSP. Send the policy as a header whenever you can.
• 'self' doesn't include subdomains. https://cdn.example.com must be listed separately.
• Avoid wide sources such as https:, * or a whole CDN domain that hosts anyone's files. Each one lets an attacker load code from somewhere they control.
• Keep policies short enough to read. If yours is very long, you probably have third-party scripts that need review.

Trusted Types (next step)

Once your CSP is enforced, require-trusted-types-for 'script' makes the browser reject strings passed to dangerous DOM sinks such as innerHTML, unless they go through a policy you define. It blocks most DOM-based cross-site scripting. Browser support is not universal yet, so roll it out in report-only mode first, exactly as above.

Rollout record

Response headers checklist

Use this to review the headers a site actually sends, not the ones you think you configured. Hosts, CDNs, frameworks and proxies all add, change and drop headers, so always check the live response.

How to check

From a terminal:

curl -sSI https://example.com/
curl -sSI https://example.com/login
curl -sSI https://example.com/api/health
curl -sSI http://example.com/

Check at least: the home page, a logged-in page, an API response, a static asset, an error page (/this-page-does-not-exist) and the plain http:// address. Error pages and API routes are often served by a different layer and miss headers the main pages have.

Transport

• http:// requests redirect to https:// with a 301 or 308, on the apex domain and www.
• Strict-Transport-Security is present on HTTPS responses, with max-age of at least 31536000.
• includeSubDomains is only set once every subdomain works over HTTPS, including old marketing and mail subdomains.
• preload is only set if you have read the requirements at hstspreload.org and accept that removal takes months.
• HSTS is not sent over plain HTTP (browsers ignore it there, but it signals a misconfigured layer).

Framing, sniffing and referrers

• Content-Security-Policy includes frame-ancestors 'none' (or a list of hosts allowed to embed you).
• X-Frame-Options: DENY or SAMEORIGIN is also set, for older browsers. If both are set, they agree.
• X-Content-Type-Options: nosniff is on every response, including API and static assets.
• Referrer-Policy is strict-origin-when-cross-origin or stricter. Use no-referrer on pages whose URLs contain tokens, such as password reset pages.

Content Security Policy

• A CSP header is present on HTML responses (see csp-rollout.md).
• script-src doesn't contain 'unsafe-inline' without a nonce or hash, and doesn't contain *, https: or data:.
• object-src 'none' and base-uri are set.
• The policy reports somewhere you read.
• There is only one enforced CSP. Two enforced policies both apply, so the effective policy is the strictest combination, which surprises people.

Cross-origin isolation and resource policy

• Cross-Origin-Opener-Policy: same-origin on pages that don't need to talk to popups from other origins. Use same-origin-allow-popups if you open payment or sign-in popups that must message back.
• Cross-Origin-Resource-Policy: same-origin on private assets and API responses that other sites have no reason to load.
• Cross-Origin-Embedder-Policy: require-corp only if you need cross-origin isolation (for example SharedArrayBuffer). It breaks third-party embeds that don't opt in, so test first.

Permissions

• Permissions-Policy turns off features you don't use: camera=(), microphone=(), geolocation=(), usb=(), payment=() and so on.
• Features you do use are allowed only for self or the specific embedded origin that needs them.

CORS (API responses)

• Access-Control-Allow-Origin is not * on any endpoint that uses cookies or returns private data.
• The origin is checked against an exact list, not a "contains" or "ends with" test. A "contains" test accepts example.com.attacker.net, and an "ends with" test accepts attacker-example.com.
• Access-Control-Allow-Credentials: true only appears with an exact origin, never with a reflected one.
• Vary: Origin is set when the allowed origin changes per request, so caches don't serve one site's CORS answer to another.
• Preflight (OPTIONS) responses don't allow more methods or headers than the API uses.

Caching of private data

• Logged-in pages and API responses with personal data send Cache-Control: no-store (or private, no-cache if you need revalidation).
• Your CDN is configured not to cache responses that set cookies or vary by user.
• Fingerprinted static assets send a long Cache-Control: public, max-age=31536000, immutable.
• HTML that carries a CSP nonce is not cached by a shared cache.

Cookies

• Session cookies have Secure, HttpOnly and SameSite=Lax (or Strict).
• Session cookies use the __Host- prefix where possible, which forces Secure, Path=/ and no Domain, so subdomains can't set or read them.
• No cookie has a Domain attribute wider than it needs.
• Cookies that must work in cross-site iframes use SameSite=None; Secure and nothing else does.
• Logout sends Clear-Site-Data: "cookies", "storage" if you want the browser to drop all local state for your origin.

Information leaks

• No X-Powered-By header (Express, PHP and others add it by default).
• Server header doesn't include version numbers.
• Error responses don't include stack traces, SQL, file paths or internal hostnames.
• No debug headers left from development (X-Debug-Token, X-Request-Body and the like).
• Source maps are not publicly served for production bundles, or you have decided that is acceptable.

Discovery files

• /.well-known/security.txt exists, with a contact address and an Expires date in the future.
• /.env, /.git/config, /config.json and backup files (.bak, .old, ~) return 404, not the file.

After every change

• Re-run the curl commands above on the same set of URLs.
• Run your URL through a public security headers checker and compare with last time.
• Watch CSP reports and error tracking for a day.

Header record

Evidence and action log

Keep one copy of this per incident. Write as you go, in UTC, in short factual lines. Record what you saw and did, not what you think it means; put interpretations in the "Notes" column.

Store it somewhere the attacker can't edit, and limit who can read it. It may become evidence for insurers, regulators or a court.

Incident ID: [ID] Opened (UTC): [time] Lead: [name]

Action log

Evidence collected

Hashing each exported file when you collect it lets you show later that it wasn't changed. On macOS and Linux: shasum -a 256 <file>. On Windows: Get-FileHash <file> -Algorithm SHA256.

Credentials

Accounts and sessions

Attacker artefacts found

Record before removing.

Notifications

Open questions

First hour: suspected breach or leaked key

Use this when you think someone has accessed something they shouldn't, or a credential with real power has been exposed. Print it, or keep it somewhere you can open when your main systems might not be trustworthy.

The first hour has three goals, in this order:

1. Stop it getting worse (contain).
2. Keep the evidence you will need to understand what happened.
3. Tell the right people early, with facts.

Fixing the root cause and writing the full report come later.

Incident started (UTC): [time] Noticed by: [name] How noticed: [alert, user report, provider email, scanner]

Incident lead: [name] Notes kept by: [name] Notes location: [document or channel]

---

Minutes 0 to 10: confirm and organise

• One person takes the lead. Everyone else reports to them, so actions don't collide.
• Start a written log now (see evidence-log.md). Record every action with a UTC time.
• Write one sentence on what you know: "At [time] we saw [what] affecting [which system]."
• Open a private channel or call for the response. Don't discuss it in public channels, or in any channel the attacker might be able to read if an account is compromised.
• Decide the working severity. Leaked admin or cloud credentials, signs of data access, or signs of an attacker inside your systems all count as the highest level until proven otherwise.

Minutes 10 to 30: contain

Contain first, investigate second. But contain in a way that keeps evidence (next section).

• Revoke or rotate the exposed credential (see "Key rotation order" below). For a confirmed leak, this is the first action.
• Disable compromised accounts. Suspend rather than delete, so their history and audit trail survive.
• End active sessions for affected accounts, and for all admins if an admin account is involved.
• Block the access path if you know it: an IP range at the firewall or edge, an API key, an OAuth app, a public storage link.
• Isolate affected machines from the network rather than shutting them down. Shutting down loses memory contents and running processes.
• Pause risky automation that could spread the problem: deploy pipelines, sync jobs, scheduled exports.
• Put the affected feature in maintenance mode if data is actively being taken and you can't stop it any other way.

Don't:

• Wipe, reimage or restore over affected systems yet.
• Delete the attacker's files, accounts or keys before recording them.
• Rotate credentials from a machine that might be compromised. Use a known-clean device.
• Contact the attacker, or reply to an extortion message, without legal advice.

Minutes 10 to 40: keep evidence (in parallel)

Logs expire, and some providers keep them for only a few days. Export first, read later.

• Export audit logs from the affected providers: cloud console, git host, identity provider, database, payment platform, email.
• Export web server, CDN, WAF and application logs covering at least the 7 days before the first sign of trouble.
• Take snapshots of affected cloud disks and databases before changing them.
• Save copies of any attacker artefacts: files, scripts, new users, new keys, changed settings. Record names, IDs and timestamps.
• Screenshot dashboards that show the activity (usage spikes, unusual regions, new resources).
• Save the original alert, email or report that started this, with full headers.
• Store all of this in one access-controlled place, separate from the affected systems. Note who collected each item and when.
• Extend log retention on affected services if you can.

Minutes 20 to 60: tell people

Tell people early with what you know, and say clearly what you don't know yet.

Data protection laws can set short deadlines. Under the GDPR, for example, a reportable personal data breach must be notified to the supervisory authority within 72 hours of becoming aware of it. Other regions and sectors have their own rules. This kit can't tell you what applies to you; that is why the legal or privacy contact is in the first hour.

Key rotation order

Rotate in order of power: the credentials that could be used to create new access or undo your other rotations go first.

1. Identity and cloud administration. Cloud root or owner accounts, organisation admin accounts, identity provider admins, domain registrar and DNS accounts. Change passwords, reset MFA if there is any doubt, remove unknown MFA devices and recovery options.
2. CI/CD and source control. Deploy keys, CI secrets, git host tokens and personal access tokens, package registry publish tokens. These can ship new code to production and to your users.
3. Secrets managers and key stores. The master credentials that unlock all the others.
4. Databases and storage. Database passwords and connection strings, storage access keys, backup credentials.
5. Signing secrets. Session and JWT signing keys, OAuth client secrets, webhook signing secrets, encryption keys. Rotating session keys logs everyone out; accept that.
6. Payment and money-moving keys. Payment provider secret keys, payout and banking API credentials.
7. Third-party APIs. Email, SMS, maps, analytics, AI and other service keys, especially anything with a spending meter.
8. Everything else that the compromised system or person could read.

For each one:

• Create the new credential with the narrowest scope that works.
• Update every place it is used.
• Deploy and confirm things work.
• Revoke the old one, and record the time.
• Look for credentials the attacker created (new keys, tokens, users, OAuth grants, SSH keys) and remove them after recording them.

End of the first hour

• The exposed credentials are revoked, or there is a written plan with a time for each.
• Evidence is exported and stored safely.
• The right people know, and the next update time is set.
• There is a list of open questions: how they got in, what they touched, whether they still have access.
• Someone owns each open question, with a time to report back.
• You have decided whether you need outside help (an incident response firm, your provider's security team, law enforcement).

Questions to answer next

These usually take hours to days. Write each answer with the evidence behind it.

• How did they get in, and is that path closed?
• When did it start? (The first sign is rarely the first event.)
• What did they access, change or take?
• Do they still have any access: accounts, keys, scheduled jobs, backdoors?
• Whose data was involved, and how many people?
• What do we need to tell users, partners and regulators, and by when?

Contacts

Secret scanning

A secret scanner reads your code and git history and flags anything that looks like a key, token, password or private key. This folder sets one up at three layers, so a leak has to get past all of them:

1. On your machine, before a commit is created (pre-commit hook).
2. In CI, on every pull request and every push to your main branch.
3. In your git host, using its own secret scanning and push protection where available.

The files use gitleaks, an open-source scanner (MIT licence) that runs as a single binary on Windows, macOS and Linux. The same ideas apply to other scanners if your team already uses one.

Files in this folder

Set it up in four steps

1. Install gitleaks on your machine. Use your package manager (brew install gitleaks, scoop install gitleaks, winget install gitleaks) or download a release from the gitleaks GitHub releases page.
2. Copy .gitleaks.toml to the root of your repository. gitleaks picks it up automatically from there.
3. Run a first full scan of history, with secrets redacted from the output:

   gitleaks git --redact --verbose .

Deal with every finding before you go further. A finding in old history is still a live secret until it is rotated. Follow leaked-secret-response.md.

1. Add the pre-commit hook (pre-commit-setup.md) and copy secret-scan.yml to .github/workflows/secret-scan.yml.

Older gitleaks releases use gitleaks detect instead of gitleaks git, and gitleaks protect --staged instead of gitleaks git --pre-commit --staged. If a command in this kit says "unknown command", upgrade gitleaks rather than changing the files.

How the config works

.gitleaks.toml has three parts.

[extend] useDefault = true keeps the built-in rule set. It covers the common cloud providers, payment platforms, chat tools, private keys and generic high-entropy tokens. Don't remove this line unless you plan to maintain every rule yourself.

[[rules]] adds a rule for a token format that only your company uses. The example matches tokens shaped like exco_live_ followed by 32 letters and digits. Change the id, description, regex and keywords to match your own format. keywords is a fast pre-filter: gitleaks only runs the regex on lines that contain one of them, so keep at least one short, distinctive keyword.

[[allowlists]] tells gitleaks what to ignore. The example shows the four kinds of entry:

Older gitleaks releases only understand a single [allowlist] table. If yours rejects [[allowlists]], upgrade, or rename the header to [allowlist] and keep the same fields.

How the CI workflow works

secret-scan.yml runs in three situations:

Notes on the choices:

• It downloads a pinned gitleaks release and checks it against the published checksums file before running it. Raise GITLEAKS_VERSION when you upgrade locally, so CI and laptops use the same rules.
• It runs the binary directly instead of a marketplace action. Some third-party actions need a licence key for organisation accounts; the binary doesn't.
• --redact keeps secrets out of the CI log. Without it, the scanner would print the very secret it found into a log that many people can read.
• permissions: contents: read gives the job the least access it needs.
• To make the scan block merges, add the gitleaks job as a required status check in your branch protection rules.
• If your default branch isn't main, change the branches line.

Rules for the allowlist

The allowlist is where scanners quietly stop working. Keep it small and reviewed.

• Allowlist values or files, never whole folders of real code.
• Never allowlist a real secret because "it's only the test key". Test keys still give access to your account, and test environments often hold copies of real data.
• Add a commits entry only after the secret in that commit has been rotated and the old one revoked.
• Review changes to .gitleaks.toml in pull requests like any security change. Consider a CODEOWNERS entry for it.

Inline ignores

gitleaks also skips a line that ends with the marker gitleaks:allow inside a comment in that file. It is quick, but it hides the decision inside code where nobody reviews it. Prefer an allowlist entry, which keeps every exception in one file.

A baseline for old findings

If a large, old repository has many findings you have already dealt with, you can record them in a baseline and only fail on new ones:

gitleaks git --report-path gitleaks-baseline.json .
gitleaks git --baseline-path gitleaks-baseline.json --redact .

Only do this after every finding in the baseline has been rotated or confirmed as a false positive. A baseline of unreviewed findings is a list of live keys that you have agreed to stop looking at.

Turn on your git host's scanning too

• GitHub: secret scanning and push protection are on by default for public repositories. For private repositories they depend on your plan. Check Settings, then "Code security".
• GitLab: secret detection runs as a CI template, and recent versions offer push protection.
• Bitbucket: has secret scanning for repositories in Bitbucket Cloud.

Host scanning often knows about partner token formats and can alert the provider, who may revoke the key for you. It doesn't replace local scanning: by the time it runs, the secret has already left your machine.

What scanning can't do

• It finds patterns. A password with no recognisable shape, typed into a config file, can slip through.
• It can't see secrets that never touch git: screenshots, chat messages, logs, browser bundles built in CI.
• It can't undo a leak. Once a secret has been pushed anywhere public, treat it as used and rotate it.

When a secret is found

A secret scanner, a colleague, a provider email or a stranger has told you a key is in your repository. The order of the steps matters: rotate first, then clean up history. Rewriting history first feels productive, but the key keeps working the whole time, and copies already exist in clones, forks, CI caches and scanners run by people who are not on your side.

Assume the secret has been seen if it was ever pushed to a remote, even a private one, even for a minute.

Step 0: is it real?

Spend two minutes, not twenty.

• Open the finding. Note the file, commit, author and date. Don't paste the secret into chat or a ticket.
• Decide what it is: which provider, which account, which environment.
• Check it is a real credential, not a placeholder or a revoked key. The provider's dashboard usually lists active keys by their last few characters.
• If you can't tell within a few minutes, treat it as real.

If it is a false positive, add a narrow allowlist entry (see README.md) and stop here.

Step 1: rotate (minutes, not hours)

• Create a new credential in the provider's dashboard, with the narrowest scope that works.
• Update it everywhere the old one is used: host environment variables, CI secrets, secrets manager, other services that call this one. A key inventory makes this quick.
• Redeploy the services that read it, and check they work with the new value.
• Revoke or delete the old credential. Until this step is done, the leak is still open.
• Write down the time you revoked it. You'll need it for step 2.

Some secrets can't be swapped instantly without downtime, such as a database password used by a fleet of servers. In that case add a second credential, move traffic to it, then remove the first. Don't leave the old one active "until the weekend".

Special cases:

Step 2: look for misuse

• Check the provider's usage, billing and audit logs from the commit date to the revocation time.
• Look for actions you don't recognise: new API keys, new users, data exports, changed settings, unusual regions or IP addresses.
• For databases and storage, look for bulk reads, new tables, deleted rows or public links created.
• Export the relevant logs now. Some providers keep them for only a few days.

If you find misuse, stop here and switch to ../incident/first-hour-checklist.md. This is now an incident, not a clean-up.

Step 3: remove it from the code

• Replace the value in the code with a read from an environment variable or secrets manager.
• Add the file pattern to .gitignore if the secret lived in a config file.
• Merge that change normally. This removes the secret from the current code, not from history.

Step 4: purge history (when it matters)

Rewriting history is disruptive. Do it when the repository is public, or when the secret can't be rotated (rare), or when your policy requires it. For a private repository with a rotated key, many teams skip this step and record the decision.

The usual tool is git filter-repo. Work on a fresh mirror clone, not your working copy:

git clone --mirror https://github.com/example-co/example-repo.git
cd example-repo.git
printf '%s\n' 'exco_live_REPLACE_WITH_THE_LEAKED_VALUE==>REMOVED' > ../replacements.txt
git filter-repo --replace-text ../replacements.txt
git push --force --mirror

To remove a whole file from every commit instead:

git filter-repo --invert-paths --path config/production.json

After the push:

• Delete replacements.txt. It contains the secret.
• Ask everyone with a clone to re-clone. Old clones still contain the secret and will push it back if someone merges an old branch.
• Close or rebase open pull requests that were based on the old history.
• On GitHub, cached views of old commits and pull requests can remain reachable. Contact GitHub support to request removal of cached views if the repository is public.
• Forks keep their own copy. You can't rewrite them.
• Run the scanner over the full history again to confirm it is gone.

Step 5: stop it happening again

• Find the cause: no hook installed, a hook skipped, a file not in .gitignore, a secret in a test, a value copied from a dashboard into code.
• Fix the cause, not only the instance. Usually that means turning on the pre-commit hook for everyone, adding CI scanning, or moving a config file out of the repo.
• Add the provider to your key inventory with an owner and a rotation date.
• Write a short note: what leaked, how long it was exposed, what was rotated, whether misuse was found. Keep it with your security records.

Who to tell

• The owner of the account the key belonged to, straight away.
• Your security contact or team lead, if you have one.
• The provider, if you see misuse. Many have an abuse or security contact and can help trace activity.
• If personal data may have been accessed, the people responsible for privacy in your organisation. Data protection laws can set short deadlines for notifying a regulator and users, so get advice early.

Response log

Pre-commit secret scanning

A pre-commit hook runs on the developer's machine every time they run git commit. If it finds a possible secret in the staged changes, the commit is stopped before it exists. This is the cheapest place to catch a leak: nothing has been pushed, so nothing needs rotating.

There are two ways to set it up. Pick one per repository.

Option A: the pre-commit framework

Use this if your team already uses the pre-commit framework, or works across several languages.

1. Install the framework: pipx install pre-commit (or pip install pre-commit, or brew install pre-commit).
2. Copy .pre-commit-config.yaml to the root of your repository. If you already have one, add the gitleaks entry to its repos list.
3. Update the pinned version to the newest release:

   pre-commit autoupdate --repo https://github.com/gitleaks/gitleaks

1. Install the hook in your clone:

   pre-commit install

1. Test it on the whole repository once:

   pre-commit run gitleaks --all-files

The framework downloads and builds gitleaks for you, so developers don't need to install it separately. The first run takes a little longer while it does this.

Option B: a plain git hook

Use this if you don't want another tool. Each developer needs gitleaks installed.

1. Copy hooks/pre-commit into your repository, for example as .githooks/pre-commit.
2. Make sure it has LF line endings and is executable:

   git update-index --chmod=+x .githooks/pre-commit

On macOS and Linux, also run chmod +x .githooks/pre-commit in your clone.

1. Point git at the folder. Each developer runs this once per clone:

   git config core.hooksPath .githooks

1. Test it by staging a fake key and committing:

   echo "token = exco_live_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" > leak-test.txt
   git add leak-test.txt
   git commit -m "test hook"

The commit should be stopped. Then remove the test file: git rm --cached leak-test.txt and delete it.

The hook stops the commit if gitleaks is missing, rather than silently skipping the scan. If you would rather warn and continue, change exit 1 in the first block to exit 0, but then the hook only protects people who remembered to install the scanner.

Windows notes

• Git for Windows runs hooks with its bundled shell, so the #!/bin/sh hook works without WSL.
• Save the hook with LF line endings. A hook with CRLF endings fails with a confusing "not found" error. Add this to .gitattributes so git keeps it right:

  .githooks/* text eol=lf

• Install gitleaks with scoop install gitleaks or winget install gitleaks, and open a new terminal so it is on your PATH.

Rolling it out to a team

1. Merge the config and hook in one pull request, with a short note in your contributing guide.
2. Ask everyone to run the one-time setup command (pre-commit install or git config core.hooksPath .githooks).
3. Keep the CI workflow (secret-scan.yml) on as well. Hooks are optional by nature: anyone can skip them with git commit --no-verify, and new clones don't have them until someone runs the setup step. CI is the layer that can't be skipped.
4. Agree a rule for skipping the hook: only for a confirmed false positive, and the allowlist fix follows in the same pull request.

When the hook stops a commit

1. Read the finding. With --redact the secret itself is hidden, but the file, line and rule are shown.
2. If it is a real secret, remove it from the file and load it from an environment variable or secrets manager instead. Then unstage and restage the file. Because the commit never happened, you don't need to rotate the key, unless it was also pasted somewhere else.
3. If it is a false positive, add a narrow entry to .gitleaks.toml (a specific value pattern or a single file path) and commit that change with the rest.

Speed

gitleaks only scans staged changes in the hook, so it is usually well under a second. If it gets slow, check that large generated files and binary assets are covered by paths in the allowlist.