axonops/audit

# 审计 **面向 Go 服务的结构化、模式约束审计日志** [](https://github.com/axonops/audit/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/axonops/audit) [](https://goreportcard.com/report/github.com/axonops/audit) [](LICENSE)  [🚀 Quick Start](#-quick-start) | [✨ Features](#-key-features) | [📚 Examples](examples/) | [📖 API Reference](https://pkg.go.dev/github.com/axonops/audit) ## ⚠️ 状态 该库处于 **预发布（v0.x）** 阶段。在 v1.0.0 之前，次要版本之间 API 可能会变更。请固定依赖版本。 ## 🔍 概述 audit 是一个 Go 审计日志库。审计日志与应用程序日志不同：应用程序日志记录技术细节用于调试（`log/slog`、`zap`），而审计日志记录 **谁在何时对什么资源做了什么**，以满足合规性、取证和问责要求。如果你的应用程序处理用户数据、身份验证或财务交易，SOX、HIPAA 和 GDPR 等法规要求具备结构化的审计追踪，而应用程序日志记录器无法强制执行这些结构。 该库将审计配置分为两个层级： - **编译时（分类法）：** 你的事件模式——存在哪些事件类型、哪些字段是必需的、哪些是可选的——在 YAML 文件中定义，并通过 `go:embed` 嵌入到二进制文件中。代码生成器（`audit-gen`）根据此模式生成类型化的 Go 构造器，因此无效的事件名称和缺失的必需字段会在编译时被捕获，而不是运行时。分类法是你的审计契约，会随二进制文件一起发布，且在不重新编译的情况下无法更改。 - **运行时（输出）：** 事件去向——文件、syslog、Webhook——在启动时通过单独的 YAML 文件配置。输出目的地、路由过滤器、格式化和敏感度标签排除策略都可以在不重新编译的情况下根据环境进行调整。 该库会根据编译后的分类法验证事件，并异步将事件同时发送到多个输出，支持 **[JSON](docs/json-format.md)** 和 **[CEF（通用事件格式）](docs/cef-format.md)** 以便集成 SIEM。 ## ✨ 主要特性 | 功能 | 描述 | 文档 | |------|------|------| | 📋 **分类法验证** | 在 YAML 中定义事件模式；运行时验证每个事件 | [了解更多](docs/taxonomy-validation.md) | | ⚙️ **代码生成** | `audit-gen` 生成类型化构造器；拼写错误会成为编译错误 | [了解更多](docs/code-generation.md) | | 🛡️ **CEF 格式** | 适用于 Splunk、ArcSight、QRadar 等 SIEM 平台的通用事件格式 | [了解更多](docs/cef-format.md) | | 📄 **JSON 格式** | 行分隔的 JSON，具有确定的字段顺序 | [了解更多](docs/json-format.md) | | 📡 **5 种输出类型** | 文件（轮转）、syslog（RFC 5424）、Webhook（NDJSON）、Loki（流标签）、stdout —— 可同时向所有输出发送 | [了解更多](docs/outputs.md) | | 🔀 **事件路由** | 按类别或严重性将事件路由到特定输出 | [了解更多](docs/event-routing.md) | | 🔒 **敏感度标签** | 将字段分类为 PII/财务；按输出剥离以符合 GDPR/PCI 合规性 | [了解更多](docs/sensitivity-labels.md) | | ⚡ **异步投递** | 亚微秒级入队；后台排水 goroutine 异步投递 | [了解更多](docs/async-delivery.md) | | 🌐 **HTTP 中间件** | 自动捕获 HTTP 请求字段用于审计日志 | [了解更多](docs/http-middleware.md) | | 📊 **指标与监控** | 跟踪丢弃的事件、投递错误和输出健康状态 | [了解更多](docs/metrics-monitoring.md) | | 📝 **YAML 配置** | 使用环境变量替换的 YAML 配置输出 | [了解更多](docs/output-configuration.md) | | 🔐 **HMAC 完整性** | 使用 NIST 批准算法的每输出篡改检测 | [了解更多](docs/hmac-integrity.md) | | 🧪 **测试支持** | 与生产验证相同的内存记录器 | [了解更多](docs/testing.md) | ## ❓ 为何需要审计日志？ 审计日志不同于应用程序日志，它们的用途根本不同： | | 🔧 应用程序日志 | 📋 审计日志 | |---|---|---| | **目的** | 调试、故障排除、可观测性 | 合规、取证、问责 | | **受众** | 开发者、SRE | 安全团队、审计员、法律 | | **保证** | 尽力而为 —— 丢失日志行无妨 | 模式强制 —— 缺失字段即合规缺口 | | **保留** | 数天至数周 | 数月至数年（监管要求） | | **内容** | 技术细节（错误、堆栈跟踪） | 谁在何时对什么资源做了什么，以及为什么 | | **目的地** | 日志聚合（OpenSearch、Datadog、Loki） | SIEM（Splunk、ArcSight、QRadar）、合规归档 | 如果你的应用程序处理用户数据、财务交易、身份验证或访问控制，SOX、HIPAA、GDPR 和 PCI-DSS 等法规要求具备审计追踪。应用程序日志记录器（`log/slog`、`zap`、`zerolog`）无法强制执行合规所需的结构、完整性和投递保证。 ## 💡 为何选择 audit？ 目前没有现有的 Go 库能提供带有多输出广播和 SIEM 原生格式支持的模式强制审计日志： - 📋 **模式强制** —— 每个事件都根据你的分类法进行验证；缺失的必需字段会被拒绝，而不是静默丢弃 - 🛡️ **SIEM 原生输出** —— 开箱即用支持 [CEF 格式](docs/cef-format.md)（适用于 Splunk、ArcSight、QRadar）以及 [JSON](docs/json-format.md) 用于日志聚合器 - 📡 **多输出广播** —— 同时发送到 [文件、syslog、Webhook、Loki 和 stdout](docs/outputs.md)，每个输出可拥有独立的格式化和过滤器 - 🔒 **敏感字段剥离** —— [将字段分类为 PII 或财务信息](docs/sensitivity-labels.md)；按输出剥离以符合 GDPR/PCI 合规性 - ⚡ **非阻塞** —— 亚微秒级的 `AuditEvent()` 调用；通过后台排水 goroutine 进行 [异步投递](docs/async-delivery.md)，并具备完整性监控 - 🔌 **无供应商锁定** —— [可插拔的指标接口](docs/metrics-monitoring.md)；核心库不依赖 Prometheus、OpenTelemetry 或任何日志框架 ## 🚀 快速开始 该库采用 YAML 优先的工作流：在分类法文件中定义事件，在另一个文件中配置输出，并生成类型安全的 Go 代码。 ### 1️⃣ 定义你的分类法（`taxonomy.yaml`）——这是你的源代码 ``` version: 1 categories: write: severity: 3 events: - user_create security: severity: 8 events: - auth_failure events: user_create: description: "A new user account was created" fields: outcome: { required: true } actor_id: { required: true } auth_failure: description: "An authentication attempt failed" fields: outcome: { required: true } actor_id: { required: true } ``` ### 2️⃣ 配置输出（`outputs.yaml`）——这是你的配置 ``` version: 1 app_name: my-service host: "${HOSTNAME:-localhost}" outputs: console: type: stdout siem_log: type: file file: path: "./audit-cef.log" formatter: type: cef vendor: "MyCompany" product: "MyApp" version: "1.0" ``` ### 3️⃣ 生成类型安全代码 ``` go run github.com/axonops/audit/cmd/audit-gen \ -input taxonomy.yaml \ -output audit_generated.go \ -package main ``` ### 4️⃣ 使用生成的构造器 ``` // Required fields are constructor parameters — typos are compile errors err := logger.AuditEvent( NewUserCreateEvent("alice", "success"). SetTargetID("user-42"), ) ``` ### 输出 **📄 JSON**（默认格式化器）： ``` {"timestamp":"...","event_type":"user_create","severity":3,"app_name":"my-service","host":"prod-01","timezone":"UTC","pid":12345,"actor_id":"alice","outcome":"success","target_id":"user-42","event_category":"write"} ``` **🛡️ CEF**（SIEM 格式化器）： ``` CEF:0|MyCompany|MyApp|1.0|user_create|A new user account was created|3|rt=... act=user_create deviceProcessName=my-service dvchost=prod-01 dvcpid=12345 suser=alice outcome=success cat=write ``` ## 📦 安装 需要 **Go 1.26+**。 ``` go get github.com/axonops/audit # core: logger, taxonomy, validation, formatters, stdout output go get github.com/axonops/audit/file # file output with rotation go get github.com/axonops/audit/syslog # RFC 5424 syslog (TCP/UDP/TLS/mTLS) go get github.com/axonops/audit/webhook # batched HTTP webhook with SSRF protection go get github.com/axonops/audit/loki # Grafana Loki with stream labels and gzip go get github.com/axonops/audit/outputconfig # YAML-based output configuration ``` ## 🏗️ 模块结构 | 模块 | 描述 | |------|------| | `github.com/axonops/audit` | 核心：Logger、分类法验证、JSON + CEF 格式化器、HTTP 中间件、stdout 输出、广播、路由、`audittest` | | `github.com/axonops/audit/file` | 带基于大小的轮转和 gzip 压缩的文件输出 | | `github.com/axon/audit/syslog` | RFC 5424 syslog 输出（TCP/UDP/TLS/mTLS） | | `github.com/axonops/audit/webhook` | 带重试和 SSRF 保护的批量 HTTP Webhook | | `github.com/axonops/audit/loki` | Grafana Loki 输出，带流标签、gzip、多租户 | | `github.com/axonops/audit/outputconfig` | 基于 YAML 的输出配置，支持环境变量替换 | | `github.com/axonops/audit/outputs` | 便捷方式：单个空白导入即可注册所有输出工厂 | | `github.com/axonops/audit/secrets` | 用于 `ref+` URI 解析的密钥提供者接口 | | `github.com/axonops/audit/secrets/openbao` | OpenBao KV v2 密钥提供者 | | `github.com/axonops/audit/secrets/vault` | HashiCorp Vault KV v2 密钥提供者 | | `github.com/axonops/audit/cmd/audit-gen` | 代码生成器：将 YAML 分类法转换为类型化 Go 构造器 | 输出被隔离在独立模块中，以便核心库保持最小的第三方依赖。只需导入你需要的输出模块——或者 `import _ "github.com/axonops/audit/outputs"` 来注册所有输出。 ## 🧪 测试 `audittest` 包提供了一个用于测试审计事件的内存记录器： ``` func TestUserCreation(t *testing.T) { logger, events, _ := audittest.NewLoggerQuick(t, "user_create") // Exercise the code under test... err := logger.AuditEvent(audit.NewEventKV("user_create", "outcome", "success", "actor_id", "alice")) require.NoError(t, err) // Assert immediately — NewLoggerQuick uses synchronous delivery. assert.Equal(t, 1, events.Count()) assert.Equal(t, "alice", events.Events()[0].StringField("actor_id")) } ``` 更多信息请参见 [示例 4](examples/04-testing/) 和 [测试文档](docs/testing.md)。 ## 📚 文档 | 资源 | 描述 | |------|------| | 📖 [渐进式示例](examples/) | 从“Hello World”到[完整库存演示](examples/17-capstone/) 的 17 个示例，涵盖每种输出类型、TLS 策略、路由、格式化器、测试和缓冲） | | 📘 [API 参考](https://pkg.go.dev/github.com/axonops/audit) | pkg.go.dev 文档 | | 🏗️ [架构](ARCHITECTURE.md) | 管道设计、模块边界、线程安全 | | 🤝 [贡献](CONTRIBUTING.md) | 开发设置、PR 流程、代码规范 | | 📝 [变更日志](CHANGELOG.md) | 发布历史和重大变更 | | ❌ [错误参考](docs/error-reference.md) | 每个错误的解释及恢复指南 | | 🔧 [故障排除](docs/troubleshooting.md) | 常见问题及解决方法 | | 🔒 [安全策略](SECURITY.md) | 漏洞报告 | | ⚡ [基准测试](BENCHMARKS.md) | 性能基线和方法论 | ## 🙏 感谢 audit 基于优秀的开源项目构建。完整归属和许可详情请参见 [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md)： - [github.com/goccy/go-yaml](https://github.com/goccy/go-yaml) — YAML 解析（MIT） - [github.com/axonops/srslog](https://github.com/axonops/srslog) — RFC 5424 syslog（BSD-3-Clause） - [github.com/rgooding/go-syncmap](https://github.com/rgooding/go-syncmap) — 通用 sync.Map（Apache-2.0） ## 📄 许可证 [Apache License 2.0](LICENSE) — 版权所有 2026 AxonOps Limited。

标签：CEF 格式, EVTX分析, GDPR, Go 语言, HIPAA, HMAC 完整性校验, JSON 格式, OISF, Schema 校验, SOX, Syslog, Webhook, 事件溯源, 事件路由, 代码生成, 力导向图, 多输出, 安全日志, 审计日志, 异步投递, 敏感标签, 文件日志, 文档结构分析, 日志审计, 日志库, 日志框架, 日志签名, 日志管理, 日志规范, 日志路由, 日志输出, 渗透测试工具, 类型安全, 结构化日志, 编译时校验