siem-backend/README.md

Greenfield SIEM

Release 1.2 – Product Restoration: Die skalierbare Greenfield-Pipeline bleibt bestehen; Rule-Sets, Suppressions, Grafana und ein deutlich umfangreicheres Analysten-UI sind wieder Bestandteil des Produkts. ClickHouse ist für den bekannten KVM-Host standardmäßig auf 26.3.17.56 gepinnt.

Kompletter Neuaufbau des bisherigen Eventpfads. Der HTTP-Ingress-Vertrag bleibt kompatibel, die SIEM-Produktebene wurde gegenüber der ersten Greenfield-Version wieder vollständig ausgebaut.

Was dieses Projekt löst

Der Eventpfad ist append-only, asynchron und auf große Datenmengen ausgelegt:

Windows Agents
    │ POST /ingest
    ▼
Ingress API ──► PostgreSQL (nur Agent-Authentifizierung / Control Plane)
    │
    ▼
Redpanda (persistente Queue, 24h Recovery-Puffer)
    │
    ▼
Processor
    ├──► ClickHouse (normalisierte, durchsuchbare Events, 90 Tage)
    └──► gzip Spool ──► Garage/S3 (Raw-Batches, 30 Tage)
             │
             └── rclone übernimmt Upload + Retention

ClickHouse ──► Rule Engine ──► PostgreSQL (Rules / Suppressions / Findings)
ClickHouse + PostgreSQL ──► Analyst API/UI
ClickHouse + Prometheus ──► Grafana

Keine Event-Zeilen in PostgreSQL. Keine MariaDB. Keine synchronen Detection-Abfragen im Ingress. Keine Raw-XML-Duplikate in ClickHouse.

One-click Deployment

Voraussetzung: Docker Engine / Docker Desktop mit Docker Compose Plugin.

Linux / macOS / WSL

chmod +x deploy.sh
./deploy.sh

Windows PowerShell

./deploy.ps1

Das Deployment vervollständigt bei jedem Start die .env, ohne vorhandene Secrets zu überschreiben. Fehlende Secrets werden kryptographisch zufällig erzeugt. Die Garage-Konfiguration wird anschließend automatisch von einem Compose-Init-Service erzeugt; ClickHouse-Schema und TTLs werden bei jedem Start idempotent geprüft. Danach werden die SIEM-Binaries gebaut und alle Dienste gestartet.

Danach:

• UI: http://SERVER:8080/ui
• Ingress: http://SERVER:8090/ingest
• Grafana: http://SERVER:3000 (Port wird bei Konflikten automatisch verschoben)
• Redpanda Console: lokal http://127.0.0.1:8081
• Prometheus: lokal http://127.0.0.1:9090

Beim ersten Start werden UI_USERNAME=admin und ein zufälliges UI_PASSWORD erzeugt. Browser fragen diese Zugangsdaten beim Öffnen von /ui ab.

Alle konfigurierbaren Parameter stehen in .env.example. deploy.sh/deploy.ps1 ergänzt fehlende Schlüssel automatisch in einer vorhandenen .env; damit werden auch unvollständige .env-Dateien aus der ersten Greenfield-Version repariert. Zugangsdaten lassen sich jederzeit mit ./credentials.sh anzeigen.

UI-Benutzer/Passwort und Enrollment-Key werden am Ende des Deployments ausgegeben und stehen außerdem in der geschützten .env. Die UI/API ist standardmäßig per HTTP Basic Auth geschützt; für Zugriff über ein fremdes Netz gehört zusätzlich TLS davor.

Bestehende Collector können den bisherigen Enrollment-Key weiterverwenden, ohne eine .env von Hand anzulegen. Linux/macOS/WSL: ENROLLMENT_KEY="ALTER_KEY" ./deploy.sh. PowerShell: $env:ENROLLMENT_KEY="ALTER_KEY"; ./deploy.ps1. Alle anderen Secrets werden trotzdem zufällig erzeugt.

Upgrade / Reparatur der ersten Greenfield-Version

Die erste ausgelieferte Greenfield-Version hatte drei Deployment-Probleme:

1. deploy/garage/garage.toml wurde erst auf dem Host erzeugt und fehlte im ZIP; außerdem war rpc_public_addr für das Single-Node-Setup ungünstig gesetzt.
2. ClickHouse exponierte nur HTTP 8123, nicht den nativen Client-Port 9000.
3. .env enthielt nur einen Teil der tatsächlich konfigurierbaren Parameter.

