Questa pagina è stata tradotta dall'API Cloud Translation.

Gestione degli spedizionieri

Puoi utilizzare i metodi dell'API Google Security Operations Forwarder Management per eseguire le seguenti operazioni in modo programmatico:

Crea e gestisci gli spedizionieri.
Creare e gestire i raccoglitori.
Recupera i contenuti dei file di configurazione (.conf) e autenticazione (_auth.conf) di un forwarder Google SecOps.

I forwarder sono composti da uno o più raccoglitori. La configurazione di ogni raccoglitore specifica il meccanismo di importazione (ad esempio File, Kafka, PCAP, Splunk o Syslog) e il tipo di log.

Se i requisiti hardware sono soddisfatti, puoi utilizzare molti raccoglitori sullo stesso forwarder per importare dati da una serie di meccanismi e tipi di log. Ad esempio, puoi installare un forwarder con due raccoglitori syslog in ascolto dei dati PAN_FIREWALL e CISCO_ASA_FIREWALL su porte separate, rispettivamente.

L'API ti consente di creare forwarder e i relativi raccoglitori nell'istanza Google SecOps. Una volta creato un forwarder, puoi utilizzare l'endpoint Generate Forwarder Files per ottenere i contenuti dei file (come payload JSON) per i file di configurazione (.conf) e autenticazione (_auth.conf) di un forwarder. Questi contenuti possono poi essere scritti nei rispettivi file .conf per l'implementazione con il servizio Google SecOps Forwarder su un sistema Windows o Linux.

Per esempi Python che utilizzano l'API Forwarder Management, consulta il repository GitHub.

Crea un forwarder e i relativi raccoglitori

È necessario creare un forwarder prima di poter creare uno dei relativi raccoglitori.

Per creare un forwarder e i relativi raccoglitori:

Crea un inoltro.
Crea un raccoglitore per lo spedizioniere.
(Facoltativo) Ripeti il passaggio 2 per aggiungere altri raccoglitori.

Recuperare le credenziali di autenticazione API

Il tuo rappresentante di Google Security Operations ti fornirà una credenziale dell'account di servizio Google Developer per consentire al client API di comunicare con l'API.

Devi anche fornire l'ambito di autenticazione quando inizializzi il client API. OAuth 2.0 utilizza un ambito per limitare l'accesso di un'applicazione a un account. Quando un'applicazione richiede un ambito, il token di accesso rilasciato all'applicazione è limitato all'ambito concesso.

Utilizza il seguente ambito per inizializzare il client API Backstory:

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

Esempio Python

L'esempio Python seguente mostra come utilizzare le credenziali OAuth2 e il client HTTP utilizzando google.oauth2 e googleapiclient.

# 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/

Limiti delle query API Backstory

L'API Backstory applica limiti al volume di richieste che possono essere effettuate da un singolo cliente alla piattaforma Google SecOps. Se raggiungi o superi il limite di query, il server API Backstory restituisce HTTP 429 (RESOURCE_EXHAUSTED) al chiamante. Quando sviluppi applicazioni per l'API Backstory, Google consiglia di applicare limiti di frequenza all'interno del sistema per evitare l'esaurimento delle risorse. Questi limiti si applicano a tutte le API Backstory, incluse le API di ricerca, gestione del forwarder e strumenti.

Consulta l'elenco dettagliato delle quote dell'API Backstory.

Viene applicato il seguente limite per la gestione degli inoltratori e viene misurato in query al secondo (QPS):

API Backstory	Endpoint API	Limite
Gestione degli spedizionieri	Crea agente di inoltro	1 QPS
	Recupera agente di inoltro	1 QPS
	Elenca agenti di inoltro	1 QPS
	Aggiorna forwarder	1 QPS
	Elimina agente di inoltro	1 QPS
Gestione dei raccoglitori	Crea raccoglitore	1 QPS
	Recupera raccoglitore	1 QPS
	Elenco raccoglitori	1 QPS
	Aggiorna raccoglitore	1 QPS
	Elimina raccoglitore	1 QPS

