Datenquellen per Push anbinden

Handbuch · API und Verfügbarkeit · Adapter · Ingest-Referenz

Dieses Kapitel beschreibt die noch nicht in v1.25.0 veröffentlichte Push-Erweiterung. Prüfe vor der Einrichtung, ob deine Instanz die Integrationsendpunkte in ihrer OpenAPI-Spezifikation enthält.

Datenfluss und Zuständigkeit

Quellsystem im Kundennetz
  → lokaler Adapter: lesen, zuordnen, Batch dauerhaft speichern
  → ausgehend HTTPS / TCP 443
  → ISMS Lite: validieren, Nachweise speichern, Abweichungen bewerten
  → Verwaltungsclient: Abweichungen abrufen und Maßnahmen verknüpfen

Ein extern betriebener VPS benötigt dafür keinen Zugang ins Kundennetz. Hersteller-Zugangsdaten bleiben beim Adapter. Er benötigt lesenden Zugriff auf die Quellsysteme und ausgehend HTTPS zur ISMS-Instanz mit gültigem Zertifikat.

Verantwortlicher Aufgaben
Betreiber des Adapters Herstellerzugang, Filter, vollständiger Abruf einschließlich Paging, stabile IDs, Zuordnung, Zeitplanung, lokale Dateirechte und Überwachung
ISMS Lite Quellenbindung, Validierung, wiederholbare Annahme, verschlüsselte Nachweise, Audit-Protokoll und regelbasierte Abweichungen
Fachlich Verantwortliche Asset-Eigentümer, Kritikalität, RPO, Bewertung, Ausnahmen, Maßnahmen und Freigaben

ISMS Lite führt über diesen Kanal keine Netzwerk-Discovery durch, speichert keine laufenden Rohlogströme und steuert keine Backups oder Netzwerkgeräte. Es ersetzt weder Inventarisierung noch Monitoring, SIEM oder Backup-Software. Die Vollständigkeit einer Herstellerabfrage und die tatsächliche Nutzbarkeit eines gemeldeten Restore-Punkts müssen an der Quelle geprüft werden.

1. Zwei getrennte Schlüssel erstellen

Unter Einstellungen > API-Zugänge anlegen:

Schlüssel Scopes
Adapter ausschließlich ingest:write
Einrichtung und Verwaltung integrations:manage, integrations:read sowie assets:read und assets:write für Assetquellen oder backup-jobs:read und backup-jobs:write für Backup-Jobquellen

Den Verwaltungsschlüssel nicht im regelmäßig ausgeführten Adapter-Task hinterlegen. integrations:read erlaubt das Lesen sämtlicher Integrationsmetadaten und Nachweise der Instanz. Der reine Adapter-Schlüssel darf nur seinen zugeordneten Quellen Daten liefern; er erhält keinen allgemeinen Asset-Schreibzugriff.

Mit dem Adapter-Schlüssel seine ID ermitteln:

