Forwarder Management API

Mit der Google Security Operations Forwarder Management API können Sie Folgendes programmatisch tun:

  • Forwarder erstellen und verwalten.
  • Collectors erstellen und verwalten.
  • Rufen Sie den Dateiinhalt für die Konfigurationsdateien (.conf) und Authentifizierungsdateien (_auth.conf) eines Google Security Operations-Forwarders ab.

Forwarder bestehen aus einem oder mehreren Collectors. Die Konfiguration jedes Collectors gibt seinen Aufnahmemechanismus (z. B. Datei, Kafka, PCAP, Splunk oder Syslog) und den Logtyp an.

Wenn die Hardwareanforderungen erfüllt sind, können Sie viele Collectors mit demselben Forwarder verwenden, um Daten von einer Vielzahl von Mechanismen und Logtypen aufzunehmen. Sie können beispielsweise einen Forwarder mit zwei Syslog-Collectors installieren, die PAN_FIREWALL- und CISCO_ASA_FIREWALL-Daten jeweils auf separaten Ports überwachen.

Mit der API können Sie Forwarder und deren Collectors in Ihrer Google Security Operations-Instanz erstellen. Nachdem ein Forwarder erstellt wurde, können Sie den Endpunkt Generate Forwarder Files verwenden, um den Dateiinhalt (als JSON-Nutzlast) für die Konfigurationsdateien (.conf) und Authentifizierungsdateien (_auth.conf) eines Forwarders abzurufen. Diese Inhalte können dann zur Bereitstellung mit dem Google Security Operations Forwarder-Dienst auf einem Windows- oder Linux-System in die entsprechenden .conf-Dateien geschrieben werden.

Python-Beispiele, in denen die Forwarder Management API verwendet wird, finden Sie im GitHub-Repository.

Forwarder und dessen Collector erstellen

Ein Forwarder muss erstellt werden, bevor einer seiner Collectors erstellt werden kann.

So erstellen Sie einen Forwarder und dessen Collector(s):

  1. Erstellen Sie einen Forwarder.
  2. Erstellen Sie einen Collector für den Forwarder.
  3. Optional: Wiederholen Sie Schritt 2, um weitere Collectors hinzuzufügen.

