security-headers()
Open source · MIT · Zero dependencies

Grade your security headers, A+ to F.

Scans any URL for HSTS, CSP, X-Frame-Options and the rest, flags dangerous values and information disclosure, then returns a single letter grade with ranked fixes. Set a minimum grade and it fails your build.

Get started View source
SECURITY HEADERS REPORT · TLS 1.3 Grade B 72/100
✓ Strict-Transport-Securitymax-age=31536000; includeSubDomains
✗ Content-Security-PolicyMISSING, add CSP to prevent XSS
✓ X-Content-Type-Optionsnosniff
✓ X-Frame-OptionsDENY
⚠ Referrer-Policyconsider strict-origin-when-cross-origin
✗ Permissions-PolicyMISSING, restrict browser features
⚠ Servernginx/1.24.0, remove version number
⚠ X-Powered-ByExpress, remove this header

Why it matters

Headers are the cheapest hardening you can ship.

A handful of response headers do a lot of quiet work. HSTS forces every connection over TLS. A well-formed Content-Security-Policy closes off most cross-site scripting. X-Frame-Options stops clickjacking. None of them need application changes, yet plenty of live sites ship without them.

The subtle failures are the ones a manual check misses: a CSP that allows unsafe-inline and undoes its own protection, or a Server header leaking an exact version that hands attackers a shortlist of known exploits. This tool weighs each header, penalises the dangerous values, and turns the result into one grade you can gate a deploy on.

How grading works

Weighted score, single letter, threshold you control.
A+
95 to 100
A
85 to 94
B
70 to 84
C
55 to 69
D
40 to 54
F
below 40

High-weight headers are HSTS and CSP. Medium weight covers X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy and Cross-Origin-Opener-Policy. Cross-Origin-Resource-Policy is low weight. Dangerous CSP values and information disclosure both cost points.

Install

No dependencies, no build step.
# Run without installing
npx @trustyourwebsite/security-headers https://example.com

# Or install globally
npm install -g @trustyourwebsite/security-headers
security-headers https://example.com

Common options

--formatjson, text, table or csv. Table is the default.
--ciExit code 1 when the grade is below the threshold.
--min-gradeMinimum grade for CI mode. Default B.
--follow-redirectsFollow HTTP redirects. On by default.
--outputWrite the report to a file.
--timeoutRequest timeout in milliseconds. Default 10000.
# Fail the build if the grade drops below B
security-headers https://example.com --ci --min-grade B

# JSON report saved to a file
security-headers https://example.com --format json --output report.json

→ also usable as a library via checkHeaders()