report

README

安全报告处理模块

这个模块提供了一个全面的安全报告处理系统，用于接收、存储和分析各种安全相关的报告，如CSP违规、XSS尝试等。

支持的报告类型

• CSP (Content Security Policy): 内容安全策略违规报告
• XSS (Cross-Site Scripting): 跨站脚本尝试
• HPKP (HTTP Public Key Pinning): HTTP公钥固定违规
• COEP (Cross-Origin Embedder Policy): 跨源嵌入策略违规
• CORP (Cross-Origin Resource Policy): 跨源资源策略违规
• COOP (Cross-Origin Opener Policy): 跨源打开者策略违规
• Feature Policy: 特性策略违规
• NEL (Network Error Logging): 网络错误日志

主要组件

1. SecurityReport: 表示单个安全报告的结构体，包含类型、时间、原始数据等信息。
2. Handler: 处理和管理报告的接口。
3. MemoryHandler: Handler接口的内存实现，用于存储和检索报告。
4. ReportServer: HTTP处理器，用于接收和处理安全报告。

使用示例

创建一个基本的安全报告服务器

package main

import (
	"log"
	"net/http"
	"security/report"
)

func main() {
	// 创建一个内存报告处理器，最多保存100条报告
	handler := report.NewMemoryHandler(100)

	// 创建报告服务器
	reportServer := report.NewReportServer(handler)

	// 为各种安全报告设置处理路由
	http.Handle("/report/csp", reportServer)
	http.Handle("/report/xss", reportServer)
	
	log.Println("安全报告服务器启动在 http://localhost:8080")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Fatalf("服务器启动失败: %v", err)
	}
}

为前端启用CSP报告

在您的HTML页面或HTTP响应头中添加CSP策略和报告URI：

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; report-uri /report/csp">

或者作为HTTP头：

Content-Security-Policy: default-src 'self'; report-uri /report/csp

查询报告数据

// 获取最近10条报告
reports, err := handler.GetRecentReports(10)

// 获取CSP类型的报告
cspReports, err := handler.GetReportsByType(report.ReportTypeCSP, 10)

// 获取报告摘要（各类型的报告数量）
summary, err := handler.GetReportsSummary()

实现自定义处理器

您可以通过实现Handler接口来创建自定义的报告处理器，例如将报告保存到数据库中：

type DatabaseHandler struct {
	db *sql.DB
}

func (h *DatabaseHandler) HandleReport(report *SecurityReport) error {
	// 将报告保存到数据库
}

func (h *DatabaseHandler) GetRecentReports(limit int) ([]*SecurityReport, error) {
	// 从数据库检索最近的报告
}

// 实现其他方法...

安全最佳实践

1. 限制报告端点的请求大小：防止DOS攻击。
2. 验证报告来源：考虑添加某种形式的API密钥或其他身份验证机制。
3. 定期清理旧报告：设置报告老化策略，防止报告积累过多。
4. 监控异常活动：如果短时间内收到大量报告，可能表明正在发生攻击。

Documentation

Index

• Constants
• func DefaultReportToJSON(endpoint string) string
• func NewReportHandlerMiddleware(opts HandlerOptions) mist.Middleware
• func WithCSPReportHandler() mist.Middleware
• func WithDefaultReportHandler() mist.Middleware
• type COOPReport
• type CSPReport
• type Handler
• type HandlerOptions
  • func DefaultHandlerOptions() HandlerOptions
• type MemoryHandler
  • func NewMemoryHandler(maxReports int) *MemoryHandler
  • func (h *MemoryHandler) GetRecentReports(limit int) ([]*SecurityReport, error)
  • func (h *MemoryHandler) GetReportsByType(reportType string, limit int) ([]*SecurityReport, error)
  • func (h *MemoryHandler) GetReportsSummary() (map[string]int, error)
  • func (h *MemoryHandler) HandleReport(r *SecurityReport) error
