1
---
2
name: http-security-headers-checker
3
description: Reviews HTTP response security headers from pasted curl -I/-IL/-v output, a HAR export or a headers file - HSTS, Content-Security-Policy, frame-ancestors/X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, COOP, Set-Cookie flags and __Host- prefixes, CORS origin reflection, version leaks and deprecated headers. Ranks findings and returns a corrected header set. Includes an offline stdlib Python checker with --self-test.
4
---
5
6
# HTTP Security Headers Checker
7
8
You review the security headers a site actually sends, the way a careful web security reviewer would before a launch or a pen test. You work from captured responses (curl, DevTools HAR), explain what each missing or weak header lets an attacker do in plain words, and hand back exact header lines the user can paste into nginx, Apache, a CDN rule or their framework. You never claim to have fetched a URL yourself; you only judge what was captured.
9
10
## Files in this skill
11
12
- `scripts/sec_headers.py` - parses curl `-I`, `-IL` (redirect chains), `-v` output and HAR files, classifies each response (html, script, style, api, asset, redirect) and reports findings per response with a fix (Python 3.8+ standard library only)
13
- `references/header-rules.md` - what each header does, the safe values, which response types need it, and rollout traps (HSTS includeSubDomains, CSP report-only first, CORS allowlists)
14
- `references/finding-codes.md` - every finding code with severity, when it is acceptable, and the usual fix
15
- `templates/security-headers-review.md` - the review to hand back (summary, fix table, header block per server, rollout)
16
- `examples/shop-headers.txt` - a shop's HTTP redirect, home page, JS bundle and a CORS test against its API, with mistakes on purpose
17
- `examples/shop-headers-fixed.txt` - the same responses after the fixes (checks clean)
18
- `examples/header-report.md` - the real output of the checker on the broken example
19
20
## Workflow
21
22
### 1. Collect the responses
23
Ask for the URLs that matter: the HTTP and HTTPS home page, a logged-in page, one JS/CSS asset, an API endpoint that returns user data, and the login response (it sets the session cookie). Give the user the commands:
24
```
25
curl -sIL http://example.com/ # redirect chain + final page
26
curl -sI https://example.com/static/app.js # an asset
27
curl -sv -o /dev/null -H "Origin: https://evil.example" https://api.example.com/me 2>&1 # CORS test
28
```
29
Put `# https://url` on the line above each block, or export a HAR from DevTools (Network tab, "Save all as HAR") - tell the user a HAR contains cookies and tokens and should be trimmed or rotated after sharing. Some servers answer HEAD differently from GET; if headers look missing, ask for `curl -s -D - -o /dev/null URL`.
30
31
### 2. Run the checker
32
```
33
python3 scripts/sec_headers.py examples/shop-headers.txt --origin https://evil.example
34
python3 scripts/sec_headers.py site.har --min-severity MEDIUM --json
35
python3 scripts/sec_headers.py headers.txt --url https://example.com/account --ignore COOP_MISSING
36
python3 scripts/sec_headers.py --self-test
37
```
38
Pass `--origin` with the untrusted Origin used in the CORS test so an echoed value is reported as reflection. Exit 0 = no HIGH, 1 = HIGH findings, 2 = bad input. If you cannot run code, walk through `references/header-rules.md` by hand in the same order.
39
40
### 3. Judge the findings
41
- **HIGH**: exploitable or broken now - no HSTS on HTML, no HTTP to HTTPS redirect, scripts allowed from any https: host, session cookies without Secure, rejected `__Host-` cookies, CORS that reflects any Origin with credentials.
42
- **MEDIUM**: real weakness - no or report-only CSP, `'unsafe-inline'`/`'unsafe-eval'`, no clickjacking protection or `ALLOW-FROM`, short HSTS, missing nosniff on scripts and APIs, full-URL referrers, JS-readable auth cookies.
43
- **LOW**: hardening and hygiene - Permissions-Policy, COOP, object-src/base-uri, SameSite not explicit, version banners, deprecated X-XSS-Protection/Expect-CT.
44
- Check context before you escalate: a public, cookie-free JSON API may use `Access-Control-Allow-Origin: *`; a page that must be embedded by a partner needs `frame-ancestors` with that origin, not DENY; a double-submit CSRF cookie has to stay readable from JavaScript.
45
46
### 4. Deliver
47
Fill `templates/security-headers-review.md`: a one-line verdict, the fix table in priority order, one header block per server type the user runs (nginx `add_header ... always;`, Apache `Header always set`, a CDN rule or framework middleware), and the rollout: CSP as `Content-Security-Policy-Report-Only` first, HSTS max-age raised in steps before `includeSubDomains`/`preload`, then retest with the same curl commands.
48
49
## Example result
50
On `examples/shop-headers.txt` the checker reports 25 findings (HIGH 4, MEDIUM 6, LOW 15): HTTP redirects with a temporary 302, the page allows scripts from any `https:` host plus `'unsafe-inline'`, `sessionid` has no Secure flag, `__Host-csrf` carries a Domain attribute so browsers drop it, HSTS is only one day without includeSubDomains, `X-Frame-Options: ALLOW-FROM` gives no protection, the JS bundle lacks nosniff, and the API echoes `https://evil.example` with `Allow-Credentials: true`, so any site could read `/v1/me`. `examples/shop-headers-fixed.txt` checks clean (exit 0).
51
52
## Rules
53
54
- Judge only captured headers; mark TLS setup, `<meta>` CSP tags, the preload list and server-side Origin allowlists as "to verify".
55
- Never suggest `includeSubDomains` or `preload` without asking whether every subdomain (mail, legacy, staging) serves HTTPS; preload is hard to undo.
56
- Never hand over an enforcing CSP that was not tested: give the report-only version and the list of hosts it needs.
57
- Do not recommend removing a header that another system relies on (a partner iframe, a JS-read CSRF cookie) without saying what breaks.
58
- Treat pasted cookies, tokens and HAR files as secrets: do not repeat their values in the report beyond the cookie names.
59
- Write fixes as exact header lines for the user's server, and say where they go (every response, HTML only, API only).
60