Zur Chronicle API migrieren

Unterstützt in:

Dieses Dokument gilt für Sie, wenn Sie die SOAR API programmatisch über Integrationen, benutzerdefinierte Skripts oder benutzerdefinierte Aktionen aufrufen. In diesem Dokument werden die Schritte und Überlegungen beschrieben, die Ihnen helfen, programmatische API-Verweise auf die neuen SOAR-API-Endpunkte als Teil der Chronicle API zu aktualisieren.

Die Chronicle API-Oberfläche bietet mehrere Verbesserungen, die Ihren Entwicklungsprozess optimieren sollen. Außerdem werden Einschränkungen und Komplexitäten der älteren API behandelt.

Die alte SOAR API und die zugehörigen API-Schlüssel sind bis zum 30. November 2026 verfügbar. Danach funktionieren sie nicht mehr.

Vorbereitung

Bevor Sie die SOAR API-Migration durchführen, müssen Sie Folgendes tun:

Wichtige Änderungen und Verbesserungen

In der folgenden Tabelle sind die wichtigsten Unterschiede zwischen den alten und neuen API-Oberflächen aufgeführt:

Funktionsbereich Alte API Neue API Details
Authentifizierung API-Token oauth 2.0 Die neue Authentifizierungsmethode bietet erweiterte Sicherheitsfunktionen und standardisiert den Prozess.
Datenmodelle Flache Strukturen Ressourcenorientiertes Design Das neue Design verbessert die Datenkonsistenz und vereinfacht die Objektbearbeitung.
Endpunktbenennung Inkonsistent RESTful und standardisiert Durch eine einheitliche Namensgebung wird die API intuitiver und lässt sich einfacher integrieren.

Zeitplan für die Einstellung

Die alte API-Oberfläche für SOAR wird voraussichtlich am 30. November 2026 vollständig eingestellt. Wir empfehlen Ihnen, die Migration vor diesem Datum abzuschließen, um Dienstunterbrechungen zu vermeiden.

Migrationsschritte

In diesem Abschnitt werden die Schritte beschrieben, die für die erfolgreiche Migration Ihrer Anwendungen zur Chronicle API erforderlich sind:

Dokumentation ansehen

Machen Sie sich mit der umfassenden Dokumentation für die neue API vertraut, einschließlich des Chronicle API-Referenzhandbuchs.

Endpunkte der neuen API zuordnen

Suchen Sie die entsprechenden neuen Endpunkte für jeden der alten API-Aufrufe, die Ihre Anwendung ausführt. Ordnen Sie die alten Datenmodelle den neuen zu und berücksichtigen Sie dabei alle strukturellen Änderungen oder neuen Felder. Weitere Informationen finden Sie in der Tabelle zur Zuordnung von API-Endpunkten.

Optional: Staging-Integration erstellen

Wenn Sie eine benutzerdefinierte Integration oder eine Komponente einer kommerziellen Integration bearbeiten, empfehlen wir, die Änderungen zuerst in eine Staging-Integration zu übertragen. So können Sie Tests durchführen, ohne Ihre Produktionsautomatisierungsabläufe zu beeinträchtigen. Wenn Sie eine benutzerdefinierte Anwendung migrieren, die die SOAR API verwendet, können Sie mit dem nächsten Schritt fortfahren. Weitere Informationen zum Staging von Integrationen finden Sie unter Integrationen im Staging-Modus testen.

Dienstendpunkt und URLs aktualisieren

Ein Dienstendpunkt ist die Basis-URL, die die Netzwerkadresse eines API-Dienstes angibt. Ein einzelner Dienst kann mehrere Dienstendpunkte haben. Chronicle ist ein regionaler Dienst und unterstützt nur regionale Endpunkte.

Alle neuen Endpunkte verwenden ein einheitliches Präfix, sodass die endgültige Endpunktadresse vorhersehbar ist. Das folgende Beispiel zeigt die neue Struktur der Endpunkt-URL:

