Push-Ingest: Vertrag und Auswertung

Handbuch · API und Verfügbarkeit · Datenquellen einrichten · Adapter

Diese Referenz gilt für die Push-Erweiterung nach v1.25.0. Die maschinenlesbaren Schemas stehen in der OpenAPI-Spezifikation der eigenen Instanz. Für die erste Einrichtung die Schrittfolge für Datenquellen verwenden.

Endpunkte

Basispfad auf der eigenen Instanz: /api/v1/integrations. Authentifizierung, Größenbegrenzung und Rate-Limit sind in der API-Anleitung beschrieben. Schreibanfragen benötigen Content-Type: application/json.

Methode	Pfad relativ zum Basispfad	Zweck / Scope
GET	/identity	Schlüssel-ID und zugeordnete Quellen; ingest:write
GET	/sources	Quellenliste; integrations:read
POST	/sources	Quelle anlegen; integrations:manage und Fachrechte
GET	/sources/{id}	Konfiguration und Aktualität; integrations:read
PUT	/sources/{id}	Vollständige Konfiguration mit Revision ändern; integrations:manage und Fachrechte
GET	/sources/{id}/bindings	Zuordnungen und Fehlstatus; integrations:read
POST	/sources/{id}/bindings	Explizite Zuordnung und Feldzuständigkeit; integrations:manage und Fachrechte
POST	/sources/{id}/batches	Atomarer Import; der Quelle zugeordneter Schlüssel mit ingest:write
GET	/sources/{id}/observations	Nachweismetadaten; integrations:read
GET	/sources/{id}/observations/{childId}	Nachweis mit entschlüsseltem Inhalt; integrations:read
GET	/sources/{id}/deviations	Abweichungsliste; integrations:read
GET	/sources/{id}/deviations/{childId}	Abweichung samt Begründung; integrations:read
PUT	/sources/{id}/deviations/{childId}	Fallentscheidung; integrations:manage
GET	/sources/{id}/deviations/{childId}/decisions	Unveränderliche Entscheidungshistorie mit entschlüsselten Begründungen; integrations:read

Fachrechte bei Quellen und Bindings: assets:read plus assets:write bzw. backup-jobs:read plus backup-jobs:write. Beim Verknüpfen einer Maßnahme zusätzlich measures:read und measures:write.

Listen antworten mit { "items": [], "offset": 0, "limit": 100 }. offset beginnt bei 0, limit liegt zwischen 1 und 100 und ist standardmäßig 100. Für vollständige Ergebnisse den Offset um die Seitengröße erhöhen, bis eine kürzere oder leere Seite zurückkommt. Alle Pfad-IDs sind UUIDs.

Quellenkonfiguration und Binding

Feld	Vertrag
name	Nicht leer, höchstens 200 Zeichen
apiKeyId	UUID des zugeordneten Adapter-Schlüssels
enabled	Boolean
objectKind	asset oder backup_job; nach Anlage unveränderlich
coverage	Nicht leer, höchstens 200 Zeichen; nach Anlage unveränderlich
expectedIntervalHours	1 bis 8760 Stunden
missingGraceHours	0 bis 8760 Stunden
createAssets	null oder Vorgaben für neue Assets: ownerId, criticality (Ganzzahl 1 bis 5), assetType, managedFields; nur bei asset
rules	rpo, restore, sourceStale als Boolean; backupFailures als Ganzzahl 1 bis 20 oder null

Erlaubte assetType-Werte: server, database, service, software, network, cloud_service, other. managedFields enthält nur name, location, ip_address, os_platform, höchstens vier Einträge. Alle Konfigurationsfelder sind erforderlich; unbekannte Felder werden abgelehnt.

