API Forwarder Management

Puoi utilizzare l'API Google Security Operations Forwarder Management per eseguire quanto segue in modo programmatico:

  • Crea e gestisci i forwarder.
  • Creare e gestire i collezionisti.
  • Recupera i contenuti dei file di configurazione (.conf) e di autenticazione (_auth.conf) di un forwarder di Google Security Operations.

Gli inoltratori sono composti da uno o più collezionisti. 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 collector nello stesso forwarder per importare i dati da una serie di meccanismi e tipi di log. Ad esempio, puoi installare un forwarder con due collector syslog in ascolto rispettivamente per i dati PAN_FIREWALL e CISCO_ASA_FIREWALL su porte separate.

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

Per gli esempi di Python che utilizzano l'API di gestione dei forwarder, consulta il repository GitHub.

Crea un forwarder e i relativi collector

È necessario creare un forwarder prima di poter creare i relativi collector.

Per creare un forwarder e i relativi collector:

  1. Crea un forwarder.
  2. Crea un raccoglitore per il forwarder.
  3. (Facoltativo) Ripeti il passaggio 2 per aggiungere altri collezionisti.

Come eseguire l'autenticazione con l'API Google Security Operations

Questa API Google Security Operations utilizza il protocollo OAuth 2.0 per l'autenticazione e l'autorizzazione. La tua applicazione può completare queste attività utilizzando una delle seguenti implementazioni:

  • Utilizza la libreria client dell'API di Google per il tuo linguaggio di programmazione.

  • Interfacciarsi direttamente con il sistema OAuth 2.0 utilizzando HTTP.

Consulta la documentazione di riferimento della libreria di autenticazione di Google in Python.

Le librerie di autenticazione di Google sono un sottoinsieme delle librerie client dell'API di Google. Consulta le altre implementazioni linguistiche.

Ottenere le credenziali di autenticazione dell'API

Il 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 durante l'inizializzazione del 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 emesso per l'applicazione è limitato all'ambito concesso.

Utilizza il seguente ambito per inizializzare il client API di Google:

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

Esempio di Python

Il seguente esempio in Python 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 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 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 di query dell'API Chronicle

L'API Chronicle applica limiti al volume di richieste che un singolo cliente può effettuare alla piattaforma Google Security Operations. Se raggiungi o superi il limite di query, il server dell'API Chronicle restituisce HTTP 429 (RESOURCE_EXHAUSTED) all'utente chiamante. Quando sviluppi applicazioni per l'API Chronicle, 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 Chronicle, tra cui le API di ricerca, di gestione dei forwarder e di strumenti.

Consulta l'elenco dettagliato dei limiti delle query dell'API Chronicle.

Il seguente limite per l'API di gestione del forwarder di Chronicle viene applicato e viene misurato in query al secondo (QPS):

API Chronicle Endpoint API Limite
Gestione dei corrieri Crea inoltro 1 QPS
Recupera forwarder 1 QPS
Elenca i forwarder 1 QPS
Aggiorna mittente 1 QPS
Elimina mittente 1 QPS
Gestione dei collezionisti Crea raccoglitore 1 QPS
Recupera il raccoglitore 1 QPS
Elenco raccoglitori 1 QPS
Aggiorna raccoglitore 1 QPS
Elimina raccoglitore 1 QPS

Riferimento all'API Forwarder

Questa sezione descrive gli endpoint per la creazione e la gestione dei forwarder. Per gli endpoint per la creazione e la gestione dei collector, consulta il riferimento all'API Collector.

Crea inoltro

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

Per alcune impostazioni, i valori di configurazione mancanti o con valore zero nel corpo della richiesta vengono impostati su 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 stringa Obbligatorio Il nome del forwarder. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config object Facoltativo Le impostazioni di configurazione per questo inoltro. 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 valore viene applicato durante la creazione del forwarder. Per maggiori dettagli 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 per determinate impostazioni durante la creazione della risorsa se questi campi mancano o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, consulta Campi di configurazione del forwarder.

Campi di risposta

Oltre ai campi specificati nella richiesta e ai campi per i quali vengono applicati i valori predefiniti, la risposta include i seguenti campi generati e solo per l'output.

Campo Tipo Descrizione
nome stringa L'ID risorsa del corriere. Il formato è "forwarders/forwarderID". Ad esempio:

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

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

  • ATTIVO: il mittente è autorizzato a caricare i dati.
  • SOSPENSIONE: il mittente non è autorizzato a caricare dati.

Il valore predefinito è ACTIVE.
Esempio di risposta

Questo è un esempio della risposta restituita per l'esempio di richiesta riportato 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 forwarder

