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.

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

Die Chronicle API-Oberfläche bietet mehrere Verbesserungen, die den Entwicklungsprozess optimieren und den API-Standards von Google Cloud entsprechen. Dadurch werden Zuverlässigkeit, Sicherheit und Leistung verbessert und die Integration in Cloud-Audit-Logs, Cloud Monitoring, Cloud Identity und Identity and Access Management (IAM) wird gestärkt. Außerdem werden viele der Einschränkungen und Komplexitäten der Legacy-APIs behoben.

Was sich ändert

Alle programmatischen Anfragen an die Legacy-Endpunkte der Backstory API und der Ingestion API müssen auf die moderne Chronicle API umgestellt 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, damit moderne Endpunkte und Authentifizierungsabläufe verwendet werden. 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, um die Chronicle API zu verwenden. Weitere Informationen finden Sie unter SOAR-Integrationen migrieren.

Was sich nicht ändert

Aktionen, die direkt in der Benutzeroberfläche von Google Security Operations 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
Verwaltung von Anmeldedaten Manuelle Vorgehensweise mit Google-Ansprechpartnern Self-Service-Verwaltung von Dienstkonten, Anmeldedaten und IAM-Berechtigungen Die Selfservice-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 Legacy-Audit-Streams Cloud-Audit-Logs, die in Ihr Google Cloud -Projekt eingebunden sind Die direkte Integration bietet zentrale Audit-Trails und 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 APIs und Dienste von Google Cloud beschrieben Diese modernen Authentifizierungsmethoden bieten mehr Sicherheit und standardisieren den Ablauf der Anmeldedaten.
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 Eine einheitliche Benennung macht die API intuitiver und einfacher zu integrieren.
Ökosystem Sehr eingeschränkt Integration in MCP, Terraform, Clientbibliotheken und SDKs Breite Kompatibilität mit modernen Cloud-Tools und Automatisierungs-Frameworks.
Partnerautorisierung Partnertoken oder API-Schlüssel, der direkt in Kundencodes verwendet wird Projektübergreifende IAM-Delegierung für Mandantenressourcen; TenantService-Methoden auf Partnerebene 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 mandantenfähigen Partner-Workflows hängt die Autorisierung in der Chronicle API von der Ressourceneigentümerschaft ab. Das Projekt, in dem eine Ressource gehostet wird, bestimmt, welche Anmeldedaten und IAM-Berechtigungen ein Partner benötigt. Die Beschränkung von Mandantenvorgängen auf vom Mandanten delegierte Anmeldedaten entspricht dem grundlegenden Sicherheitsprinzip, dass Partner ohne ausdrückliche Genehmigung des Mandanten nicht auf Mandantendaten zugreifen, diese abrufen oder ändern können. In der folgenden Tabelle wird die Partnerautorisierung in der Legacy-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 im Partnerprojekt die Berechtigungen chronicle.googleapis.com/tenants.* haben.
Chronicle API: andere Dienste wie InstanceService und ForwarderService GetInstance, UpdateInstance, GenerateForwarderFiles und andere mandantenspezifische Methoden Mandanteninstanz: 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 Hauptkonto der Workload Identity-Föderation 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 alte SIEM API wird voraussichtlich 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 keine Legacy-APIs (Backstory API und Ingestion API) mehr von neuen Instanzen aus aufrufen.
  • Bis zum 20. Juli 2027 müssen Sie alle vorhandenen Instanzen zur Chronicle API migrieren, da die Legacy-APIs dann nicht mehr verfügbar sind.

Hinweis

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

  • Auf moderner SIEM-Infrastruktur bereitstellen: Die Instanz muss im Projekt von Google Cloud oder Ihrem MSSP-Partner mit der modernen SIEM-Infrastruktur bereitgestellt werden. 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 Ihre Instanz gehostet wird, 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, um die Chronicle API zu verwenden.