Riferimento ai metodi API di inoltro

Questa sezione descrive gli endpoint per la creazione e la gestione degli inoltratori. Per gli endpoint per la creazione e la gestione dei raccoglitori, consulta il riferimento API Collector.

Crea agente di inoltro

Crea un nuovo forwarder nell'istanza Google SecOps. Il nuovo inoltro includerà tutti i valori di configurazione dell'inoltro forniti nel corpo della richiesta. I valori di configurazione per i raccoglitori devono essere specificati utilizzando Create Collector dopo aver utilizzato Create Forwarder.

Per alcune impostazioni, i valori di configurazione mancanti o pari a zero nel corpo della richiesta vengono impostati sui valori predefiniti. Per informazioni dettagliate sui campi e sui valori del forwarder, consulta Campi di configurazione del forwarder.

Richiesta

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

Corpo della richiesta

{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}

Parametri del corpo

Campo	Tipo	Obbligatorio	Descrizione
display_name	string	Obbligatorio	Il nome dello spedizioniere. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config	oggetto	Facoltativo	Le impostazioni di configurazione per questo forwarder. Consulta Campi di configurazione del forwarder.

Esempio di richiesta

Questo esempio mostra le coppie chiave:valore richieste in una richiesta Create Forwarder. Se un campo non è specificato nella richiesta e ha un valore predefinito, questo viene applicato durante la creazione del forwarder. Per informazioni dettagliate sui valori predefiniti, consulta Campi di configurazione del forwarder.

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

Risposta

Se la richiesta riesce, la risposta restituisce un codice di stato HTTP 200 (OK).

La risposta mostra i valori di configurazione applicati durante la creazione del forwarder. I valori di configurazione predefiniti vengono applicati a determinate impostazioni durante la creazione delle risorse se questi campi sono mancanti o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, vedi Campi di configurazione del forwarder.

Campi di risposta

Oltre ai campi specificati nella richiesta e a quelli per cui vengono applicati i valori predefiniti, la risposta include i seguenti campi generati e di sola output.

Campo	Tipo	Descrizione
nome	string	L'ID risorsa dello spedizioniere. Il formato è "forwarders/forwarderID". Ad esempio: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
state	enum	Specifica lo stato attuale dello spedizioniere. I valori validi sono: ATTIVO: il responsabile dell'inoltro è autorizzato a caricare i dati. SOSPESO: il responsabile dell'inoltro non è autorizzato a caricare dati. Il valore predefinito è ACTIVE.

Campo

Tipo

Descrizione

nome

string

L'ID risorsa dello spedizioniere. Il formato è "forwarders/forwarderID". Ad esempio:

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

state

enum

Specifica lo stato attuale dello spedizioniere. I valori validi sono:

ATTIVO: il responsabile dell'inoltro è autorizzato a caricare i dati.
SOSPESO: il responsabile dell'inoltro non è autorizzato a caricare dati.

Il valore predefinito è ACTIVE.

Esempio di risposta

Questo è un esempio della risposta restituita per la richiesta di esempio riportata sopra.

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

Recupera agente di inoltro

Restituisce un forwarder.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

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

Elenca agenti di inoltro

Elenca tutti i forwarder per un'istanza Google SecOps.

Richiesta

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

Esempio di richiesta

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

Risposta

Restituisce un elenco di inoltratori.

Esempio di risposta

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

Aggiorna forwarder

Puoi aggiornare un forwarder utilizzando il parametro di query URL updateMask per specificare i campi da aggiornare.

Ad esempio, per aggiornare il nome visualizzato, utilizzeresti il parametro di query updateMask come segue nella richiesta di patch:

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi che vuoi aggiornare (nelle loro posizioni esatte).

Richiesta

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}?updateMask=<field_1,field_2>

Corpo della richiesta

{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  },
}

Parametri del corpo