Restituisce un mittente.

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 i forwarder

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 mittente

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

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

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi da aggiornare (nelle rispettive 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 stringa Obbligatorio Il nome del forwarder. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config object Facoltativo Le impostazioni di configurazione per questo inoltro. Consulta Campi di configurazione del forwarder.
Esempio di richiesta

Questo è un esempio di richiesta di aggiornamento del forwarder in cui vengono specificati nuovi valori per displayName e viene aggiunta un'etichetta dei 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 l'esempio di richiesta riportato sopra.

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

Elimina mittente

Consente di eliminare un forwarder.

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 di 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, viene restituito un codice di stato HTTP 200 (OK). Inoltre, restituisce i contenuti di un file di configurazione del forwarder, inclusi i dati di configurazione per i collector del forwarder, nonché i contenuti del file di autenticazione (_auth.conf) utilizzato dal forwarder per autenticarsi con l'istanza Google SecOps.

Campi di configurazione del forwarder

La tabella seguente 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 stringa Facoltativo Lo spazio dei nomi per identificare i log di questo inoltro.

Nota:si tratta di un'impostazione globale che si applica al forwarder e ai relativi collector, a meno che non venga sostituita a livello di collector. Per ulteriori informazioni, vedi 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:si tratta di un'impostazione globale che si applica al forwarder e ai relativi collector, a meno che non venga sostituita a livello di collector.
metadata.labels.key stringa Facoltativo La chiave di un campo nell'elenco delle etichette dei metadati.
metadata.labels.value stringa Facoltativo Il valore di un campo nell'elenco delle etichette dei metadati.
regex_filters.description stringa Facoltativo Descrive cosa viene filtrato e perché.
regex_filters.regexp stringa Facoltativo L'espressione regolare utilizzata per trovare corrispondenze con ogni riga in arrivo.
regex_filters.behavior enum Facoltativo

Specifica lo stato della funzionalità del server. I valori validi sono:

  • ALLOW: questo stato consente il caricamento della riga filtrata.
  • BLOCCA: questo stato impedisce il caricamento della riga filtrata.
server_settings object Facoltativo Impostazioni che configurano il server HTTP integrato del forwarder, che può essere utilizzato per configurare le opzioni di bilanciamento del carico e di 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.
  • SOSPESO In questo stato, le impostazioni del server non vengono applicate.
server_settings.graceful_timeout integer Facoltativo Il numero di secondi dopo i quali il forwarder restituisce un controllo di idoneità/integrità errato e continua ad accettare nuove connessioni. Si tratta anche del tempo di attesa tra la ricezione di un segnale di arresto e l'inizio effettivo 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 che le connessioni attive si chiudano autonomamente prima di essere 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à da parte del bilanciatore del carico. Deve essere compreso tra 1024 e 65535.

Il valore predefinito è 8080.
server_settings.http_settings.host stringa Facoltativo L'indirizzo IP o il nome host che può essere risolto in indirizzi IP su cui il server deve ascoltare.

Il valore predefinito è 0.0.0.0 (il sistema locale).
server_settings.http_settings.read_timeout integer Facoltativo Il numero massimo di secondi consentiti per leggere intere richieste, inclusi l'intestazione e il corpo.

Il valore predefinito è 3.
server_settings.http_settings.read_header_timeout integer Facoltativo Il numero massimo di secondi consentiti 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 di attesa 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 presenza 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 il forwarder è 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 all'API Collector

Questa sezione descrive gli endpoint per lavorare con i collezionisti.

Quando crei e aggiorni i collector, tieni presente che ogni configurazione del collector può specificare le impostazioni di importazione per uno, ma non più di uno, dei seguenti elementi:

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

Per gli endpoint per lavorare con i forwarder, consulta il riferimento all'API Forwarder.

Crea raccoglitore

Crea un nuovo raccoglitore nell'account Google SecOps. I valori di configurazione per i raccoglitori devono essere specificati utilizzando Crea raccoglitore dopo aver utilizzato Crea inoltro.

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

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 stringa Obbligatorio Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config object Obbligatorio Le impostazioni di configurazione per questo raccoglitore. Consulta la sezione 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 tutti i campi non specificati, vengono applicati valori predefiniti durante la creazione del collector.

In questo esempio, il tipo di raccoglitore è file, pertanto 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 ulteriori informazioni, 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 raccoltore. I valori di configurazione predefiniti vengono applicati per determinate impostazioni durante la creazione della risorsa se questi campi mancano o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, consulta Campi di configurazione del raccoglitore.

Campi di risposta

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

Campo Tipo Descrizione
nome stringa 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 l'esempio di richiesta riportato 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 il 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 collector 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. In genere è meglio sovrascrivere campi specifici per evitare di sovrascrivere accidentalmente tutti i dati. Per sovrascrivere campi specifici, fornisci un FieldMask alla richiesta di aggiornamento.

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

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi da aggiornare (nelle rispettive 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 stringa Obbligatorio Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config object Facoltativo Le impostazioni di configurazione per questo inoltro. Consulta la sezione Campi di configurazione del raccoglitore.
Esempio di richiesta

Questo è un esempio di richiesta di aggiornamento del raccoglitore in cui la richiesta specifica nuovi valori per displayName, logType, assetNamespace e protocol.

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 l'esempio di richiesta riportato 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

Consente di eliminare 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 stringa Obbligatorio Un tipo di log supportato (che può essere importato da Google SecOps). Per un elenco dei tipi di log supportati per i quali Google SecOps ha un parser, consulta la colonna Etichetta di importazione nella pagina Parser predefiniti supportati. Per un elenco completo dei tipi di log supportati, utilizza l'endpoint logtypes.
metadata.asset_namespace object Facoltativo Lo spazio dei nomi per identificare i log di questo raccoglitore.

Nota:si tratta di un'impostazione globale che si applica al forwarder e ai relativi collector, a meno che non venga sostituita a livello di collector. Per ulteriori informazioni, vedi Configurare gli spazi dei nomi.
metadata.labels list Facoltativo Un elenco di coppie chiave:valore arbitrarie che possono essere specificate nella configurazione del collector.

Nota:si tratta di un'impostazione globale che si applica al forwarder e ai relativi collector, a meno che non venga sostituita a livello di collector.
metadata.labels.key stringa Facoltativo La chiave di un campo nell'elenco delle etichette dei metadati.
metadata.labels.value stringa Facoltativo Il valore di un campo nell'elenco delle etichette dei metadati.
regex_filters.description stringa Facoltativo Descrive cosa viene filtrato e perché.
regex_filters.regexp stringa Facoltativo L'espressione regolare utilizzata per trovare corrispondenze con ogni riga in arrivo.
regex_filters.behavior enum Facoltativo

Specifica lo stato della funzionalità del server. I valori validi sono:

  • ALLOW: questo stato consente il caricamento della 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:

  • ATTIVA: il buffering è attivo.
  • SOSPENSIONE: il buffering è disattivato.
disk_buffer.directory_path stringa Facoltativo Il percorso della directory per i file scritti.
disk_buffer.max_file_buffer_bytes integer Facoltativo La dimensione massima del file in buffer.
max_seconds_per_batch integer Facoltativo Il numero di secondi tra un batch e l'altro.

Il valore predefinito è 10.
max_bytes_per_batch integer Facoltativo Il numero di byte in coda prima del caricamento collettivo 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 raccoglitore file, il campo file_settings.file_path deve essere aggiunto alla configurazione e deve essere assegnato un valore. Ad esempio:

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

I tipi di collezionisti e i relativi campi sono elencati nelle righe successive di questa tabella. I tipi di collezionisti disponibili sono:
  • file
  • kafka
  • pcap
  • splunk
  • syslog
file_settings.file_path stringa Facoltativo Il percorso del file da monitorare.
kafka_settings.authentication.username stringa Facoltativo Il nome utente di un'identità utilizzata per l'autenticazione.
kafka_settings.authentication.password stringa Facoltativo La password dell'account identificato dal nome utente.
kafka_settings.topic stringa Facoltativo L'argomento Kafka da cui importare i dati. Per maggiori dettagli, vedi Raccogliere i dati dagli argomenti Kafka.
kafka_settings.group_id stringa Facoltativo Un ID gruppo.
kafka_settings.timeout integer Facoltativo Il numero massimo di secondi che un numero attende prima che la connessione sia completata.

Il valore predefinito è 60.
kafka_settings.brokers stringa 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 in modo da aggiungere un nuovo broker, specifica tutti i broker esistenti e il nuovo broker.
kafka_settings.tls_settings.certificate stringa Facoltativo Il percorso e il nome file del certificato. Ad esempio:

/path/to/cert.pem
kafka_settings.tls_settings.certificate_key stringa Facoltativo Il percorso e il nome file della chiave del certificato. Ad esempio:

/path/to/cert.key
kafka_settings.tls_settings.minimum_tls_version stringa Facoltativo La versione TLS minima.
kafka_settings.tls_settings.insecure_skip_verify bool Facoltativo Se true, abilita la verifica della certificazione SSL.

Il valore predefinito è false.
pcap_settings.network_interface stringa Facoltativo L'interfaccia da ascoltare per i dati PCAP.
pcap_settings.bpf stringa Facoltativo Berkeley Packet Filter (BPF) per pcap.
splunk_settings.authentication.username stringa Facoltativo Il nome utente di un'identità utilizzata per l'autenticazione.
splunk_settings.authentication.password stringa Facoltativo La password dell'account identificato dal nome utente.
splunk_settings.host stringa 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 i dati di 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 i dati di Splunk.

Il valore predefinito è 30.
splunk_settings.query_string stringa Facoltativo La query utilizzata per filtrare i record in Splunk.

Ad esempio: search index=* sourcetype=dns
splunk_settings.query_mode stringa 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 stringa 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 che ascolta i dati syslog.
syslog_settings.buffer_size integer Facoltativo Le dimensioni in byte del buffer della 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 stringa Facoltativo Il percorso e il nome file del certificato. Ad esempio:

/path/to/cert.pem
syslog_settings.tls_settings.certificate_key stringa Facoltativo Il percorso e il nome file della chiave del certificato. Ad esempio:

/path/to/cert.key
syslog_settings.tls_settings.minimum_tls_version stringa Facoltativo La versione TLS minima.
syslog_settings.tls_settings.insecure_skip_verify bool Facoltativo Se true, abilita la verifica della certificazione SSL.

Il valore predefinito è false.