Authentifizierung bei der Google Security Operations API[:#Authenticate]

Diese Google Security Operations API verwendet zur Authentifizierung und Autorisierung das OAuth 2.0-Protokoll. Ihre Anwendung kann diese Aufgaben mit einer der folgenden Implementierungen ausführen:

  • Google API-Clientbibliothek für Ihre Computersprache verwenden

  • Direkte Schnittstelle zum OAuth 2.0-System über HTTP

Informationen zur Google-Authentifizierungsbibliothek in Python finden Sie in der Referenzdokumentation.

Google-Authentifizierungsbibliotheken sind eine Teilmenge der Google API-Clientbibliotheken. Weitere Sprachimplementierungen

Anmeldedaten für die API-Authentifizierung abrufen

Ihr Google Security Operations-Mitarbeiter stellt Ihnen die Anmeldedaten für das Google-Entwicklerdienstkonto zur Verfügung, über die der API-Client mit der API kommunizieren kann.

Sie müssen beim Initialisieren Ihres API-Clients auch den Authentifizierungsbereich angeben. OAuth 2.0 verwendet einen Bereich, um den Zugriff einer Anwendung auf ein Konto zu beschränken. Wenn eine Anwendung einen Bereich anfordert, ist das an die Anwendung ausgegebene Zugriffstoken auf den gewährten Bereich beschränkt.

Verwenden Sie den folgenden Bereich, um Ihren Google API-Client zu initialisieren:

https://www.googleapis.com/auth/chronicle-backstory

Beispiel für Python

Das folgende Python-Beispiel zeigt, wie die OAuth2-Anmeldedaten und der HTTP-Client mit google.oauth2 und googleapiclient verwendet werden.

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.oauth2 import service_account
from googleapiclient import _auth

SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']

# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

# Create a credential using Google Developer Service Account Credential and Google Security Operations API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build an HTTP client to make authorized OAuth requests.
http_client = _auth.authorized_http(credentials)

# <your code continues here>

Chronicle API-Abfragelimits

Die Chronicle API erzwingt Limits für die Anzahl der Anfragen, die von einem beliebigen Kunden an die Google Security Operations-Plattform gestellt werden können. Wenn Sie das Abfragelimit erreichen oder überschreiten, gibt der Chronicle API-Server den HTTP-Statuscode 429 (RESOURCE_EXHAUSTED) an den Aufrufer zurück. Bei der Entwicklung von Anwendungen für die Chronicle API empfiehlt Google, Ratenbegrenzungen in Ihrem System durchzusetzen, um eine Ressourcenausschöpfung zu vermeiden. Diese Limits gelten für alle Chronicle APIs, einschließlich der Search API, Forwarder Management API und der Tooling API.

Das folgende Limit für die Chronicle Forwarder Management API wird erzwungen und in Abfragen pro Sekunde (Queries per Second, QPS) gemessen:

Chronicle API API-Endpunkt Limit
Forwarder-Verwaltung Forwarder erstellen 1 Abfragen pro Sekunde
Forwarder abrufen 1 Abfragen pro Sekunde
Forwarder auflisten 1 Abfragen pro Sekunde
Forwarder aktualisieren 1 Abfragen pro Sekunde
Forwarder löschen 1 Abfragen pro Sekunde
Collector-Verwaltung Collector erstellen 1 Abfragen pro Sekunde
Collector abrufen 1 Abfragen pro Sekunde
Collectors auflisten 1 Abfragen pro Sekunde
Collector aktualisieren 1 Abfragen pro Sekunde
Collector löschen 1 Abfragen pro Sekunde

Forwarder API-Referenz

In diesem Abschnitt werden die Endpunkte zum Erstellen und Verwalten von Forwardern beschrieben. Informationen zu Endpunkte zum Erstellen und Verwalten von Collectors finden Sie in der Referenz zur Collector API.

Forwarder erstellen

Erstellt einen neuen Forwarder in der Google SecOps-Instanz. Der neue Forwarder schließt alle forwarder-Konfigurationswerte ein, die im Anfragetext angegeben sind. Konfigurationswerte für Collectors müssen nach der Verwendung von Create Forwarder mit dem Befehl Create Collector angegeben werden.

Bei bestimmten Einstellungen werden Konfigurationswerte, die fehlen oder im Anfragetext fehlen, auf Standardwerte gesetzt. Weitere Informationen zu Forwarder-Feldern und -Werten finden Sie unter Forwarder-Konfigurationsfelder.

Anfrage

POST https://backstory.googleapis.com/v2/forwarders

Anfragetext
{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}
Körperparameter
Feld Typ Erforderlich Beschreibung
display_name String Erforderlich Der Name des Forwarders. Dieser Name wird auf der Google SecOps-Oberfläche angezeigt.
config Objekt Optional Die Konfigurationseinstellungen für diesen Forwarder. Siehe Felder für die Forwarder-Konfiguration.
Anfragebeispiel

Dieses Beispiel zeigt die erforderlichen Schlüssel/Wert-Paare in einer Forwarder-Anfrage erstellen. Wenn ein Feld in der Anfrage nicht angegeben ist und einen Standardwert hat, wird der Standardwert beim Erstellen des Forwarders angewendet. Weitere Informationen zu Standardwerten finden Sie unter Felder für die Forwarder-Konfiguration.

POST https://backstory.googleapis.com/v2/forwarders
{
  "display_name": "chronicle_forwarder"
}

Antwort

Wenn die Anfrage erfolgreich ist, wird in der Antwort der HTTP-Statuscode 200 (OK) zurückgegeben.

Die Antwort zeigt die Konfigurationswerte, die beim Erstellen des Forwarders angewendet wurden. Standardkonfigurationswerte werden auf bestimmte Einstellungen bei der Ressourcenerstellung angewendet, wenn diese Felder im Anfragetext fehlen oder Nullwerte enthalten. Weitere Informationen finden Sie unter Felder für die Forwarder-Konfiguration.

Antwortfelder

Zusätzlich zu den in der Anfrage angegebenen Feldern und den Feldern, auf die Standardwerte angewendet werden, enthält die Antwort die folgenden generierten Felder und reinen Ausgabefelder.

Feld Typ Beschreibung
Name String Die Ressourcen-ID des Forwarders. Das Format ist „forwarders/forwarderID“. Beispiel:

forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
state enum

Gibt den aktuellen Status des Forwarders an. Gültige Werte sind:

  • ACTIVE: Der Forwarder darf Daten hochladen.
  • SUSPENDED: Der Forwarder darf keine Daten hochladen.

Der Standardwert ist ACTIVE.
Antwortbeispiel

Dies ist ein Beispiel für die Antwort, die für das obige Anfragebeispiel zurückgegeben wurde.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

Forwarder abrufen

Gibt einen Forwarder zurück.

Anfrage

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}