Campo	Tipo	Obbligatorio	Descrizione
display_name	string	Obbligatorio	Il nome dello spedizioniere. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config	oggetto	Facoltativo	Le impostazioni di configurazione per questo forwarder. Consulta Campi di configurazione del forwarder.

Esempio di richiesta

Questo è un esempio di richiesta di aggiornamento del forwarder in cui la richiesta specifica nuovi valori per displayName e aggiunge un'etichetta di metadati.

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

Esempio di risposta

Questo è un esempio della risposta restituita per la richiesta di esempio riportata sopra.

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

Elimina agente di inoltro

Elimina un agente di inoltro.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

Se l'operazione riesce, Delete Forwarder restituisce una risposta vuota con un codice di stato HTTP 200 (OK).

{}

Genera file di inoltro

Genera e restituisce i contenuti dei file di configurazione (.conf) e autenticazione (_auth.conf) del forwarder.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

Se l'operazione riesce, restituisce un codice di stato HTTP 200 (OK). Restituisce anche i contenuti di un file di configurazione del forwarder, inclusi i dati di configurazione per i raccoglitori del forwarder, nonché i contenuti del file di autenticazione (_auth.conf) utilizzato dal forwarder per l'autenticazione con l'istanza Google SecOps.

Campi di configurazione dell'agente di inoltro

La seguente tabella elenca le impostazioni di configurazione del forwarder che puoi specificare utilizzando Crea forwarder e Aggiorna forwarder. Se non specifichi un valore per un'impostazione quando utilizzi Crea inoltro, viene applicato il valore predefinito dell'impostazione (mostrato di seguito).

I seguenti campi possono essere forniti nell'oggetto config del corpo della richiesta.

