audit

Audit Logging

The internal/audit package provides structured audit logging for security-sensitive operations in the cd-operator.

Overview

Audit logging captures important events like PR merges, promotions, external test executions, and configuration changes. Events are logged as structured JSON to stdout for ingestion by log aggregation systems.

Features

• Non-blocking: Events are processed asynchronously through a buffered channel
• Context-aware: Extracts actor and correlation ID from context
• Structured JSON: All events logged as JSON for easy parsing
• Graceful shutdown: Flushes pending events during shutdown
• Error resilience: Logging failures don't fail business operations

Usage

Creating an Audit Logger

import (
    "github.com/grhili/cd-operator/internal/audit"
    "github.com/grhili/cd-operator/pkg/logger"
)

// Create underlying logger
log, err := logger.New(logger.Config{
    Level:  "info",
    Format: "json",
})

// Create audit logger
auditLog, err := audit.NewJSONLogger(log, audit.Config{
    BufferSize: 1000,  // Optional, defaults to 1000
})
defer auditLog.Close(context.Background())

Logging Events

// Add actor and correlation ID to context
ctx := context.Background()
ctx = audit.WithActor(ctx, "user@example.com")
ctx = audit.WithCorrelationID(ctx, "req-123")

// Log a successful PR merge
err := auditLog.LogEvent(ctx, audit.AuditEvent{
    EventType: audit.EventTypePRMerged,
    Resource:  "PR #123",
    Action:    "merge",
    Status:    audit.EventStatusSuccess,
    Metadata: map[string]string{
        "repo":   "cd-operator",
        "branch": "main",
    },
    Message: "Pull request merged successfully",
})

Event Types

Available event types:

• PR Operations: pr.merged, pr.qualified, pr.disqualified
• Promotions: promotion.triggered, promotion.completed, promotion.failed
• External Tests: external_test.started, external_test.completed, external_test.failed
• ArgoCD: argocd.sync, argocd.sync_completed, argocd.sync_failed
• Configuration: config.changed, config.deleted
• Authentication: auth.failure, auth.success
• Webhooks: webhook.received, webhook.rejected

Event Statuses

• success: Operation completed successfully
• failed: Operation failed
• pending: Operation in progress
• skipped: Operation was skipped

Example Output

{
  "timestamp": "2026-02-16T22:00:00Z",
  "event_type": "pr.merged",
  "actor": "user@example.com",
  "resource": "PR #123",
  "action": "merge",
  "status": "success",
  "metadata": {
    "repo": "cd-operator",
    "branch": "main"
  },
  "correlation_id": "req-123",
  "message": "Pull request merged successfully"
}

Integration with Controllers

import "github.com/grhili/cd-operator/internal/audit"

type Controller struct {
    auditLog audit.Logger
}

func (c *Controller) Reconcile(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {
    // Add service account as actor
    ctx = audit.WithActor(ctx, "system:serviceaccount:cd-system:cd-operator")
    ctx = audit.WithCorrelationID(ctx, req.NamespacedName.String())

    // ... business logic ...

    // Log success
    c.auditLog.LogEvent(ctx, audit.AuditEvent{
        EventType: audit.EventTypePRMerged,
        Resource:  fmt.Sprintf("PR #%d", prNumber),
        Action:    "merge",
        Status:    audit.EventStatusSuccess,
    })

    return reconcile.Result{}, nil
}

Best Practices

1. Always set actor: Use audit.WithActor() to track who performed the action
2. Use correlation IDs: Link related events with audit.WithCorrelationID()
3. Add metadata: Include relevant context in the Metadata field
4. Handle errors gracefully: Don't fail operations if audit logging fails
5. Close on shutdown: Call auditLog.Close() during graceful shutdown

Testing

Use audit.NewNoOpLogger() in tests to disable audit logging:

func TestMyFunction(t *testing.T) {
    auditLog := audit.NewNoOpLogger()
    // ... test code ...
}

Performance

• Buffered channel: Default 1000 events, configurable
• Async processing: Non-blocking - events queued immediately
• Dropped events: If buffer is full, events are dropped with error log
• Graceful degradation: Audit failures don't block operations

Security Considerations

• Audit logs contain sensitive information - secure log storage
• Use centralized log aggregation for compliance
• Set up alerts on authentication failures and unauthorized access
• Regularly review audit logs for anomalies
• Consider log retention policies for compliance (SOC2, HIPAA, etc.)