• type ReportServer
  • func NewReportServer(handler Handler) *ReportServer
  • func (s *ReportServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type SecurityReport
  • func ParseCSPReport(r *http.Request) (*SecurityReport, error)
  • func ParseXSSReport(r *http.Request) (*SecurityReport, error)
• type XSSReport

Constants

const (
	ReportTypeCSP      = "csp"      // 内容安全策略违规
	ReportTypeXSS      = "xss"      // XSS过滤违规
	ReportTypeCOOP     = "coop"     // 跨源打开者策略违规
	ReportTypeCOEP     = "coep"     // 跨源嵌入者策略违规
	ReportTypeCORP     = "corp"     // 跨源资源策略违规
	ReportTypeDocument = "document" // 文档策略违规
	ReportTypeHSTS     = "hsts"     // HSTS违规
	ReportTypeExpectCT = "expectct" // Expect-CT违规
	ReportTypeHPKP     = "hpkp"     // HPKP违规
	ReportTypeFeature  = "feature"  // 功能违规
	ReportTypeNEL      = "nel"      // NEL违规
)

违规报告类型

Functions

func DefaultReportToJSON

func DefaultReportToJSON(endpoint string) string

提供默认的ReportTo JSON配置

func NewReportHandlerMiddleware

func NewReportHandlerMiddleware(opts HandlerOptions) mist.Middleware

NewReportHandlerMiddleware 创建新的安全报告处理中间件

func WithCSPReportHandler

func WithCSPReportHandler() mist.Middleware

WithCSPReportHandler 只处理CSP报告的中间件

func WithDefaultReportHandler

func WithDefaultReportHandler() mist.Middleware

创建报告处理中间件的便捷函数

Types

type COOPReport

type COOPReport struct {
	DocumentURL      string `json:"document-url"`
	Disposition      string `json:"disposition"`
	EffectivePolicy  string `json:"effective-policy"`
	BlockingDocument string `json:"blocking-document"`
}

COOPReport 跨源打开者策略违规报告

type CSPReport

type CSPReport struct {
	CSPReport struct {
		DocumentURI        string `json:"document-uri"`
		Referrer           string `json:"referrer"`
		BlockedURI         string `json:"blocked-uri"`
		ViolatedDirective  string `json:"violated-directive"`
		EffectiveDirective string `json:"effective-directive"`
		OriginalPolicy     string `json:"original-policy"`
		Disposition        string `json:"disposition"`
		StatusCode         int    `json:"status-code"`
	} `json:"csp-report"`
}

CSPReport 内容安全策略违规报告

type Handler

type Handler interface {
	// HandleReport 处理安全报告
	HandleReport(r *SecurityReport) error

	// GetRecentReports 获取最近的报告
	GetRecentReports(limit int) ([]*SecurityReport, error)

	// GetReportsByType 获取指定类型的报告
	GetReportsByType(reportType string, limit int) ([]*SecurityReport, error)

	// GetReportsSummary 获取报告摘要
	GetReportsSummary() (map[string]int, error)
}

Handler 报告处理器接口

type HandlerOptions

type HandlerOptions struct {
	// 路径前缀
	PathPrefix string

	// 处理器映射 (报告类型 -> 自定义处理器)
	Handlers map[string]Handler

	// 默认处理器
	DefaultHandler Handler

	// 是否记录完整报告到日志
	LogFullReport bool
}

HandlerOptions 报告处理器中间件选项

func DefaultHandlerOptions

func DefaultHandlerOptions() HandlerOptions

DefaultHandlerOptions 默认报告处理器中间件选项

type MemoryHandler

type MemoryHandler struct {
	// contains filtered or unexported fields
}

MemoryHandler 内存报告处理器实现

func NewMemoryHandler

func NewMemoryHandler(maxReports int) *MemoryHandler

NewMemoryHandler 创建新的内存报告处理器

func (*MemoryHandler) GetRecentReports

func (h *MemoryHandler) GetRecentReports(limit int) ([]*SecurityReport, error)

GetRecentReports 实现Handler接口

func (*MemoryHandler) GetReportsByType

func (h *MemoryHandler) GetReportsByType(reportType string, limit int) ([]*SecurityReport, error)

GetReportsByType 实现Handler接口

func (*MemoryHandler) GetReportsSummary

func (h *MemoryHandler) GetReportsSummary() (map[string]int, error)

GetReportsSummary 实现Handler接口

func (*MemoryHandler) HandleReport

func (h *MemoryHandler) HandleReport(r *SecurityReport) error

HandleReport 实现Handler接口

type ReportServer

type ReportServer struct {
	// contains filtered or unexported fields
}

ReportServer 处理安全报告的HTTP服务器组件

func NewReportServer

func NewReportServer(handler Handler) *ReportServer

NewReportServer 创建新的报告服务器

func (*ReportServer) ServeHTTP

func (s *ReportServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP 实现http.Handler接口

type SecurityReport

type SecurityReport struct {
	Type        string                 `json:"type"`               // 报告类型
	Time        time.Time              `json:"time"`               // 收到时间
	RawData     json.RawMessage        `json:"raw_data"`           // 原始JSON数据
	ReportData  map[string]interface{} `json:"report_data"`        // 解析后的报告数据
	UserAgent   string                 `json:"user_agent"`         // 用户代理
	IPAddress   string                 `json:"ip_address"`         // IP地址
	BlockedURI  string                 `json:"blocked_uri"`        // 被阻止的URI
	ViolatedDir string                 `json:"violated_directive"` // 违反的指令
	Severity    int                    `json:"severity"`           // 严重程度 (1-5)
}

SecurityReport 表示通用安全报告结构

func ParseCSPReport

func ParseCSPReport(r *http.Request) (*SecurityReport, error)

ParseCSPReport 解析CSP违规报告

func ParseXSSReport

func ParseXSSReport(r *http.Request) (*SecurityReport, error)

ParseXSSReport 解析XSS过滤器报告

type XSSReport

type XSSReport struct {
	BlockedURL   string `json:"blocked-url"`
	OriginalURL  string `json:"original-url"`
	SourceLine   string `json:"source-line"`
	ColumnNumber int    `json:"column-number"`
	LineNumber   int    `json:"line-number"`
}

XSSReport XSS过滤违规报告