Anfragetext

Geben Sie keinen Anfragetext an.

Anfragebeispiel
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56
Antwortbeispiel
{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

Forwarder auflisten

Listet alle Forwarder für eine Google SecOps-Instanz auf.

Anfrage

GET https://backstory.googleapis.com/v2/forwarders

Anfragebeispiel

GET https://backstory.googleapis.com/v2/forwarders

Antwort

Gibt eine Liste der Forwarder zurück.

Antwortbeispiel
{
  "forwarders": [
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
      "displayName": "chronicle_forwarder_1",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
          ...
         },
      },
      "state": "ACTIVE"
    },
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde57",
      "displayName": "chronicle_forwarder_2",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
       ...
       },
      },
      "state": "ACTIVE"
    }
  ]
}

Forwarder aktualisieren

Sie können einen Forwarder aktualisieren, indem Sie mit dem URL-Suchparameter updateMask die Felder angeben, die aktualisiert werden sollen.

Um beispielsweise den Anzeigenamen zu aktualisieren, verwendest du den updateMask-Abfrageparameter wie folgt in der Patch-Anfrage:

?updateMask=displayName

Der Anfragetext sollte nur die Felder enthalten, die Sie aktualisieren möchten (an ihrer genauen Position).

Anfrage

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}?updateMask=<field_1,field_2>
Anfragetext
{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  },
}
Körperparameter
Feld Typ Erforderlich Beschreibung
display_name String Erforderlich Der Name des Forwarders. Dieser Name wird auf der Google SecOps-Oberfläche angezeigt.
config Objekt Optional Die Konfigurationseinstellungen für diesen Forwarder. Siehe Felder für die Forwarder-Konfiguration.
Anfragebeispiel

Dies ist ein Beispiel für eine Update-Forwarder-Anfrage, bei der in der Anfrage neue Werte für displayName angegeben und ein Metadatenlabel hinzugefügt wird.

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56?updateMask=displayName,config.metadata.labels
{
  "display_name": "UpdatedForwarder",
  "config": {
    "metadata": {
      "labels": [
        {
          "key": "office",
          "value": "corporate",
        }
      ]
    }
  }
}
Antwortbeispiel

Dies ist ein Beispiel für die Antwort, die für das obige Anfragebeispiel zurückgegeben wurde.

{
  "name": "forwarders/{forwarderUUID}",
  "displayName": "UpdatedForwarder",
  "config": {
    "uploadCompression": "false",
    "metadata": {
      "labels": [
        {
          "key": "office",
          "value": "corporate"
        }
      ]
    }
  },
  "state": "ACTIVE"
}

Forwarder löschen

Löscht einen Forwarder.

Anfrage

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}
Anfragetext

Geben Sie keinen Anfragetext an.

Anfragebeispiel
DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56
Antwortbeispiel

Wenn der Vorgang erfolgreich ist, gibt Delete Forwarder eine leere Antwort mit dem HTTP-Statuscode 200 (OK) zurück.

{}

Forwarderdateien generieren

Generiert und gibt den Inhalt der Konfigurationsdateien (.conf) und Authentifizierungsdateien (_auth.conf) des Forwarders zurück.

Anfrage

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}:generateForwarderFiles
Anfragetext

Geben Sie keinen Anfragetext an.

Anfragebeispiel
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56:generateForwarderFiles
Antwortbeispiel

Wenn der Vorgang erfolgreich ist, wird der HTTP-Statuscode 200 (OK) zurückgegeben. Außerdem werden der Inhalt einer Forwarder-Konfigurationsdatei einschließlich der Konfigurationsdaten für die Collectors des Forwarders sowie der Inhalt der Authentifizierungsdatei (_auth.conf) zurückgegeben, die vom Forwarder zur Authentifizierung bei der Google SecOps-Instanz verwendet wird.

