Coraza审计日志完全解析：JSON、OCSF格式深度剖析与实战指南

【免费下载链接】coraza OWASP Coraza WAF is a golang modsecurity compatible web application firewall library 项目地址: https://gitcode.com/gh_mirrors/co/coraza

OWASP Coraza WAF作为一款高性能的Golang ModSecurity兼容Web应用防火墙库，其审计日志系统是安全监控和事件分析的核心组件。本文将深入解析Coraza审计日志的两种主要格式——JSON和OCSF，帮助您全面掌握Coraza审计日志的配置、解析和优化技巧。🚀

📊 Coraza审计日志架构概览

Coraza的审计日志系统位于internal/auditlog/目录，采用模块化设计，包含三个核心组件：

1. Log Writer - 负责将日志写入适当的流
2. Log Formatter - 将AuditLog结构转换为二进制表示
3. Logger - 包含目录、权限等配置

审计日志支持多种输出格式，其中最常用的是JSON格式和OCSF格式，分别对应formats_json.go和formats_ocsf.go两个核心文件。

🔍 JSON格式审计日志详解

JSON格式是Coraza审计日志的默认格式，提供简洁明了的日志结构。让我们看看如何配置和使用JSON审计日志：

JSON格式配置示例

// 启用JSON格式审计日志
waf, err := coraza.NewWAF(coraza.NewWAFConfig().
    WithAuditLog(
        coraza.AuditLogConfig{
            Enabled:     true,
            Formatter:   auditlog.JSONFormatter{},
            Writer:      auditlog.NewHTTPSWriter(),
            Parts:       "ABCDEFGHIJKZ",
        },
    ))

JSON日志结构分析

JSON格式审计日志包含以下关键字段：

• transaction - 事务信息（时间戳、ID、客户端IP等）
• request - 请求详细信息（方法、URI、协议、头部等）
• response - 响应信息（状态码、头部、正文等）
• audit_data - 审计数据（包含匹配的规则信息）
• messages - 规则匹配消息

传统JSON格式支持

Coraza还提供传统JSON格式（legacy JSON），位于formats_json.go，兼容旧版ModSecurity日志格式：

type legacyJSONFormatter struct{}

func (legacyJSONFormatter) Format(al plugintypes.AuditLog) ([]byte, error) {
    // 传统格式转换逻辑
}

🌐 OCSF格式审计日志深度剖析

OCSF（Open Cybersecurity Schema Framework）是新兴的网络安全事件日志开放标准，Coraza从v3版本开始支持OCSF格式，提供更结构化的安全事件日志。

OCSF格式优势

1. 标准化 - 符合OCSF v1.2.0标准
2. 结构化 - 统一的安全事件描述格式
3. 互操作性 - 易于与SIEM系统集成
4. 可扩展 - 支持丰富的元数据字段

OCSF日志配置

// 启用OCSF格式审计日志
waf, err := coraza.NewWAF(coraza.NewWAFConfig().
    WithAuditLog(
        coraza.AuditLogConfig{
            Enabled:     true,
            Formatter:   auditlog.OCSFFormatter{},
            Writer:      auditlog.NewSerialWriter(),
            Parts:       "ABCDEFGHIJKZ",
        },
    ))

OCSF事件结构

OCSF格式将WAF事件映射为标准化的安全事件结构：

• metadata - 事件元数据（版本、类别、类型等）
• actor - 参与者信息（用户、进程等）
• http_request - HTTP请求详细信息
• http_response - HTTP响应信息
• enrichments - 丰富数据（地理位置、威胁情报等）
• unmapped - 未映射的原始数据

⚙️ 审计日志配置最佳实践

1. 日志部分控制

Coraza支持灵活的日志部分配置，通过Parts参数控制记录哪些部分：

// 只记录关键部分
Parts: "ABHZ"

// 记录完整审计日志
Parts: "ABCDEFGHIJKZ"

各部分含义：

• A - 审计日志头
• B - 请求头
• C - 请求体
• D - 保留
• E - 响应体
• F - 响应头
• G - 审计日志尾部
• H - 审计日志观察者
• I - 请求体（替代C）
• J - 响应体（替代E）
• K - 审计日志尾部（替代G）
• Z - 最终边界

2. 日志写入器选择

Coraza提供多种日志写入器：

• SerialWriter - 串行写入器，位于serial_writer.go
• ConcurrentWriter - 并发写入器，位于concurrent_writer.go
• HTTPSWriter - HTTP/S写入器，位于https_writer.go
• SyslogWriter - Syslog写入器，位于syslog_writer.go

