API Forwarder Management

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

  • Crea e gestisci gli inoltro.
  • Crea e gestisci i raccoglitori.
  • Recupera i contenuti dei file di configurazione (.conf) e di autenticazione (_auth.conf) per l'inoltro di Google Security Operations.

I forwarding 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.

Supponendo che i requisiti hardware siano soddisfatti, è possibile utilizzare molti raccoglitori sullo stesso forwarding per importare i dati da vari meccanismi e tipi di log. Ad esempio, puoi installare un forwarding con due collettori syslog che ascoltino i dati PAN_FIREWALL e CISCO_ASA_FIREWALL rispettivamente su porte separate.

L'API consente di creare forwarding e relativi raccoglitori nella tua istanza di Google Security Operations. Una volta creato un utente di inoltro, puoi utilizzare l'endpoint Genera file di inoltro per recuperare i contenuti del file (come payload JSON) per la configurazione (.conf) e i file di autenticazione (_auth.conf) di un utente di inoltro. 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 Python che utilizzano l'API Forwarder Management, consulta il repository GitHub.

Crea un server di inoltro e i relativi raccoglitori

È necessario creare un server di inoltro prima di poter creare i suoi raccoglitori.

Per creare uno strumento di inoltro e i relativi raccoglitori:

  1. Crea un inoltro.
  2. Crea un raccoglitore per l'utente che esegue l'inoltro.
  3. (Facoltativo) Ripeti il passaggio 2 per aggiungere altri raccoglitori.

Come eseguire l'autenticazione con l'API Google Security Operations[:#authenticate]

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:

  • Utilizzare la libreria client dell'API di Google per la lingua del tuo computer.

  • Interfaccia diretta con il sistema OAuth 2.0 tramite HTTP.

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

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

Recupero delle credenziali di autenticazione API

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

Devi inoltre fornire l'ambito dell'autenticazione durante l'inizializzazione del client API. OAuth 2.0 usa 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 tuo client API di Google:

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

Esempio Python

Il seguente esempio 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.oauth2 import service_account
from googleapiclient import _auth

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

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

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

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

# <your code continues here>

Limiti di query dell'API Chronicle

L'API Chronicle impone dei limiti sul volume di richieste che possono essere effettuate da qualsiasi cliente rispetto alla piattaforma Google Security Operations. Se raggiungi o superi il limite di query, il server API Chronicle restituisce HTTP 429 (RESOURCE_EXHAUSTED) al chiamante. Durante lo sviluppo di 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 Search, Forwarder Management e Tooling.

Il seguente limite per l'API Chronicle Forwarder Management viene applicato e misurato in query al secondo (QPS):

API Chronicle Endpoint API Limite
Gestione dello strumento di inoltro Crea forwarding 1 QPS
Installa forwarding 1 QPS
Elenco forwardinger 1 QPS
Aggiorna forwarding 1 QPS
Elimina forwarding 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 API Forwarder

Questa sezione descrive gli endpoint per la creazione e la gestione dei server di inoltro. Per gli endpoint per la creazione e la gestione dei raccoglitori, consulta il riferimento dell'API Collector.

Crea forwarding

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

Per alcune impostazioni, i valori di configurazione mancanti o con valore zero nel corpo della richiesta vengono impostati sui valori predefiniti. Per maggiori dettagli sui campi e sui valori del forwarding, vedi Campi di configurazione del forwarding.

Richiesta

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

Corpo della richiesta
{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}
Parametri corporei
Campo Tipo Obbligatorio Descrizione
display_name stringa Obbligatorio Il nome dell'inoltro. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config oggetto Facoltativo Le impostazioni di configurazione per questo forwarding. Consulta Campi di configurazione dello strumento di forwarding.
Esempio di richiesta

Questo esempio mostra le coppie chiave:valore necessarie in una richiesta di creazione del forwarding. Se un campo non è specificato nella richiesta e ha un valore predefinito, quest'ultimo viene applicato durante la creazione del server di inoltro. Per maggiori dettagli sui valori predefiniti, consulta Campi di configurazione dello strumento di forwarding.

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

Risposta

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

La risposta mostra i valori di configurazione applicati durante la creazione dello strumento di inoltro. I valori di configurazione predefiniti vengono applicati per determinate impostazioni durante la creazione delle risorse, se questi campi non sono presenti o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, consulta Campi di configurazione dello strumento di forwarding.

Campi di risposta

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

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

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

Specifica lo stato attuale del server di inoltro. I valori validi sono:

  • ATTIVO: l'utente che ha effettuato l'inoltro è autorizzato a caricare i dati.
  • SOSPESO: l'utente che ha effettuato l'inoltro 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"
}