Felder für die Forwarder-Konfiguration

In der folgenden Tabelle sind die Konfigurationseinstellungen der Forwarder aufgeführt, die Sie mit „Forwarder erstellen“ und „Forwarder aktualisieren“ angeben können. Wenn Sie bei der Verwendung von „Forwarder erstellen“ keinen Wert für eine Einstellung angeben, wird der Standardwert der Einstellung (siehe unten) angewendet.

Folgende Felder können im Objekt config des Anfragetexts angegeben werden.

Feld Typ Erforderlich Beschreibung
upload_compression bool Optional Wenn true, werden Batches von Daten vor dem Upload komprimiert.

Der Standardwert ist false.
metadata.asset_namespace String Optional Der Namespace zum Identifizieren von Logs aus diesem Forwarder.

Hinweis: Dies ist eine globale Einstellung, die für den Forwarder und die Collectors des Forwarders gilt, sofern sie nicht auf Collector-Ebene überschrieben wird. Weitere Informationen finden Sie unter Namespaces konfigurieren.
metadata.labels list Optional Eine Liste beliebiger Schlüssel/Wert-Paare, die in der Forwarder-Konfiguration angegeben werden können.

Hinweis: Dies ist eine globale Einstellung, die für den Forwarder und die Collectors des Forwarders gilt, sofern sie nicht auf Collector-Ebene überschrieben wird.
metadata.labels.key String Optional Der Schlüssel für ein Feld in der Liste der Metadatenlabels.
metadata.labels.value String Optional Der Wert für ein Feld in der Liste der Metadatenlabels.
regex_filters.description String Optional Beschreibt, was gefiltert wird und warum.
regex_filters.regexp String Optional Der reguläre Ausdruck, der für den Abgleich mit jeder eingehenden Zeile verwendet wird.
regex_filters.behavior enum Optional

Gibt den Status der Serverfunktionalität an. Gültige Werte sind:

  • ZULASSEN: Bei diesem Status kann die gefilterte Zeile hochgeladen werden.
  • BLOCK: Dieser Status verhindert, dass die gefilterte Zeile hochgeladen wird.
server_settings Objekt Optional Einstellungen zum Konfigurieren des integrierten HTTP-Servers des Forwarders, mit dem Optionen für das Load-Balancing und die Hochverfügbarkeit für die Syslog-Erfassung unter Linux konfiguriert werden können.
server_settings.state enum Optional

Gibt den Status der Serverfunktionalität an. Gültige Werte sind:

  • ACTIVE: Bei diesem Status werden die Servereinstellungen wie angegeben angewendet.
  • SUSPENDED In diesem Status werden die Servereinstellungen nicht angewendet.
server_settings.graceful_timeout Ganzzahl Optional Die Anzahl der Sekunden, nach denen der Forwarder eine schlechte Bereitschafts-/Systemdiagnose zurückgibt und noch neue Verbindungen akzeptiert. Dies ist auch die Wartezeit zwischen dem Empfang eines Signals zum Anhalten und dem tatsächlichen Herunterfahren des Servers selbst. Dadurch hat der Load-Balancer Zeit, den Forwarder aus dem Pool zu entfernen.

Der Standardwert ist 15.
server_settings.drain_timeout Ganzzahl Optional Die Anzahl der Sekunden, nach denen der Forwarder darauf wartet, dass aktive Verbindungen erfolgreich geschlossen werden, bevor sie vom Server geschlossen werden.

Der Standardwert ist 10.
server_settings.http_settings.port Ganzzahl Optional Die Portnummer, die der HTTP-Server auf Systemdiagnosen des Load-Balancers überwacht. Muss zwischen 1024 und 65535 liegen.

Der Standardwert ist 8080.
server_settings.http_settings.host String Optional Die IP-Adresse oder der Hostname, der in IP-Adressen aufgelöst werden kann, die der Server überwachen soll.

Der Standardwert ist 0.0.0.0 (das lokale System).
server_settings.http_settings.read_timeout Ganzzahl Optional Die maximale Anzahl von Sekunden, die ganze Anfragen, einschließlich Header und Text, gelesen werden dürfen.

Der Standardwert ist 3.
server_settings.http_settings.read_header_timeout Ganzzahl Optional Die maximale Anzahl von Sekunden, die zum Lesen von Anfrageheadern erlaubt ist.