Campo	Tipo	Obbligatorio	Descrizione
upload_compression	bool	Facoltativo	Se `true`, i batch di dati vengono compressi prima del caricamento. Il valore predefinito è `false`.
metadata.asset_namespace	string	Facoltativo	Lo spazio dei nomi per identificare i log di questo forwarder. Nota:questa è un'impostazione globale che si applica al forwarder e ai suoi raccoglitori, a meno che non venga sostituita a livello di raccoglitore. Per saperne di più, consulta Configurare gli spazi dei nomi.
metadata.labels	list	Facoltativo	Un elenco di coppie chiave:valore arbitrarie che possono essere specificate nella configurazione del forwarder. Nota:questa è un'impostazione globale che si applica al forwarder e ai suoi raccoglitori, a meno che non venga sostituita a livello di raccoglitore.
metadata.labels.key	string	Facoltativo	La chiave di un campo nell'elenco delle etichette dei metadati.
metadata.labels.value	string	Facoltativo	Il valore di un campo nell'elenco delle etichette dei metadati.
regex_filters.description	string	Facoltativo	Descrive cosa viene filtrato e perché.
regex_filters.regexp	string	Facoltativo	L'espressione regolare utilizzata per trovare corrispondenze con ogni riga in entrata.
regex_filters.behavior	enum	Facoltativo	Specifica lo stato della funzionalità del server. I valori validi sono: ALLOW: questo stato consente di caricare la riga filtrata. BLOCCA: questo stato impedisce il caricamento della riga filtrata.
server_settings	oggetto	Facoltativo	Impostazioni che configurano il server HTTP integrato del forwarder, che può essere utilizzato per configurare le opzioni di bilanciamento del carico e alta disponibilità per la raccolta di syslog su Linux.
server_settings.state	enum	Facoltativo	Specifica lo stato della funzionalità del server. I valori validi sono: ATTIVO: in questo stato, le impostazioni del server vengono applicate come specificato. SOSPENSIONE In questo stato, le impostazioni del server non vengono applicate.
server_settings.graceful_timeout	integer	Facoltativo	Numero di secondi dopo i quali il forwarder restituisce un controllo di integrità/prontezza errato e accetta comunque nuove connessioni. Questo è anche il tempo di attesa tra la ricezione di un segnale di arresto e l'inizio dell'arresto del server stesso. In questo modo il bilanciatore del carico ha il tempo di rimuovere il forwarder dal pool. Il valore predefinito è `15`.
server_settings.drain_timeout	integer	Facoltativo	Il numero di secondi dopo i quali il forwarder attende la chiusura automatica delle connessioni attive prima che vengano chiuse dal server. Il valore predefinito è `10`.
server_settings.http_settings.port	integer	Facoltativo	Il numero di porta su cui il server HTTP rimane in ascolto per i controlli di integrità dal bilanciatore del carico. Deve essere compreso tra 1024 e 65535. Il valore predefinito è `8080`.
server_settings.http_settings.host	string	Facoltativo	L'indirizzo IP o il nome host che può essere risolto in indirizzi IP, a cui il server deve rimanere in ascolto. Il valore predefinito è `0.0.0.0` (il sistema locale).
server_settings.http_settings.read_timeout	integer	Facoltativo	Il numero massimo di secondi consentito per leggere le richieste complete, che includono l'intestazione e il corpo. Il valore predefinito è `3`.
server_settings.http_settings.read_header_timeout	integer	Facoltativo	Il numero massimo di secondi consentito per leggere le intestazioni delle richieste. Il valore predefinito è `3`.
server_settings.http_settings.write_timeout	integer	Facoltativo	Il numero massimo di secondi consentiti per inviare una risposta. Il valore predefinito è `3`.
server_settings.http_settings.idle_timeout	integer	Facoltativo	Il numero massimo di secondi da attendere per la richiesta successiva quando le connessioni inattive sono abilitate. Il valore predefinito è `3`.
server_settings.http_settings.route_settings.available_status_code	integer	Facoltativo	Il codice di stato restituito quando viene ricevuto un controllo di vivacità e il forwarder è disponibile. Il valore predefinito è `204`.
server_settings.http_settings.route_settings.ready_status_code	integer	Facoltativo	Il codice di stato restituito quando l'inoltro è pronto ad accettare il traffico. Il valore predefinito è `204`.
server_settings.http_settings.route_settings.unready_status_code	integer	Facoltativo	Il codice di stato restituito quando il forwarder non è pronto ad accettare il traffico. Il valore predefinito è `503`.

Riferimento ai metodi API Collector

Questa sezione descrive gli endpoint per l'utilizzo dei raccoglitori.

Quando crei e aggiorni i raccoglitori, tieni presente che ogni configurazione del raccoglitore può specificare le impostazioni di importazione per uno solo dei seguenti elementi:

Dati dei file di log
Argomenti Kafka
Dati dei pacchetti (pcap)
Dati Splunk
Dati Syslog

Per gli endpoint per l'utilizzo dei forwarder, consulta il riferimento API Forwarder.

Crea raccoglitore

Crea un nuovo raccoglitore nell'account Google SecOps. I valori di configurazione per collectors devono essere specificati utilizzando Create Collector dopo aver utilizzato Create Forwarder.

Per alcune impostazioni, i valori di configurazione mancanti o pari a zero nel corpo della richiesta vengono impostati sui valori predefiniti. Per informazioni dettagliate sui campi e sui valori di configurazione del collettore, vedi Campi di configurazione del collettore.

Richiesta

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

Corpo della richiesta

{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  }
  "state": enum
}

Parametri del corpo

Campo	Tipo	Obbligatorio	Descrizione
display_name	string	Obbligatorio	Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config	oggetto	Obbligatorio	Le impostazioni di configurazione per questo raccoglitore. Consulta Campi di configurazione del raccoglitore.
state	enum	Facoltativo	Specifica lo stato attuale del raccoglitore. I valori validi sono: ATTIVO: il raccoglitore è autorizzato ad accettare dati. SOSPESO: il raccoglitore non è autorizzato ad accettare dati.

Campo

Tipo

Obbligatorio

Descrizione

