@hailbytes/security-headers

Analyze HTTP security headers for your web application. Get an A–F grade, per-header findings, and one-line remediation — as a library, CLI, or CI gate.

What it does

Fetches (or accepts raw header objects) and grades 7 security header categories — HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and Cross-Origin policies. Returns an A+ to F letter grade, a 0–100 percentage score, per-header findings, and specific remediation steps.

Install

npm install @hailbytes/security-headers
# or run directly
npx @hailbytes/security-headers https://example.com

Quick Start

CLI

# Scan a URL and print a color report
npx @hailbytes/security-headers https://example.com

# Output raw JSON
npx @hailbytes/security-headers https://example.com --json

# Use as a CI gate (exits 1 on grade D or F)
npx @hailbytes/security-headers https://staging.example.com || echo "Security headers gate failed"

Library — analyze a URL

import { analyze } from '@hailbytes/security-headers';

const report = await analyze('https://example.com');

console.log(report.grade);       // 'A+' | 'A' | 'B' | 'C' | 'D' | 'F'
console.log(report.score);       // 0–100
console.log(report.percentage);  // 0–100
console.log(report.headers);     // HeaderFinding[]

Library — analyze raw headers (offline / in tests)

import { analyzeHeaders } from '@hailbytes/security-headers';

const report = analyzeHeaders({
  'strict-transport-security': 'max-age=31536000; includeSubDomains',
  'content-security-policy': "default-src 'self'",
  'x-frame-options': 'DENY',
  'x-content-type-options': 'nosniff',
  'referrer-policy': 'strict-origin-when-cross-origin',
});

console.log(report.grade); // 'B' or higher
for (const h of report.headers) {
  if (h.status !== 'good') {
    console.log(h.header, h.recommendations);
  }
}

Report Shape

interface SecurityHeaderReport {
  url?: string;
  grade: 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
  score: number;
  maxScore: number;
  percentage: number;       // 0–100
  headers: HeaderFinding[]; // one per checked header
  analyzedAt: string;       // ISO 8601 timestamp
}

interface HeaderFinding {
  header: string;           // header name
  score: number;            // points earned
  maxScore: number;         // max available
  status: 'good' | 'warning' | 'missing' | 'error';
  raw?: string;             // raw header value
  findings: string[];       // what is wrong
  recommendations: string[]; // how to fix it
}

Grading Scale

| Grade | Score | |---|---| | A+ | ≥ 90% | | A | ≥ 75% | | B | ≥ 60% | | C | ≥ 40% | | D | ≥ 20% | | F | < 20% |

Headers Checked

| Header | Max Points | Key Checks | |---|---|---| | Strict-Transport-Security | 20 | max-age ≥ 1 year, includeSubDomains, preload | | Content-Security-Policy | 30 | presence, no unsafe-inline/eval, no wildcards | | X-Frame-Options | 15 | DENY or SAMEORIGIN (or CSP frame-ancestors) | | X-Content-Type-Options | 10 | nosniff | | Referrer-Policy | 10 | strict values only | | Permissions-Policy | 10 | presence | | Cross-Origin Policies | 5 | COEP, COOP, CORP |

Who Is This For

Security engineers, DevSecOps teams, and ASM platform integrations that need automated header auditing on every deployment, pentesters who run this against every target scope, and developers who want to verify their app's security posture without leaving the terminal.

See Also

• @hailbytes/asm-scope-parser — Parse and normalize attack surface scope definitions
• @hailbytes/mcp-security-scanner — Security scanner for MCP server configurations
• HailBytes ASM — Attack Surface Management platform

Part of the HailBytes open-source security toolkit.