SIEM-Integration

Achtung

Der aktuelle verifizierte SIEM-Exportpfad ist event-zentriert ueber GET /events (Polling) und signierte Webhooks (Push). Cloud-Enrichment, Threat-Intelligence-Anreicherung und dedizierte SIEM-Exportformate (CEF, LEEF, OCSF) sind Zielarchitektur. Jobs, Incidents und Traces sind heute Operator-Reads, kein eigener SIEM-Exportstrom. Fuer die Grenzziehung zwischen Audit, Logging, Monitoring, SIEM und Telemetrie siehe superheld-architecture/specs/observability-separation.md.

Superheld laesst sich in bestehende SIEM-Plattformen (Security Information and Event Management) integrieren. Diese Seite beschreibt die verfuegbaren Integrationsmuster, das Event-Format und einen Beispiel-Workflow.

Hinweis

Das hier dokumentierte Event-Schema beschreibt den aktuellen kanonischen Zielvertrag. Der Workspace bildet diesen Vertrag inzwischen weitgehend ab, ohne dass daraus bereits ein unveränderlicher externer Stabilitätsanspruch abgeleitet werden sollte. Für Begriffsdefinitionen siehe Glossar.

Event-Struktur (kanonisch)

Jedes Superheld-Event wird als strukturiertes JSON-Objekt ausgeliefert — sowohl über Webhooks als auch über die Polling-API. Dieses Schema ist die kanonische Referenz.

{
  "event_id": "evt_7f2a9c",
  "type": "risk.event.created",
  "timestamp": "2026-03-14T14:32:08Z",
  "tenant_id": "tenant-acme",
  "device_id": "dev_3c8a1f",
  "threat_category": "phishing",
  "confidence": 0.94,
  "action_taken": "block",
  "policy_id": "pol_default",
  "severity": "high",
  "description": "Gefälschte Login-Seite eines Finanzdienstleisters erkannt und blockiert.",
  "indicators": [
    "sha256:a1b2c3d4e5f6...",
    "sig_fin_phish_042"
  ],
  "metadata": {
    "agent_version": "0.1.0",
    "model_version": "detect-v3.2",
    "device_platform": "android"
  }
}

Hinweis

Personenbezogene Daten werden vor der Übertragung redaktiert. URLs werden als SHA-256-Hashes übermittelt, E-Mail-Adressen durch Platzhalter ersetzt. Kanonische Bedrohungskategorien: phone_scam, social_engineering, malicious_app, phishing, remote_control, deepfake. Die öffentliche Dokumentation beschreibt hier bewusst nur die belastbaren Redaktionsprinzipien und nicht jede interne Regelvariante. Siehe Telemetrie und Logging.

Webhook-Integration

Die Webhook-Integration ermöglicht Echtzeit-Zustellung von Alerts an Ihr SIEM-System.

Einrichtung

Im aktuellen verifizierten Pfad werden Webhooks ueber die API registriert:

curl -s \
  -X POST http://127.0.0.1:8080/webhooks \
  -H "Authorization: Bearer <tenant-app-token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://siem.example.com/ingest","secret":"your-signing-secret"}'

Die Runtime erfordert eine HTTPS-URL und einen Signing-Secret. Ein Web-Dashboard fuer die Webhook-Verwaltung ist heute nicht als Ist-Stand belegt.

Superheld signiert jeden Webhook-Request mit einem HMAC-SHA256-Hash im Header X-Superheld-Signature. Ihr SIEM-System muss diese Signatur verifizieren, um die Authentizität sicherzustellen.

# Beispiel: Webhook-Signatur verifizieren
echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SIGNING_SECRET"

Achtung

Sicherheitshinweise für Webhook-Verifikation:

