headers-check ⚡

Instant security header audit for any URL. No setup, no signup, no config.

npx headers-check example.com

That's it. Or run directly from GitHub:

npx github:kai-learner/headers-check example.com

Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Security Header Audit
  https://github.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Score: [████████████████░░░░] B (79/100)

  ⚠ Content-Security-Policy
    Value: default-src 'none'; ...
    › 'unsafe-inline' weakens XSS protection
    › Wildcard (*) source defeats the purpose of CSP

  ✓ Strict-Transport-Security — max-age=31536000; includeSubdomains; preload
  ✓ X-Frame-Options — deny
  ✓ X-Content-Type-Options — nosniff
  ✓ Referrer-Policy — strict-origin-when-cross-origin
  ✗ Permissions-Policy
    LOW — Controls browser feature access (camera, mic, geolocation, etc.)
    Fix: camera=(), microphone=(), geolocation=(), payment=(), usb=()

What It Checks

Header	Severity	Why It Matters
Content-Security-Policy	🔴 HIGH	Prevents XSS from loading external scripts
Strict-Transport-Security	🔴 HIGH	Forces HTTPS, blocks SSL stripping
X-Frame-Options	🟡 MEDIUM	Stops clickjacking via iframes
X-Content-Type-Options	🟡 MEDIUM	Prevents MIME sniffing attacks
Referrer-Policy	🔵 LOW	Controls URL leakage in Referer header
Permissions-Policy	🔵 LOW	Restricts browser feature access
X-XSS-Protection	⚪ INFO	Legacy XSS filter (deprecated, but noted)

It doesn't just check presence — it validates values too:

• CSP: flags unsafe-inline, unsafe-eval, wildcard sources
• HSTS: flags short max-age, missing includeSubDomains
• X-Frame-Options: flags unexpected values
• And more

Usage

# Check a domain (https:// auto-added)
npx headers-check example.com

# Check a full URL
npx headers-check https://api.example.com

# Multiple targets
npx headers-check example.com api.example.com staging.example.com

# JSON output (for CI/scripting)
npx headers-check example.com --json

# Help
npx headers-check --help

Install Globally

npm install -g headers-check
headers-check example.com

Exit Codes

Code	Meaning
0	All HIGH-severity headers present
1	One or more HIGH-severity headers missing, or request failed

This makes it usable in CI pipelines:

# GitHub Actions example
- name: Check security headers
  run: npx headers-check ${{ env.DEPLOY_URL }}

JSON Output

npx headers-check example.com --json

{
  "url": "https://example.com",
  "score": 65,
  "grade": "C",
  "missing": [...],
  "warned": [...],
  "passing": [...],
  "results": [...]
}

Bug Bounty Use Case

Looking for missing security headers on bug bounty targets? This is your scanner:

# Quick audit — exits 1 if HIGH headers missing (good for scripting)
npx headers-check https://target.com

# Get the full data for your report
npx headers-check https://target.com --json | jq '.missing[] | select(.severity == "HIGH")'

Read more: Missing Security Headers: The Easiest Bug Bounty Findings Nobody Talks About

Scoring

• HIGH header present + no warnings: 20 pts
• MEDIUM header present + no warnings: 10 pts
• LOW header present + no warnings: 5 pts
• INFO header present: 2 pts
• Any header present but with warnings: 50% of pts
• Missing: 0 pts

Grade	Score
A+	90–100
A	80–89
B	70–79
C	60–69
D	40–59
F	0–39

No Dependencies (Almost)

Only runtime dependency: chalk for terminal colors. Everything else is Node.js built-ins. Works on Node 16+.

License

MIT