Ein Binding enthält externalId (nicht leer, maximal 200 Zeichen), targetId (UUID) und managedFields. Für ein bestehendes Binding muss das Ziel unverändert bleiben. Die Quellenanlage antwortet mit { "id": "UUID", "revision": 1 }; Änderungen verwenden { "revision": 1, "source": { ... } } und liefern die erhöhte Revision. Lesende Antworten enthalten die Regeln und fachlichen Vorgaben unter config sowie Zeitstempel wie last_received_at und last_observed_at.

Batch-Vertrag

Beispiel für eine bereits gebundene Assetquelle mit Compliance-Nachweis. UUID, Quellenrevision, Coverage, Zeitpunkte und externe ID durch tatsächliche Werte ersetzen:

{
  "schemaVersion": 1,
  "batchId": "8d2ce318-9ab1-4e50-b715-94e690c1d250",
  "sourceRevision": 1,
  "coverage": "site-a-managed-assets",
  "mode": "delta",
  "observedAt": "2026-09-19T08:00:00Z",
  "totalObjects": 1,
  "objects": [
    {
      "externalId": "device-123",
      "observations": [
        {
          "eventId": "device-123-compliance-20260919T080000Z",
          "checkType": "device_compliance",
          "result": "passed",
          "observedAt": "2026-09-19T08:00:00Z",
          "validUntil": "2026-09-20T08:00:00Z",
          "evidence": { "summary": "Die zugeordneten Geräterichtlinien sind erfüllt." }
        }
      ]
    }
  ]
}

Feld	Vertrag
schemaVersion	Aktuell exakt 1
batchId	UUID, vor dem ersten Senden dauerhaft speichern
sourceRevision, coverage	Müssen zur aktuellen Quellenkonfiguration passen
mode	delta für Teillieferung, full für den gesamten konfigurierten Bereich
observedAt	Erhebungszeitpunkt mit Zeitzone; höchstens fünf Minuten in der Zukunft
totalObjects	Exakte Länge von objects, auch bei 0
objects[].externalId	Stabile ID, nicht leer, maximal 200 Zeichen und pro Batch eindeutig
objects[].asset	Optional; bei Neuanlage erforderlich. name ist Pflicht, bis 200 Zeichen; location, ip_address, os_platform optional, jeweils bis 200 Zeichen oder null
objects[].observations	Pflicht-Array, auch leer zulässig

Grenzen je Anfrage: 1 MiB JSON, 500 Objekte, insgesamt 1000 Beobachtungen, höchstens 20 Beobachtungen pro Objekt. Unbekannte Felder sind unzulässig. Ein full-Batch wird nicht über mehrere Requests zusammengesetzt. Die Anzahl bestätigt nur den Inhalt des Requests; sie beweist keinen vollständigen Herstellerabruf.

Alle Änderungen eines Batches werden gemeinsam angenommen oder zurückgerollt. Erfolg antwortet mit HTTP 200:

{
  "batchId": "8d2ce318-9ab1-4e50-b715-94e690c1d250",
  "objects": [{ "externalId": "device-123", "targetId": "UUID-IN-ISMS-LITE" }],
  "observations": 1
}

observations zählt neu eingefügte Beobachtungen. Identische bekannte Ereignisse werden nicht erneut gespeichert.

Beobachtungen und Evidence

Feld	Vertrag
eventId	Innerhalb der Quelle unveränderliche Ereignis-ID, maximal 200 Zeichen
checkType	backup_point, backup_run, restore_test, device_compliance, config_backup
result	passed, failed oder unknown
observedAt	Tatsächlicher Erhebungszeitpunkt mit Zeitzone, nicht später als der Batch-Zeitpunkt
validUntil	Später als observedAt, höchstens 366 Tage danach
restorePointAt	Optional oder null, nicht später als die Beobachtung; bei backup_point mit passed erforderlich
evidence.summary	Nicht leere Zusammenfassung, höchstens 4000 Zeichen
evidence.reference	Optionaler HTTPS-Link, höchstens 2000 Zeichen
evidence.sha256	Optionale SHA-256-Prüfsumme als 64 kleine Hex-Zeichen

