Wir haben die Navigationsstruktur unserer Dokumentation neu organisiert, um sie direkt an Ihre betrieblichen Arbeitsabläufe anzupassen. Weitere Informationen finden Sie in den Versionshinweisen und im Video zur Anleitung.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Von der Legacy-SIEM-API zur Chronicle API migrieren

Unterstützt in:

Google SecOps SIEM

In diesem Dokument erfahren Sie, wie Sie Anwendungen verwalten, die eine der Legacy-SIEM-APIs (Backstory API und Ingestion API) aufrufen. Es werden die Schritte beschrieben, die Sie ausführen müssen, um den programmatischen Zugriff einzurichten und alle Verweise von den Legacy-SIEM-API-Endpunkten zu den modernen Chronicle API-Endpunkten zu aktualisieren.

Eine kurze Übersicht über den Migrationsprozess finden Sie im eingebetteten Video.

Die Chronicle API-Oberfläche bietet mehrere Verbesserungen, die Ihren Entwicklungsprozess optimieren und den Google Cloud API-Standards entsprechen, um Zuverlässigkeit, Sicherheit und Leistung zu verbessern und die Integration mit Cloud-Audit-Logs, Cloud Monitoring, Cloud Identity und Identity and Access Management (IAM) zu stärken. Außerdem werden viele der Einschränkungen und Komplexitäten der Legacy-APIs behoben.

Was ändert sich?

Alle programmatischen Anfragen an Legacy-Backstory API- und Ingestion API-Endpunkte müssen zur modernen Chronicle API migriert werden. Wenn Ihre Organisation benutzerdefinierte Integrationen, Automatisierungsskripts oder Drittanbietertools verwendet, die diese Legacy-Endpunkte aufrufen, müssen Sie diese Arbeitslasten vor dem 20. Juli 2027 aktualisieren, um moderne Endpunkte und Authentifizierungsabläufe zu verwenden.

Was bleibt gleich?

Aktionen, die direkt in der Google SecOps-Benutzeroberfläche ausgeführt werden, rufen bereits die moderne Chronicle API auf. Wenn Ihre Organisation nur über die Benutzeroberfläche mit Google SecOps interagiert oder Ihre Integrationen bereits Chronicle API-Endpunkte aufrufen, müssen Sie nichts weiter tun.

Wichtige Änderungen und Verbesserungen

In der folgenden Tabelle sind die wichtigsten Unterschiede zwischen der Legacy-SIEM-API und der Chronicle API aufgeführt:

Funktionsbereich	Legacy-SIEM-API	Chronicle API	Details
Anmeldedatenverwaltung	Manueller Prozess mit Google-Mitarbeitern	Self-Service-Verwaltung von Dienstkonten, Anmeldedaten und IAM-Berechtigungen	Die Self-Service-Verwaltung von Anmeldedaten und IAM vereinfacht das Onboarding und macht manuelle Supportanfragen überflüssig.
Compliance standards	Eingeschränkter Support	Integrierte Unterstützung für Datenstandortkontrollen, VPC Service Controls, Access Transparency, CMEK und FedRAMP	Moderne integrierte Infrastrukturkontrollen erfüllen die Compliance- und regulatorischen Standards der Branche.
Logging und Prüfung	Legacy-Audit-Streams	Cloud-Audit-Logs in Ihr Google Cloud Projekt eingebunden	Die direkte Integration bietet zentralisierte Audit-Trails und Monitoring.
Authentifizierung	API-Token und Anmeldedaten des Dienstkontos	OAuth 2.0 mit Unterstützung für moderne Authentifizierungsmethoden, einschließlich Workload Identity und Dienstkonten, wie unter Authentifizierung für Google Cloud APIs und Dienste beschrieben	Diese modernen Authentifizierungsmethoden bieten mehr Sicherheit und standardisieren den Anmeldedatenfluss.
Datenmodelle und API-Design	Einfache, proprietäre Strukturen	Ressourcenorientiertes Design, RESTful-Architektur und standardisierte Namensgebung gemäß AIPs	Dieses moderne Design verbessert die Datenkonsistenz, macht die API intuitiver und vereinfacht die Objektbearbeitung.
Endpunktbenennung	Uneinheitlich	RESTful und standardisiert	Eine einheitliche Namensgebung macht die API intuitiver und einfacher zu integrieren.
Ökosystem	Sehr eingeschränkt	Integration mit MCP, Terraform, Clientbibliotheken und SDKs	Breite Kompatibilität mit modernen Cloud-Tools und Automatisierungsframeworks.

