Von der Legacy-SIEM API zur Chronicle API migrieren

Unterstützt in:

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

Im eingebetteten Video finden Sie einen kurzen Überblick über den Migrationsprozess.

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

Was sich ändert

Alle programmatischen Anfragen an die Legacy-Endpunkte der Backstory API und der Ingestion API müssen zur modernen Chronicle API migriert werden. Wenn in Ihrer Organisation benutzerdefinierte Integrationen, Automatisierungsskripts oder Drittanbietertools verwendet werden, die Aufrufe an diese Legacy-Endpunkte ausführen, müssen Sie diese Arbeitslasten vor dem 20. Juli 2027 auf moderne Endpunkte und Authentifizierungsabläufe umstellen. Wenn Ihre Organisation Google Security Operations SOAR verwendet, müssen Sie außerdem Ihre SOAR-Integrationen und ‑Connectors (z. B. die Google Chronicle-Integration) aktualisieren, damit sie die Chronicle API verwenden. Weitere Informationen finden Sie unter SOAR-Integrationen migrieren.

Was sich nicht ändert

Aktionen, die direkt in der Google Security Operations-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 unternehmen.

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-Ansprechpartnern 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.
Compliancestandards 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 Regulierungsstandards der Branche.
Logging und Prüfung Alte Audit-Streams Cloud-Audit-Logs, die in Ihr Google Cloud -Projekt eingebunden sind Die direkte Integration bietet zentralisierte Prüfpfade und zentrales Monitoring.
Authentifizierung API-Token und Dienstkonto-Anmeldedaten 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 Benennung 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 wird die API intuitiver und lässt sich einfacher integrieren.
Ökosystem Sehr begrenzt Integration mit MCP, Terraform, Clientbibliotheken und SDKs Umfassende Kompatibilität mit modernen Cloud-Tools und Automatisierungs-Frameworks.
Partnerautorisierung Partner-Token oder API-Schlüssel, die direkt in Kundencodes verwendet werden Projektübergreifende IAM-Delegierung für Mandantenressourcen; TenantService-Methoden mit Partnerbereich TenantService-Methoden werden im Partnerprojekt ausgeführt. Für alle anderen Mandanten-APIs ist eine projektübergreifende IAM-Delegierung erforderlich, die vom Mandanten im Mandantenprojekt gewährt wird.

Partnerautorisierung

Bei Partner-Workflows mit mehreren Mandanten hängt die Autorisierung in der Chronicle API vom Ressourceninhaber ab. Das Projekt, in dem eine Ressource gehostet wird, bestimmt, welche Anmeldedaten und IAM-Berechtigungen ein Partner benötigt. Die Einschränkung von Mandantenvorgängen auf mandantendelegierte Anmeldedaten entspricht dem grundlegenden Sicherheitsprinzip, dass Partner ohne die ausdrückliche Erlaubnis des Mandanten nicht auf Mandantendaten zugreifen, sie abrufen oder ändern dürfen. In der folgenden Tabelle wird die Partnerautorisierung in der alten Backstory API und der Chronicle API verglichen:

API Methoden Ressourcenbereich Autorisierung
Legacy Backstory API /v1/partner/customer/* Endpunkte Alle Kundencodes des Partners Partner rufen diese Endpunkte direkt mit ihren eigenen Partner-Tokens oder API-Schlüsseln auf.
Chronicle API: TenantService CreateTenant, ListTenants und UpdateTenant Instanz des Partners: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/* Partner rufen diese Methoden direkt mit ihren eigenen Dienstkonten oder Anmeldedaten auf, die chronicle.googleapis.com/tenants.*-Berechtigungen im Partnerprojekt haben.
Chronicle API: andere Dienste wie InstanceService und ForwarderService GetInstance, UpdateInstance, GenerateForwarderFiles und andere Methoden auf Mandantenebene Instanz des Mandanten: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/... Mit Partneranmeldedaten allein kann nicht auf Mandantendaten zugegriffen oder diese geändert werden. Der Mandantenadministrator muss dem Dienstkonto oder dem Workload Identity Federation-Hauptkonto des Partners im Google Cloud -Projekt des Mandanten IAM-Rollen wie roles/chronicle.admin, roles/chronicle.viewer oder eine benutzerdefinierte Rolle zuweisen.

Zeitplan für die Einstellung

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

  • Ab dem 26. Oktober 2026 können Sie die Legacy-APIs (Backstory API und Ingestion API) nicht mehr über neue 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 sein werden.

Hinweis

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

  • Auf moderner SIEM-Infrastruktur bereitstellen:Achten Sie darauf, dass die Instanz in Ihrem oder dem Google Cloud Projekt Ihres MSSP-Partners mit der modernen SIEM-Infrastruktur bereitgestellt wird. Eine ausführliche Anleitung finden Sie unter SIEM-Migration – Übersicht.
  • 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.
  • SOAR-Integrationen identifizieren:Wenn in Ihrer Umgebung Google SecOps SOAR mit Google Security Operations SIEM verbunden ist, prüfen Sie Ihre vorhandenen Connectors. Weitere Informationen finden Sie unter SOAR-Integrationen migrieren.

SOAR-Integrationen migrieren

Wenn Ihre Organisation Google SecOps SOAR mit Google SecOps SIEM verbindet, müssen Sie Ihre SOAR-Integrationen und ‑Connectors (z. B. die Google Chronicle-Integration) migrieren, damit sie die Chronicle API verwenden.

Eine detaillierte Anleitung zum Aktualisieren der Google Chronicle-Integration und der Connectors für die Verwendung der Chronicle API, einschließlich des Auffindens des Chronicle API-Stamms Ihrer Umgebung und der Konfiguration von Authentifizierungsdaten, finden Sie unter Migration von der Backstory API zur Chronicle API.

Zur Chronicle API migrieren

So migrieren Sie Ihre benutzerdefinierten Skripts und Integrationen von den Legacy-APIs zur Chronicle API:

  1. API-Nutzung prüfen:Ermitteln Sie alle benutzerdefinierten Skripts und Integrationen in Ihrer Umgebung, die Legacy-Endpunkte aufrufen.
  2. Authentifizierung und Autorisierung einrichten:Konfigurieren Sie Ihre Umgebung, um Anfragen an die Chronicle API zu authentifizieren und zu autorisieren.
  3. Endpunkte zuordnen und URLs aktualisieren:Ersetzen Sie Legacy-Endpunkte durch ihre modernen regionalen Entsprechungen.
  4. API-Logik aktualisieren:Passen Sie Ihre Anfrage-Nutzlasten und die Verarbeitung von Antworten an die Datenmodelle der modernen API an.
  5. 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 benutzerdefinierte 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 überprüfen. Wenn Ihre Organisation auch Google SecOps SOAR verwendet, lesen Sie den Abschnitt SOAR-Integrationen migrieren.

Authentifizierung und Autorisierung einrichten

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

  1. 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 Identitätsföderation von Arbeitslasten, da sie die Verwaltung und Speicherung langlebiger Dienstkontoschlüssel 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.
  2. IAM-Berechtigungen gewähren:Gewähren 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 mapping 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 dem Dienstkonto oder dem externen Identitätshauptkonto die benutzerdefinierte Rolle zu.
    • Vordefinierte Rolle:Weisen Sie dem Dienstkonto oder dem externen Identitätshauptkonto eine vordefinierte Google SecOps-Rolle zu. Dadurch wird wahrscheinlich mehr Zugriff gewährt als für eine bestimmte Automatisierung erforderlich ist.
    • Delegierung für Mandantenpartner:Wenn Sie ein MSSP oder Partner sind, der Mandantenressourcen außerhalb von TenantService verwaltet (z. B. GetInstance, UpdateInstance oder GenerateForwarderFiles), muss der Mandantenadministrator Ihrem Dienstkonto oder Workload Identity Federation-Principal die erforderlichen IAM-Rollen im Google Cloud -Projekt des Mandanten explizit zuweisen.
  3. Umgebungsvariable für Anmeldedaten festlegen:Konfigurieren Sie Ihre Laufzeitumgebung für die Verwendung der Anmeldedaten mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen. Diese Variable sollte entweder auf die heruntergeladene JSON-Datei mit dem Dienstkontoschlüssel oder auf die Konfigurationsdatei für Anmeldedaten 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"
    
  4. OAuth-Bereiche aktualisieren:Aktualisieren Sie den Bereichsstring, wenn in Ihren Legacy-Integrationsskripts explizit OAuth-Bereiche für die Tokenerstellung angefordert wurden. Der Legacy-Bereich gewährt keinen Zugriff auf die moderne API-Oberfläche:

    • Umfang der alten Hintergrundgeschichte: 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 für die Chronicle API vertraut.

Endpunkte der Chronicle API zuordnen

Ermitteln Sie die entsprechenden modernen Endpunkte für jeden der Legacy-API-Aufrufe, die Ihre Anwendung ausführt. Ordnen Sie Ihre vorhandenen Datenmodelle den modernen Strukturen zu und berücksichtigen Sie dabei alle Schemaänderungen oder zusätzlichen Felder. Details zu allen SIEM-Endpunkten finden Sie unter SIEM API-Endpunkt mapping. Wenn Ihr Workflow auch mit SOAR-Endpunkten interagiert, sehen Sie sich die SOAR API-Endpunkt-Endpunktzuordnungstabelle 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. Das folgende Beispiel zeigt die moderne Endpunkt-URL-Struktur:

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

Die endgültige Adresse für den Endpunkt lautet dann:

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

Wobei:

  • service_endpoint: Eine regionale Serviceadresse.
  • api_version: Die abzufragende API-Version. Kann v1alpha, v1beta oder v1 sein.
  • project_id: Ihre Projekt-ID (dasselbe Projekt wie für Ihre IAM-Berechtigungen).
  • location: Der Standort Ihres Projekts (Region), entspricht den regionalen Endpunkten.
  • instance_id: Ihre Google SecOps SIEM-Kundennummer.

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 vollständige Liste aller unterstützten Endpunkte finden Sie in der offiziellen Referenzdokumentation Service endpoint der Chronicle API.

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 identifizieren und zu implementieren. Einige Legacy-Endpunkte bleiben möglicherweise ähnlich, Sie müssen Ihre Integrationen jedoch an die neuesten Datenmodelle und Endpunktstrukturen anpassen.

Google Cloud Clientbibliotheken verwenden

Vereinfachen Sie die Integration, um Authentifizierung, Aktualisierung von Tokens und Transportdetails automatisch zu verarbeiten. Wir empfehlen, dafür die offiziellen Google Cloud Clientbibliotheken zu verwenden. Die Chronicle API wird in acht Programmiersprachen unterstützt, darunter Python, Go, Java, Node.js und C#. Details zur Installation und Verwendung finden Sie unter Clientbibliotheken und SDK.

Integration testen

Testen Sie die aktualisierte Anwendung in einer Staging-Umgebung, bevor Sie sie in der Produktion bereitstellen:

  1. Testplan erstellen:Definieren Sie Testläufe, die alle migrierten Funktionen abdecken.
  2. Tests ausführen:Führen Sie automatisierte und manuelle Tests durch, um die Richtigkeit und Gültigkeit zu bestätigen.
  3. 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 Principal:Achten Sie darauf, dass Sie die richtigen Anmeldedaten verwenden.
    • Wenn Sie die Identitätsföderation von Arbeitslasten verwenden, prüfen Sie, ob der externe Identitätspincipal mit dem Principal ü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 deaktiviert wurde. Verwenden Sie keine Legacy-Dienstkonten (deren E-Mail-Adresse häufig bk oder malachite-cx enthält) für moderne Chronicle API-Endpunkte.
  • IAM-Rollen:Prüfen Sie, ob dem Dienstkonto oder dem externen Identitätshauptkonto 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 mapping.

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 in Ihren benutzerdefinierten Scripts der moderne Bereich https://www.googleapis.com/auth/chronicle (oder der umfassendere Bereich https://www.googleapis.com/auth/cloud-platform) angefordert wird. Der alte 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 Workload Identity-Föderationskonfigurationsdatei verweist.

HTTP 404 „Nicht gefunden“ 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, führt das zu Fehlern. Eine vollständige Liste der regionalen Adressen finden Sie unter Dienstendpunkt aktualisieren oder in der offiziellen Referenz zu Dienstendpunkten.

Nächste Schritte

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