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-Referenzen im Rahmen der Chronicle API auf die neuen SOAR API-Endpunkte zu aktualisieren.

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

Die alte SOAR API und die alten API-Schlüssel sind bis zum 31. März 2027 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 werden 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 mehr Sicherheit und standardisiert den Prozess.
Datenmodelle Flache Strukturen Ressourcenorientiertes Design Dieses neue Design verbessert die Datenkonsistenz und vereinfacht die Objektbearbeitung.
Endpunktbenennung Inkonsistent RESTful und standardisiert Eine einheitliche Benennung macht die API intuitiver und einfacher zu integrieren.

Zeitplan für die Einstellung

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

Migrationsschritte

In diesem Abschnitt werden die Schritte beschrieben, die für eine 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 Referenzhandbuchs für die Chronicle API.

Endpunkte der neuen API-Oberfläche zuordnen

Ermitteln 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 strukturelle Änderungen oder neue Felder. Weitere Informationen finden Sie in der Zuordnungstabelle für API-Endpunkte.

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 kannst du Tests durchführen, ohne deine 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 URL-Struktur für Endpunkte:

[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-Kundennummer.

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

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

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

So rufen Sie beispielsweise eine Liste aller Fälle für ein Projekt in den USA ab:

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 für die 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. Wenn Sie diesen neuen Ablauf implementieren möchten, müssen Sie Ihre Antwortintegrationen oder ‑anwendungen aktualisieren. Der Nutzer, der das Script ausführt, muss die erforderlichen Berechtigungen für die Zielendpunkte haben. Eine ausführliche Anleitung finden Sie auf der Seite Bei der Chronicle API authentifizieren.

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 Workload Identity den erforderlichen Zugriff auf SOC-Rollen und -Umgebungen zu gewähren.

Wenn Sie einem Dienstkonto oder einer Workload Identity-Föderation Zugriff auf Google SecOps gewähren möchten, müssen Sie die Identität den Zugriffssteuerungsparametern 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 Einstellungen > Zugriffsverwaltung > 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 Zugriffssteuerungsparametern der Plattform zuzuordnen.

    1. Geben Sie im Feld IdP / Nutzergruppe eine der folgenden Optionen ein:
      • Die vollständige E-Mail-Adresse Ihres Dienstkontos, wenn die Identität mit Cloud Identity eingerichtet wurde.
      • Der Workload Identity-Hauptkontostring, 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 gegebenenfalls die erforderlichen E‑Mail-Adressen der Nutzer ein. Drücken Sie nach jeder E‑Mail-Adresse die Eingabetaste.
      Eingeschränkte Aktionen Wählen Sie die eingeschränkten Aktionen aus, um bestimmte Vorgänge innerhalb von 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 in der API-Referenz. Nicht alle Methoden haben sich wesentlich geändert und ein Teil des vorhandenen Codes kann wiederverwendet werden. Das Hauptziel 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 identifizieren und zu implementieren.

Integration testen

Testen Sie die 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 Genauigkeit und Gültigkeit zu bestätigen.
  3. Leistung überwachen: Bewerten Sie die Leistung Ihrer Anwendung mit der neuen API.

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