Installa forwarding

Restituisce uno strumento di inoltro.

Richiesta

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

Corpo della richiesta

Non includere il 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"
}

Elenco forwardinger

Elenca tutti gli forwarding 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 forwarding.

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 forwarding

Puoi aggiornare un utente che esegue l'inoltro utilizzando il parametro di query dell'URL updateMask per specificare i campi da aggiornare.

Ad esempio, per aggiornare il nome visualizzato, dovresti usare 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 corporei
Campo Tipo Obbligatorio Descrizione
display_name stringa Obbligatorio Il nome dell'inoltro. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config oggetto Facoltativo Le impostazioni di configurazione per questo forwarding. Consulta Campi di configurazione dello strumento di forwarding.
Esempio di richiesta

Questo è un esempio di richiesta di aggiornamento del forwarding in cui la richiesta specifica nuovi valori per displayName e aggiunge un'etichetta 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 forwarding

Elimina un inoltro.

Richiesta

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

Non includere il 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 forwarding

Genera e restituisce i contenuti dei file di configurazione (.conf) e di autenticazione (_auth.conf) dell'utente di inoltro.

Richiesta

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

Non includere il 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 ha esito positivo, restituisce un codice di stato HTTP 200 (OK). Restituisce anche i contenuti di un file di configurazione dell'utente che esegue l'inoltro, inclusi i dati di configurazione per i raccoglitori dello strumento di inoltro, nonché i contenuti del file di autenticazione (_auth.conf) utilizzato dal server di inoltro per l'autenticazione con l'istanza Google SecOps.

Campi di configurazione dello strumento di forwarding

La tabella seguente elenca le impostazioni di configurazione dell'utente di inoltro che puoi specificare utilizzando Crea inoltro e Aggiorna inoltro. Se non specifichi un valore per un'impostazione quando utilizzi Crea forwarding, verrà 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 dal forwarding.

Nota: questa è un'impostazione globale che si applica all'utente che esegue l'inoltro e ai raccoglitori del forwarding, a meno che non venga eseguito l'override a livello del 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 forwarding.

Nota: questa è un'impostazione globale che si applica all'utente che esegue l'inoltro e ai raccoglitori del forwarding, a meno che non venga eseguito l'override a livello del raccoglitore.
metadata.labels.key stringa Facoltativo Chiave per 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 una corrispondenza 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 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 server di inoltro, 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.
  • SOSPESO In questo stato, le impostazioni del server non vengono applicate.
server_settings.graceful_timeout numero intero Facoltativo Numero di secondi dopo i quali il server di inoltro restituisce un controllo di idoneità/integrità non adeguata e accetta ancora nuove connessioni. Questo è anche il tempo di attesa tra la ricezione di un segnale di arresto e l'inizio effettivo dell'arresto del server stesso. Ciò concede al bilanciatore del carico il tempo di rimuovere il forwarding dal pool.

Il valore predefinito è 15.
server_settings.drain_timeout numero intero Facoltativo Il numero di secondi dopo i quali il server di inoltro attende che le connessioni attive si chiudano autonomamente prima di essere chiuse dal server.

Il valore predefinito è 10.
server_settings.http_settings.port numero intero Facoltativo Il numero di porta su cui il server HTTP rimane in ascolto per i controlli di integrità dal bilanciatore del carico. Il valore deve essere compreso tra 1024 e 65535.

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

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

Il valore predefinito è 3.
server_settings.http_settings.read_header_timeout numero intero Facoltativo Il numero massimo di secondi consentiti per leggere le intestazioni delle richieste.

Il valore predefinito è 3.
server_settings.http_settings.write_timeout numero intero Facoltativo Il numero massimo di secondi consentiti per inviare una risposta.

Il valore predefinito è 3.
server_settings.http_settings.idle_timeout numero intero Facoltativo Il numero massimo di secondi di attesa per la prossima richiesta quando le connessioni inattive vengono abilitate.

Il valore predefinito è 3.
server_settings.http_settings.route_settings.available_status_code numero intero Facoltativo Il codice di stato restituito quando viene ricevuto un controllo di attività e l'inoltro è disponibile.

Il valore predefinito è 204.
server_settings.http_settings.route_settings.ready_status_code numero intero Facoltativo Il codice di stato restituito quando il server di inoltro è pronto ad accettare il traffico.

Il valore predefinito è 204.
server_settings.http_settings.route_settings.unready_status_code numero intero Facoltativo Il codice di stato restituito quando il server di inoltro non è pronto ad accettare il traffico.

Il valore predefinito è 503.

Riferimento API raccoglitore

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

Quando crei e aggiorni i raccoglitori, tieni presente che ogni configurazione dei raccoglitori 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 Splunk
  • Dati Syslog

Per gli endpoint per l'utilizzo dei servizi di inoltro, consulta il riferimento API forwarding.

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 forwarding.

Per alcune impostazioni, i valori di configurazione mancanti o con valore zero nel corpo della richiesta vengono impostati come valori predefiniti. Per maggiori dettagli 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 corporei
Campo Tipo Obbligatorio Descrizione
display_name stringa 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 necessarie in una richiesta Crea raccoglitore. Per tutti i campi non forniti, durante la creazione del raccoglitore vengono applicati i valori predefiniti.

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 maggiori 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 ha esito positivo, la risposta restituisce un codice di stato HTTP 200 (OK).

La risposta mostra i valori di configurazione applicati durante la creazione del raccoglitore. I valori di configurazione predefiniti vengono applicati per determinate impostazioni durante la creazione delle risorse, se questi campi non sono presenti 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 cui 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 raccoglitore

Restituisce un raccoglitore.

Richiesta

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

Non includere il 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 forwarding 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 di sovrascrivere solo campi specifici della configurazione del raccoglitore. Conviene 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 una FieldMask al fine di aggiornare il nome visualizzato per 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 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 corporei
Campo Tipo Obbligatorio Descrizione
displayName stringa Obbligatorio Il nome del raccoglitore. Questo nome viene visualizzato nell'interfaccia di Google SecOps.
config oggetto Facoltativo Le impostazioni di configurazione per questo forwarding. Consulta 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 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 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

Elimina un raccoglitore.

Richiesta

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

Non includere il 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 ha esito positivo, 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 dispone di un parser, consulta la colonna Etichetta di importazione nella pagina Analizzatori predefiniti supportati. Per 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 da questo raccoglitore.

Nota: questa è un'impostazione globale che si applica all'utente che esegue l'inoltro e ai raccoglitori del forwarding, a meno che non venga eseguito l'override a livello del 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 all'utente che esegue l'inoltro e ai raccoglitori del forwarding, a meno che non venga eseguito l'override a livello del raccoglitore.
metadata.labels.key stringa Facoltativo Chiave per 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 una corrispondenza 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 di caricare la riga filtrata.
  • BLOCCA: questo stato impedisce il caricamento della riga filtrata.
disk_buffer.state enum Facoltativo

Specifica lo stato di buffering del disco per il raccoglitore. I valori validi sono:

  • ATTIVO: il buffering è attivato.
  • SOSPENDATO: il buffering è disattivato.
disk_buffer.directory_path stringa Facoltativo Il percorso della directory per i file scritti.
disk_buffer.max_file_buffer_bytes numero intero Facoltativo La dimensione massima del file presente nel buffer.
max_seconds_per_batch numero intero Facoltativo Il numero di secondi tra i batch.

Il valore predefinito è 10.
max_bytes_per_batch numero intero Facoltativo Il numero di byte in coda prima del caricamento batch del forwarding.

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, è necessario aggiungere il campo file_settings.file_path alla configurazione e assegnare 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 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 dati dagli argomenti Kafka.
kafka_settings.group_id stringa Facoltativo Un ID gruppo.
kafka_settings.timeout numero intero Facoltativo Il numero massimo di secondi di attesa prima che una connessione venga 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 al fine di aggiungere un nuovo broker, devi specificare 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, consente la verifica della certificazione SSL.

Il valore predefinito è false.
pcap_settings.network_interface stringa Facoltativo L'interfaccia per ascoltare i dati PCAP.
pcap_settings.bpf stringa Facoltativo Il Berkeley Packet Filtro (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 dell'API REST Splunk.
splunk_settings.port numero intero Facoltativo La porta per l'API REST Splunk.
splunk_settings.minimum_window_size numero intero 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 numero intero 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 stringa Facoltativo La query utilizzata per filtrare i record all'interno di 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 di 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 in ascolto dei dati di syslog.
syslog_settings.port numero intero Facoltativo La porta di destinazione in cui si trova il raccoglitore e rimane in ascolto dei dati syslog.
syslog_settings.buffer_size numero intero Facoltativo La dimensione in byte del buffer del socket TCP.

Il valore predefinito per TCP è 65536.
Il valore predefinito per UDP è 8192.
syslog_settings.connecton_timeout numero intero 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, consente la verifica della certificazione SSL.

Il valore predefinito è false.