display_name

string

Obbligatorio

Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.

config

oggetto

Obbligatorio

Le impostazioni di configurazione per questo raccoglitore. Consulta Campi di configurazione del raccoglitore.

state

enum

Facoltativo

Specifica lo stato attuale del raccoglitore. I valori validi sono:

ATTIVO: il raccoglitore è autorizzato ad accettare dati.
SOSPESO: il raccoglitore non è autorizzato ad accettare dati.

Esempio di richiesta

Questo esempio mostra le coppie chiave:valore richieste in una richiesta Create Collector. Per i campi non forniti, vengono applicati i valori predefiniti durante la creazione del raccoglitore.

In questo esempio, il tipo di raccoglitore è file, quindi la configurazione del raccoglitore include file_settings per indicare il tipo di raccoglitore e le relative impostazioni. Se il tipo di raccoglitore è syslog, la configurazione del raccoglitore include syslog_settings. Per saperne di più, consulta Campi di configurazione del raccoglitore.

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

Risposta

Se la richiesta riesce, la risposta restituisce un codice di stato HTTP 200 (OK).

La risposta mostra i valori di configurazione applicati durante la creazione del collettore. I valori di configurazione predefiniti vengono applicati a determinate impostazioni durante la creazione delle risorse se questi campi sono mancanti o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, vedi Campi di configurazione del raccoglitore.

Campi di risposta

Oltre ai campi specificati nella richiesta e a quelli per cui vengono applicati i valori predefiniti, la risposta include i seguenti campi:

Campo	Tipo	Descrizione
nome	string	L'ID risorsa del raccoglitore. Il formato è "forwarders/{forwarderID}/collectors/{collectorID}". Ad esempio: `forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56`

Esempio di risposta

Questo è un esempio della risposta restituita per la richiesta di esempio riportata sopra.

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

Recupera raccoglitore

Restituisce un raccoglitore.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

{
  "name": "?",
  "displayName": "abc_collector",
  "config": {
    "logType": "tomcat",
    "maxSecondsPerBatch": "10",
    "maxBytesPerBatch": "1048576"
  }
}

Elenco raccoglitori

Elenca i raccoglitori esistenti per il forwarder specificato.

Richiesta

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

Esempio di richiesta

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

Risposta

Restituisce più raccoglitori.

Esempio di risposta

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

Aggiorna raccoglitore

Quando aggiorni un raccoglitore con l'API, puoi scegliere di sovrascrivere l'intera configurazione del raccoglitore o solo campi specifici della configurazione del raccoglitore. In genere è meglio sovrascrivere campi specifici per evitare di sovrascrivere accidentalmente tutti i dati. Per sovrascrivere campi specifici, fornisci una maschera di campo alla richiesta di aggiornamento.

Per fornire un FieldMask per aggiornare il nome visualizzato di un raccoglitore, fornisci il parametro di query URL updateMask nella richiesta patch. Ad esempio:

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi che vuoi aggiornare (nelle loro posizioni esatte).

Richiesta

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}?updateMask=<field_1,field_2>

Corpo della richiesta

{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  },
}

Parametri del corpo

Campo	Tipo	Obbligatorio	Descrizione
displayName	string	Obbligatorio	Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config	oggetto	Facoltativo	Le impostazioni di configurazione per questo forwarder. Consulta Campi di configurazione del raccoglitore.

Esempio di richiesta

Questo è un esempio di richiesta di Update Collector in cui la richiesta specifica nuovi valori per displayName, logType, assetNamespace e protocollo.

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

Esempio di risposta

Questo è un esempio della risposta restituita per la richiesta di esempio riportata sopra.

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

Elimina raccoglitore

Elimina un raccoglitore.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

Se l'operazione riesce, Delete Collector restituisce una risposta vuota con un codice di stato HTTP 200 (OK).

{}

Campi di configurazione del raccoglitore

I seguenti campi possono essere forniti nell'oggetto config del corpo della richiesta.

