Diese Seite wurde von der Cloud Translation API übersetzt.

Forwarder-Verwaltung

Mit den Methoden der Google Security Operations Forwarder Management API haben Sie folgende programmatische Möglichkeiten:

Weiterleitungsadressen erstellen und verwalten
Collectors erstellen und verwalten
Ruft den Dateiinhalt für die Konfigurationsdatei (.conf) und die Authentifizierungsdatei (_auth.conf) eines Google SecOps-Forwarders ab.

Forwarder bestehen aus einem oder mehreren Collectoren. In der Konfiguration jedes Collectors werden der Aufnahmemechanismus (z. B. Datei, Kafka, PCAP, Splunk oder Syslog) und der Logtyp angegeben.

Sofern die Hardwareanforderungen erfüllt sind, können Sie viele Collectors auf demselben Forwarder verwenden, um Daten aus verschiedenen Mechanismen und Logtypen zu erfassen. Sie können beispielsweise einen Forwarder mit zwei Syslog-Collectoren installieren, die jeweils an separaten Ports auf PAN_FIREWALL- und CISCO_ASA_FIREWALL-Daten warten.

Mit der API können Sie Weiterleitungen und die zugehörigen Collectors in Ihrer Google SecOps-Instanz erstellen. Nachdem ein Forwarder erstellt wurde, können Sie mit dem Endpunkt „Generate Forwarder Files“ (Forwarder-Dateien generieren) die Dateiinhalte (als JSON-Nutzlast) für die Konfigurations- (.conf) und Authentifizierungsdateien (_auth.conf) eines Forwarders abrufen. Diese Inhalte können dann in die entsprechenden .conf-Dateien geschrieben werden, um mit dem Google SecOps Forwarder-Dienst auf einem Windows- oder Linux-System bereitgestellt zu werden.

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

Weiterleitung und zugehörige Collector(s) erstellen

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

So erstellen Sie einen Forwarder und die zugehörigen Collectors:

Weiterleitung erstellen
Erstellen Sie einen Collector für den Forwarder.
Optional: Wiederholen Sie Schritt 2, um weitere Sammler hinzuzufügen.

API-Authentifizierungsdaten abrufen

Ihr Google Security Operations-Ansprechpartner stellt Ihnen eine Google Developer-Dienstkonto-Anmeldedaten zur Verfügung, damit der API-Client mit der API kommunizieren kann.

Sie müssen den Auth Scope auch beim Initialisieren Ihres API-Clients angeben. Bei OAuth 2.0 wird der Zugriff einer Anwendung auf ein Konto mithilfe eines Bereichs eingeschränkt. Wenn eine Anwendung einen Bereich anfordert, ist das für die Anwendung ausgegebene Zugriffstoken auf den gewährten Bereich beschränkt.

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

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

Beispiel für Python

Das folgende Python-Beispiel zeigt, wie Sie die OAuth2-Anmeldedaten und den HTTP-Client mit google.oauth2 und googleapiclient verwenden.

# 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.auth.transport import requests
from google.oauth2 import service_account

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 the Google Developer Service Account Credential and Backstory API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)

# Your endpoint GET|POST|PATCH|etc. code will vary below

# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

# requests GET example
response = http_session.request("GET", url)

# POST example uses json
body = {
  "foo": "bar"
}
response = http_session.request("POST", url, json=body)

