Coraza WAF审计日志JSON格式配置问题解析

背景介绍

Coraza WAF作为一款开源的Web应用防火墙，其审计日志功能对于安全分析至关重要。在最新版本中，官方文档明确支持通过SecAuditLogFormat指令将审计日志输出为JSON格式，这相比传统的ModSecurity格式更便于日志系统解析和处理。

问题现象

用户在使用coraza-spoa与HAProxy集成时发现，尽管在配置文件中设置了SecAuditLogFormat JSON指令，但实际输出的日志信息中，核心审计内容仍以字符串形式嵌套在JSON结构中，未能实现完全JSON化。具体表现为：

• 外层日志框架已采用JSON格式
• 核心审计信息仍以传统格式存储在message字段内

技术分析

经过深入排查，发现问题根源在于coraza-spoa组件的实现方式：

1. 审计日志与错误日志的差异

   • Coraza WAF明确区分审计日志(Audit Log)和错误日志(Error Log)
   • JSON格式化配置仅作用于审计日志，不影响错误日志格式
   • 用户最初混淆了这两种日志类型

2. coraza-spoa的特殊处理

   • coraza-spoa组件在错误回调处理中进行了额外封装
   • 即使底层Coraza核心已生成JSON格式审计日志，组件仍会进行二次处理
   • 导致最终输出不符合预期格式

3. 版本兼容性验证

   • 在标准Coraza环境中测试确认JSON格式化功能正常
   • 问题特定存在于coraza-spoa集成方案中

解决方案建议

1. 明确日志类型区分

   • 审计日志：记录完整事务信息，支持JSON格式化
   • 错误日志：记录拦截事件，保持原有格式

2. 组件级优化方向

   • 修改coraza-spoa的日志处理逻辑
   • 保持原始JSON结构不进行额外封装
   • 或提供配置选项控制格式化行为

3. 临时解决方案

   • 对于必须使用当前版本的用户
   • 可在日志收集端添加解析层处理混合格式
   • 使用正则表达式提取关键字段

技术实现细节

Coraza WAF的日志格式化核心逻辑位于规则匹配处理器中，当检测到JSON格式配置时，会直接将审计信息序列化为JSON结构。而在coraza-spoa实现中，错误回调函数对日志消息进行了重新封装，导致格式变化。

最佳实践建议

1. 生产环境中建议：

   • 统一使用最新稳定版本
   • 明确区分审计和错误日志输出路径
   • 为不同日志类型配置适当的格式化方式

2. 开发环境中建议：

   • 测试各组件版本兼容性
   • 验证日志输出是否符合预期
   • 建立自动化测试验证日志格式

总结

Coraza WAF本身具备完善的JSON日志支持能力，但在特定集成方案中可能因组件实现差异导致功能异常。开发者应充分理解各日志类型的区别，并在集成测试阶段重点关注日志输出格式的验证工作。对于需要深度集成的用户，建议参与社区贡献，共同完善各适配组件的功能一致性。