axonops/go-audit

## 🔍 概述 go-audit 是一个用于 Go 的审计日志库。审计日志不同于 应用程序日志——应用程序日志记录用于调试的技术细节 (`log/slog`、`zap`)，而审计日志记录**谁在 何时对哪个资源执行了什么操作**，用于合规性、取证和 问责。如果你的应用程序处理用户数据、身份验证 或财务交易，像 SOX、HIPAA 和 GDPR 这样的法规 要求具备应用程序日志工具无法强制执行的结构化审计追踪。 go-audit 将审计配置分为两层： - **编译时 (分类法)：** 你的事件模式——存在哪些事件类型、哪些字段是必需的、哪些是可选的——被定义在一个 YAML 文件中，并通过 `go:embed` 嵌入到你的二进制文件中。代码生成器 (`audit-gen`) 根据此模式生成强类型的 Go 构建器， 因此无效的事件名称和缺失的必需字段会被 编译器捕获，而不是在运行时才发现。分类法就是你的审计契约——它 随二进制文件一起发布，不重新编译便无法更改。 - **运行时 (输出)：** 事件的去向——文件、syslog、webhook——在一个单独的 YAML 文件中配置并在启动时加载。输出 目标、路由过滤器、格式化器和敏感标签 排除项都可以针对不同环境进行更改，而无需重新构建。 该库根据编译好的分类法验证事件， 将它们异步地同时传送到多个输出，并支持 [JSON](docs/json-format.md) 和 [CEF (Common Event Format)](docs/cef-format.md) 以用于 SIEM 集成。 ## ✨ 主要特性 ## ❓ 为什么需要审计日志？ 审计日志不是应用程序日志。它们服务于根本 不同的目的： | | 🔧 应用程序日志 | 📋 审计日志 | |---|---|---| | **目的** | 调试、故障排除、可观测性 | 合规性、取证、问责 | | **受众** | 开发人员、SRE | 安全团队、审计人员、法务 | | **保证** | 尽力而为——丢失一条日志没关系 | 模式强制执行——缺失一个字段就是合规漏洞 | | **保留期** | 几天到几周 | 几个月到几年（法规要求） | | **内容** | 技术细节（错误、堆栈跟踪） | 谁在何时对哪个资源执行了什么操作以及原因 | | **目的地** | 日志聚合器 (OpenSearch、Datadog、Loki) | SIEM (Splunk、ArcSight、QRadar)、合规归档 | 如果你的应用程序处理用户数据、财务交易、 身份验证或访问控制，像 SOX、HIPAA、GDPR 和 PCI-DSS 等法规会要求提供审计追踪。应用程序日志库 (`log/slog`、 `zap`、`zerolog`) 不强制执行合规性所要求的 结构、完整性或交付保证。 ## 💡 为什么选择 go-audit？ 现有的 Go 库中没有提供带有 多输出扇出和 SIEM 原生格式支持的模式强制审计日志： - 📋 **模式强制执行**——每个事件都根据你的分类法进行验证；缺失必需字段的事件会被拒绝，而不是被静默丢弃 - 🛡️ **SIEM 原生输出**——开箱即用的 [CEF 格式](docs/cef-format.md) 可直接被 Splunk、ArcSight、QRadar 理解，并附带用于日志聚合器的 [JSON](docs/json-format.md) - 📡 **多输出扇出**——将事件同时发送到[文件、syslog、webhook 和标准输出](docs/outputs.md)，每个都带有自己的格式化器和过滤器 - 🔒 **敏感字段剥离**——[将字段分类为 PII 或财务](docs/sensitivity-labels.md)；按输出剥离它们以满足 GDPR/PCI 合规性 - ⚡ **非阻塞**——亚微秒级的 `AuditEvent()` 调用；通过带有完整性监控的后台排空 goroutine 进行[异步交付](docs/async-delivery.md) - 🔌 **无供应商锁定**——[可插拔的指标接口](docs/metrics-monitoring.md)；核心不依赖 Prometheus、OpenTelemetry 或日志框架 ## 🚀 快速入门 go-audit 采用 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/go-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","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/go-audit # core: logger, taxonomy, validation, formatters, stdout output go get github.com/axonops/go-audit/file # file output with rotation go get github.com/axonops/go-audit/syslog # RFC 5424 syslog (TCP/UDP/TLS/mTLS) go get github.com/axonops/go-audit/webhook # batched HTTP webhook with SSRF protection go get github.com/axonops/go-audit/outputconfig # YAML-based output configuration ``` ## 🏗️ 模块结构 | 模块 | 描述 | |--------|-------------| | `github.com/axonops/go-audit` | 核心：Logger、分类法验证、JSON + CEF 格式化器、HTTP 中间件、标准输出、扇出、路由、`audittest` | | `github.com/axonops/go-audit/file` | 具有基于大小轮换和 gzip 压缩的文件输出 | | `github.com/axonops/go-audit/syslog` | RFC 5424 syslog 输出 (TCP/UDP/TLS/mTLS) | | `github.com/axonops/go-audit/webhook` | 具有重试和 SSRF 防护功能的批量 HTTP webhook | | `github.com/axonops/go-audit/outputconfig` | 带有环境变量替换的基于 YAML 的输出配置 | 输出被隔离在单独的模块中，因此核心库仅包含 最少的第三方依赖。只需导入你使用的输出即可。 ## 📚 文档 | 资源 | 描述 | |----------|-------------| | 📖 [渐进式示例](examples/) | 从 "hello world" 到带有五个输出的[完整 CRUD API](examples/11-crud-api/) 的 12 个示例 | | 📘 [API 参考](https://pkg.go.dev/github.com/axonops/go-audit) | pkg.go.dev 文档 | | 🏗️ [架构](ARCHITECTURE.md) | 流水线设计、模块边界、线程安全 | | 🤝 [贡献](CONTRIBUTING.md) | 开发设置、PR 流程、代码标准 | | 📝 [更新日志](CHANGELOG.md) | 发布历史和重大变更 | | ❌ [错误参考](docs/error-reference.md) | 每个错误的解释及恢复指南 | | 🔧 [故障排除](docs/troubleshooting.md) | 常见问题及解决方法 | | 🔒 [安全政策](SECURITY.md) | 漏洞报告 | | ⚡ [基准测试](BENCHMARKS.md) | 性能基线和方法论 | ## ⚠️ 状态 此库目前为**预发布版 (v0.x)**。在 v1.0.0 发布之前，次版本号之间的 API 可能会发生变化。请固定你的依赖版本。 ## 🙏 致谢 go-audit 建立在优秀的开源项目之上。有关完整的归属和 许可详情，请参阅 [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md)。 - [gopkg.in/yaml.v3](https://github.com/go-yaml/yaml) — YAML 解析 (MIT / Apache-2.0) - [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) — Generic sync.Map (Apache-2.0) ## 📄 许可证 [Apache License 2.0](LICENSE) — 版权所有 2026 AxonOps Limited.

标签：API集成, CEF格式, EVTX分析, GDPR, Go语言, HIPAA, HMAC完整性校验, Homebrew安装, JSON格式, OISF, ProjectDiscovery, Schema约束, SOX, Syslog, Webhook, 事件溯源, 事件路由, 人工智能安全, 代码生成, 分类法验证, 力导向图, 可观测性, 合规性, 多输出扇出, 安全合规, 审计日志, 开源库, 异步投递, 搜索引擎爬虫, 敏感度标签, 数据保护, 日志审计, 日志管理, 日志系统, 渗透测试工具, 程序破解, 类型安全, 结构化日志, 编译时检查, 网络代理, 防篡改