feat: add backing store for disk buffering of events

Author: notque

audittools/README.md

@@ -0,0 +1,119 @@
+# audittools
+
+`audittools` provides a standard interface for generating and sending CADF (Cloud Auditing Data Federation) audit events to a RabbitMQ message broker.
+
+## Certification Requirements (PCI DSS, SOC 2, and more)
+
+As a cloud provider subject to strict audits (including PCI DSS and more), we must ensure the **completeness** and **integrity** of audit logs while maintaining service **availability**.
+
+### Standard Production Configuration
+
+**You MUST configure a Backing Store with Persistent Storage (PVC).**
+
+*   **Configuration**: Set `BackingStorePath` to a mount point backed by a PVC.
+*   **Requirement**: This ensures that audit events are preserved even in double-failure scenarios (RabbitMQ outage + Pod crash/reschedule).
+*   **Compliance**: Satisfies requirements for guaranteed event delivery and audit trail completeness.
+
+### Non-Compliant Configurations
+
+The following configurations are available for development or specific edge cases but are **NOT** recommended for production services subject to audit:
+
+1.  **Ephemeral Storage (emptyDir)**:
+    *   *Risk*: Data loss if the Pod is rescheduled during a RabbitMQ outage.
+    *   *Status*: **Development / Testing Only**.
+
+2.  **No Backing Store**:
+    *   *Behavior*: The service will **block** (stop processing requests) if the RabbitMQ broker is down and the memory buffer fills up.
+    *   *Risk*: Service downtime (Violation of Availability targets).
+    *   *Status*: **Not Recommended**. Only acceptable if service downtime is preferred over *any* storage complexity.
+
+## Usage
+
+### Basic Setup
+
+To use `audittools`, you typically initialize an `Auditor` with your RabbitMQ connection details.
+
+```go
+import "github.com/sapcc/go-bits/audittools"
+
+func main() {
+    // ...
+    auditor, err := audittools.NewAuditor(audittools.AuditorOpts{
+        EnvPrefix: "MYSERVICE_AUDIT", // Configures env vars like MYSERVICE_AUDIT_RABBITMQ_URL
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    // ...
+}
+```
+
+### Sending Events
+
+```go
+event := cadf.Event{
+    // ... fill in event details ...
+}
+auditor.Record(event)
+```
+
+## Disk-Based Buffering
+
+`audittools` includes buffering to ensure audit events are not lost if the RabbitMQ broker becomes unavailable. Events are temporarily written to disk and replayed once the connection is restored.
+
+### Configuration
+
+Buffering is enabled by providing a `BackingStorePath`.
+
+```go
+auditor, err := audittools.NewAuditor(audittools.AuditorOpts{
+    EnvPrefix:        "MYSERVICE_AUDIT",
+    BackingStorePath: "/var/lib/myservice/audit-buffer",
+})
+```
+
+Or via environment variables:
+
+*   `MYSERVICE_AUDIT_BACKING_STORE_PATH`: Directory to store buffered events.
+*   `MYSERVICE_AUDIT_BACKING_STORE_MAX_TOTAL_SIZE`: (Optional) Max total size of the buffer in bytes.
+
+### Kubernetes Deployment
+
+If running in Kubernetes, you have two main options for the backing store:
+
+1.  **Persistent Storage (PVC) - Recommended for Audit Compliance**:
+    *   Mount a Persistent Volume Claim (PVC) at the `BackingStorePath`.
+    *   **Pros**: Data survives Pod deletion, rescheduling, and rolling updates.
+    *   **Cons**: Adds complexity (volume management, access modes).
+    *   **Use Case**: **Required** for strict audit compliance to ensure no data is lost even if the service instance fails during a broker outage.
+
+2.  **Ephemeral Storage (emptyDir)**:
+    *   Mount an `emptyDir` volume at the `BackingStorePath`.
+    *   **Pros**: Simple, fast, no persistent volume management.
+    *   **Cons**: Data is lost if the *Pod* is deleted or rescheduled. However, it survives container restarts within the same Pod.
+    *   **Use Case**: Suitable for non-critical environments or where occasional data loss during complex failure scenarios (simultaneous broker outage + pod rescheduling) is acceptable.
+
+### Behavior
+
+The system transitions through the following states to ensure zero data loss:
+
+1.  **Normal Operation**: Events are sent directly to RabbitMQ.
+2.  **RabbitMQ Outage**: Events are written to the disk backing store. The application continues without blocking.
+3.  **Disk Full**: If the backing store reaches `BackingStoreMaxTotalSize`, writes fail. Events are buffered in memory (up to 20).
+4.  **Fail-Closed**: If the memory buffer fills up, `auditor.Record()` **blocks**. This pauses the application to prevent data loss.
+5.  **Recovery**: A background routine continuously drains the backing store to RabbitMQ once it becomes available. New events are persisted to disk during draining to prevent blocking.
+
+**Additional Details**:
+
+*   **Security**: The directory is created with `0700` permissions, and files with `0600`, ensuring only the service user can access the sensitive audit data.
+*   **Capacity**: If `BackingStoreMaxTotalSize` is configured, the store will reject new writes when full, preserving existing data.
+
+### Metrics
+
+The backing store exports the following Prometheus metrics:
+
+*   `audittools_backing_store_writes_total`: Total number of audit events written to disk.
+*   `audittools_backing_store_reads_total`: Total number of audit events read from disk.
+*   `audittools_backing_store_errors_total`: Total number of errors, labeled by operation (`write_full`, `write_io`, `read_unmarshal`, etc.).
+*   `audittools_backing_store_size_bytes`: Current total size of the backing store in bytes.
+*   `audittools_backing_store_files_count`: Current number of files in the backing store.

audittools/auditor.go

@@ -17,12 +17,12 @@ import (
 	"fmt"
 	"net"
 	"net/url"
+	"os"
 	"strconv"
 	"testing"
 
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/sapcc/go-api-declarations/cadf"
-
 	"github.com/sapcc/go-bits/assert"
 	"github.com/sapcc/go-bits/internal"
 	"github.com/sapcc/go-bits/logg"
@@ -63,6 +63,14 @@ type AuditorOpts struct {
 	//   - "audittools_successful_submissions" (counter, no labels)
 	//   - "audittools_failed_submissions" (counter, no labels)
 	Registry prometheus.Registerer
+
+	// Optional. If given, the Auditor will buffer events in this directory when the RabbitMQ server is unreachable.
+	// If EnvPrefix is given, this can also be set via the environment variable "${PREFIX}_BACKING_STORE_PATH".
+	BackingStorePath string
+
+	// Optional. If given, limits the total size of the backing store in bytes.
+	// If EnvPrefix is given, this can also be set via the environment variable "${PREFIX}_BACKING_STORE_MAX_TOTAL_SIZE".
+	BackingStoreMaxTotalSize int64
 }
 
 func (opts AuditorOpts) getConnectionOptions() (rabbitURL url.URL, queueName string, err error) {
@@ -99,6 +107,20 @@ func (opts AuditorOpts) getConnectionOptions() (rabbitURL url.URL, queueName str
 		User:   url.UserPassword(username, pass),
 		Path:   "/",
 	}
+
+	// also read backing store path from env if not set explicitly
+	if opts.BackingStorePath == "" {
+		opts.BackingStorePath = os.Getenv(opts.EnvPrefix + "_BACKING_STORE_PATH")
+	}
+	if opts.BackingStoreMaxTotalSize == 0 {
+		if val := os.Getenv(opts.EnvPrefix + "_BACKING_STORE_MAX_TOTAL_SIZE"); val != "" {
+			size, err := strconv.ParseInt(val, 10, 64)
+			if err == nil {
+				opts.BackingStoreMaxTotalSize = size
+			}
+		}
+	}
+
 	return rabbitURL, queueName, nil
 }
 
@@ -144,11 +166,29 @@ func NewAuditor(ctx context.Context, opts AuditorOpts) (Auditor, error) {
 	if err != nil {
 		return nil, err
 	}
+
+	var backingStore BackingStore
+	if opts.BackingStorePath != "" {
+		bsRegistry := opts.Registry
+		if bsRegistry == nil {
+			bsRegistry = prometheus.DefaultRegisterer
+		}
+		backingStore, err = NewFileBackingStore(FileBackingStoreOpts{
+			Directory:    opts.BackingStorePath,
+			MaxTotalSize: opts.BackingStoreMaxTotalSize,
+			Registry:     bsRegistry,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to initialize backing store: %w", err)
+		}
+	}
+
 	eventChan := make(chan cadf.Event, 20)
 	go auditTrail{
 		EventSink:           eventChan,
 		OnSuccessfulPublish: func() { successCounter.Inc() },
 		OnFailedPublish:     func() { failureCounter.Inc() },
+		BackingStore:        backingStore,
 	}.Commit(ctx, rabbitURL, queueName)
 
 	return &standardAuditor{