Nachweisinhalte werden verschlüsselt gespeichert und beim berechtigten Detailabruf entschlüsselt; der Abruf wird protokolliert. Der Server lädt verlinkte Inhalte nicht herunter und prüft nicht selbst den behaupteten Hash einer externen Datei. Die Erreichbarkeit und Aufbewahrung externer Nachweise liegen beim Betreiber. Dokumentdateien über die Fach-API ablegen, keine Rohlogs, Backup-Dateien, Konfigurationen oder Geheimnisse als Summary einliefern.

Wiederholung, Reihenfolge und Vollabgleich

Dieselbe batchId mit demselben Inhalt liefert bei einer Wiederholung das ursprüngliche Ergebnis. Dieselbe ID mit verändertem Inhalt führt zu batchConflict. Identische eventId und Ereignisinhalte dürfen in späteren Batches erneut vorkommen. Veränderte Inhalte unter derselben Ereignis-ID führen zu eventConflict.

Neue Bewertungen erhalten neue Ereignis-IDs und neue Erhebungszeitpunkte. Die Kombination aus Objekt, Prüftyp und Zeitpunkt darf nicht durch ein anderes Ereignis mehrdeutig werden. Verspätete Nachweise bleiben historisch erhalten und ersetzen keinen neueren Bewertungsstand.

Ein neuer Vollabgleich muss zeitlich neuer sein als der zuletzt angenommene Vollabgleich. Fehlende Objekte werden nur durch einen erfolgreichen full-Batch und nach der konfigurierten Karenzzeit markiert. Ein verspäteter Delta-Stand hebt eine neuere Fehlmarkierung nicht auf. Der fachliche Assetstatus wird nicht automatisch auf stillgelegt gesetzt.

Bewertungsregeln

ISMS Lite wertet beim Import und ungefähr jede Minute aus. Es trennt das Prüfergebnis passed / failed / unknown vom Bearbeitungsstand eines Vorgangs.

Regel	Bewertung
rpo	Nur bei aktivierter Regel, Assetzuordnung und fachlich gesetztem Asset-RPO. Alter des gültig als verwendbar gemeldeten Restore-Punkts gegen das RPO: überschritten = failed, eingehalten = passed. Ohne gültigen verwendbaren Punkt = unknown.
restore_test	Bei aktivierter Restore-Regel Ergebnis des neuesten Nachweises; fehlend oder abgelaufen = unknown.
backup_failures	Die konfigurierte Anzahl neuester, aufeinanderfolgender, gültiger Fehlversuche ergibt failed. Neuester gültiger Erfolg = passed; nicht erreichte Fehlerschwelle oder unklare Daten = unknown.
source_stale	Bei aktivierter Regel nach Überschreiten von expectedIntervalHours seit letzter Erhebung = unknown; ohne Erhebung zählt die Quellenanlage.
object_missing	Seit vollständigem Abgleich nach Karenzzeit nicht mehr gesehen = unknown.
target_deleted	Fachliches Zielobjekt gelöscht = unknown; Historie bleibt bestehen.
device_compliance, config_backup	Ergebnis der neuesten gelieferten Beobachtung; nach Ablauf = unknown. Ohne bisherige Beobachtung dieses Typs keine solche Regelbewertung.

Abgelaufene Nachweise werden nicht als Erfolg fortgeschrieben. Ein Backup-Jobfehler beweist keine RPO-Verletzung. Die Auswertung des tatsächlichen Restore-Punkt-Alters ist getrennt von der bestehenden fachlichen Prüfung eines konfigurierten Backup-Intervalls.

Abweichungen bearbeiten

Für failed und unknown kann ein Integrationsvorgang entstehen. Pro Quelle, Objekt und Regel gibt es höchstens einen aktiven Vorgang. Er ist kein Audit-Finding und keine BCM-Übung.