Eine ausführliche Anleitung zum Upgrade der Google Chronicle-Integration und der Connectors für die Verwendung der Chronicle API, einschließlich der Suche nach dem Chronicle API-Stammverzeichnis 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: Identifizieren 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 Äquivalente.
  4. API-Logik aktualisieren: Passen Sie Ihre Anfragenutzlasten und die Antwortverarbeitung 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 identifizieren, die backstory.googleapis.com oder malachiteingestion-pa.googleapis.com aufrufen. Sie können diese Integrationen identifizieren, indem Sie Ihre Codebasis, Automatisierungsskripts und Drittanbietertools prüfen. Wenn Ihre Organisation auch Google SecOps SOAR verwendet, lesen Sie den Hilfeartikel 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, mit der sich Ihre Arbeitslasten bei der Chronicle API authentifizieren sollen. Wir empfehlen die Verwendung der Identitätsföderation von Arbeitslasten, um die Sicherheit zu erhöhen, da so die Verwaltung und Speicherung langlebiger Dienstkontoschlüssel vermieden wird. 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 externen Identitäts-Hauptkonto), 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 alten Aufrufe ersetzen.

  3. Umgebungsvariable für Anmeldedaten festlegen: Konfigurieren Sie Ihre Laufzeitumgebung so, dass die Anmeldedaten mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) verwendet werden. Legen Sie dazu die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS fest. Diese Variable sollte entweder auf die heruntergeladene JSON-Datei des Dienstkontoschlüssels oder auf die Konfigurationsdatei für Anmeldedaten der 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 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 alten 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, die Ihre Anwendung ausführt. Ordnen Sie Ihre vorhandenen Datenmodelle den modernen Strukturen zu und berücksichtigen Sie dabei Schemaänderungen oder zusätzliche Felder. Details zu allen SIEM-Endpunkten finden Sie unter SIEM API-Endpunkt-Endpunktzuordnung. Wenn Ihr Workflow auch mit SOAR-Endpunkten interagiert, finden Sie weitere Informationen in der Zuordnungstabelle für SOAR-API-Endpunkt-Endpunkte.

Dienstendpunkt aktualisieren

Aktualisieren Sie die Basis-URL Ihrer API-Aufrufe, sodass sie auf den richtigen regionalen Dienstendpunkt verweist. Die Chronicle API ist ein regionaler Dienst. Sie müssen daher 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]/...

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 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 Referenz in der Dokumentation zu Dienstendpunkten 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 des regionalen Endpunkts (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

Firewallkonfiguration prüfen

Wenn Sie Firewalls oder authentifizierte Proxys zwischen Ihrer Umgebung und dem Internet verwenden, konfigurieren Sie Regeln, um ausgehende HTTPS-Verbindungen über TCP-Port 443 zuzulassen. Gewähren Sie Zugriff auf die folgenden Hosts:

  • Chronicle API-Endpunkt: <var>REGION</var>-chronicle.googleapis.com oder chronicle.<var>REGION</var>.rep.googleapis.com
  • Google-Authentifizierungsendpunkte: oauth2.googleapis.com, www.googleapis.com und accounts.google.com (plus sts.googleapis.com und iamcredentials.googleapis.com, wenn Sie die Identitätsföderation von Arbeitslasten oder die Identitätsübernahme des Dienstkontos verwenden)

Vollständige Endpunktdetails, Hinweise zu Google-IP-Bereichen, Optionen für private Konnektivität und Schritte zur Überprüfung finden Sie unter Firewallkonfiguration für die Chronicle API überprüfen.

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, aber Sie müssen Ihre Integrationen aktualisieren, damit sie den neuesten Datenmodellen und Endpunktstrukturen entsprechen.

Google Cloud -Clientbibliotheken verwenden

Vereinfachen Sie die Integration, um Authentifizierung, Tokenaktualisierung 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#. Weitere Informationen 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 aus, um die Genauigkeit 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 Hauptkonto: Achten Sie darauf, dass Sie die richtigen Anmeldedaten verwenden.
    • Wenn Sie die Workload Identity-Föderation verwenden, prüfen Sie, ob das externe Identitätskonto mit dem Konto übereinstimmt, das 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 (oft mit bk oder malachite-cx in der E-Mail-Adresse) für moderne Chronicle API-Endpunkte.
  • IAM-Rollen: Prüfen Sie, ob dem Dienstkonto oder dem externen Identitäts-Hauptkonto 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 benutzerdefinierten Skripts den modernen Bereich https://www.googleapis.com/auth/chronicle (oder den umfassenderen Bereich https://www.googleapis.com/auth/cloud-platform) anfordern. 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 auf die richtige JSON-Schlüsseldatei oder die Konfigurationsdatei für die Workload Identity-Föderation in Ihrer Laufzeitumgebung verweist.

HTTP 404 Nicht gefunden oder regionale Abweichungen

Wenn Ihre API-Aufrufe einen HTTP 404 Not Found zurückgeben oder keine Verbindung herstellen können, 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 dies 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