Zeitplan für die Einstellung

Die Legacy-SIEM-API wird am 20. Juli 2027 eingestellt. Wir empfehlen, die Migration vor diesem Datum abzuschließen, um Dienstunterbrechungen zu vermeiden:

Ab dem 26. Oktober 2026 können Sie Legacy-APIs (Backstory API und Ingestion API) nicht mehr von neuen Instanzen aufrufen.
Bis zum 20. Juli 2027 müssen Sie alle vorhandenen Instanzen zur Chronicle API migrieren, da die Legacy-APIs nicht mehr verfügbar sind.

Hinweis

Bevor Sie zur Chronicle API migrieren, müssen Sie Folgendes tun:

In der modernen SIEM-Infrastruktur bereitstellen: Achten Sie darauf, dass Ihre Instanz in Ihrem Google Cloud Projekt mit der modernen SIEM-Infrastruktur bereitgestellt wird. Eine detaillierte Anleitung finden Sie unter Übersicht zur SIEM-Migration.
Chronicle API aktivieren: Rufen Sie in der Google Cloud Konsole Ihr Projekt auf und aktivieren Sie die Chronicle API (chronicle.googleapis.com). Weitere Informationen finden Sie unter API in Ihrem Google Cloud Projekt aktivieren.

Zur Chronicle API migrieren

Migrieren Sie Ihre Skripts und Integrationen von den Legacy-APIs zur Chronicle API. Führen Sie dazu die folgenden Schritte aus:

API-Nutzung prüfen: Ermitteln Sie alle Skripts und Integrationen in Ihrer Umgebung, die Legacy-Endpunkte aufrufen.
Authentifizierung und Autorisierung einrichten: Konfigurieren Sie Ihre Umgebung, um Anfragen an die Chronicle API zu authentifizieren und zu autorisieren.
Endpunkte zuordnen und URLs aktualisieren: Ersetzen Sie Legacy-Endpunkte durch ihre modernen regionalen Entsprechungen.
API-Logik aktualisieren: Passen Sie Ihre Anfrage-Nutzlasten und die Antwortverarbeitung an die Datenmodelle der modernen API an.
Integration testen: Validieren Sie die Änderungen in einer Staging-Umgebung, bevor Sie sie in der Produktion bereitstellen.

API-Nutzung prüfen

Prüfen Sie Ihre Umgebung, um Skripts oder Integrationen zu ermitteln, die backstory.googleapis.com oder malachiteingestion-pa.googleapis.com aufrufen. Sie können diese Integrationen ermitteln, indem Sie Ihre Codebasis, Ihre Automatisierungsskripts und Ihre Drittanbietertools prüfen.

Authentifizierung und Autorisierung einrichten

Konfigurieren Sie Ihre Umgebung, um Anfragen an die Chronicle API zu authentifizieren und zu autorisieren:

