trustyourwebsite/security-headers
GitHub: trustyourwebsite/security-headers
零依赖的 Node.js 网站安全响应头审计工具，提供 A+ 到 F 评分并支持 CI/CD 自动化集成，帮助团队在部署阶段拦截不达标的 Header 配置。
Stars: 0 | Forks: 0
# @trustyourwebsite/security-headers
零依赖的 Node.js 工具，用于评估网站安全 headers（HSTS、CSP、X-Frame-Options 等），并提供 A+ 到 F 的评分。对 CI 友好，具有可配置的最低评级阈值。
由 [TrustYourWebsite](https://trustyourwebsite.com) 开发 —— 为欧盟小型企业提供自动化网站合规扫描。
## 快速开始
```
npx @trustyourwebsite/security-headers https://example.com
```
## 安装
```
# 全局安装
npm install -g @trustyourwebsite/security-headers
# 或者作为 dev dependency
npm install --save-dev @trustyourwebsite/security-headers
```
## 命令行用法
```
# 基本扫描
security-headers https://example.com
# JSON 输出
security-headers https://example.com --format json
# 将报告保存到文件
security-headers https://example.com --format json --output report.json
# CI 模式 — 如果等级低于 B 则失败
security-headers https://example.com --ci --min-grade B
# 所有选项
security-headers https://example.com \
--format table \
--follow-redirects \
--max-redirects 5 \
--timeout 10000 \
--user-agent "MyBot/1.0"
```
### 命令行选项
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `--format` | `table` | 输出格式：`json`、`text`、`table`、`csv` |
| `--follow-redirects` | `true` | 跟随 HTTP 重定向 |
| `--no-follow-redirects` | | 不跟随重定向 |
| `--max-redirects` | `5` | 最大重定向次数 |
| `--timeout` | `10000` | 请求超时时间（毫秒） |
| `--output` | | 将报告保存到文件 |
| `--ci` | | 如果评级低于阈值，则以退出码 1 退出 |
| `--min-grade` | `B` | CI 模式的最低评级 |
| `--user-agent` | | 自定义 User-Agent 字符串 |
## 库用法
```
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[]
```
## 输出示例
```
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
| Header | 权重 | 检查内容 |
|--------|--------|---------------|
| `Strict-Transport-Security` | 高 | max-age >= 1 年，includeSubDomains，preload |
| `Content-Security-Policy` | 高 | 危险值（unsafe-inline、unsafe-eval、通配符），指令 |
| `X-Content-Type-Options` | 中 | 必须为 `nosniff` |
| `X-Frame-Options` | 中 | DENY 或 SAMEORIGIN |
| `Referrer-Policy` | 中 | 尊重隐私的值 |
| `Permissions-Policy` | 中 | 限制危险功能 |
| `Cross-Origin-Opener-Policy` | 中 | 优先使用 same-origin |
| `Cross-Origin-Resource-Policy` | 低 | same-origin 或 same-site |
| `Cross-Origin-Embedder-Policy` | 低 | require-corp 实现隔离 |
| `Cache-Control` | 低 | 敏感页面使用 no-store 或 private |
| `X-XSS-Protection` | 低 | 已弃用 — 应为 `0` 或不存在 |
我们还会检查应该移除的**信息泄露** headers：
- `Server`（暴露软件版本）
- `X-Powered-By`（暴露框架）
- `X-AspNet-Version` / `X-AspNetMvc-Version`
## 评级系统
| 评级 | 分数 | 条件 |
|-------|-------|------------|
| A+ | 90-100 | 无任何失败项 |
| A | 80-89 | 无严重（高权重）失败项 |
| B | 65-79 | |
| C | 50-64 | |
| D | 35-49 | |
| F | 0-34 | |
## CI/CD 集成
### 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
```
## 设计决策
- **零运行时依赖。** 仅使用 Node.js 内置模块（`node:https`、`node:http`、`node:tls`、`node:fs`）。安全工具应具有最小的攻击面。
- **强大的 CSP 解析器。** 解析所有 CSP 指令，并标记带有具体修复建议的危险值。
- **CI 优先。** 带有退出码的 `--ci` 模式使其易于添加到任何流水线中。
## 要求
- Node.js 18+
## 相关项目
- [TrustYourWebsite](https://trustyourwebsite.com) — 为欧盟企业提供全面的网站合规扫描
- [@trustyourwebsite/dns-auth-check](https://github.com/trustyourwebsite/dns-auth-check) — SPF、DKIM、DMARC、BIMI 和 MTA-STS 邮件身份验证审计工具
- [@trustyourwebsite/cookie-consent-validator](https://github.com/trustyourwebsite/cookie-consent-validator) — 验证 Cookie 同意横幅是否真正在“全部拒绝”时停止跟踪
## 许可证
MIT
由 [TrustYourWebsite](https://trustyourwebsite.com) 开发 —— 我们通过自动化网站扫描帮助欧盟小型企业保持合规。[获取免费合规扫描](https://trustyourwebsite.com)。
标签：CSP, DevSecOps, GNU通用公共许可证, HSTS, HTTPS, HTTP安全头, Linux安全, MITM代理, Node.js, npx, SMB合规, X-Frame-Options, 上游代理, 二进制发布, 前端安全, 头部检测, 安全扫描, 安全标准, 安全评分, 开源工具, 时序注入, 暗色界面, 网站安全, 网络安全, 自动化攻击, 隐私保护, 零依赖