• Verwenden Sie einen zeitkonstanten Vergleich (constant-time comparison) zur Signaturprüfung, um Timing-Angriffe zu verhindern.
• Prüfen Sie die Signatur vor der Verarbeitung des Payloads.
• Speichern Sie den Signing-Secret nicht in Klartextlogs.
• Die aktuelle Workspace-Runtime dokumentiert keine zusaetzlichen Timestamp- oder Idempotency-Header fuer Webhook-Deduplication; Empfaenger sollten daher auf Event-IDs und ihre eigene Idempotenzlogik setzen.

Retry-Verhalten

Die aktuelle Workspace-Runtime wiederholt fehlgeschlagene Zustellungen (HTTP-Status >= 400) mit insgesamt 3 Versuchen und exponentiellem Backoff (1 s, 2 s, 4 s). Nach Ausschöpfen der Versuche landet die Zustellung in der Dead-Letter-Queue.

Polling-API

Alternativ zur Push-Methode können SIEM-Systeme Ereignisse periodisch über die REST-API abrufen.

curl -s "http://127.0.0.1:8080/events?severity=high&limit=100" \
  -H "Authorization: Bearer <tenant-app-token>"

Parameter	Typ	Beschreibung
severity	string	Einzelner Schweregrad als Filter
limit	integer	Maximale Anzahl zurückgegebener Ereignisse (max. 500)
cursor	string	Paginierungs-Cursor für folgende Seiten

Die API gibt has_more und cursor zurück, solange weitere Ergebnisse vorhanden sind. Ein typisches Polling-Intervall liegt bei 60 Sekunden für hochkritische Umgebungen oder 5 Minuten für Standardkonfigurationen.

Mapping auf SIEM-Events

Superheld-Alerts lassen sich direkt auf die Event-Taxonomien gängiger SIEM-Plattformen abbilden:

Superheld-Feld	Splunk CIM	Elastic ECS	Microsoft Sentinel
threat_category	signature	threat.indicator.type	ThreatType
severity	severity	event.severity	Severity
device_id	dest	host.id	DeviceId
source_channel	transport	event.module	SourceSystem
action_taken	action	event.action	ActionTaken
indicators.url_hash	url_hash	threat.indicator.url	Url

Beispiel-Workflow

Der folgende Ablauf zeigt, wie ein Superheld-Alert über das SIEM-System bis zur SOC-Untersuchung fließt:

Ablauf im Detail

1. Erkennung — Der Guardian Agent auf dem Endgerät erkennt eine Bedrohung und erzeugt ein Detection Event. Nur anonymisierte Metadaten werden an die Superheld Cloud übertragen.
2. Anreicherung — Die Superheld Cloud nimmt das Event entgegen, leitet Alerts und bei hoher Severity auch Incidents ab und stellt das Event ueber Webhooks oder GET /events zur Verfuegung. Threat-Intelligence-Anreicherung (bekannte Kampagnen, IOC-Abgleich) ist Zielarchitektur.
3. SIEM-Ingestion — Das angereicherte Event wird per Webhook an die SIEM-Plattform gepusht. Dort findet eine Korrelation mit bestehenden Events statt.
4. SOC-Investigation — Bei Übereinstimmung mit einer Erkennungsregel erzeugt das SIEM ein Ticket für das SOC-Team. Der Analyst kann über die Superheld-API zusätzliche Kontextdaten (Scan-Historie, Gerätedetails) abrufen.
5. Reaktion — Basierend auf der Bewertung löst der SOC-Analyst eine Maßnahme aus — etwa die Quarantäne des betroffenen Geräts oder die Freigabe eines fälschlich blockierten Elements.

Achtung

Stellen Sie sicher, dass Ihr SIEM-Endpunkt über eine gültige TLS-Konfiguration verfügt. Superheld lehnt Verbindungen zu Endpunkten ohne gültiges Zertifikat ab.

---

Technischer Support für Integrationen: integrations@superheld.app API-Dokumentation: API-Referenz Event-Schema: Siehe OpenAPI-Spezifikation Begriffe: Siehe Glossar