@trustyourwebsite/security-headers

Zero-dependency Node.js tool that grades website security headers (HSTS, CSP, X-Frame-Options, etc.) with A+ to F scoring. CI-friendly with configurable minimum grade threshold.

Built by TrustYourWebsite — automated website compliance scanning for EU small businesses.

Quick Start

npx @trustyourwebsite/security-headers https://example.com

Installation

# Global install
npm install -g @trustyourwebsite/security-headers

# Or as a dev dependency
npm install --save-dev @trustyourwebsite/security-headers

CLI Usage

# Basic scan
security-headers https://example.com

# JSON output
security-headers https://example.com --format json

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

# CI mode — fail if grade below B
security-headers https://example.com --ci --min-grade B

# All options
security-headers https://example.com \
  --format table \
  --follow-redirects \
  --max-redirects 5 \
  --timeout 10000 \
  --user-agent "MyBot/1.0"

CLI Options

Option	Default	Description
--format	table	Output format: json, text, table, csv
--follow-redirects	true	Follow HTTP redirects
--no-follow-redirects		Do not follow redirects
--max-redirects	5	Maximum redirect hops
--timeout	10000	Request timeout in milliseconds
--output		Save report to file
--ci		Exit code 1 if grade below threshold
--min-grade	B	Minimum grade for CI mode
--user-agent		Custom User-Agent string

Library Usage

import { checkHeaders } from '@trustyourwebsite/security-headers';

const result = await checkHeaders('https://example.com', {
  followRedirects: true,
  timeout: 10000,
});

console.log(result.grade);  // 'A+' | 'A' | 'B' | 'C' | 'D' | 'F'
console.log(result.score);  // 0-100
console.log(result.headers); // HeaderResult[]

Output Example

Security Headers Report
=======================
URL:    https://example.com
Grade:  B (72/100)
TLS:    TLS 1.3

Headers:
  ✓ Strict-Transport-Security        max-age=31536000; includeSubDomains
  ✗ Content-Security-Policy           MISSING — Add CSP to prevent XSS attacks
  ✓ X-Content-Type-Options            nosniff
  ✓ X-Frame-Options                   DENY
  ⚠ Referrer-Policy                   no-referrer-when-downgrade — Consider strict-origin-when-cross-origin
  ✗ Permissions-Policy                MISSING — Restrict access to browser features
  ✓ X-XSS-Protection                  0 (correctly disabled)
  ✗ Cross-Origin-Opener-Policy        MISSING

Information Disclosure:
  ⚠ Server: nginx/1.24.0 — Remove version number
  ⚠ X-Powered-By: Express — Remove this header

Recommendations:
  1. Add Content-Security-Policy header (HIGH priority)
  2. Add Permissions-Policy header (MEDIUM priority)
  3. Remove server version from Server header (LOW priority)

Full website compliance scan → https://trustyourwebsite.com

Headers Checked

Header	Weight	What We Check
Strict-Transport-Security	High	max-age >= 1 year, includeSubDomains, preload
Content-Security-Policy	High	Dangerous values (unsafe-inline, unsafe-eval, wildcards), directives
X-Content-Type-Options	Medium	Must be nosniff
X-Frame-Options	Medium	DENY or SAMEORIGIN
Referrer-Policy	Medium	Privacy-respecting values
Permissions-Policy	Medium	Dangerous features restricted
Cross-Origin-Opener-Policy	Medium	same-origin preferred
Cross-Origin-Resource-Policy	Low	same-origin or same-site
Cross-Origin-Embedder-Policy	Low	require-corp for isolation
Cache-Control	Low	no-store or private for sensitive pages
X-XSS-Protection	Low	Deprecated — should be 0 or absent

We also check for information disclosure headers that should be removed:

• Server (reveals software version)
• X-Powered-By (reveals framework)
• X-AspNet-Version / X-AspNetMvc-Version

Grading System

Grade	Score	Conditions
A+	90-100	No fails of any kind
A	80-89	No critical (high severity) fails
B	65-79
C	50-64
D	35-49
F	0-34

CI/CD Integration

GitHub Actions

- name: Check security headers
  run: npx @trustyourwebsite/security-headers https://your-site.com --ci --min-grade B

GitLab CI

security-headers:
  script:
    - npx @trustyourwebsite/security-headers https://your-site.com --ci --min-grade B

Design Decisions

• Zero runtime dependencies. Uses only Node.js built-in modules (node:https, node:http, node:tls, node:fs). Security tools should have minimal attack surface.
• Robust CSP parser. Parses all CSP directives and flags dangerous values with specific remediation advice.
• CI-first. --ci mode with exit codes makes it easy to add to any pipeline.

Requirements

• Node.js 18+

Related

• TrustYourWebsite — Full website compliance scanning for EU businesses
• @trustyourwebsite/dns-auth-check — SPF, DKIM, DMARC, BIMI and MTA-STS email authentication auditor
• @trustyourwebsite/cookie-consent-validator — Verify cookie consent banners actually stop tracking on "Reject All"

License

MIT

---

Built by TrustYourWebsite — we help EU small businesses stay compliant with automated website scanning. Get a free compliance scan.