# PATCH example uses params and json
params = {
  "foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)

# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/

Backstory API-Abfragelimits

Die Backstory API erzwingt Limits für die Anzahl der Anfragen, die von einem Kunden an die Google SecOps-Plattform gesendet werden können. Wenn Sie das Abfragelimit erreichen oder überschreiten, gibt der Backstory API-Server den HTTP-Fehler 429 (RESOURCE_EXHAUSTED) an den Aufrufer zurück. Wenn Sie Anwendungen für die Backstory API entwickeln, empfiehlt Google, Ratenbegrenzungen in Ihrem System zu erzwingen, um eine Erschöpfung der Ressourcen zu vermeiden. Diese Limits gelten für alle Backstory-APIs, einschließlich der Search-, Forwarder Management- und Tooling-APIs.

Detaillierte Liste der Backstory API-Kontingente

Das folgende Limit für die Forwarder-Verwaltung wird erzwungen und in Abfragen pro Sekunde (QPS) gemessen:

Backstory API	API-Endpunkt	Limit
Forwarder-Verwaltung	Forwarder erstellen	1 QPS
	Forwarder abrufen	1 QPS
	Weiterleitungen auflisten	1 QPS
	Forwarder aktualisieren	1 QPS
	Forwarder löschen	1 QPS
Collector-Verwaltung	Collector erstellen	1 QPS
	Collector abrufen	1 QPS
	Collectors auflisten	1 QPS
	Collector aktualisieren	1 QPS
	Collector löschen	1 QPS

Referenz zu Forwarder API-Methoden

In diesem Abschnitt werden die Endpunkte zum Erstellen und Verwalten von Weiterleitungen beschrieben. Endpunkte zum Erstellen und Verwalten von Collectors finden Sie in der Collector API-Referenz.

Forwarder erstellen

Erstellt einen neuen Forwarder in der Google SecOps-Instanz. Der neue Forwarder enthält alle Forwarder-Konfigurationswerte, die im Anfragetext angegeben sind. Konfigurationswerte für collectors müssen mit „Create Collector“ (Collector erstellen) angegeben werden, nachdem „Create Forwarder“ (Forwarder erstellen) verwendet wurde.

Bei bestimmten Einstellungen werden Konfigurationswerte, die im Anfragetext fehlen oder den Wert „0“ haben, auf Standardwerte gesetzt. Weitere Informationen zu den Feldern und Werten des Forwarders finden Sie unter Felder für die Forwarder-Konfiguration.

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 Spediteurs. Dieser Name wird in der Google SecOps-Benutzeroberfläche angezeigt.
config	Objekt	Optional	Die Konfigurationseinstellungen für diesen Forwarder. Weitere Informationen finden Sie unter Felder für die Forwarder-Konfiguration.

Beispielanfrage

In diesem Beispiel sehen Sie die erforderlichen Schlüssel/Wert-Paare in einer Create Forwarder-Anfrage. Wenn ein Feld in der Anfrage nicht angegeben ist und einen Standardwert hat, wird dieser 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

Bei einer erfolgreichen Anfrage wird in der Antwort der HTTP-Statuscode 200 (OK) zurückgegeben.

Die Antwort enthält die Konfigurationswerte, die beim Erstellen des Forwarders angewendet wurden. Bei der Ressourcenerstellung werden für bestimmte Einstellungen Standardkonfigurationswerte angewendet, wenn die entsprechenden Felder im Anfragetext fehlen oder den Wert „0“ haben. Weitere Informationen finden Sie unter Felder für die Forwarder-Konfiguration.

Antwortfelder

Zusätzlich zu den in der Anfrage angegebenen Feldern und den Feldern, für die Standardwerte angewendet werden, enthält die Antwort die folgenden generierten Felder, die nur ausgegeben werden.

Feld	Typ	Beschreibung
Name	String	Die Ressourcen-ID des Spediteurs. 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: AKTIV: Der Spediteur darf Daten hochladen. GESPERRT: Der Spediteur darf keine Daten hochladen. Der Standardwert ist ACTIVE.

Feld

Typ

Beschreibung

Name

String

Die Ressourcen-ID des Spediteurs. 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:

AKTIV: Der Spediteur darf Daten hochladen.
GESPERRT: Der Spediteur darf keine Daten hochladen.

Der Standardwert ist ACTIVE.

Beispielantwort

Dies ist ein Beispiel für die Antwort, die für das obige Beispiel für eine Anfrage zurückgegeben wird.

{
  "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 Weiterleitungsdienst zurück.

Anfrage

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

Anfragetext

Geben Sie keinen Anfragetext an.

Beispielanfrage

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

Beispielantwort

{
  "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"
}

Weiterleitungen auflisten

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

Anfrage

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

Beispielanfrage

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

Antwort

Gibt eine Liste von Weiterleitungen zurück.

Beispielantwort

{
  "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-Abfrageparameter updateMask die zu aktualisierenden Felder angeben.

Wenn Sie beispielsweise den Anzeigenamen aktualisieren möchten, verwenden Sie den Abfrageparameter updateMask in der Patch-Anfrage so:

?updateMask=displayName

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

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 Spediteurs. Dieser Name wird in der Google SecOps-Benutzeroberfläche angezeigt.
config	Objekt	Optional	Die Konfigurationseinstellungen für diesen Forwarder. Weitere Informationen finden Sie unter Felder für die Forwarder-Konfiguration.

Beispielanfrage

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

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",
        }
      ]
    }
  }
}