Mit dieser Version reicht im bestehenden Projektverzeichnis:

./deploy.sh
./doctor.sh

Das Deploy-Skript behält bestehende Secrets, ergänzt fehlende .env-Werte und erzeugt Garage-Konfiguration sowie ClickHouse-Schema über Compose-Init-Services neu. Die Daten-Volumes werden dabei nicht gelöscht.

Falls .env gelöscht wurde, aber alte PostgreSQL-Volumes mit einem unbekannten alten Passwort weiter existieren, kann dieses Passwort nicht automatisch rekonstruiert werden. In einer reinen Testinstallation ist dann ./reset-DANGEROUS.sh der saubere Neustart; bei produktiven Daten zuerst Backup beziehungsweise Passwort-Recovery durchführen.

ClickHouse-Zugang

Für den bekannten KVM-Host mit QEMU Virtual CPU version 2.5+ ist clickhouse/clickhouse-server:26.3.17.56 der Standard, weil diese Version auf der VM nachweislich startet, während 26.6 dort mit SIGILL/Exit 132 abbricht. Der Preflight testet das Binary vor dem Stackstart.

ClickHouse besitzt zwei verschiedene Schnittstellen:

• HTTP: 127.0.0.1:8123
• nativer ClickHouse-Client: 127.0.0.1:9000

Benutzer, Passwort und Datenbank stehen vollständig in .env:

CLICKHOUSE_DB=siem
CLICKHOUSE_USER=siem
CLICKHOUSE_PASSWORD=...
CLICKHOUSE_HTTP_PORT=8123
CLICKHOUSE_NATIVE_PORT=9000

Am einfachsten:

./credentials.sh
docker compose exec clickhouse clickhouse-client \
  --user "$(grep '^CLICKHOUSE_USER=' .env | cut -d= -f2-)" \
  --password "$(grep '^CLICKHOUSE_PASSWORD=' .env | cut -d= -f2-)" \
  --database "$(grep '^CLICKHOUSE_DB=' .env | cut -d= -f2-)"

Für DBeaver/DataGrip oder einen lokalen clickhouse-client den nativen Port 9000 verwenden. Port 8123 ist die HTTP-Schnittstelle, keine Login-Weboberfläche.

Garage-Zugang / Diagnose

Garage wird im Single-Node-Modus automatisch konfiguriert. Die Konfiguration liegt in einem Docker-Volume und muss nicht mehr als Host-Datei erzeugt werden. Prüfung:

docker compose exec garage /garage status
docker compose logs --tail=100 garage garage-config

S3 läuft lokal auf 127.0.0.1:3900. Access-Key, Secret-Key und Bucket stehen in .env.

Bestehender Ingress bleibt kompatibel

POST /ingest
X-API-Key: <agent-api-key>
X-Enrollment-Key: <nur bei Erstanmeldung erforderlich>
Content-Type: application/json

Beispiel:

[
  {
    "host": "CLIENT-01",
    "channel": "Security",
    "id": 4740,
    "source": "windows-agent",
    "ts": "2026-07-23T12:00:00Z",
    "meta": {
      "provider": "Microsoft-Windows-Security-Auditing",
      "target_user": "alice",
      "workstation": "CLIENT-42",
      "src_ip": "10.10.20.15"
    }
  }
]

Alternativ darf msg weiterhin das bisherige Windows-XML enthalten. Der Processor extrahiert daraus die relevanten Felder. Das XML wird nicht als ClickHouse-Spalte gespeichert, sondern nur im komprimierten Raw-Archiv.

Erfolgreiche Aufnahme:

{"accepted":1}

HTTP 202 bedeutet: Der Batch wurde authentifiziert und dauerhaft in die Queue geschrieben. ClickHouse muss dafür nicht synchron antworten.

Speicherdesign

ClickHouse siem.events

Eine kanonische Tabelle enthält u. a.:

• Event- und Ingest-Zeit
• Agent / Host / Channel / Provider / Event-Code
• normalisierte category, action, outcome, severity
• User / Subject / Target User
• Source-/Destination-IP und Ports
• Workstation
• Logon-Type
• Prozess / Parent-Prozess / Commandline
• seltene XML-Felder in attributes Map(String,String)
• Raw-Object-Key + Index im archivierten Originalbatch
• Queue-Partition / Offset / stabile Event-UID
• Ingest-Verzögerung zur Erkennung von Agent-/Queue-Zeitproblemen
• häufige Authentifizierungsdetails (Domain, Status/Substatus, FailureReason, Auth-Package)

