🛡️ 安全响应头过滤器

📖 简介

安全响应头过滤器用于向HTTP响应中添加各种安全相关的响应头，提高应用的安全性，防范常见的Web安全攻击。

为什么需要安全响应头？

防止点击劫持攻击 (Clickjacking)
防止MIME类型嗅探攻击
增强XSS防护
强制HTTPS传输
控制浏览器权限
设置内容安全策略

⚙️ 配置说明

基础配置

yaml

gateway:
  filter:
    secure-headers:
      enabled: true                    # 是否启用安全响应头过滤器
      rules:                          # 安全响应头规则列表
        - urls:                       # 匹配的URL路径
            - /**
          forbid-urls:                # 排除的URL路径（可选）
            - /public/**
          disabled-policies:          # 禁用的安全策略列表（可选）
            - "strict-transport-security"  # 禁用HTTPS强制传输
          x-frame-options: "DENY"     # 防止点击劫持（覆盖默认值）
          x-content-type-options: "nosniff"  # 防止MIME嗅探（覆盖默认值）
          # ... 其他安全头配置

完整配置示例

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        # 使用默认安全策略
        - urls:
            - /**
          forbid-urls:
            - /public/**
            - /assets/**
          disabled-policies:                    # 禁用特定策略
            - "strict-transport-security"       # HTTP环境下禁用HSTS
          custom-headers:
            X-Custom-Security: "enabled"
            X-Gateway-Version: "1.0.0"
        
        # 完全自定义策略
        - urls:
            - /admin/**
          x-frame-options: "DENY"
          x-content-type-options: "nosniff"
          x-xss-protection: "1; mode=block"
          strict-transport-security: "max-age=31536000; includeSubDomains"
          content-security-policy: "default-src 'self'; script-src 'self' 'unsafe-inline'"
          referrer-policy: "strict-origin-when-cross-origin"
          permissions-policy: "geolocation=(), microphone=(), camera=()"
          cross-origin-embedder-policy: "require-corp"
          cross-origin-opener-policy: "same-origin"
          cross-origin-resource-policy: "same-origin"
        
        # API接口特殊策略
        - urls:
            - /api/**
          disabled-policies:
            - "x-frame-options"                 # API不需要防点击劫持
            - "permissions-policy"              # API不需要权限策略
          content-security-policy: "default-src 'none'"  # 覆盖默认CSP
          custom-headers:
            X-API-Version: "v1"

🔧 默认值处理和策略禁用

默认安全响应头

过滤器内置了一套安全的默认响应头配置：

响应头	默认值	说明
X-Frame-Options	`DENY`	完全禁止页面嵌入iframe
X-Content-Type-Options	`nosniff`	禁止MIME类型嗅探
X-XSS-Protection	`1; mode=block`	启用XSS防护并阻止攻击
Referrer-Policy	`strict-origin-when-cross-origin`	严格的引用策略
Permissions-Policy	`camera=(), microphone=(), geolocation=()`	禁用敏感权限
Cross-Origin-Embedder-Policy	`require-corp`	要求跨域资源策略
Cross-Origin-Opener-Policy	`same-origin`	限制跨域窗口打开
Cross-Origin-Resource-Policy	`same-origin`	限制跨域资源访问

使用默认配置

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        - urls:
            - /**

禁用特定策略

通过 disabled-policies 可以禁用不需要的默认安全策略：

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        - urls:
            - /**
          disabled-policies:          # 禁用特定策略
            - "strict-transport-security"    # HTTP环境下禁用HSTS
            - "x-frame-options"              # 允许页面嵌入
            - "permissions-policy"           # 不限制浏览器权限

覆盖默认值

如果配置了具体的响应头值，会覆盖默认值：

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        - urls:
            - /**
          x-frame-options: "SAMEORIGIN"        # 覆盖默认的DENY
          content-security-policy: "default-src 'self'"  # 添加CSP（默认未设置）

支持的禁用策略名称

策略名称	对应响应头
`x-frame-options`	X-Frame-Options
`x-content-type-options`	X-Content-Type-Options
`x-xss-protection`	X-XSS-Protection
`strict-transport-security`	Strict-Transport-Security
`content-security-policy`	Content-Security-Policy
`referrer-policy`	Referrer-Policy
`permissions-policy`	Permissions-Policy
`cross-origin-embedder-policy`	Cross-Origin-Embedder-Policy
`cross-origin-opener-policy`	Cross-Origin-Opener-Policy
`cross-origin-resource-policy`	Cross-Origin-Resource-Policy

📋 支持的安全响应头

标准安全响应头

响应头	配置字段	说明	推荐值
X-Frame-Options	`x-frame-options`	防止点击劫持攻击	`DENY` 或 `SAMEORIGIN`
X-Content-Type-Options	`x-content-type-options`	防止MIME类型嗅探	`nosniff`
X-XSS-Protection	`x-xss-protection`	XSS防护	`1; mode=block`
Strict-Transport-Security	`strict-transport-security`	强制HTTPS	`max-age=31536000; includeSubDomains`
Content-Security-Policy	`content-security-policy`	内容安全策略	根据应用需求配置
Referrer-Policy	`referrer-policy`	引用策略	`strict-origin-when-cross-origin`
Permissions-Policy	`permissions-policy`	权限策略	`geolocation=(), microphone=(), camera=()`

跨域安全响应头

响应头	配置字段	说明	推荐值
Cross-Origin-Embedder-Policy	`cross-origin-embedder-policy`	跨域嵌入策略	`require-corp`
Cross-Origin-Opener-Policy	`cross-origin-opener-policy`	跨域开启策略	`same-origin`
Cross-Origin-Resource-Policy	`cross-origin-resource-policy`	跨域资源策略	`same-origin`

自定义响应头

yaml

custom-headers:
  X-Custom-Security: "enabled"
  X-Gateway-Version: "1.0.0"
  X-Rate-Limit: "1000"

🔧 配置详解

X-Frame-Options

防止页面被嵌入到iframe中，预防点击劫持攻击。

yaml

x-frame-options: "DENY"          # 完全禁止嵌入
# 或
x-frame-options: "SAMEORIGIN"    # 只允许同源嵌入

Content-Security-Policy

内容安全策略，控制页面可以加载的资源。

yaml

# 基础策略
content-security-policy: "default-src 'self'"

# 详细策略
content-security-policy: "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.example.com; style-src 'self' 'unsafe-inline'"

# API接口策略
content-security-policy: "default-src 'none'"

Strict-Transport-Security

强制使用HTTPS连接。

yaml

# 基础配置
strict-transport-security: "max-age=31536000"

# 包含子域名
strict-transport-security: "max-age=31536000; includeSubDomains"

# 包含预加载
strict-transport-security: "max-age=31536000; includeSubDomains; preload"

Permissions-Policy

控制浏览器功能权限。

yaml

# 禁用所有权限
permissions-policy: "geolocation=(), microphone=(), camera=()"

# 允许同源使用
permissions-policy: "geolocation=(self), microphone=(self)"

# 允许特定域名
permissions-policy: "geolocation=(self \"https://example.com\")"

🎯 使用场景

Web应用安全加固

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        # 使用默认安全配置，简化配置
        - urls:
            - /**
          disabled-policies:
            - "strict-transport-security"  # HTTP环境下禁用
          # 只需要配置特殊的响应头
          content-security-policy: "default-src 'self'; script-src 'self' 'unsafe-inline'"

API接口安全

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        - urls:
            - /api/**
          disabled-policies:
            - "x-frame-options"      # API不需要防点击劫持
            - "permissions-policy"   # API不需要权限控制
          content-security-policy: "default-src 'none'"  # 覆盖默认CSP
          custom-headers:
            X-API-Version: "v1"
            X-Rate-Limit: "1000"

静态资源优化

yaml

gateway:
  filter:
    secure-headers:
      enabled: true
      rules:
        - urls:
            - /static/**
            - /assets/**
          forbid-urls:
            - /static/public/**
          x-content-type-options: "nosniff"
          cross-origin-resource-policy: "cross-origin"

💡 最佳实践

安全配置建议

使用默认配置
- 通过 disabled-policies 禁用不适用的策略
- 只配置需要特殊处理的响应头
分层配置
- 全站基础安全策略（使用默认值）
- API接口专用策略（禁用不必要的策略）
- 静态资源特殊处理
环境适配
- HTTP环境禁用 strict-transport-security
- 开发环境可以放宽某些策略
- 生产环境使用最严格的配置
CSP策略
- 从严格开始，逐步放宽
- 使用nonce或hash值
- 定期审查和更新
HTTPS强制
- 生产环境必须启用HSTS
- 包含子域名保护
- 考虑预加载列表

性能优化

响应头缓存
- 静态资源使用长期缓存
- 动态内容合理设置
条件应用
- 使用forbid-urls排除不需要的路径
- 避免重复设置相同的头

兼容性考虑

浏览器支持
- 检查目标浏览器兼容性
- 提供降级方案
第三方集成
- 考虑嵌入式应用需求
- 调整跨域策略

📊 监控与调试

响应头验证

bash

# 检查响应头
curl -I https://example.com/api/test

# 查看安全评分
# 使用在线工具如 securityheaders.com

日志监控

yaml

log:
  level: debug  # 开启调试日志查看响应头设置情况

常见问题

CSP策略过严
- 检查浏览器控制台错误
- 逐步调整策略
iframe嵌入问题
- 调整X-Frame-Options设置
- 考虑业务需求
第三方资源加载失败
- 更新CSP白名单
- 检查跨域设置

⚠️ 注意事项

配置测试
- 在测试环境充分验证
- 避免影响正常功能
渐进部署
- 先启用报告模式
- 逐步切换到强制模式
定期更新
- 关注安全最佳实践
- 更新安全策略
业务兼容
- 考虑现有业务影响
- 提供过渡方案

重要提示

安全响应头配置需要谨慎测试
CSP策略可能影响页面功能
HSTS一旦启用难以撤销
建议分阶段部署

🛡️ 安全响应头过滤器 ​

📖 简介 ​

⚙️ 配置说明 ​

基础配置 ​

完整配置示例 ​

🔧 默认值处理和策略禁用 ​

默认安全响应头 ​

使用默认配置 ​

禁用特定策略 ​

覆盖默认值 ​

支持的禁用策略名称 ​

📋 支持的安全响应头 ​

标准安全响应头 ​

跨域安全响应头 ​

自定义响应头 ​

🔧 配置详解 ​

X-Frame-Options ​

Content-Security-Policy ​

Strict-Transport-Security ​

Permissions-Policy ​

🎯 使用场景 ​

Web应用安全加固 ​

API接口安全 ​

静态资源优化 ​

💡 最佳实践 ​

安全配置建议 ​

性能优化 ​

兼容性考虑 ​

📊 监控与调试 ​

响应头验证 ​

日志监控 ​

常见问题 ​

⚠️ 注意事项 ​

🔗 相关链接 ​

🛡️ 安全响应头过滤器

📖 简介

⚙️ 配置说明

基础配置

完整配置示例

🔧 默认值处理和策略禁用

默认安全响应头

使用默认配置

禁用特定策略

覆盖默认值

支持的禁用策略名称

📋 支持的安全响应头

标准安全响应头

跨域安全响应头

自定义响应头

🔧 配置详解

X-Frame-Options

Content-Security-Policy

Strict-Transport-Security

Permissions-Policy

🎯 使用场景

Web应用安全加固

API接口安全

静态资源优化

💡 最佳实践

安全配置建议

性能优化

兼容性考虑

📊 监控与调试

响应头验证

日志监控

常见问题

⚠️ 注意事项

🔗 相关链接