Campo	Tipo	Obbligatorio	Descrizione
log_type	string	Obbligatorio	Un tipo di log supportato (uno che può essere importato da Google SecOps). Per un elenco dei tipi di log supportati per i quali Google SecOps dispone di un parser, consulta la colonna Etichetta di importazione nella pagina Parser predefiniti supportati. Per ottenere un elenco completo dei tipi di log supportati, utilizza l'endpoint `logtypes`.
metadata.asset_namespace	oggetto	Facoltativo	Lo spazio dei nomi per identificare i log di questo raccoglitore. Nota:questa è un'impostazione globale che si applica al forwarder e ai suoi raccoglitori, a meno che non venga sostituita a livello di raccoglitore. Per saperne di più, consulta Configurare gli spazi dei nomi.
metadata.labels	list	Facoltativo	Un elenco di coppie chiave:valore arbitrarie che possono essere specificate nella configurazione del raccoglitore. Nota:questa è un'impostazione globale che si applica al forwarder e ai suoi raccoglitori, a meno che non venga sostituita a livello di raccoglitore.
metadata.labels.key	string	Facoltativo	La chiave di un campo nell'elenco delle etichette dei metadati.
metadata.labels.value	string	Facoltativo	Il valore di un campo nell'elenco delle etichette dei metadati.
regex_filters.description	string	Facoltativo	Descrive cosa viene filtrato e perché.
regex_filters.regexp	string	Facoltativo	L'espressione regolare utilizzata per trovare corrispondenze con ogni riga in entrata.
regex_filters.behavior	enum	Facoltativo	Specifica lo stato della funzionalità del server. I valori validi sono: ALLOW: questo stato consente di caricare la riga filtrata. BLOCCA: questo stato impedisce il caricamento della riga filtrata.
disk_buffer.state	enum	Facoltativo	Specifica lo stato del buffering del disco per il raccoglitore. I valori validi sono: ATTIVO: il buffering è abilitato. SUSPENDED: il buffering è disattivato.
disk_buffer.directory_path	string	Facoltativo	Il percorso della directory per i file scritti.
disk_buffer.max_file_buffer_bytes	integer	Facoltativo	La dimensione massima dei file memorizzati nella cache.
max_seconds_per_batch	integer	Facoltativo	Il numero di secondi tra i batch. Il valore predefinito è `10`.
max_bytes_per_batch	integer	Facoltativo	Il numero di byte in coda prima del caricamento in batch del forwarder. Il valore predefinito è `1048576`.
<collector_type>_settings.<fields>		Obbligatorio	Specifica un tipo di raccoglitore e le relative impostazioni. Ogni raccoglitore deve specificare un tipo di raccoglitore e i relativi campi. Ad esempio, per utilizzare il tipo di raccolta `file`, è necessario aggiungere il campo `file_settings.file_path` alla configurazione e assegnargli un valore. Ad esempio: `"file_settings": { "file_path": "/opt/chronicle/edr/output/sample.txt", }` I tipi di raccoglitore e i relativi campi sono elencati nelle righe successive di questa tabella. I tipi di raccoglitore disponibili sono: `file` `kafka` `pcap` `splunk` `syslog`
file_settings.file_path	string	Facoltativo	Il percorso del file da monitorare.
kafka_settings.authentication.username	string	Facoltativo	Il nome utente di un'identità utilizzata per l'autenticazione.
kafka_settings.authentication.password	string	Facoltativo	La password dell'account identificato dal nome utente.
kafka_settings.topic	string	Facoltativo	L'argomento Kafka da cui importare i dati. Per maggiori dettagli, vedi Raccogliere dati dagli argomenti Kafka.
kafka_settings.group_id	string	Facoltativo	Un ID gruppo.
kafka_settings.timeout	integer	Facoltativo	Il numero massimo di secondi che una chiamata attenderà per completare la connessione. Il valore predefinito è `60`.
kafka_settings.brokers	string	Facoltativo	Una stringa ripetuta che elenca i broker Kafka. Ad esempio: "broker-1:9092", "broker-2:9093" Nota:tutti i valori vengono sostituiti durante un'operazione di aggiornamento. Pertanto, per aggiornare un elenco di broker e aggiungerne uno nuovo, specifica tutti i broker esistenti e il nuovo broker.
kafka_settings.tls_settings.certificate	string	Facoltativo	Il percorso e il nome del file del certificato. Ad esempio: `/path/to/cert.pem`
kafka_settings.tls_settings.certificate_key	string	Facoltativo	Il percorso e il nome file della chiave del certificato. Ad esempio: `/path/to/cert.key`
kafka_settings.tls_settings.minimum_tls_version	string	Facoltativo	La versione TLS minima.
kafka_settings.tls_settings.insecure_skip_verify	bool	Facoltativo	Se `true`, attiva la verifica della certificazione SSL. Il valore predefinito è `false`.
pcap_settings.network_interface	string	Facoltativo	L'interfaccia da ascoltare per i dati PCAP.
pcap_settings.bpf	string	Facoltativo	Il filtro Berkeley Packet Filter (BPF) per pcap.
splunk_settings.authentication.username	string	Facoltativo	Il nome utente di un'identità utilizzata per l'autenticazione.
splunk_settings.authentication.password	string	Facoltativo	La password dell'account identificato dal nome utente.
splunk_settings.host	string	Facoltativo	L'host o l'indirizzo IP per l'API REST di Splunk.
splunk_settings.port	integer	Facoltativo	La porta per l'API REST di Splunk.
splunk_settings.minimum_window_size	integer	Facoltativo	L'intervallo di tempo minimo in secondi per una determinata ricerca Splunk. Per i dettagli, consulta Raccogliere dati Splunk. Il valore predefinito è `10`.
splunk_settings.maximum_window_size	integer	Facoltativo	L'intervallo di tempo massimo in secondi per una determinata ricerca Splunk. Per i dettagli, consulta Raccogliere dati Splunk. Il valore predefinito è `30`.
splunk_settings.query_string	string	Facoltativo	La query utilizzata per filtrare i record in Splunk. Ad esempio: `search index=* sourcetype=dns`
splunk_settings.query_mode	string	Facoltativo	La modalità di query per Splunk. Ad esempio: `realtime`
splunk_settings.cert_ignored	bool	Facoltativo	Se `true`, il certificato viene ignorato.
syslog_settings.protocol	enum	Facoltativo	Specifica il protocollo che il raccoglitore utilizzerà per ascoltare i dati syslog. I valori validi sono: `TCP` `UDP`
syslog_settings.address	string	Facoltativo	L'indirizzo IP o il nome host di destinazione in cui risiede il raccoglitore e ascolta i dati syslog.
syslog_settings.port	integer	Facoltativo	La porta di destinazione in cui risiede il raccoglitore e rimane in ascolto dei dati syslog.
syslog_settings.buffer_size	integer	Facoltativo	Le dimensioni in byte del buffer del socket TCP. Il valore predefinito per TCP è `65536`. Il valore predefinito per UDP è `8192`.
syslog_settings.connecton_timeout	integer	Facoltativo	Il numero di secondi di inattività dopo i quali la connessione TCP viene interrotta. Il valore predefinito è `60`.
syslog_settings.tls_settings.certificate	string	Facoltativo	Il percorso e il nome del file del certificato. Ad esempio: `/path/to/cert.pem`
syslog_settings.tls_settings.certificate_key	string	Facoltativo	Il percorso e il nome file della chiave del certificato. Ad esempio: `/path/to/cert.key`
syslog_settings.tls_settings.minimum_tls_version	string	Facoltativo	La versione TLS minima.
syslog_settings.tls_settings.insecure_skip_verify	bool	Facoltativo	Se `true`, attiva la verifica della certificazione SSL. Il valore predefinito è `false`.