审计日志
DD 提供异步审计日志功能，记录安全相关事件，支持完整性签名和条目序列号追踪。
AuditLogger
异步安全审计事件记录器。
创建
go
func NewAuditLogger(cfg AuditConfig) (*AuditLogger, error)使用传入的 AuditConfig 创建异步审计记录器。可用 DefaultAuditConfig() 获取带合理默认值的配置。
返回错误的情况：配置校验失败（如 BufferSize 为负数）。
go
// 使用默认配置
auditLogger, _ := dd.NewAuditLogger(dd.DefaultAuditConfig())
// 自定义配置
cfg := dd.DefaultAuditConfig()
cfg.JSONFormat = true
cfg.MinimumSeverity = dd.AuditSeverityWarning
auditLogger, _ := dd.NewAuditLogger(cfg)方法
| 方法 | 签名 | 说明 |
|---|---|---|
Log | (event AuditEvent) | 记录审计事件（异步） |
LogSensitiveDataRedaction | (pattern, field, message string) | 敏感数据脱敏事件 |
LogRateLimitExceeded | (message string, metadata map[string]any) | 速率限制事件 |
LogSecurityViolation | (violationType, message string, metadata map[string]any) | 安全违规事件 |
LogReDoSAttempt | (pattern, message string) | ReDoS 攻击事件 |
LogIntegrityViolation | (message string, metadata map[string]any) | 完整性违规事件 |
LogPathTraversalAttempt | (path, message string) | 路径遍历事件 |
Stats | () AuditStats | 审计统计 |
Close | () error | 关闭并刷新剩余事件 |
使用示例
go
audit, _ := dd.NewAuditLogger(dd.DefaultAuditConfig())
defer audit.Close()
// 记录敏感数据脱敏
audit.LogSensitiveDataRedaction("password", "login_form", "检测到密码字段明文")
// 记录速率限制
audit.LogRateLimitExceeded("API 请求超过限制", map[string]any{
"client_ip": "192.168.1.100",
"limit": 100,
"current": 150,
})
// 记录安全违规
audit.LogSecurityViolation("sql_injection", "SQL 注入尝试", map[string]any{
"input": "' OR 1=1 --",
})AuditConfig
审计日志配置。
go
type AuditConfig struct {
Enabled bool // 是否启用审计（默认 true）
Output *os.File // 输出文件（默认 os.Stderr）；为 nil 时不产生输出，事件仅计入统计
BufferSize int // 异步事件缓冲区大小（默认 1000；为负数将校验失败）
IncludeTimestamp bool // 是否包含时间戳（默认 true）
JSONFormat bool // JSON 格式输出（默认 true）
MinimumSeverity AuditSeverity // 最低记录严重级别（默认 AuditSeverityInfo）
IntegritySigner *IntegritySigner // 完整性签名器（可选；配置后每条审计事件被签名）
}默认配置
go
func DefaultAuditConfig() AuditConfig返回默认审计配置，审计日志默认启用。
方法
| 方法 | 签名 | 说明 |
|---|---|---|
Validate | () error | 验证配置合法性（BufferSize 为负数则返回错误） |
Clone | () AuditConfig | 复制配置（IntegritySigner 为共享引用，不深拷贝） |
AuditEvent
审计事件结构体。
go
type AuditEvent struct {
Type AuditEventType `json:"type"`
Timestamp time.Time `json:"timestamp"`
Message string `json:"message"`
Pattern string `json:"pattern,omitempty"`
Field string `json:"field,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
Severity AuditSeverity `json:"severity"`
}AuditStats
审计统计数据结构。
go
type AuditStats struct {
TotalEvents int64 // 总事件数
Dropped int64 // 丢弃事件数（缓冲区满时累加）
ByType map[AuditEventType]int64 // 按类型统计
BufferSize int // 缓冲区大小
BufferUsage int // 当前缓冲区使用量
}AuditVerificationResult
审计验证结果。
go
type AuditVerificationResult struct {
Valid bool // 验证是否通过
Event *AuditEvent // 解析出的事件
RawEvent string // 原始事件字符串
Error error // 验证错误
}审计事件类型
| 常量 | String() | 说明 |
|---|---|---|
AuditEventSensitiveDataRedacted | "SENSITIVE_DATA_REDACTED" | 敏感数据已脱敏 |
AuditEventRateLimitExceeded | "RATE_LIMIT_EXCEEDED" | 速率限制超出 |
AuditEventReDoSAttempt | "REDOS_ATTEMPT" | ReDoS 攻击尝试 |
AuditEventSecurityViolation | "SECURITY_VIOLATION" | 安全违规 |
AuditEventIntegrityViolation | "INTEGRITY_VIOLATION" | 完整性违规 |
AuditEventInputSanitized | "INPUT_SANITIZED" | 输入已清洗 |
AuditEventPathTraversalAttempt | "PATH_TRAVERSAL_ATTEMPT" | 路径遍历尝试 |
AuditEventLog4ShellAttempt | "LOG4SHELL_ATTEMPT" | Log4Shell 攻击尝试 |
AuditEventNullByteInjection | "NULL_BYTE_INJECTION" | Null 字节注入 |
AuditEventOverlongEncoding | "OVERLONG_ENCODING" | 超长编码攻击 |
AuditEventHomographAttack | "HOMOGRAPH_ATTACK" | 同形字攻击 |
审计严重级别
| 常量 | String() | 说明 |
|---|---|---|
AuditSeverityInfo | "INFO" | 信息 |
AuditSeverityWarning | "WARNING" | 警告 |
AuditSeverityError | "ERROR" | 错误 |
AuditSeverityCritical | "CRITICAL" | 严重 |
MarshalJSON
go
func (s AuditSeverity) MarshalJSON() ([]byte, error)AuditSeverity 实现了 json.Marshaler 接口，JSON 序列化时输出字符串而非整数：
go
event := dd.AuditEvent{
Type: dd.AuditEventSecurityViolation,
Severity: dd.AuditSeverityCritical,
}
data, _ := json.Marshal(event)
// Severity 序列化为 "CRITICAL"，而非 3验证审计条目
go
func VerifyAuditEvent(entry string, signer *IntegritySigner) *AuditVerificationResult验证审计日志条目的完整性。
go
cfg, _ := dd.DefaultIntegrityConfigSafe()
signer, _ := dd.NewIntegritySigner(cfg)
result := dd.VerifyAuditEvent(logEntry, signer)
if result != nil && result.Valid {
fmt.Println("审计条目验证通过")
}