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 in 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-Berechtigungen 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 Überwachung.
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	Flache, 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	Inkonsistent	RESTful und standardisiert	Durch eine einheitliche Namensgebung ist 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 moderner SIEM-Infrastruktur bereitstellen: Achten Sie darauf, dass die Instanz in Ihrem Projekt oder im Projekt Ihres MSSP-Partners Google Cloud bereitgestellt wird, wobei die moderne SIEM-Infrastruktur genutzt wird. Eine detaillierte Anleitung finden Sie unter Übersicht zur SIEM-Migration.
Chronicle API aktivieren: Rufen Sie in der Google Cloud Console das Projekt auf, in dem sich Ihre Instanz befindet, 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 die Verwaltung und Speicherung von Dienstkontoschlüsseln mit langer Lebensdauer vermeidet und so die Sicherheit erhöht. 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 sich Arbeitslasten, die außerhalb von Google Cloud ausgeführt werden, 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 Prinzipal der externen Identität), die für die Authentifizierung verwendet wird, die erforderlichen IAM-Berechtigungen. Unter SIEM API-Endpunkt-Endpunktzuordnung finden Sie die spezifischen IAM-Berechtigungen, die für die modernen Endpunkte erforderlich sind, die Ihre Legacy-Aufrufe ersetzen.
- Benutzerdefinierte Rolle (empfohlen): Erstellen Sie eine benutzerdefinierte IAM-Rolle mit den erforderlichen Berechtigungen und weisen Sie die benutzerdefinierte Rolle dem Dienstkonto oder dem Prinzipal der externen Identität zu.
- Vordefinierte Rolle: Weisen Sie dem Dienstkonto oder dem Prinzipal der externen Identität eine vordefinierte Google SecOps-Rolle zu. Dadurch wird wahrscheinlich mehr Zugriff gewährt, als für eine bestimmte Automatisierung erforderlich ist.
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, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen. Diese Variable sollte entweder auf die heruntergeladene JSON-Datei des Dienstkontoschlüssels oder auf 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 den Bereichsstring, wenn Ihre Legacy-Integrationsskripts explizit OAuth-Bereiche für die Tokenerstellung 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 auf ähnliche Weise 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 Struktur der modernen Endpunkt-URL:

[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 API-Version, die abgefragt werden soll. 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
Vereinigte Staaten (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 Google Cloud verwenden

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 wird in acht Programmiersprachen unterstützt, darunter Python, Go, Java, Node.js und C#. Weitere Informationen 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 Prinzipal der externen Identität 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 Prinzipal der externen Identität 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? Erhalten Sie Antworten von Community-Mitgliedern und Google SecOps-Experten.