Security Headers skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Security Headers"
  short_description: "Every response, every header, one layer"
  default_prompt: "$security-headers Our scanner says we're missing security headers — fix them in nginx"

#!/usr/bin/env python3
"""Audit HTTP security response headers for one or more URLs.

Usage: python3 audit_headers.py [--insecure] URL [URL ...]

Sends a GET per URL without following redirects; a 3xx is checked only for
HSTS and disclosure headers, and its Location is printed so you can audit it. Prints a verdict per header: ok, weak, missing,
remove, duplicate. Exit 0 when every URL passes, 1 when any header is missing,
weak, duplicated or should be removed, 2 on usage or connection errors.
Standard library only.
"""
import re
import ssl
import sys
import urllib.error
import urllib.request


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):  # report the 3xx itself
        return None


def check_hsts(v, https):
    if not https:
        return "info", "not expected on plain HTTP"
    if v is None:
        return "missing", "add max-age=63072000; includeSubDomains"
    m = re.search(r"max-age\s*=\s*\"?(\d+)", v, re.I)
    age = int(m.group(1)) if m else 0
    if age < 15552000:
        return "weak", f"max-age={age} (< 180 days; fine only during staged rollout)"
    note = "includeSubDomains" if "includesubdomains" in v.lower() else "no includeSubDomains"
    return "ok", f"max-age={age}, {note}"


def check_equals(expected):
    def f(v, _https):
        if v is None:
            return "missing", f"set {expected}"
        return ("ok", v) if v.strip().lower() == expected.lower() else ("weak", f"{v!r}, expected {expected}")
    return f


def check_referrer(v, _https):
    good = {"no-referrer", "strict-origin-when-cross-origin", "same-origin", "strict-origin", "no-referrer-when-downgrade"}
    if v is None:
        return "missing", "set strict-origin-when-cross-origin (browser default, but be explicit)"
    last = v.split(",")[-1].strip().lower()
    if last in ("unsafe-url", "origin-when-cross-origin", "origin"):
        return "weak", f"{v} leaks full URLs or origins cross-site"
    return ("ok", v) if last in good else ("weak", v)


def check_frames(headers, _https):
    csp = headers.get("content-security-policy") or ""
    xfo = headers.get("x-frame-options")
    if "frame-ancestors" in csp.lower():
        return "ok", "CSP frame-ancestors" + (f" + XFO {xfo}" if xfo else "")
    if xfo and xfo.strip().upper() in ("DENY", "SAMEORIGIN"):
        return "ok", f"X-Frame-Options {xfo}"
    return "missing", "add CSP frame-ancestors 'self' (and X-Frame-Options DENY)"


def check_csp(v, _https):
    if v is None:
        return "missing", "see content-security-policy skill"
    low = v.lower()
    issues = []
    if "script-src" not in low and "default-src" not in low:
        issues.append("no script-src")
    if "'unsafe-inline'" in low and "nonce-" not in low and "sha256-" not in low:
        issues.append("unsafe-inline without nonce/hash")
    if "object-src" not in low and "default-src 'none'" not in low:
        issues.append("no object-src")
    return ("weak", "; ".join(issues)) if issues else ("ok", "present")


SIMPLE = {
    "x-content-type-options": check_equals("nosniff"),
    "referrer-policy": check_referrer,
    "content-security-policy": check_csp,
}
OPTIONAL = ["permissions-policy", "cross-origin-opener-policy", "cross-origin-resource-policy", "cross-origin-embedder-policy"]
REMOVE = {"x-powered-by": "version disclosure", "x-aspnet-version": "version disclosure",
          "x-aspnetmvc-version": "version disclosure", "public-key-pins": "obsolete", "expect-ct": "obsolete"}
TRACKED = ["strict-transport-security", "content-security-policy", "x-frame-options", "x-content-type-options",
           "referrer-policy", "permissions-policy", "cross-origin-opener-policy"]


def audit(url, ctx):
    opener = urllib.request.build_opener(NoRedirect, urllib.request.HTTPSHandler(context=ctx))
    req = urllib.request.Request(url, headers={"User-Agent": "audit-headers/1.0"})
    try:
        resp = opener.open(req, timeout=15)
    except urllib.error.HTTPError as e:  # 3xx/4xx/5xx still carry headers
        resp = e
    status = resp.status if hasattr(resp, "status") else resp.code
    raw = resp.headers
    headers = {k.lower(): v for k, v in raw.items()}
    https = url.lower().startswith("https://")
    rows = []
    v, n = check_hsts(headers.get("strict-transport-security"), https)
    rows.append(("strict-transport-security", v, n))
    if 300 <= status < 400:  # redirects need HSTS and no disclosure; page headers matter on the target
        rows.append(("(redirect)", "info", f"-> {headers.get('location', '?')}; audit the target URL too"))
        return status, rows + disclosure_rows(raw, headers)
    for name, fn in SIMPLE.items():
        verdict, note = fn(headers.get(name), https)
        rows.append((name, verdict, note))
    verdict, note = check_frames(headers, https)
    rows.append(("frame protection", verdict, note))
    for name in OPTIONAL:
        val = headers.get(name)
        rows.append((name, "ok" if val else "info", val or "not set (recommended unless it breaks a flow)"))
    return status, rows + disclosure_rows(raw, headers)


def disclosure_rows(raw, headers):
    rows = []
    xxss = headers.get("x-xss-protection")
    if xxss is not None and xxss.strip() != "0":
        rows.append(("x-xss-protection", "remove", f"{xxss!r}; set 0 or remove"))
    for name, why in REMOVE.items():
        if name in headers:
            rows.append((name, "remove", f"{headers[name]!r}: {why}"))
    server = headers.get("server")
    if server and re.search(r"\d", server):
        rows.append(("server", "remove", f"{server!r} discloses a version"))
    for name in TRACKED:
        count = len(raw.get_all(name) or [])
        if count > 1:
            rows.append((name, "duplicate", f"sent {count} times; keep one layer"))
    return rows


def main(argv):
    insecure = "--insecure" in argv
    urls = [a for a in argv if a != "--insecure"]
    if not urls:
        print(__doc__.strip(), file=sys.stderr)
        return 2
    ctx = ssl.create_default_context()
    if insecure:
        ctx.check_hostname = False
        ctx.verify_mode = ssl.CERT_NONE
    failed = False
    for url in urls:
        try:
            status, rows = audit(url, ctx)
        except (urllib.error.URLError, OSError, ValueError) as e:
            print(f"\n{url}\n  ERROR: {e}")
            return 2
        print(f"\n{url}  [HTTP {status}]")
        for name, verdict, note in rows:
            print(f"  {verdict:<9} {name:<30} {note}")
            if verdict in ("missing", "weak", "remove", "duplicate"):
                failed = True
    print("\nRESULT:", "FAIL" if failed else "PASS")
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))