Häufig genutzte Felder werden nicht zusätzlich in attributes dupliziert. Die Map enthält nur unbekannte Restfelder, maximal 32 Einträge pro Event mit begrenzter Länge. Das vollständige Original bleibt im Raw-Archiv.

Die Tabelle verwendet ReplacingMergeTree, Monats-Partitionen und einen zeitbasierten Sortierschlüssel. Die Standard-TTL beträgt 90 Tage.

Deduplication

Die Pipeline ist absichtlich at-least-once. Ein Crash nach ClickHouse-Insert aber vor dem Redpanda-Commit kann einen Batch erneut liefern.

Daher erhält schon der Ingress-Batch eine stabile ID aus SHA-256(agent_id + Batch-Inhalt). Die Event-ID lautet:

<batch_uid>:<event-index-im-batch>

Damit werden sowohl ein Redpanda-Retry als auch ein identischer HTTP-Retry des Collectors als dasselbe Event erkannt. Queue-Partition und Offset werden zusätzlich nur zur Provenienz gespeichert.

• Eventtabelle: ReplacingMergeTree
• Detection-Zähler: uniqExact(event_uid)
• Dashboard-Rollups: uniqExactState(event_uid) / uniqExactMerge

Wiederholte Verarbeitung verfälscht damit keine Zähler.

Dashboard-Rollup

siem.events_5m wird über eine Materialized View fortlaufend gepflegt. Die Startseite zählt nicht Millionen Einzelereignisse, sondern arbeitet auf dem 5-Minuten-Rollup.

Standard-Retention:

Datenklasse	Retention
Vollständig durchsuchbare normalisierte Events	90 Tage
5-Minuten-Rollups	730 Tage
Raw-Batches in Garage/S3	30 Tage
Redpanda Recovery-Queue	24 Stunden
Detections / Agent-Metadaten	dauerhaft, bis organisatorisch bereinigt
Prometheus Betriebsmetriken	30 Tage

Anpassbar vor dem ersten Start in .env:

EVENT_RETENTION_DAYS=90
ROLLUP_RETENTION_DAYS=730
RAW_RETENTION=720h
KAFKA_RETENTION_MS=86400000

Rule-Sets und Detection Engine

Der Detector ist nicht mehr auf einige hart codierte Go-Regeln beschränkt. Beim Start werden versionierte Rule-Sets aus deploy/rules/ nach PostgreSQL synchronisiert. Aktivierungszustände aus dem UI bleiben bei Updates erhalten. Eigene Regeln werden im Rule-Set custom gespeichert.

Mitgeliefert werden 19 Regeln in vier Rule-Sets:

Rule-Set	Regeln	Beispiele
Windows Core	5	Audit Log gelöscht, Dienst installiert, Scheduled Task, Audit Policy, Firewall
Windows Authentication	5	Lockout, Failed-Logon-Burst, Password Spray, Kerberos, NTLM
Windows Account & Admin	5	privilegierte Gruppen, Benutzer angelegt/aktiviert/gelöscht, Passwort-Reset
Defender & PowerShell	4	Malware, Defender deaktiviert, EncodedCommand, verdächtige Download-/Memory-Muster

Regeltypen sind event, threshold und distinct. Bedingungen werden über eine Feld-/Operator-Allowlist in ClickHouse-SQL kompiliert; Rule-Dateien enthalten kein frei ausführbares SQL. Einzelne Regeln und komplette Rule-Sets können aktiviert/deaktiviert werden. Suppressions können nach Rule-ID, Host, User oder Source-IP begrenzt und zeitlich befristet werden.

Es gibt weiterhin keine pauschale new_event_id-Detection. Event 5857 und vergleichbare Betriebsereignisse sind normale Events. Details zum Format stehen in RULES.md.

Analysten-UI

/ui ist wieder eine eigentliche SIEM-Oberfläche und nicht nur eine einfache Eventtabelle. Enthalten sind:

• Overview: 24h-KPIs, Eventvolumen, Top Hosts/Event-IDs und Authentication-Übersicht
• Investigation: Zeit-, Host-, User-, IP-, Event-ID-, Channel- und Textfilter mit Drill-down
• Event Details: Message, Commandline, relevante Attribute, Raw-Archiv-Referenz und Normalisierungsfelder
• Detections: Severity, Status, Rule/Rule-Set, MITRE-Tags und Status-Workflow
• Rule-Sets: Set- und Regel-Toggles sowie Custom-Rule-Editor
• Suppressions: anlegen und entfernen, optional mit Ablaufzeit
• Agents: Enrollment-/Last-Seen-Übersicht und Aktivierung

Die initiale Investigation ist zeitlich und per Ergebnislimit begrenzt. Das Overview verwendet kleine Rollups beziehungsweise begrenzte Aggregationen statt unkontrollierter Vollscans.

Grafana

Grafana ist wieder Bestandteil des Standard-Stacks. Es wird automatisch mit einem dedizierten, SELECT-only ClickHouse-Benutzer und dem ClickHouse-Datasource provisioniert. Das administrative SIEM-UI und Grafana haben bewusst getrennte Aufgaben: UI für Workflow/Rules/Findings, Grafana für freie Visualisierung und Explore.

Mitgelieferte Dashboards:

• SIEM Security Overview: Eventvolumen, aktive Hosts, Failed Logons, Lockouts, Top Hosts/Event-IDs, Authentication, Top Failed Users und Source-IPs
• SIEM Pipeline Health: Ingress/Redpanda/ClickHouse-Erreichbarkeit, Event-/Batch-Rate, Rejections und Scrape-Latenzen

Zugangsdaten:

./credentials.sh

Standardmäßig:

http://SERVER:3000

GRAFANA_PORT wird wie die anderen Host-Ports durch preflight.sh auf Konflikte geprüft.

Raw-Event wiederherstellen

Die Eventliste enthält raw_object_key. Das Original ist ein gzip-komprimierter Ingress-Batch.

Einfacher über das mitgelieferte Hilfsskript:

./raw-event.sh '2026/07/23/12/<object>.json.gz' <raw_index>

Ohne raw_index wird der gesamte dekomprimierte Ingress-Batch ausgegeben. raw_index bezeichnet das Event innerhalb dieses JSON-Batches.

Stress-Test

Der Stress-Agent ist im selben Image enthalten und benötigt eine explizite Bestätigung:

docker compose run --rm ingress stress-agent \
  --url http://ingress:8080/ingest \
  --api-key stress-agent-key \
  --enrollment-key "$(grep '^ENROLLMENT_KEY=' .env | cut -d= -f2-)" \
  --scenario mixed \
  --rate 5000 \
  --batch 250 \
  --duration 5m \
  --confirm-load-test

Szenarien: mixed, failed-logon, lockout, catalog.

Nur in einer kontrollierten Umgebung beziehungsweise gegen das eigene SIEM verwenden.

Betriebschecks

Der schnellste Gesamtcheck:

./doctor.sh

Er prüft Containerstatus, HTTP-Readiness, Redpanda/Consumer-Lag, ClickHouse-Zeilen und Speicher, aktuelle Ingest-Verzögerung, Control-Plane-Zähler, Raw-Spool und aktuelle Fehler.

Zusätzlich:

docker compose ps
docker compose logs -f ingress processor detector api

Ingress:

curl http://127.0.0.1:8090/healthz
curl http://127.0.0.1:8090/readyz

ClickHouse Zeilenzahl / Speicher:

docker compose exec clickhouse clickhouse-client \
  --user "$(grep '^CLICKHOUSE_USER=' .env | cut -d= -f2-)" \
  --password "$(grep '^CLICKHOUSE_PASSWORD=' .env | cut -d= -f2-)" \
  --query "SELECT formatReadableQuantity(sum(rows)), formatReadableSize(sum(bytes_on_disk)) FROM system.parts WHERE database='$(grep '^CLICKHOUSE_DB=' .env | cut -d= -f2-)' AND table='events' AND active"

Queue:

docker compose exec redpanda rpk group describe siem-processor-v1

Hardware für das Single-Node-Deployment

Für einen Test reichen typischerweise 4 CPU-Kerne, 8 GB RAM und SSD-Speicher. Für eure bisher beobachtete Produktivrate würde ich mindestens 8 Kerne, 16 GB RAM und schnelle lokale NVMe einplanen. Die benötigte SSD-Größe hängt stark von Eventgröße, Commandlines und Raw-XML ab; ./doctor.sh zeigt die reale Kompression und Wachstumsrate, sodass die Retention nach einigen Tagen anhand echter Werte dimensioniert werden kann.

Kapazität

