Funktionsrollback

ARCHITECTURE.md

@@ -1,42 +1,100 @@
-# Architekturentscheidungen
+# Greenfield SIEM – Architektur 1.2
 
-## 1. MariaDB ist kein Event Store mehr
+## Leitprinzip
 
-PostgreSQL ist ausschließlich Control Plane. ClickHouse ist ausschließlich Event-/Analytics-Plane. Dadurch konkurrieren Agent-Updates, Incident-Status und Benutzeraktionen nicht mit Milliarden append-only Events.
+Der skalierbare Eventpfad und die SIEM-Produktebene sind getrennt. Ein langsames Dashboard, eine Rule-Auswertung oder ein Grafana-Query darf niemals den HTTP-Ingress blockieren.
 
-## 2. Queue vor Datenbank
+```text
+Collectors
+   │
+   ▼
+HTTP Ingress ───────────────► PostgreSQL (Agent-Auth)
+   │ 202 Accepted
+   ▼
+Redpanda
+   │
+   ▼
+Processor ─────► ClickHouse events ─────► Rule Engine
+   │                    │                     │
+   │                    │                     ▼
+   │                    │                PostgreSQL Findings
+   │                    │
+   │                    ├────► Analyst API/UI
+   │                    └────► Grafana (read-only)
+   │
+   └────► gzip spool ─────► Garage/S3
 
-Der Ingress quittiert erst, nachdem Redpanda den Batch bestätigt hat. ClickHouse-Ausfälle führen damit nicht zu HTTP-Timeout-Kaskaden bei den Collectoren. Der Processor kann nachholen, solange die Queue-Retention nicht überschritten wird.
+Prometheus ◄──── Ingress / Redpanda / ClickHouse
+    │
+    └─────────────────────► Grafana Pipeline Health
+```
 
-## 3. Ein kanonisches Event
+## Stores
 
-Es gibt keine parallelen `event_logs`, `event_occurrences`, `event_count_buckets`, `raw_event`- und Rule-Helper-Kopien mehr. Die einzige langfristige Eventtabelle ist `siem.events`. Das Dashboard-Rollup ist eine explizite, kleine Materialized View.
+### ClickHouse
 
-## 4. Raw getrennt von Analytics
+Einzige kanonische, vollständig durchsuchbare Eventtabelle. Normalisierte Felder werden spaltenorientiert gespeichert; unbekannte Restattribute liegen begrenzt in einer Map. Vollständige XML-/Raw-Batches werden nicht dupliziert.
 
-Raw-Payloads sind für Parserfehler und Forensik wertvoll, aber ungeeignet als primäre Analytics-Zeile. Sie werden gzip-komprimiert in S3-kompatiblen Object Storage verschoben. ClickHouse speichert nur den Object-Key und den Index im Batch.
+- `events`: 90 Tage Standard-TTL
+- `events_5m`: 5-Minuten-Rollup, 730 Tage Standard-TTL
+- `ReplacingMergeTree` + stabile `event_uid` gegen Retry-Duplikate
 
-## 5. Kein Graph als Primärspeicher
+Auf dem bekannten KVM-Host wird `26.3.17.56` verwendet, weil diese Version mit dem präsentierten QEMU-CPU-Modell läuft.
 
-Graph-Sichten können später aus ClickHouse abgeleitet werden, z. B. `(User)-[:LOGGED_ON_TO]->(Host)` mit `first_seen`, `last_seen`, `count`. Jedes einzelne Event als Graph-Knoten würde die gleiche Explosion nur in einer anderen Engine wiederholen.
+### PostgreSQL
 
-## 6. Keine TSDB für Security-Events
+Nur Control Plane und Workflow:
 
-Prometheus überwacht die Pipeline, speichert aber keine Benutzer-/Host-/IP-Eventdimensionen. Hochkardinale Security-Attribute gehören nach ClickHouse.
+- Agents / Enrollment
+- Rule-Sets und Rule-Registry
+- Suppressions
+- Detections / Status
 
-## 7. Idempotenz
+Keine Eventhistorie.
 
-Redpanda/Kafka-Consumer liefern at-least-once und auch ein Collector kann nach einem HTTP-Timeout denselben Batch erneut senden. Deshalb berechnet der Ingress `batch_uid = SHA-256(agent_id + Batch-Inhalt)` und der Processor verwendet `event_uid = batch_uid:index`. ReplacingMergeTree und `uniqExact`-States verhindern damit Zählfehler bei Queue- und identischen HTTP-Retries.
+### Redpanda
 
-## 8. UI ist kein Compute-Job
+Persistenter Recovery-Puffer und Entkopplung zwischen Ingress und Verarbeitung. Standard-Retention 24 Stunden.
 
-Die Startseite liest `events_5m` und PostgreSQL-Findings. Sie startet keine Detection-Regeln. Die Event-Timeline hat immer ein begrenztes Zeitfenster und Limit.
+### Garage/S3
 
-## 9. Retention nach Datenklasse
+Komprimiertes Rohdatenarchiv. Standard-Retention 30 Tage.
 
-- normalisierte Events: 90 Tage
-- Raw: 30 Tage
-- Rollups: 730 Tage
-- Queue: 24 Stunden
+### Prometheus
 
-Diese Werte sind Defaults, keine Compliance-Aussage. Rechtliche und organisatorische Anforderungen haben Vorrang.
+Nur Betriebsmetriken. Keine Benutzer/IP/Event-ID-Kardinalität als Labels.
+
+## Rule Engine
+
+Built-in-Rule-Sets liegen unter `deploy/rules/*.json`. Der Detector synchronisiert sie nach PostgreSQL. Das ermöglicht Versionierung im Repository und Laufzeitsteuerung über das UI.
+
+Die Rule-Definition enthält kein freies SQL. Der Compiler akzeptiert nur erlaubte Felder, Operatoren, Gruppierungen und Regeltypen und erzeugt daraus begrenzte ClickHouse-Abfragen.
+
+Regeltypen:
+
+- Event Match
+- Threshold
+- Distinct/Spread
+
+Rule-Set- und Regel-Aktivierungszustände werden nicht durch ein Softwareupdate zurückgesetzt.
+
+## Analystenoberflächen
+
+### SIEM Analyst UI
+
+Für operative Arbeit:
+
+- Overview
+- Event Investigation und Drill-down
+- Detections / Status
+- Rule-Sets / Custom Rules
+- Suppressions
+- Agents
+
+### Grafana
+
+Für Exploration, Visualisierung und Betriebsüberwachung. Grafana erhält einen eigenen ClickHouse-Account mit ausschließlich SELECT-Rechten. Das mitgelieferte Datasource-Provisioning verbindet Grafana direkt mit ClickHouse; Prometheus ist die zweite provisionierte Datasource.
+
+## Availability
+
+Das One-Click-Compose ist ein Single-Node-Deployment und nicht hochverfügbar. Die Architektur erlaubt später getrennte Redpanda-/ClickHouse-/PostgreSQL-/Object-Storage-Nodes, ohne den HTTP-Vertrag oder das Eventmodell zu ändern.