Der Standardwert ist 3.
server_settings.http_settings.write_timeout Ganzzahl Optional Die maximale Anzahl von Sekunden, die zum Senden einer Antwort zulässig ist.

Der Standardwert ist 3.
server_settings.http_settings.idle_timeout Ganzzahl Optional Die maximale Wartezeit in Sekunden auf die nächste Anfrage, wenn inaktive Verbindungen aktiviert sind.

Der Standardwert ist 3.
server_settings.http_settings.route_settings.available_status_code Ganzzahl Optional Der Statuscode, der zurückgegeben wird, wenn eine Aktivitätsprüfung empfangen wurde und der Forwarder verfügbar ist.

Der Standardwert ist 204.
server_settings.http_settings.route_settings.ready_status_code Ganzzahl Optional Der Statuscode, der zurückgegeben wird, wenn der Forwarder bereit ist, Traffic zu akzeptieren.

Der Standardwert ist 204.
server_settings.http_settings.route_settings.unready_status_code Ganzzahl Optional Der Statuscode, der zurückgegeben wird, wenn der Forwarder nicht bereit ist, Traffic zu akzeptieren.

Der Standardwert ist 503.

Collector API-Referenz

In diesem Abschnitt werden die Endpunkte für die Arbeit mit Collectors beschrieben.

Beachten Sie beim Erstellen und Aktualisieren von Collectors, dass in jeder Collector-Konfiguration Aufnahmeeinstellungen für eine, aber nicht für mehrere der folgenden Elemente angegeben werden können:

  • Protokolldateidaten
  • Kafka-Themen
  • Paketdaten (pcap)
  • Splunk-Daten
  • Syslog-Daten

Informationen zu Endpunkte für die Arbeit mit Forwardern finden Sie in der Referenz zur Forwarder API.

Collector erstellen

Erstellt im Google SecOps-Konto einen neuen Collector. Konfigurationswerte für Collectors müssen nach der Verwendung von „Forwarder erstellen“ mit der Funktion „Collector erstellen“ angegeben werden.

Für bestimmte Einstellungen werden Konfigurationswerte, die im Anfragetext fehlen oder Nullwerte enthalten, auf Standardwerte gesetzt. Weitere Informationen zu den Feldern und Werten der Collector-Konfiguration finden Sie unter Collector-Konfigurationsfelder.

Anfrage

POST https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Anfragetext
{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  }
  "state": enum
}
Körperparameter
Feld Typ Erforderlich Beschreibung
display_name String Erforderlich Der Name des Collectors. Dieser Name wird auf der Google SecOps-Oberfläche angezeigt.
config Objekt Erforderlich Die Konfigurationseinstellungen für diesen Collector. Siehe Collector-Konfigurationsfelder.
state enum Optional

Gibt den aktuellen Status des Collectors an. Gültige Werte sind:

  • ACTIVE: Der Collector darf Daten akzeptieren.
  • SUSPENDED: Der Collector darf keine Daten annehmen.
Anfragebeispiel

Dieses Beispiel zeigt die erforderlichen Schlüssel/Wert-Paare in einer Create Collector-Anfrage. Auf alle Felder, die nicht angegeben sind, werden beim Erstellen des Collectors Standardwerte angewendet.

In diesem Beispiel ist der Collector-Typ file. Daher enthält die Collector-Konfiguration file_settings, um den Collector-Typ und seine Einstellungen anzugeben. Wenn der Collector-Typ syslog ist, enthält die Collector-Konfiguration syslog_settings. Weitere Informationen finden Sie unter Collector-Konfigurationsfelder.

POST https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors
{
  "display_name": "abc_collector",
  "config" {
    "log_type": "CS_EDR"
    "file_settings": {
      "file_path": "/opt/chronicle/edr/output/sample.txt",
    }
  }
}

Antwort

Wenn die Anfrage erfolgreich ist, wird in der Antwort der HTTP-Statuscode 200 (OK) zurückgegeben.

Die Antwort zeigt die Konfigurationswerte, die beim Erstellen des Collectors angewendet wurden. Standardkonfigurationswerte werden auf bestimmte Einstellungen bei der Ressourcenerstellung angewendet, wenn diese Felder im Anfragetext fehlen oder Nullwerte enthalten. Weitere Informationen finden Sie unter Collector-Konfigurationsfelder.

Antwortfelder

Zusätzlich zu den in der Anfrage angegebenen Feldern und den Feldern, auf die Standardwerte angewendet werden, enthält die Antwort die folgenden Felder:

Feld Typ Beschreibung
Name String Die Ressourcen-ID des Collectors. Das Format ist „forwarders/{forwarderID}/collectors/{collectorID}“. Beispiel:

forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Antwortbeispiel

Dies ist ein Beispiel für die Antwort, die für das obige Anfragebeispiel zurückgegeben wurde.

{
  "name": "forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56/collectors/
     98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
  "displayName": "abc_collector",
  "config": {
    "logType": "tomcat",
    "maxSecondsPerBatch": "10",
    "maxBytesPerBatch": "1048576"
  }
}

Collector abrufen

Gibt einen Collector zurück.

Anfrage

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Anfragetext

Geben Sie keinen Anfragetext an.

Anfragebeispiel
GET
https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Antwortbeispiel
{
  "name": "?",
  "displayName": "abc_collector",
  "config": {
    "logType": "tomcat",
    "maxSecondsPerBatch": "10",
    "maxBytesPerBatch": "1048576"
  }
}

Collectors auflisten

Listet die vorhandenen Collectors für den angegebenen Forwarder auf.

Anfrage

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Anfragebeispiel
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors

Antwort

Gibt mehrere Collectors zurück.

Antwortbeispiel
{
  "collectors": [
    {
      "name": "?",
      "displayName": "abc_collector_1",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    },
    {
      "name": "?",
      "displayName": "abc_collector_2",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    }
  ]
}

Collector aktualisieren

Wenn Sie einen Collector mit der API aktualisieren, können Sie die gesamte Collector-Konfiguration oder nur bestimmte Felder der Collector-Konfiguration überschreiben. In der Regel ist es am besten, bestimmte Felder zu überschreiben, damit Sie nicht versehentlich alle Daten überschreiben. Wenn Sie bestimmte Felder überschreiben möchten, geben Sie in Ihrer Aktualisierungsanfrage eine FieldMask an.

Um eine FieldMask zum Aktualisieren des Anzeigenamens für einen Collector bereitzustellen, musst du in der Patchanfrage den URL-Abfrageparameter "updateMask" angeben. Beispiel:

?updateMask=displayName

Der Anfragetext sollte nur die Felder enthalten, die Sie aktualisieren möchten (an ihrer genauen Position).

Anfrage

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}?updateMask=<field_1,field_2>
Anfragetext
{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  },
}
Körperparameter
Feld Typ Erforderlich Beschreibung
displayName String Erforderlich Der Name des Collectors. Dieser Name wird auf der Google SecOps-Oberfläche angezeigt.
config Objekt Optional Die Konfigurationseinstellungen für diesen Forwarder. Siehe Collector-Konfigurationsfelder.
Anfragebeispiel

Dies ist ein Beispiel für eine Update-Collector-Anfrage, bei der die Anfrage neue Werte für displayName, logType, assetNamespace und Protokoll angibt.

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56?updateMask=displayName,config.logType,config.metadata.assetNamespace,config.syslogSettings.protocol
{
  "display_name": "UpdatedCollector"
  "config": {
    "metadata": {
      "asset_namespace": "COLLECTOR",
      },
      "log_type": "CISCO_ASA_FIREWALL",
      "syslog_settings": {
        "protocol": "TCP",
      }
    }
  }
Antwortbeispiel

Dies ist ein Beispiel für die Antwort, die für das obige Anfragebeispiel zurückgegeben wurde.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
  "displayName": "UpdatedCollector",
  "config": {
    "logType": "CISCO_ASA_FIREWALL",
    "metadata": {
      "assetNamespace": "COLLECTOR"
    },
    "maxSecondsPerBatch": 10,
    "maxBytesPerBatch": "1048576",
    "syslogSettings": {
      "protocol": "TCP",
      "address": "0.0.0.0",
      "port": 10514,
    }
  },
  "state": "ACTIVE"
}

Collector löschen

Löscht einen Collector.

Anfrage

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Anfragetext

Geben Sie keinen Anfragetext an.

Anfragebeispiel
DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Antwortbeispiel

Wenn der Vorgang erfolgreich ist, gibt Delete Collector eine leere Antwort mit dem HTTP-Statuscode 200 (OK) zurück.

{}

Collector-Konfigurationsfelder

Folgende Felder können im Objekt config des Anfragetexts angegeben werden.

Feld Typ Erforderlich Beschreibung
log_type String Erforderlich Unterstützter Logtyp, der von Google SecOps aufgenommen werden kann. Eine Liste der unterstützten Logtypen, für die Google SecOps einen Parser hat, finden Sie in der Spalte "Aufnahmelabel" auf der Seite Unterstützte Standardparser. Eine vollständige Liste der unterstützten Logtypen erhalten Sie mit dem Endpunkt logtypes.
metadata.asset_namespace Objekt Optional Der Namespace zum Identifizieren von Logs aus diesem Collector.

Hinweis: Dies ist eine globale Einstellung, die für den Forwarder und die Collectors des Forwarders gilt, sofern sie nicht auf Collector-Ebene überschrieben wird. Weitere Informationen finden Sie unter Namespaces konfigurieren.
metadata.labels list Optional Eine Liste beliebiger Schlüssel/Wert-Paare, die in der Collector-Konfiguration angegeben werden können.

Hinweis: Dies ist eine globale Einstellung, die für den Forwarder und die Collectors des Forwarders gilt, sofern sie nicht auf Collector-Ebene überschrieben wird.
metadata.labels.key String Optional Der Schlüssel für ein Feld in der Liste der Metadatenlabels.
metadata.labels.value String Optional Der Wert für ein Feld in der Liste der Metadatenlabels.
regex_filters.description String Optional Beschreibt, was gefiltert wird und warum.
regex_filters.regexp String Optional Der reguläre Ausdruck, der für den Abgleich mit jeder eingehenden Zeile verwendet wird.
regex_filters.behavior enum Optional

Gibt den Status der Serverfunktionalität an. Gültige Werte sind:

  • ZULASSEN: Bei diesem Status kann die gefilterte Zeile hochgeladen werden.
  • BLOCK: Dieser Status verhindert, dass die gefilterte Zeile hochgeladen wird.
disk_buffer.state enum Optional

Gibt den Pufferstatus des Laufwerks für den Collector an. Gültige Werte sind:

  • ACTIVE: Die Pufferung ist aktiviert.
  • SUSPENDED: Die Pufferung ist deaktiviert.
disk_buffer.directory_path String Optional Der Verzeichnispfad für geschriebene Dateien.
disk_buffer.max_file_buffer_bytes Ganzzahl Optional Die maximale Größe der zwischengespeicherten Datei.
max_seconds_per_batch Ganzzahl Optional Die Anzahl der Sekunden zwischen Batches.

Der Standardwert ist 10.
max_bytes_per_batch Ganzzahl Optional Die Anzahl der Byte, die vor dem Batch-Upload des Forwarders in die Warteschlange gestellt wurden.

Der Standardwert ist 1048576.
<collector_type>_settings.<fields> Erforderlich Gibt einen Collector-Typ und die zugehörigen Einstellungen an. Für jeden Collector müssen ein Collector-Typ und seine Felder angegeben werden. Wenn Sie beispielsweise den Collector-Typ file verwenden möchten, muss das Feld file_settings.file_path der Konfiguration hinzugefügt und mit einem Wert versehen werden. Beispiel:

"file_settings": {
  "file_path": "/opt/chronicle/edr/output/sample.txt",
}

Die Collector-Typen und ihre Felder werden in den nachfolgenden Zeilen dieser Tabelle aufgeführt. Folgende Collector-Typen sind verfügbar:
  • file
  • kafka
  • pcap
  • splunk
  • syslog
file_settings.file_path String Optional Der Pfad der zu überwachenden Datei.
kafka_settings.authentication.username String Optional Der Nutzername einer für die Authentifizierung verwendeten Identität.
kafka_settings.authentication.password String Optional Das Passwort des durch den Nutzernamen identifizierten Kontos.
kafka_settings.topic String Optional Das Kafka-Thema, aus dem Daten aufgenommen werden sollen. Weitere Informationen finden Sie unter Daten aus Kafka-Themen erfassen.
kafka_settings.group_id String Optional Eine Gruppen-ID.
kafka_settings.timeout Ganzzahl Optional Die maximale Anzahl von Sekunden, die ein Wählvorgang wartet, bis eine Verbindung hergestellt wurde.

