headerguard

Scan any URL for missing or misconfigured HTTP security headers — in one command.

pip install headerguard
headerguard scan https://example.com

---

What it checks

Header	Severity	What it prevents
Strict-Transport-Security	🔴 critical	Protocol downgrade, MITM attacks
Content-Security-Policy	🟠 high	XSS, data injection
X-Frame-Options	🟠 high	Clickjacking
X-Content-Type-Options	🟡 medium	MIME sniffing
Referrer-Policy	🟡 medium	Referrer info leakage
Permissions-Policy	🟡 medium	Unrestricted camera/mic/location access
X-XSS-Protection	🟢 low	Legacy XSS filter
Cache-Control	🟢 low	Sensitive data cached by browser

---

CLI

# Scan a URL (shows coloured results + score)
headerguard scan https://yoursite.com

# JSON output (pipe to jq, CI logs, etc.)
headerguard scan https://yoursite.com --json

# Only show critical and high severity issues
headerguard scan https://yoursite.com --severity high

# Fail with exit code 1 if any check fails (CI use)
headerguard scan https://yoursite.com --fail-on-findings

# Custom timeout
headerguard scan https://yoursite.com --timeout 5

# List all available checks
headerguard checks

Example output:

HeaderGuard — https://example.com
Security Score: 42/100

  ✔ [CRITICAL] Strict-Transport-Security
  ✘ [HIGH] Content-Security-Policy
       Recommendation: Content-Security-Policy: default-src 'self'
       Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
  ✘ [HIGH] X-Frame-Options
       Recommendation: X-Frame-Options: DENY
  ...

---

Python API

from headerguard import check_headers, score

headers = {
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
    "Content-Security-Policy": "default-src 'self'",
}

results = check_headers(headers)
print(f"Score: {score(results)}/100")

for r in results:
    status = "✔" if r["passed"] else "✘"
    print(f"  {status} [{r['severity']}] {r['name']}")
    if not r["passed"]:
        print(f"    → {r['recommendation']}")

---

CI/CD

- name: Security header check
  run: |
    pip install headerguard
    headerguard scan ${{ env.PRODUCTION_URL }} --fail-on-findings --severity high

---

License

MIT © Bhupendra Tale