state	Bedeutung
open	Fehler oder unbekannter Zustand besteht
recovered	Technisch wieder passed; fachlicher Abschluss steht aus
closed	Berechtigter Abschluss mit Begründung

Ein erneuter Fehler vor Abschluss öffnet denselben Vorgang wieder. Nach einem abgeschlossenen Vorgang kann eine neue Abweichung einen neuen Vorgang erzeugen. Zur Bearbeitung PUT /sources/{id}/deviations/{childId} mit allen vier Feldern senden:

{
  "state": "keep",
  "measureId": null,
  "exceptionUntil": null,
  "reason": "Ursache wird geprüft; nächste Bewertung nach dem geplanten Lauf."
}

keep behält den Bearbeitungsstand. measureId verknüpft eine vorhandene Maßnahme; null entfernt die Verknüpfung. Eine Maßnahme bei Bedarf zuerst über die Fach-API anlegen. exceptionUntil setzt eine begründete Ausnahme in der Zukunft, höchstens 365 Tage ab Entscheidung; null entfernt sie. excepted zeigt eine aktive Ausnahme, das Prüfergebnis bleibt sichtbar. reason ist erforderlich und höchstens 4000 Zeichen lang. Vorhandene Verknüpfungen und Ausnahmen vor einer Änderung lesen und bewusst wieder mitsenden.

state: "close" schließt nach Prüfung einen erholten Vorgang. Noch aktive Vorgänge dürfen nur geschlossen werden, wenn die Quelle oder die zugehörige abschaltbare Regel deaktiviert wurde. Bereits geschlossene Vorgänge sind nicht weiter änderbar. Entscheidungen und Begründungen bleiben verschlüsselt als unveränderliche Historie unter /decisions erhalten.

Weder Erholung noch Abschluss erzeugen eine Risikoakzeptanz, Control-Freigabe oder Maßnahmenerledigung. Die automatische Anlage oder Erledigung von Maßnahmen ist nicht enthalten.

Konflikte beheben

Integrationsfehler verwenden beispielsweise HTTP 409, code: "conflict" und details.reason. Die folgende Tabelle nennt reason-Werte, keine eigenständigen Fehlercodes.

details.reason	Vorgehen
sourceRevision	Aktuelle Quelle lesen; Revision und Coverage prüfen. Bereits angenommene Batches unverändert lassen.
batchConflict	Dieselbe Batch-ID wurde anders verwendet. Originaldatei erneut senden oder für eine neue Lieferung eine neue ID erzeugen.
eventConflict	Ereignisinhalt wurde nachträglich verändert. Ursprüngliches Ereignis erhalten; eine neue Bewertung als neues Ereignis liefern.
observationTimeConflict	Objekt, Prüftyp und Zeitpunkt bereits durch anderes Ereignis belegt. Ereignisidentität und tatsächliche Erhebungszeiten prüfen.
oldSnapshot	Vollabgleich ist nicht neuer als der vorige. Tatsächlich neuen vollständigen Bestand erheben.
bindingRequired	Vorhandenes Ziel zuordnen oder bei Assetquellen die fachlich zulässige Neuanlage konfigurieren.
manualFieldConflict	Manuelle Änderung prüfen und Feldzuständigkeit im Binding bewusst korrigieren.
targetDeleted	Gelöschtes Ziel nicht erneut importieren; bei beabsichtigter Neuerfassung eine neue Quellenidentität verwenden.
deviationActive	Nur erholte oder ausdrücklich aus der Bewertung genommene Vorgänge schließen; geschlossene Vorgänge unverändert lassen.
exceptionDate	HTTP 400: Ausnahme muss zukünftig und höchstens 365 Tage entfernt sein.

Bei einem fachlichen Konflikt bleibt der gesamte Batch ohne Teilimport. Ein unverändert wiederholter 400 oder 409 löst die Ursache nicht. Bei unklarer Transportantwort dagegen dieselbe gespeicherte Datei erneut senden.