checking-http-security-headers

Checking HTTP Security Headers

Overview

HTTP response headers are the cheapest defense-in-depth layer most web apps ship. Each header closes one specific attack class — HSTS forces HTTPS, CSP blocks script injection, X-Frame-Options blocks clickjacking, etc. Missing headers don't break the app; they just leave the attack class open. This skill probes for the presence + value correctness of the canonical security-relevant headers.

When the skill produces findings

Finding	Severity	Threshold	Affected control
HSTS header missing	HIGH	No Strict-Transport-Security on HTTPS response	OWASP A05:2021
HSTS max-age below preload threshold	MEDIUM	max-age under 31536000s (1y)	hstspreload.org
HSTS includeSubDomains missing for preload	LOW	preload directive without includeSubDomains	hstspreload.org
CSP header missing	HIGH	No Content-Security-Policy header	OWASP A03:2021
CSP allows unsafe-inline	MEDIUM	script-src or style-src includes 'unsafe-inline'	OWASP A03:2021
CSP allows unsafe-eval	MEDIUM	script-src includes 'unsafe-eval'	OWASP A03:2021
CSP frame-ancestors AND X-Frame-Options both missing	HIGH	Clickjacking open	CWE-1021
X-Content-Type-Options:nosniff missing	MEDIUM	MIME-sniff attack open	OWASP A05:2021
Referrer-Policy missing or unsafe-url	MEDIUM	Cross-origin URL leakage	OWASP A05:2021
Permissions-Policy missing	LOW	Camera/mic/geo permissions unrestricted	Permissions Policy spec
Server: header discloses version	LOW	nginx/1.18.0 → fingerprintable	CWE-200
Cache-Control public on authenticated response	HIGH	Shared cache may serve user A's response to user B	CWE-525

Prerequisites

• Python 3.9+
• Authorization for non-local targets

Instructions

Step 1 — Confirm authorization

"Do you have authorization to perform header testing on this target?
 I need confirmation before proceeding."

Step 2 — Run the scanner

python3 ${CLAUDE_PLUGIN_ROOT}/skills/checking-http-security-headers/scripts/check_headers.py \
    https://example.com \
    --authorized

Options:

Usage: check_headers.py URL [OPTIONS]

Options:
  --authorized       Attest authorization (required for non-local)
  --output FILE
  --format FMT       json | jsonl | markdown (default: markdown)
  --min-severity SEV (default: info)
  --timeout SECS     Per-probe timeout (default: 10)
  --authenticated    Treat as authenticated endpoint (stricter Cache-Control gate)

Step 3 — Interpret findings

HIGH = open exploitable class (no HSTS = MITM downgrade open; no CSP = XSS class wide open; no clickjacking guard = UI-redress attacks). MEDIUM/LOW = posture hardening.

Step 4 — Cross-skill chaining

• After this skill, suggest auditing-cors-policy (#3) — CSP and CORS interact; certain CSP directives need matching CORS headers.
• For HSTS preload submission, see references/PLAYBOOK.md § HSTS preload checklist.

Examples

Example 1 — Mozilla Observatory grade improvement

User: "Observatory gives us a D. What's missing?"

python3 ${CLAUDE_PLUGIN_ROOT}/skills/checking-http-security-headers/scripts/check_headers.py \
    https://example.com \
    --authorized \
    --format markdown

The Markdown report groups by severity; map each finding to the PLAYBOOK.md snippet for the target server type. Observatory grade typically moves D → B after addressing all HIGH findings.

Example 2 — HSTS preload eligibility pre-submission

User: "We want to submit to hstspreload.org. Is our HSTS config ready?"

python3 ${CLAUDE_PLUGIN_ROOT}/skills/checking-http-security-headers/scripts/check_headers.py \
    https://example.com \
    --authorized --min-severity low

Look for "HSTS max-age below preload threshold" and "includeSubDomains missing" — both must clear before submission, OR hstspreload.org will reject.

Example 3 — Authenticated-endpoint Cache-Control sweep

User: "We had a Cache-Control bug last quarter where authenticated responses got cached publicly. Audit /api/* to make sure it's fixed."

python3 ${CLAUDE_PLUGIN_ROOT}/skills/checking-http-security-headers/scripts/check_headers.py \
    https://api.example.com/me \
    --authorized --authenticated

The --authenticated flag bumps Cache-Control posture from MEDIUM to HIGH and adds a check for Cache-Control: public (forbidden on authenticated content).

Output

JSON / JSONL / Markdown. Exit codes 0 / 1 / 2 per lib/report.py.

Error Handling

• No HTML response → INFO finding noting headers may not apply (JSON APIs use a subset of headers).
• Redirect to login → follows once, audits the destination page.
• Connection error → exit 2.

Resources

• references/THEORY.md — Per-header reasoning, attack-class mapping
• references/PLAYBOOK.md — Config snippets per server type for each required header
• ../analyzing-tls-config/references/AUTHORIZATION.md — Active-scan authorization