Beispielantwort

Dies ist ein Beispiel für die Antwort, die für das obige Beispiel für eine Anfrage zurückgegeben wird.

{
  "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.

Beispielanfrage

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

Beispielantwort

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

{}

Forwarder-Dateien generieren

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

Anfrage

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

Anfragetext

Geben Sie keinen Anfragetext an.

Beispielanfrage

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

Beispielantwort

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

Felder für die Forwarder-Konfiguration

In der folgenden Tabelle sind die Einstellungen für die Forwarder-Konfiguration aufgeführt, die Sie mit „Create Forwarder“ und „Update Forwarder“ angeben können. Wenn Sie beim Erstellen eines Forwarders keinen Wert für eine Einstellung angeben, wird der Standardwert der Einstellung (siehe unten) angewendet.

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

Feld	Typ	Erforderlich	Beschreibung
upload_compression	bool	Optional	Bei `true` werden Datenbatches vor dem Hochladen komprimiert. Der Standardwert ist `false`.
metadata.asset_namespace	String	Optional	Der Namespace zum Identifizieren von Logs von diesem Forwarder. Hinweis:Dies ist eine globale Einstellung, die für den Forwarder und die zugehörigen Collectoren gilt, sofern sie nicht auf Collectorebene ü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 zugehörigen Collectoren gilt, sofern sie nicht auf Collectorebene ü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: ALLOW: In diesem Status kann die gefilterte Zeile hochgeladen werden. BLOCK: In diesem Status wird verhindert, dass die gefilterte Zeile hochgeladen wird.
server_settings	Objekt	Optional	Einstellungen, mit denen der integrierte HTTP-Server des Forwarders konfiguriert wird. Dieser kann verwendet werden, um Load-Balancing- und Hochverfügbarkeitsoptionen für die Syslog-Erfassung unter Linux zu konfigurieren.
server_settings.state	enum	Optional	Gibt den Status der Serverfunktionalität an. Gültige Werte: AKTIV: In 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 fehlerhafte Bereitschafts-/Systemdiagnose zurückgibt und weiterhin neue Verbindungen akzeptiert. Dies ist auch die Zeit, die zwischen dem Empfang eines Signals zum Beenden und dem tatsächlichen Herunterfahren des Servers gewartet werden muss. So 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, die der Forwarder wartet, bis aktive Verbindungen erfolgreich geschlossen werden, bevor sie vom Server geschlossen werden. Der Standardwert ist `10`.
server_settings.http_settings.port	Ganzzahl	Optional	Die Portnummer, an der der HTTP-Server auf Systemdiagnosen vom Load-Balancer wartet. 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, auf die der Server hören 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 zum Lesen vollständiger Anfragen zulässig ist, einschließlich Header und Text. Der Standardwert ist `3`.
server_settings.http_settings.read_header_timeout	Ganzzahl	Optional	Die maximale Anzahl von Sekunden, die zum Lesen von Anfrageheadern zulässig ist. Der Standardwert ist `3`.
server_settings.http_settings.write_timeout	Ganzzahl	Optional	Die maximale Anzahl an Sekunden, die zum Senden einer Antwort zulässig sind. Der Standardwert ist `3`.
server_settings.http_settings.idle_timeout	Ganzzahl	Optional	Die maximale Wartezeit in Sekunden für die nächste Anfrage, wenn Leerlaufverbindungen 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 wird 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 anzunehmen. 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 anzunehmen. Der Standardwert ist `503`.

Referenz zu Collector API-Methoden

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 Erfassungseinstellungen für genau einen der folgenden Typen angegeben werden können:

Logdateidaten
Kafka-Themen
Paketdaten (pcap)
Splunk-Daten
Syslog-Daten

Endpunkte für die Arbeit mit Spediteuren finden Sie in der Forwarder API-Referenz.

Collector erstellen

Erstellt einen neuen Collector im Google SecOps-Konto. Konfigurationswerte für Collectors müssen mit „Create Collector“ angegeben werden, nachdem „Create Forwarder“ verwendet wurde.

Bei bestimmten Einstellungen werden Konfigurationswerte, die im Anfragetext fehlen oder den Wert „0“ haben, auf Standardwerte gesetzt. Weitere Informationen zu den Feldern und Werten der Collector-Konfiguration finden Sie unter Felder der Collector-Konfiguration.

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 in der Google SecOps-Benutzeroberfläche angezeigt.
config	Objekt	Erforderlich	Die Konfigurationseinstellungen für diesen Collector. Weitere Informationen finden Sie unter Felder für die Collector-Konfiguration.
state	enum	Optional	Gibt den aktuellen Status des Collectors an. Gültige Werte sind: AKTIV: Der Collector darf Daten empfangen. SUSPENDED: Der Collector darf keine Daten annehmen.

Feld

Typ

Erforderlich

Beschreibung

display_name

String

Erforderlich

Der Name des Collectors. Dieser Name wird in der Google SecOps-Benutzeroberfläche angezeigt.

config

Objekt

Erforderlich

Die Konfigurationseinstellungen für diesen Collector. Weitere Informationen finden Sie unter Felder für die Collector-Konfiguration.

state

enum

Optional

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

AKTIV: Der Collector darf Daten empfangen.
SUSPENDED: Der Collector darf keine Daten annehmen.

Beispielanfrage

In diesem Beispiel sehen Sie die erforderlichen Schlüssel/Wert-Paare in einer Create Collector-Anfrage. Für alle Felder, die nicht angegeben werden, werden beim Erstellen des Collectors Standardwerte angewendet.

In diesem Beispiel ist der Collector-Typ file. Die Collector-Konfiguration enthält also 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 Konfigurationsfelder für Collector.

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

Bei einer erfolgreichen Anfrage wird in der Antwort der HTTP-Statuscode 200 (OK) zurückgegeben.

In der Antwort werden die Konfigurationswerte angezeigt, die beim Erstellen des Collectors angewendet wurden. Bei der Ressourcenerstellung werden für bestimmte Einstellungen Standardkonfigurationswerte angewendet, wenn die entsprechenden Felder im Anfragetext fehlen oder den Wert „0“ haben. Weitere Informationen finden Sie unter Felder für die Collector-Konfiguration.

Antwortfelder

Zusätzlich zu den in der Anfrage angegebenen Feldern und den Feldern, für 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`

Beispielantwort

Dies ist ein Beispiel für die Antwort, die für das obige Beispiel für eine Anfrage zurückgegeben wird.

{
  "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.

Beispielanfrage

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

Beispielantwort

{
  "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

Beispielanfrage

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

Antwort

Gibt mehrere Collectors zurück.

Beispielantwort

{
  "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 empfiehlt es sich, 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.

Wenn Sie eine FieldMask angeben möchten, um den Anzeigenamen für einen Collector zu aktualisieren, geben Sie den URL-Abfrageparameter „updateMask“ in der Patch-Anfrage an. Beispiel:

?updateMask=displayName

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

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 in der Google SecOps-Benutzeroberfläche angezeigt.
config	Objekt	Optional	Die Konfigurationseinstellungen für diesen Forwarder. Weitere Informationen finden Sie unter Felder für die Collector-Konfiguration.

Beispielanfrage

Dies ist ein Beispiel für eine Update Collector-Anfrage, in der neue Werte für displayName, logType, assetNamespace und protocol angegeben werden.

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",
      }
    }
  }

Beispielantwort

Dies ist ein Beispiel für die Antwort, die für das obige Beispiel für eine Anfrage zurückgegeben wird.

{
  "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.

Beispielanfrage

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

Beispielantwort

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

{}

Collector-Konfigurationsfelder

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

Feld	Typ	Erforderlich	Beschreibung
log_type	String	Erforderlich	Ein unterstützter Logtyp (einer, der von Google SecOps aufgenommen werden kann). Eine Liste der unterstützten Logtypen, für die Google SecOps einen Parser hat, finden Sie auf der Seite Unterstützte Standardparser in der Spalte „Ingestion Label“ (Aufnahmelabel). Eine vollständige Liste der unterstützten Logtypen finden Sie über den `logtypes`-Endpunkt.
metadata.asset_namespace	Objekt	Optional	Der Namespace zum Identifizieren von Logs von diesem Collector. Hinweis:Dies ist eine globale Einstellung, die für den Forwarder und die zugehörigen Collectoren gilt, sofern sie nicht auf Collectorebene ü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 zugehörigen Collectoren gilt, sofern sie nicht auf Collectorebene ü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: ALLOW: In diesem Status kann die gefilterte Zeile hochgeladen werden. BLOCK: In diesem Status wird verhindert, dass die gefilterte Zeile hochgeladen wird.
disk_buffer.state	enum	Optional	Gibt den Status der Festplattenpufferung 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 gepufferten Datei.
max_seconds_per_batch	Ganzzahl	Optional	Die Anzahl der Sekunden zwischen den Batches. Der Standardwert ist `10`.
max_bytes_per_batch	Ganzzahl	Optional	Die Anzahl der Bytes, die vor dem Upload des Forwarder-Batches in der Warteschlange stehen. Der Standardwert ist `1048576`.
<collector_type>_settings.<fields>		Erforderlich	Gibt einen Collector-Typ und seine Einstellungen an. Für jeden Collector muss 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 sind in den nachfolgenden Zeilen dieser Tabelle aufgeführt. Die verfügbaren Collector-Typen sind: `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 Identität, die für die Authentifizierung verwendet wird.
kafka_settings.authentication.password	String	Optional	Das Passwort des Kontos, das durch den Nutzernamen angegeben wird.
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 Dial-Vorgang auf den Abschluss einer Verbindung wartet. Der Standardwert ist `60`.
kafka_settings.brokers	String	Optional	Eine wiederholte Zeichenfolge mit einer Liste von Kafka-Brokern. Beispiel: „broker-1:9092“, „broker-2:9093“ Hinweis:Alle Werte werden bei einer Aktualisierung ersetzt. Wenn Sie also eine Liste von Brokern aktualisieren möchten, um einen neuen Broker hinzuzufügen, müssen Sie alle vorhandenen Broker und den neuen Broker angeben.
kafka_settings.tls_settings.certificate	String	Optional	Der Pfad und der Dateiname des Zertifikats. Beispiel: `/path/to/cert.pem`
kafka_settings.tls_settings.certificate_key	String	Optional	Der Pfad und der Dateiname des Zertifikatschlüssels. Beispiel: `/path/to/cert.key`
kafka_settings.tls_settings.minimum_tls_version	String	Optional	Die TLS-Mindestversion.
kafka_settings.tls_settings.insecure_skip_verify	bool	Optional	Wenn `true`, wird die SSL-Zertifikatsprüfung aktiviert. Der Standardwert ist `false`.
pcap_settings.network_interface	String	Optional	Die Schnittstelle, die für PCAP-Daten überwacht werden soll.
pcap_settings.bpf	String	Optional	Der Berkeley Packet Filter (BPF) für pcap.
splunk_settings.authentication.username	String	Optional	Der Nutzername einer Identität, die für die Authentifizierung verwendet wird.
splunk_settings.authentication.password	String	Optional	Das Passwort des Kontos, das durch den Nutzernamen angegeben wird.
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 Zeitbereich 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, mit der Datensätze in Splunk gefiltert werden. Beispiel: `search index=* sourcetype=dns`
splunk_settings.query_mode	String	Optional	Der Abfragemodus für Splunk. Beispiel: `realtime`
splunk_settings.cert_ignored	bool	Optional	Wenn `true`, wird das Zertifikat ignoriert.
syslog_settings.protocol	enum	Optional	Gibt das Protokoll an, das der Collector verwendet, um auf Syslog-Daten zu warten. Gültige Werte sind: `TCP` `UDP`
syslog_settings.address	String	Optional	Die Ziel-IP-Adresse oder der Hostname, auf dem sich der Collector befindet und an dem er auf Syslog-Daten wartet.
syslog_settings.port	Ganzzahl	Optional	Der Zielport, an dem sich der Collector befindet und an dem er auf Syslog-Daten wartet.
syslog_settings.buffer_size	Ganzzahl	Optional	Die Größe des Puffers 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 der die TCP-Verbindung getrennt wird. Der Standardwert ist `60`.
syslog_settings.tls_settings.certificate	String	Optional	Der Pfad und der Dateiname des Zertifikats. Beispiel: `/path/to/cert.pem`
syslog_settings.tls_settings.certificate_key	String	Optional	Der Pfad und der Dateiname des Zertifikatschlüssels. Beispiel: `/path/to/cert.key`
syslog_settings.tls_settings.minimum_tls_version	String	Optional	Die TLS-Mindestversion.
syslog_settings.tls_settings.insecure_skip_verify	bool	Optional	Wenn `true`, wird die SSL-Zertifikatsprüfung aktiviert. Der Standardwert ist `false`.