Authentifizierungsmethode auswählen:Wählen Sie eine der aufgeführten Methoden aus, um festzulegen, wie Ihre Arbeitslasten sich bei der Chronicle API authentifizieren. Wir empfehlen die Verwendung der Workload Identity-Föderation, da sie sicherer ist und die Verwaltung und Speicherung von Dienstkontoschlüsseln mit langer Lebensdauer überflüssig macht. Informationen zu erweiterten Authentifizierungsszenarien (z. B. Identitätsübernahme des Dienstkontos) finden Sie unter Bei der Chronicle API authentifizieren.
- Workload Identity-Föderation (empfohlen): Richten Sie die Workload Identity-Föderation ein, damit Arbeitslasten, die außerhalb von Google Cloud ausgeführt werden, sich mit externen Identitäten authentifizieren können.
- Dienstkonten:Wenn Sie Dienstkonten verwenden müssen, erstellen Sie ein Dienstkonto in Ihrem Google Cloud Projekt und generieren und laden Sie einen privaten Schlüssel im JSON-Format herunter. Bewahren Sie diesen Schlüssel an einem sicheren Ort auf.
IAM-Berechtigungen erteilen:Erteilen Sie der Identität (entweder dem Dienstkonto oder dem externen Identitätspartner), die für die Authentifizierung verwendet wird, die erforderlichen IAM-Berechtigungen. Weisen Sie Ihrer Identität je nach erforderlichem Zugriffsniveau die erforderlichen IAM-Rollen zu. Weitere Informationen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten. Zu den vordefinierten Rollen gehören:
Wir empfehlen, das Prinzip der geringsten Berechtigung anzuwenden und nur die Berechtigungen zu erteilen, die für Ihre Automatisierungen erforderlich sind. Verwenden Sie dazu benutzerdefinierte oder vordefinierte IAM-Rollen.

**Hinweis**: Unter SIEM API-Endpunkt-Endpunktzuordnung finden Sie die spezifischen detaillierten IAM-Berechtigungen, die für die modernen Endpunkte erforderlich sind, die Ihre Legacy-Aufrufe ersetzen.
Umgebungsvariable für Anmeldedaten festlegen:Konfigurieren Sie Ihre Laufzeitumgebung so, dass die Anmeldedaten mit den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) verwendet werden. Legen Sie dazu die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS fest. Diese Variable sollte auf die heruntergeladene JSON-Datei des Dienstkontoschlüssels oder die Konfigurationsdatei für die Workload Identity-Föderation verweisen. Die Google Cloud Clientbibliotheken erkennen diese Variable automatisch, um Anfragen zu authentifizieren:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
OAuth-Bereiche aktualisieren:Aktualisieren Sie die Bereichs-String, wenn Ihre Legacy-Integrationsskripts explizit OAuth-Bereiche für die Tokengenerierung angefordert haben. Der Legacy-Bereich gewährt keinen Zugriff auf die moderne API-Oberfläche:
- Legacy-Backstory-Bereich:https://www.googleapis.com/auth/chronicle-backstory
- Chronicle-Bereich:https://www.googleapis.com/auth/chronicle oder der umfassendere Bereich https://www.googleapis.com/auth/cloud-platform.

Endpunkte zuordnen und URLs aktualisieren

Machen Sie sich mit der Chronicle API-Oberfläche vertraut, ordnen Sie Ihre Legacy-Aufrufe zu und aktualisieren Sie die Dienstendpunkte in Ihrer Anwendung.

Referenzdokumentation ansehen

Machen Sie sich mit der umfassenden Dokumentation zur Chronicle API vertraut.

Endpunkte der Chronicle API zuordnen

Ermitteln Sie die entsprechenden modernen Endpunkte für jeden der Legacy-API-Aufrufe Ihrer Anwendung. Ordnen Sie Ihre vorhandenen Datenmodelle entsprechend den modernen Strukturen zu und berücksichtigen Sie dabei alle Schemaänderungen oder zusätzlichen Felder. Weitere Informationen zu allen SIEM-Endpunkten finden Sie unter SIEM API-Endpunkt-Endpunktzuordnung. Wenn Ihr Workflow auch mit SOAR-Endpunkten interagiert, sehen Sie sich die Tabelle zur SOAR API-Endpunkt-Endpunktzuordnung an.

Dienstendpunkt aktualisieren