Die bisher beobachteten ca. 19,2 Mio. Events in 48 Stunden entsprechen nur rund 111 Events/s. Das ist für ClickHouse/Redpanda eine kleine Last. Der neue Pfad ist bewusst für deutlich höhere Raten gebaut; die reale Grenze hängt vor allem von CPU, SSD-Durchsatz, Eventgröße, Anzahl der Hosts und Query-Last ab.

Für hohe Last zuerst skalieren:

1. KAFKA_PARTITIONS erhöhen und mehrere Processor-Instanzen starten.
2. ClickHouse auf schnelle lokale NVMe legen.
3. Redpanda und ClickHouse nicht auf dieselbe langsame Netzwerkplatte legen.
4. Raw-Retention reduzieren, wenn XML sehr groß ist.
5. Erst ab echtem Bedarf ClickHouse / Redpanda / Garage als Mehrknoten-Cluster betreiben.

Single-node vs. HA

compose.yml ist ein One-click Single-node Deployment. Es eliminiert die bisherigen Architekturprobleme, ist aber kein hochverfügbarer Cluster: fällt der eine Docker-Host aus, sind alle Komponenten betroffen.

Für echte HA sind mindestens sinnvoll:

• 3 Redpanda Broker, Replication Factor 3
• repliziertes ClickHouse (oder ClickHouse Cloud)
• 3 Garage Nodes / anderes redundantes S3
• PostgreSQL mit Backup/Replica
• Reverse Proxy/TLS und zentraler Identity Provider vor UI/API

Die Anwendungskomponenten selbst sind stateless und können danach horizontal vervielfacht werden.

Sicherheit

• Datenbank-, Redpanda-, Garage- und Prometheus-Adminports binden standardmäßig nur an 127.0.0.1.
• Nur Ingress und UI binden standardmäßig an 0.0.0.0.
• UI/API verlangen ein beim Deployment zufällig erzeugtes Basic-Auth-Passwort.
• Für produktiven externen Zugriff gehört trotzdem TLS/Reverse-Proxy vor Ingress und UI, da Basic Auth allein keine Transportverschlüsselung bietet.
• .env enthält Secrets und darf nicht ins Repository.
• Der Ingress speichert ausschließlich SHA-256-Hashes der Agent-API-Keys in PostgreSQL.
• Raw-Logs können personenbezogene Daten enthalten. Retention und Zugriffsrechte entsprechend festlegen.

Projektstruktur

cmd/siem                 ein Binary, mehrere Rollen
internal/ingress         kompatible HTTP-Aufnahme
internal/queue           Redpanda/Kafka Producer + Consumer
internal/processor       Normalisierung + ClickHouse + Raw-Spool
internal/normalize       Windows XML / Meta → kanonisches Event
internal/clickhouse      ClickHouse HTTP-Client
internal/postgres        Agenten + Detections
internal/detector        kontinuierliche Regeln
internal/api             Investigation API + UI
internal/stress          begrenzter Lastgenerator
doctor.sh                 Pipeline-/Kapazitätsdiagnose
raw-event.sh              Raw-Archiv abrufen
deploy/clickhouse        analytisches Schema
deploy/postgres          Control-Plane-Schema
compose.yml              erzeugt Garage-Konfiguration zur Laufzeit aus `.env`
deploy/prometheus        Betriebsmetriken

Reset

Nur wenn wirklich alle Daten weg sollen:

./reset-DANGEROUS.sh

Das Skript verlangt zusätzlich die Eingabe DELETE und entfernt anschließend die Docker-Volumes.

CPU-Kompatibilität und Portkonflikte

deploy.sh führt vor dem eigentlichen Start einen echten ClickHouse-Binary-Probe in einem kurzlebigen Container aus. Ein Illegal instruction/Exit 132 wird dadurch erkannt, bevor der Stack in eine Restart-Schleife gerät.

Bei amd64 benötigt das offizielle ClickHouse-Image mindestens SSE3. Bei arm64 setzt das offizielle Image ARMv8.2-A plus RCpc voraus. Bei VMs sollte deshalb nach Möglichkeit das CPU-Modell host beziehungsweise CPU-Passthrough verwendet werden.

Zusätzlich erkennt deploy.sh bereits belegte Host-Ports. Wenn AUTO_PORTS=true ist, werden nur kollidierende Ports auf freie Ersatzports verschoben und in .env gespeichert. Die tatsächlich verwendeten Werte zeigt anschließend ./credentials.sh.

Für eine vollständige Hostdiagnose:

./host-info.sh