3. 性能优化配置

waf, err := coraza.NewWAF(coraza.NewWAFConfig().
    WithAuditLog(
        coraza.AuditLogConfig{
            Enabled:     true,
            Formatter:   auditlog.JSONFormatter{},
            Writer:      auditlog.NewConcurrentWriter(), // 使用并发写入器
            Parts:       "ABHZ", // 只记录必要部分
            Concurrent:  true,   // 启用并发处理
        },
    ))

🔧 实战：自定义审计日志处理器

自定义Formatter实现

type CustomFormatter struct{}

func (f CustomFormatter) Format(al plugintypes.AuditLog) ([]byte, error) {
    // 自定义格式化逻辑
    customData := map[string]interface{}{
        "timestamp":   time.Now().Unix(),
        "transaction": al.Transaction().ID(),
        "severity":    al.Transaction().HighestSeverity(),
        "matches":     len(al.Messages()),
    }
    return json.Marshal(customData)
}

func (f CustomFormatter) MIME() string {
    return "application/json"
}

集成第三方日志系统

// 集成ELK Stack
type ELKFormatter struct {
    indexName string
}

func (f ELKFormatter) Format(al plugintypes.AuditLog) ([]byte, error) {
    elkLog := map[string]interface{}{
        "@timestamp": time.Now().Format(time.RFC3339),
        "event": map[string]interface{}{
            "kind":        "event",
            "category":    "web",
            "type":        "waf",
            "severity":    al.Transaction().HighestSeverity(),
        },
        "coraza": al,
    }
    return json.Marshal(elkLog)
}

📈 审计日志性能监控

监控指标

1. 日志延迟 - 记录处理时间
2. 吞吐量 - 每秒处理的日志数量
3. 错误率 - 日志写入失败比例
4. 存储使用 - 日志文件大小增长

性能测试配置

查看测试文件auditlog_test.go了解如何测试审计日志性能：

func BenchmarkJSONFormatter(b *testing.B) {
    // 基准测试JSON格式化性能
}

func BenchmarkOCSFFormatter(b *testing.B) {
    // 基准测试OCSF格式化性能
}

🚀 高级功能：审计日志过滤与采样

基于规则的日志过滤

// 只记录高风险事件的审计日志
waf, err := coraza.NewWAF(coraza.NewWAFConfig().
    WithAuditLog(
        coraza.AuditLogConfig{
            Enabled: true,
            Filter: func(al plugintypes.AuditLog) bool {
                // 只记录严重性>=CRITICAL的事件
                return al.Transaction().HighestSeverity() >= types.RuleSeverityCritical
            },
        },
    ))

智能采样策略

// 动态采样：高频事件降低采样率
samplingRate := 0.1 // 10%采样率
if isHighFrequencyEvent(al) {
    samplingRate = 0.01 // 1%采样率
}

🔍 故障排除与调试

常见问题解决

1. 日志不生成 - 检查Enabled配置和Parts参数
2. 性能问题 - 考虑使用ConcurrentWriter和减少Parts
3. 格式错误 - 验证Formatter的MIME类型
4. 存储问题 - 检查文件权限和磁盘空间

调试工具

使用debuglog/包中的调试日志功能：

import "github.com/corazawaf/coraza/v3/debuglog"

// 启用调试日志
logger := debuglog.Default()
logger.Info().Msg("审计日志配置完成")

📚 总结与最佳实践

Coraza审计日志系统提供了强大而灵活的日志功能，以下是关键要点：

1. 选择合适的格式 - JSON适合简单集成，OCSF适合企业级SIEM
2. 优化日志部分 - 根据需求选择必要的Parts，避免过度记录
3. 考虑性能影响 - 在高流量环境中使用并发写入器和采样
4. 定期监控 - 建立日志性能监控机制
5. 安全存储 - 确保审计日志的安全存储和访问控制

通过深入理解Coraza审计日志的JSON和OCSF格式，您可以构建更强大、更高效的安全监控系统，为Web应用提供全面的防护和审计能力。🎯

官方文档参考：internal/auditlog/README.md 核心源码位置：internal/auditlog/formats_json.go 和 internal/auditlog/formats_ocsf.go

【免费下载链接】coraza OWASP Coraza WAF is a golang modsecurity compatible web application firewall library 项目地址: https://gitcode.com/gh_mirrors/co/coraza