Aktualisieren Sie die Basis-URL Ihrer API-Aufrufe, damit sie auf den richtigen regionalen Dienstendpunkt verweist. Die Chronicle API ist ein regionaler Dienst. Sie müssen also den regionalen Dienstendpunkt aufrufen, der dem Standort Ihrer Google SecOps-Instanz entspricht.

Alle modernen Endpunkte verwenden ein einheitliches Präfix, sodass die endgültige Endpunktadresse vorhersehbar ist. Im folgenden Beispiel sehen Sie die moderne Endpunkt-URL-Struktur:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Diese Struktur ergibt die folgende endgültige Adresse für den Endpunkt:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Wobei:

service_endpoint: Eine regionale Dienstadresse.
api_version: Die abzufragende API-Version. Kann v1alpha, v1beta oder v1 sein.
project_id: Ihre Projekt-ID (dasselbe Projekt, das Sie für Ihre IAM-Berechtigungen definiert haben).
location: Der Standort Ihres Projekts (Region), entspricht den regionalen Endpunkten.
instance_id: Ihre Google Security Operations SIEM-Kunden-ID.

Regionale Adressen:

africa-south1: https://africa-south1-chronicle.googleapis.com oder https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1: https://asia-northeast1-chronicle.googleapis.com oder https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1: https://asia-south1-chronicle.googleapis.com oder https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1: https://asia-southeast1-chronicle.googleapis.com oder https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2: https://asia-southeast2-chronicle.googleapis.com oder https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1: https://australia-southeast1-chronicle.googleapis.com oder https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12: https://europe-west12-chronicle.googleapis.com oder https://chronicle.europe-west12.rep.googleapis.com
europe-west2: https://europe-west2-chronicle.googleapis.com oder https://chronicle.europe-west2.rep.googleapis.com
europe-west3: https://europe-west3-chronicle.googleapis.com oder https://chronicle.europe-west3.rep.googleapis.com
europe-west6: https://europe-west6-chronicle.googleapis.com oder https://chronicle.europe-west6.rep.googleapis.com
europe-west9: https://europe-west9-chronicle.googleapis.com oder https://chronicle.europe-west9.rep.googleapis.com
me-central1: https://me-central1-chronicle.googleapis.com oder https://chronicle.me-central1.rep.googleapis.com
me-central2: https://me-central2-chronicle.googleapis.com oder https://chronicle.me-central2.rep.googleapis.com
me-west1: https://me-west1-chronicle.googleapis.com oder https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com oder https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1: https://southamerica-east1-chronicle.googleapis.com oder https://chronicle.southamerica-east1.rep.googleapis.com
USA (us): https://us-chronicle.googleapis.com oder https://chronicle.us.rep.googleapis.com
Europa (eu): https://eu-chronicle.googleapis.com oder https://chronicle.eu.rep.googleapis.com

Eine umfassende Liste aller unterstützten Endpunkte finden Sie in der offiziellen Referenz in der Dokumentation zum Chronicle API Service-Endpunkt.

Wenn Sie beispielsweise alle Erkennungsregeln für eine Instanz am Standort us auflisten möchten, senden Sie die folgende Anfrage:

GET 
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

Wenn Sie SOAR-Ressourcen wie Fälle mit dem Alias für den regionalen Endpunkt (rep) abfragen möchten, senden Sie die folgende Anfrage:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

API-Logik aktualisieren

Sehen Sie sich die Chronicle API-REST-Referenz an, um Änderungen an Feldnamen und Datenstrukturen in Ihrer Anwendung zu ermitteln und zu implementieren. Einige Legacy-Endpunkte bleiben möglicherweise ähnlich, aber Sie müssen Ihre Integrationen aktualisieren, damit sie den neuesten Datenmodellen und Endpunktstrukturen entsprechen.

Clientbibliotheken verwenden Google Cloud

Vereinfachen Sie Ihre Integration, um Authentifizierung, Tokenaktualisierung und Transportdetails automatisch zu verarbeiten. Wir empfehlen, dazu die offiziellen Google Cloud Clientbibliotheken zu verwenden. Die Chronicle API-Unterstützung ist in acht Programmiersprachen verfügbar, darunter Python, Go, Java, Node.js und C#. Details zur Installation und Verwendung finden Sie unter Clientbibliotheken und SDK.

