Merge branch 'k8s-audit-log-import'

# Conflicts:
#	cmd/spectre/commands/server.go
#	docs/docs/configuration/storage-settings.md
#	internal/api/import_handler.go
#	internal/importexport/json_import.go
#	internal/importexport/json_import_test.go

Author: moolen

cmd/spectre/commands/server_import_test.go

@@ -368,6 +368,50 @@ func TestRunStartupImportLogsWarningWhenBothIngestorsAreSet(t *testing.T) {
 	}
 }
 
+func TestRunStartupImportLogsAuditWarnings(t *testing.T) {
+	os.Setenv("LOG_TIMESTAMP", "2024-01-01T12:00:00Z")
+	defer os.Unsetenv("LOG_TIMESTAMP")
+
+	tmpDir := t.TempDir()
+	auditPath := filepath.Join(tmpDir, "audit.log")
+	payload := `{
+		"kind":"Event",
+		"apiVersion":"audit.k8s.io/v1",
+		"auditID":"audit-warning",
+		"stage":"ResponseComplete",
+		"stageTimestamp":"2024-01-02T03:04:05Z",
+		"verb":"update",
+		"objectRef":{
+			"resource":"deployments",
+			"namespace":"default",
+			"name":"missing-payload",
+			"apiGroup":"apps",
+			"apiVersion":"v1"
+		}
+	}`
+	if err := os.WriteFile(auditPath, []byte(payload), 0o644); err != nil {
+		t.Fatalf("failed to create audit fixture: %v", err)
+	}
+
+	output := captureStartupImportOutput(t, func() {
+		err := runStartupImport(context.Background(), startupImportOptions{
+			Path:          auditPath,
+			Logger:        logging.GetLogger("test_startup_import_audit_warning"),
+			BatchIngestor: &fakeStartupImportBatchIngestor{},
+		})
+		if err != nil {
+			t.Fatalf("runStartupImport returned error: %v", err)
+		}
+	})
+
+	if !strings.Contains(output, "Import warning") {
+		t.Fatalf("expected startup import logs to contain %q, got %q", "Import warning", output)
+	}
+	if !strings.Contains(output, "missing responseObject/requestObject payload") {
+		t.Fatalf("expected startup import logs to mention missing audit payload, got %q", output)
+	}
+}
+
 func TestServerCommandDefinesStartupImportDisableCausalityFlag(t *testing.T) {
 	t.Parallel()
 

docs/docs/configuration/storage-settings.md

@@ -35,3 +35,32 @@ spectre server --data-dir=./data --scrub-sensitive-data=true
 - Applies to startup imports before imported events are processed by the embedded backend
 - Does not rewrite historical data already stored on disk
 - Leaves references such as `valueFrom` unchanged because they do not contain literal secret values
+
+## Startup Import
+
+**Flag:** `--import-path`
+**Type:** String (file or directory path)
+**Default:** `""` (disabled)
+
+**Purpose:** Import historical events at startup before the embedded backend begins serving requests.
+
+Spectre accepts these startup import formats:
+
+- Native Spectre JSON: `{"events":[...]}`
+- Kubernetes audit `Event`
+- Kubernetes audit `EventList`
+- Line-delimited Kubernetes audit JSON in `.jsonl` or `.log` files
+
+When importing official Kubernetes audit logs, Spectre:
+
+- keeps mutating requests only: `create`, `update`, `patch`, `apply`, `delete`, `deletecollection`
+- skips read-only requests such as `get`, `list`, `watch`, `proxy`, and `connect`
+- uses `responseObject` first, then `requestObject`, as the best-effort resource snapshot
+- warns and skips mutating audit entries that do not contain enough object payload or identity data to build a Spectre event
+
+**Examples:**
+
+```bash
+spectre server --import-path=/backups/events-2025-12-11.json
+spectre server --import-path=/backups/kube-apiserver-audit/
+```

internal/api/handlers/import_handler.go

@@ -114,9 +114,10 @@ func (h *ImportHandler) handleJSONEventImport(w http.ResponseWriter, r *http.Req
 		return
 	}
 
-	// Parse JSON request using new Import API
+	// Parse JSON request using shared import parser so audit import warnings can
+	// be surfaced to the caller without changing ingest semantics.
 	h.logger.Debug("Starting to parse JSON events from request body")
-	eventValues, err := importexport.Import(importexport.FromReader(decompressedBody), importexport.WithLogger(h.logger))
+	eventValues, warnings, err := importexport.ParseImportPayload(decompressedBody)
 	if err != nil {
 		h.logger.Error("Failed to parse JSON: %v", err)
 		api.WriteError(w, http.StatusBadRequest, "INVALID_JSON", err.Error())
@@ -126,6 +127,7 @@ func (h *ImportHandler) handleJSONEventImport(w http.ResponseWriter, r *http.Req
 	parseDuration := time.Since(startTime)
 	h.logger.InfoWithFields("Parsed JSON import request",
 		logging.Field("event_count", len(eventValues)),
+		logging.Field("warning_count", len(warnings)),
 		logging.Field("parse_duration", parseDuration))
 
 	// Process events through the ingest backend.
@@ -157,6 +159,12 @@ func (h *ImportHandler) handleJSONEventImport(w http.ResponseWriter, r *http.Req
 	h.logger.InfoWithFields("JSON event batch import completed",
 		logging.Field("total_events", len(eventValues)),
 		logging.Field("duration", duration))
+	if len(warnings) > 0 {
+		h.logger.Warn("JSON import completed with %d warnings", len(warnings))
+		for _, warning := range warnings {
+			h.logger.Warn("Import warning: %s", warning)
+		}
+	}
 
 	// Calculate approximate "files created" based on unique hours
 	// This is for compatibility with existing tests that expect this field
@@ -179,6 +187,7 @@ func (h *ImportHandler) handleJSONEventImport(w http.ResponseWriter, r *http.Req
 		"imported_files": 0,            // Not applicable in ingest mode
 		"duration":       duration.String(),
 		"errors":         []string{}, // No errors in success path
+		"warnings":       warnings,
 	}
 
 	h.logger.Debug("Writing import response to client")

internal/api/handlers/import_handler_test.go

@@ -0,0 +1,79 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/moolen/spectre/internal/logging"
+	"github.com/moolen/spectre/internal/models"
+)
+
+type fakeBatchIngestor struct {
+	batches [][]models.Event
+}
+
+func (f *fakeBatchIngestor) ProcessBatch(_ context.Context, events []models.Event) error {
+	chunk := make([]models.Event, len(events))
+	copy(chunk, events)
+	f.batches = append(f.batches, chunk)
+	return nil
+}
+
+func TestImportHandler_JSONImportIncludesWarnings(t *testing.T) {
+	ingestor := &fakeBatchIngestor{}
+	handler := NewImportHandler(ingestor, logging.GetLogger("import-handler-test"))
+
+	body := strings.NewReader(`{
+		"kind":"Event",
+		"apiVersion":"audit.k8s.io/v1",
+		"auditID":"audit-warning",
+		"stage":"ResponseComplete",
+		"stageTimestamp":"2024-01-02T03:04:05Z",
+		"verb":"update",
+		"objectRef":{
+			"resource":"deployments",
+			"namespace":"default",
+			"name":"missing-payload",
+			"apiGroup":"apps",
+			"apiVersion":"v1"
+		}
+	}`)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/storage/import", body)
+	req.Header.Set("Content-Type", "application/json")
+	rr := httptest.NewRecorder()
+
+	handler.Handle(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("Handle() status = %d, want %d, body=%s", rr.Code, http.StatusOK, rr.Body.String())
+	}
+
+	var response struct {
+		Status   string   `json:"status"`
+		Warnings []string `json:"warnings"`
+	}
+	if err := json.Unmarshal(rr.Body.Bytes(), &response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response.Status != "success" {
+		t.Fatalf("response status = %q, want %q", response.Status, "success")
+	}
+	if len(ingestor.batches) != 1 {
+		t.Fatalf("expected one processed batch, got %d", len(ingestor.batches))
+	}
+	if len(ingestor.batches[0]) != 0 {
+		t.Fatalf("expected warning-only import to process an empty batch, got %d events", len(ingestor.batches[0]))
+	}
+	if len(response.Warnings) == 0 {
+		t.Fatalf("response warnings = %v, want at least one warning", response.Warnings)
+	}
+	if !strings.Contains(response.Warnings[0], "missing-payload") {
+		t.Fatalf("response warnings = %v, want warning mentioning %q", response.Warnings, "missing-payload")
+	}
+}