OPA决策日志增强：支持HTTP请求头记录

背景介绍

Open Policy Agent(OPA)作为一款流行的策略即代码工具，其决策日志功能对于审计和调试至关重要。在实际生产环境中，我们经常需要在决策日志中记录更多上下文信息，特别是HTTP请求头中包含的关键数据。

当前限制

在现有OPA架构中，HTTP请求头(input.headers)仅对授权策略(system.authz)可见，而决策日志处理模块(system.log)无法直接访问这些头部信息。这导致了一个功能缺口：虽然我们可以基于请求头做授权决策，却无法将这些决策依据记录到日志中。

解决方案演进

经过社区讨论，OPA团队提出了一个优雅的解决方案：通过决策日志配置显式声明需要记录的HTTP头字段。该方案具有以下特点：

1. 配置驱动：在OPA配置文件中新增request_context配置节
2. 白名单机制：只记录明确指定的头字段，避免敏感信息泄露
3. 结构化存储：记录的头部信息会以标准化的JSON格式保存在决策日志中

配置示例

decision_logs:
  request_context:
    http:
      headers: ["x-user-id", "x-trace-id", "content-type"]

启用后，决策日志将包含如下结构：

"request_context": {
    "http": {
       "headers": {
            "x-user-id": "user123",
            "x-trace-id": "abc123def456",
            "content-type": "application/json"
        }
    }
}

技术优势

1. 安全性：避免意外记录敏感头信息(如Authorization头)
2. 灵活性：不同环境可以配置不同的记录策略
3. 可追溯性：完整记录影响决策的关键上下文
4. 性能优化：只记录必要的头字段，减少日志体积

实现建议

对于需要此功能升级的用户，建议：

1. 评估现有策略中依赖的HTTP头字段
2. 制定头部字段记录白名单
3. 在测试环境验证配置效果
4. 逐步在生产环境 rollout 变更

总结

OPA的这一增强功能填补了策略执行与审计追踪之间的关键缺口，使得基于HTTP头的授权决策能够被完整记录和审计。这种设计既满足了合规性要求，又保持了系统的灵活性和安全性，是OPA在可观测性方面的重要进步。