[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 Dienstadresse
  • 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 Security Operations SIEM-Kunden-ID.

Regionale Adressen:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • uns: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

So rufen Sie beispielsweise eine Liste aller Fälle in einem Projekt in den USA auf:

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

Authentifizierungsmethode aktualisieren

Die neue API verwendet Google Cloud IAM zur Authentifizierung. Sie müssen Ihre Anwendung oder Antwortintegration aktualisieren, um diesen neuen Authentifizierungsablauf zu implementieren. Achten Sie darauf, dass der Nutzer, der das Script ausführt, die richtigen Berechtigungen für die Endpunkte hat, auf die er zugreifen möchte. Um diesen neuen Ablauf zu implementieren, müssen Sie Ihre Antwortintegrationen oder ‑anwendungen aktualisieren. Achten Sie darauf, dass der Nutzer, der das Skript ausführt, die erforderlichen Berechtigungen für die Zielendpunkte hat. Eine detaillierte Anleitung finden Sie auf der Seite Authentifizierung bei der Chronicle API.

Dienstkonto oder Workload Identity SOAR-Parametern zuordnen

Wenn Sie ein Dienstkonto oder die Identitätsföderation von Arbeitslasten verwenden, um sich bei der Chronicle API zu authentifizieren, müssen Sie es auf der Plattform autorisieren, damit es erfolgreich mit Google SecOps kommunizieren kann. Diese Zuordnung ist erforderlich, um dem Dienstkonto oder der Arbeitslastidentität den erforderlichen Zugriff auf SOC-Rollen und ‑Umgebungen zu gewähren.

Wenn Sie Google SecOps Dienstkonto-Zugriff oder Workload Identity Federation-Zugriff gewähren möchten, müssen Sie die Identität den Zugriffskontrollparametern der Plattform zuordnen. Diese Zuordnung ist ein obligatorischer Schritt, um der Identität den erforderlichen Zugriff auf SOC-Rollen und Umgebungen zu gewähren, die für die Ausführung automatisierter Aufgaben oder API-Vorgänge erforderlich sind.

  1. Gehen Sie zu SOAR-Einstellungen> „Erweitert“ > „Gruppenzuordnung“.
  2. Klicken Sie auf Hinzufügen Hinzufügen.

  3. Füllen Sie die Felder im Dialogfeld Zuordnung hinzufügen aus, um die Identität den Parametern für die Zugriffssteuerung der Plattform zuzuordnen.

    1. Geben Sie im Feld IdP / Nutzergruppe einen der folgenden Werte ein:
      • Die vollständige E-Mail-Adresse Ihres Dienstkontos, wenn die Identität mit Cloud Identity eingerichtet wurde.
      • Der Hauptkonto-String für Workload Identity, wenn die Identität mit der Workforce Identity-Föderation eingerichtet wurde.

    2. Konfigurieren Sie die folgenden Felder für die Zugriffssteuerung:

      Feld Beschreibung
      Berechtigungsgruppen Wählen Sie die Berechtigungsgruppen aus, um festzulegen, auf welche Module und Untermodule die Identität zugreifen kann.
      SOC-Rollen Wählen Sie die SOC-Rollen aus, um die Rolle der Identität zu definieren, z. B. „Tier 1“.
      Umgebungen Wählen Sie die Umgebungen oder Umgebungsgruppen aus, auf die die Identität zugreifen kann, z. B. Alle Umgebungen.
      Gruppenmitglieder Geben Sie bei Bedarf die erforderlichen E‑Mail-Adressen der Nutzer ein. Drücken Sie nach dem Hinzufügen jeder E‑Mail-Adresse die Eingabetaste.
      Eingeschränkte Aktionen Wählen Sie die eingeschränkten Aktionen aus, um bestimmte Vorgänge in Modulen einzuschränken.

  4. Klicken Sie auf Hinzufügen.

Weitere Informationen zum Zuordnen von Nutzern und Dienstkonten finden Sie unter Nutzer auf der Plattform mithilfe von Identitäten des Drittanbieters zuordnen oder Nutzer auf der Plattform mithilfe von Cloud Identity zuordnen.

API-Logik aktualisieren

Analysieren Sie die neuen Datenmodelle und Endpunktstrukturen, die in der API-Referenz enthalten sind. Nicht alle Methoden haben sich wesentlich geändert und vorhandener Code kann wiederverwendet werden. Das primäre Ziel besteht darin, die neue Referenzdokumentation zu prüfen und für jeden spezifischen Anwendungsfall die erforderlichen Änderungen an Feldnamen und Datenstrukturen in der Logik Ihrer Anwendung zu ermitteln und zu implementieren.

Integration testen

Testen Sie Ihre aktualisierte Anwendung in einer Staging-Integration, 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 Richtigkeit und Gültigkeit zu bestätigen.
  3. Leistung beobachten: Bewerten Sie die Leistung Ihrer Anwendung mit der neuen API.

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