Der Standardwert ist 60.
kafka_settings.brokers String Optional Ein wiederholter String, der Kafka-Broker auflistet. Beispiel:

"broker-1:9092", "broker-2:9093"

Hinweis:Alle Werte werden während eines Aktualisierungsvorgangs ersetzt. Wenn Sie eine Liste von Brokern aktualisieren möchten, um einen neuen Broker hinzuzufügen, geben Sie daher alle vorhandenen Broker und den neuen Broker an.
kafka_settings.tls_settings.certificate String Optional Der Pfad und der Name der Zertifikatdatei. Beispiel:

/path/to/cert.pem
kafka_settings.tls_settings.certificate_key String Optional Pfad und Dateiname des Zertifikatschlüssels. Beispiel:

/path/to/cert.key
kafka_settings.tls_settings.minimum_tls_version String Optional Die Mindestversion für TLS.
kafka_settings.tls_settings.insecure_skip_verify bool Optional Wenn true, wird die Überprüfung der SSL-Zertifizierung aktiviert.

Der Standardwert ist false.
pcap_settings.network_interface String Optional Die Schnittstelle, auf die PCAP-Daten überwacht werden sollen.
pcap_settings.bpf String Optional Der Berkeley Packet Filter (BPF) für Pcap.
splunk_settings.authentication.username String Optional Der Nutzername einer für die Authentifizierung verwendeten Identität.
splunk_settings.authentication.password String Optional Das Passwort des durch den Nutzernamen identifizierten Kontos.
splunk_settings.host String Optional Der Host oder die IP-Adresse für die Splunk REST API.
splunk_settings.port Ganzzahl Optional Der Port für die Splunk REST API.
splunk_settings.minimum_window_size Ganzzahl Optional Der minimale Zeitraum in Sekunden für eine bestimmte Splunk-Suche. Weitere Informationen finden Sie unter Splunk-Daten erfassen.

Der Standardwert ist 10.
splunk_settings.maximum_window_size Ganzzahl Optional Der maximale Zeitraum in Sekunden für eine bestimmte Splunk-Suche. Weitere Informationen finden Sie unter Splunk-Daten erfassen.

Der Standardwert ist 30.
splunk_settings.query_string String Optional Die Abfrage, die zum Filtern von Datensätzen in Splunk verwendet wird.

Beispiel: search index=* sourcetype=dns
splunk_settings.query_mode String Optional Der Abfragemodus für Splunk.

Beispiel: realtime
splunk_settings.cert_ignored bool Optional Bei true wird das Zertifikat ignoriert.
syslog_settings.protocol enum Optional

Gibt das Protokoll an, das der Collector zum Überwachen von Syslog-Daten verwendet. Gültige Werte sind:

  • TCP
  • UDP
syslog_settings.address String Optional Die Ziel-IP-Adresse oder der Hostname, unter der sich der Collector befindet und auf Syslog-Daten wartet.
syslog_settings.port Ganzzahl Optional Der Zielport, an dem sich der Collector befindet und Syslog-Daten überwacht.
syslog_settings.buffer_size Ganzzahl Optional Die Größe des Zwischenspeichers des TCP-Sockets in Byte.

Der Standardwert für TCP ist 65536.
Der Standardwert für UDP ist 8192.
syslog_settings.connecton_timeout Ganzzahl Optional Die Anzahl der Sekunden der Inaktivität, nach denen die TCP-Verbindung unterbrochen wird.

Der Standardwert ist 60.
syslog_settings.tls_settings.certificate String Optional Der Pfad und der Name der Zertifikatdatei. Beispiel:

/path/to/cert.pem
syslog_settings.tls_settings.certificate_key String Optional Pfad und Dateiname des Zertifikatschlüssels. Beispiel:

/path/to/cert.key
syslog_settings.tls_settings.minimum_tls_version String Optional Die Mindestversion für TLS.
syslog_settings.tls_settings.insecure_skip_verify bool Optional Wenn true, wird die Überprüfung der SSL-Zertifizierung aktiviert.

Der Standardwert ist false.