$env:ISMS_URL = 'https://isms.example.org'
# ISMS_API_KEY enthält den Adapter-Schlüssel aus dem Secret Store.
$adapterHeaders = @{ Authorization = "Bearer $env:ISMS_API_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/integrations/identity" -Headers $adapterHeaders

apiKeyId aus der Antwort für die Einrichtung übernehmen. sources ist vor der ersten Zuordnung leer; später enthält es zugeordnete Quellen mit id, revision, enabled, coverage und objectKind.

2. Quelle anlegen

Mit dem Verwaltungsschlüssel POST /api/v1/integrations/sources senden. Die folgenden UUID-Platzhalter ersetzen; alle gezeigten Felder gehören zur Konfiguration.

{
  "name": "Standort A - Inventarexport",
  "apiKeyId": "UUID-DES-ADAPTER-SCHLUESSELS",
  "enabled": true,
  "objectKind": "asset",
  "coverage": "site-a-managed-assets",
  "expectedIntervalHours": 24,
  "missingGraceHours": 72,
  "createAssets": {
    "ownerId": "UUID-EINES-AKTIVEN-VERANTWORTLICHEN",
    "criticality": 3,
    "assetType": "server",
    "managedFields": ["name", "location", "ip_address", "os_platform"]
  },
  "rules": {
    "rpo": false,
    "restore": false,
    "backupFailures": null,
    "sourceStale": true
  }
}

Beispielsweise diesen Inhalt als source.json speichern und senden:

# ISMS_MANAGEMENT_KEY stammt aus der geschützten Verwaltungsumgebung.
$managementHeaders = @{ Authorization = "Bearer $env:ISMS_MANAGEMENT_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/integrations/sources" `
    -Method Post -Headers $managementHeaders -ContentType 'application/json' -InFile source.json

Die Antwort enthält die Quellen-ID id und die Konfigurationsrevision revision. Beide für den Adapter aufbewahren.

  • coverage bezeichnet einen dauerhaft gleich abgegrenzten Bestand, etwa einen Standort. Filteränderungen, die den Umfang verändern, benötigen eine neue Quelle.
  • expectedIntervalHours legt die erwartete Aktualität fest. Der tatsächliche Task muss separat geplant werden.
  • missingGraceHours ist die Wartezeit für „nicht mehr gesehen“ nach einem vollständigen Abgleich.
  • createAssets erlaubt Neuanlagen mit ausdrücklich festgelegtem Eigentümer, Assettyp und Kritikalität. Vorher fachlich freigeben; null schaltet Neuanlagen ab.
  • Für Backup-Aufträge objectKind: "backup_job" und createAssets: null verwenden. Die Aufträge vorab im Fachmodul oder über dessen API anlegen.
  • rules schaltet RPO-, Restore- und Aktualitätsprüfungen ein. backupFailures ist die Anzahl aufeinanderfolgender Fehler von 1 bis 20 oder null für aus. Die Referenz erklärt die Bewertung.

3. Vorhandene Objekte zuordnen

Mit dem Verwaltungsschlüssel POST /api/v1/integrations/sources/{id}/bindings aufrufen:

{
  "externalId": "STABILE-ID-IM-QUELLSYSTEM",
  "targetId": "UUID-IN-ISMS-LITE",
  "managedFields": ["name", "location", "ip_address", "os_platform"]
}

Bei Backup-Aufträgen oder reinen Nachweisquellen managedFields: [] verwenden. Vorhandene Objekte werden anhand dieser expliziten Zuordnung erkannt, nicht anhand von Hostname, IP- oder MAC-Adresse. Die Kombination aus Quelle und externer ID bleibt stabil. Sie lässt sich später nicht auf ein anderes Zielobjekt umhängen.

Mehrere Quellen können dasselbe Asset referenzieren. Für jedes technische Feld darf aber nur eine Quelle zuständig sein. Der Ingest verwaltet ausschließlich name, location, ip_address und os_platform. Eigentümer, Kritikalität, RPO, Risiken und Freigaben werden nicht laufend aus der Quelle überschrieben.

Wurde ein verwaltetes Feld zwischenzeitlich manuell verändert, schlägt der gesamte Batch mit 409 und details.reason: "manualFieldConflict" fehl. Nach fachlicher Prüfung entweder das Feld aus managedFields entfernen oder durch erneutes Binding mit derselben Ziel-ID bewusst den aktuellen Stand als Ausgangspunkt übernehmen. Keine automatische Konfliktauflösung durch häufigere Wiederholungen.

4. Daten liefern und Ergebnis prüfen

Das Adapter-Kapitel führt durch Assetexport und Veeam-Beispiel. Eigene Adapter senden JSON an POST /api/v1/integrations/sources/{id}/batches; den vollständigen Vertrag enthält die Ingest-Referenz.

Nach dem ersten Versand mit dem Verwaltungsschlüssel prüfen:

  1. GET .../sources/{id}: Ist last_observed_at aktuell und der erwartete Bereich konfiguriert?
  2. GET .../sources/{id}/bindings: Stimmen external_id, target_id und die Feldzuständigkeiten?
  3. GET .../sources/{id}/observations: Wurden erwartete Beobachtungen übernommen? Ein reiner Assetexport kann ohne Beobachtungen auskommen.
  4. GET .../sources/{id}/observations/{childId}: Stimmen Inhalt und Gültigkeit eines Nachweises?
  5. GET .../sources/{id}/deviations: Gibt es fachliche Abweichungen oder unbekannte Zustände?

... steht hier für /api/v1/integrations. Listen mit offset und limit vollständig durchlaufen. Quellen, Integrationsnachweise und Abweichungen werden über diese API verwaltet; dafür ist keine separate Integrationsoberfläche enthalten.

Vollabgleich oder Änderungslieferung

Ein delta-Batch meldet nur enthaltene Objekte. Aus fehlenden Objekten wird kein Schluss gezogen. Ein full-Batch muss den gesamten vereinbarten Bereich in einer erfolgreichen Anfrage enthalten. Erst dann können zuvor bekannte, jetzt fehlende Objekte nach der Karenzzeit als „nicht mehr gesehen“ gelten. Assets werden dadurch weder gelöscht noch stillgelegt.

Vor full alle Herstellerseiten lesen und die Vollständigkeit prüfen. Bei Quellfehlern keinen scheinbar vollständigen Leerbestand senden. Ein tatsächlich leerer vollständiger Bestand ist zulässig. Für größere Bestände dauerhaft getrennte Quellenbereiche oder Delta-Lieferungen verwenden; die Request-Grenzen stehen in der Referenz.

Betrieb, Änderungen und Schlüsselrotation

Den lokalen Task passend zur erwarteten Aktualität einrichten, beispielsweise über die Windows-Aufgabenplanung. Überlappende Läufe verhindern, Uhren synchronisieren und Fehler sowie ausbleibende Erhebungen überwachen. Die Quittung bestätigt die Datenannahme, nicht die fachliche Fehlerfreiheit.

Quellen mit PUT /api/v1/integrations/sources/{id} ändern:

{ "revision": 1, "source": { "...": "vollständige Quellenkonfiguration" } }

Das verkürzte Beispiel zeigt nur die Hülle. source muss die vollständige Konfiguration aus Schritt 2 enthalten. Jede Änderung erhöht die Revision. Neue Batches müssen diese Revision verwenden. objectKind und coverage sind unveränderlich; dafür eine neue Quelle anlegen. enabled: false stoppt deren Datenannahme und regelmäßige Bewertung, ohne die Historie zu löschen.

Zur Rotation einen neuen Adapter-Schlüssel anlegen, dessen ID über /identity ermitteln, die Quelle mit dieser apiKeyId aktualisieren und neue Revision sowie Schlüssel im Task hinterlegen. Anschließend den alten Schlüssel widerrufen. Ausstehende Batches bei der Umstellung bewusst abarbeiten; keinen bereits angenommenen Batch unter derselben ID verändern.

Gelöschte Fachobjekte bleiben historisch über ihre ursprüngliche Ziel-ID nachvollziehbar. Weitere Importe dieser Identität erhalten 409 targetDeleted und legen das Objekt nicht wieder an. Eine beabsichtigte neue Identität benötigt eine neue Quellenzuordnung. Nachweis- und Entscheidungshistorien werden nicht automatisch gelöscht; deren Aufbewahrung bei der Betriebsplanung berücksichtigen.