Integration testen

Testen Sie Ihre aktualisierte Anwendung in einer Staging-Integration, bevor Sie sie in der Produktion bereitstellen:

Testplan erstellen:Definieren Sie Testfälle, die alle migrierten Funktionen abdecken.
Tests ausführen:Führen Sie automatisierte und manuelle Tests aus, um Genauigkeit und Gültigkeit zu bestätigen.
Leistung beobachten:Bewerten Sie die Leistung Ihrer Anwendung mit der modernen API.

Fehlerbehebung

In diesem Abschnitt wird beschrieben, wie Sie häufige Fehler beheben, die während der Migration auftreten können.

HTTP 403 Forbidden oder PERMISSION_DENIED

Wenn Ihre API-Aufrufe den Fehler HTTP 403 Forbidden oder PERMISSION_DENIED zurückgeben, prüfen Sie Folgendes:

Authentifizierungsmethode und Prinzipal:Achten Sie darauf, dass Sie die richtigen Anmeldedaten verwenden.
- Wenn Sie die Workload Identity-Föderation verwenden, prüfen Sie, ob der externe Identitätspartner mit dem Prinzipal übereinstimmt, der an die IAM-Rollen in Ihrem Projekt gebunden ist.
- Wenn Sie ein Dienstkonto verwenden, prüfen Sie, ob das richtige Dienstkonto verwendet wird und ob es nicht deaktiviert wurde. Verwenden Sie keine Legacy-Dienstkonten (deren E-Mail-Adresse oft bk oder malachite-cx enthält) für moderne Chronicle API-Endpunkte.
IAM-Rollen: Prüfen Sie, ob dem Dienstkonto oder dem externen Identitätspartner die erforderlichen vordefinierten oder benutzerdefinierten IAM-Rollen (z. B. Chronicle API Viewer oder Chronicle API Editor) in Ihrem Google Cloud Projekt zugewiesen wurden. Informationen zu detaillierten Endpunktberechtigungen finden Sie unter SIEM API-Endpunkt-Endpunktzuordnung.

HTTP 401 Unauthorized oder UNAUTHENTICATED

Wenn Ihre API-Aufrufe mit HTTP 401 Unauthorized oder UNAUTHENTICATED fehlschlagen, prüfen Sie Folgendes:

OAuth-Bereiche:Prüfen Sie, ob Ihre Skripts den modernen Bereich anfordern: https://www.googleapis.com/auth/chronicle (oder den umfassenderen Bereich https://www.googleapis.com/auth/cloud-platform). Der Legacy-Bereich (https://www.googleapis.com/auth/chronicle-backstory) gewährt keinen Zugriff auf die moderne Chronicle API.
Umgebungsvariable:Prüfen Sie, ob die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festgelegt ist und in Ihrer Laufzeitumgebung auf die richtige JSON-Schlüsseldatei oder Konfigurationsdatei für die Workload Identity-Föderation verweist.

HTTP 404 Not Found oder regionale Abweichungen

Wenn Ihre API-Aufrufe HTTP 404 Not Found zurückgeben oder keine Verbindung hergestellt werden kann, prüfen Sie Ihre regionalen Endpunkte:

Regionaler Endpunkt:Die Chronicle API ist ein regionaler Dienst. Prüfen Sie, ob Sie den Endpunkt aufrufen, der der Region Ihrer Google SecOps-Instanz entspricht (z. B. https://europe-west3-chronicle.googleapis.com für eine Instanz in Frankfurt). Wenn Sie Anfragen an eine andere Region senden, treten Fehler auf. Eine vollständige Liste der regionalen Adressen finden Sie unter Dienstendpunkt aktualisieren oder in der offiziellen Referenz zum Dienstendpunkt.

Nächste Schritte

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten