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 raccoglitori syslog che ascoltano 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 Google Security Operations
Servizio di forwarding su sistema Windows o Linux.
Per gli esempi Python che utilizzano l'API Forwarder Management, consulta il repository GitHub.
Crea uno strumento 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:
- Crea un inoltro.
- Crea un raccoglitore per l'utente che esegue l'inoltro.
- (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. Il tuo dell'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 tuo rappresentante Google Security Operations ti fornirà uno Sviluppatore Google Credenziale dell'account di servizio per consentire al client API di comunicare con l'API.
Devi inoltre fornire l'ambito dell'autenticazione durante l'inizializzazione del client API. Utilizzi di OAuth 2.0 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 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 applica limiti sul volume di richieste che possono essere effettuate a un cliente sulla piattaforma Google Security Operations. Se raggiungi o superi i limite di query, il server API Chronicle restituisce HTTP 429 (RESOURCE_EXHAUSTED) l'utente. Durante lo sviluppo di applicazioni per l'API Chronicle, Google consiglia di applicare limiti di frequenza all'interno del sistema per evitare esaurimento. Questi limiti si applicano a tutte le API Chronicle, tra cui API Search, Forwarder Management e Tooling.
È stato applicato il seguente limite per l'API Chronicle Forwarder Management e viene 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 in Google SecOps a riga di comando. |
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, il valore predefinito viene applicato durante la creazione del forwarding. 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 del spedizioniere. Vengono applicati i valori di configurazione predefiniti impostazioni durante la creazione delle risorse, se questi campi mancano o hanno un valore pari a zero il corpo della richiesta. Per maggiori dettagli, vedi Campi di configurazione dello strumento di forwarding:
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 valori generati e solo campi di output.
Campo | Tipo | Descrizione |
---|---|---|
nome | stringa | L'ID risorsa del forwarding. Il formato è
"inoltro/ID inoltro". Ad esempio: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56 |
state | enum | Specifica lo stato attuale del server di inoltro. I valori validi sono:
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 (in la posizione esatta).
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 in Google SecOps a riga di comando. |
config | oggetto | Facoltativo | Le impostazioni di configurazione per questo forwarding. Consulta Campi di configurazione dello strumento di forwarding. |
Esempio di richiesta
Ecco un esempio di richiesta Update Forwarder 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 ha esito positivo, Elimina inoltro 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). it
restituisce anche il contenuto di un file di configurazione del server di inoltro, tra cui
di configurazione per i raccoglitori del mittente, nonché i contenuti
il file di autenticazione (_auth.conf
) utilizzato dall'utente che ha effettuato l'inoltro per eseguire l'autenticazione con
dell'istanza Google SecOps.
Campi di configurazione dello strumento di forwarding
La tabella seguente elenca le impostazioni di configurazione dello strumento di inoltro che puoi specificare utilizzando Crea forwarding e Aggiorna forwarding. Se non specifichi un valore per un'impostazione quando utilizzi Crea forwarding, il valore predefinito dell'impostazione (mostrato di seguito).
I seguenti campi possono essere forniti nell'oggetto config
della richiesta
del testo.
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 agli il server di inoltro e i raccoglitori del mittente, a meno che non venga sostituito 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 nel
del server di invio. Nota: questa è un'impostazione globale che si applica agli il server di inoltro e i raccoglitori del mittente, a meno che non venga sostituito a livello di 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. Valori validi sono:
|
server_settings | oggetto | Facoltativo | Impostazioni che configurano il server HTTP integrato del server di inoltro, che può essere utilizzata 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. Valori validi sono:
|
server_settings.graceful_timeout | numero intero | Facoltativo | Il numero di secondi dopo i quali lo strumento di inoltro restituisce un messaggio
controllo di idoneità/integrità e accetta ancora nuove connessioni. Questo è
anche il tempo di attesa tra la ricezione di un segnale e l'effettiva
dando inizio all'arresto del server stesso. Ciò consente al carico
per rimuovere il forwarding dal pool. Il valore predefinito è 15 . |
server_settings.drain_timeout | numero intero | Facoltativo | Il numero di secondi dopo i quali l'utente di inoltro attende che sia attivo
le connessioni devono essere chiuse autonomamente prima di essere chiuse
il 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 in caso di inattività
le connessioni siano abilitate. Il valore predefinito è 3 . |
server_settings.http_settings.route_settings.available_status_code | numero intero | Facoltativo | Il codice di stato restituito alla ricezione di un controllo di attività e
di inoltro di Google. Il valore predefinito è 204 . |
server_settings.http_settings.route_settings.ready_status_code | numero intero | Facoltativo | Il codice di stato restituito quando il sistema di inoltro è pronto per l'accettazione
per via del traffico. Il valore predefinito è 204 . |
server_settings.http_settings.route_settings.unready_status_code | numero intero | Facoltativo | Il codice di stato restituito quando l'utente che ha effettuato l'inoltro non è pronto ad accettare
per via del 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 il lavoro con i sistemi di inoltro, consulta Riferimento API Forwarder.
Crea raccoglitore
Crea un nuovo raccoglitore nell'account Google SecOps. Configurazione i valori per i raccoglitori devono essere specificati utilizzando Crea raccoglitore dopo aver utilizzato Crea forwarding.
Per alcune impostazioni, i valori mancanti o con valore zero nel corpo della richiesta sono impostati sui valori predefiniti e i relativi valori. 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 in Google SecOps a riga di comando. |
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:
|
Esempio di richiesta
Questo esempio mostra le coppie chiave:valore necessarie in una richiesta Crea raccoglitore. Per tutti i campi non forniti, durante il raccoglitore vengono applicati i valori predefiniti per la creazione di contenuti.
In questo esempio, il tipo di raccoglitore è file
, quindi la configurazione del raccoglitore
include file_settings
per indicare il tipo di raccoglitore e le sue impostazioni. Se
Il tipo di raccoglitore è syslog
, la configurazione del raccoglitore include
syslog_settings
. Per ulteriori informazioni, vedi
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. Vengono applicati i valori di configurazione predefiniti impostazioni durante la creazione delle risorse, se questi campi mancano o hanno un valore pari a zero il 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 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}". Per
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 collettore o sovrascrivere solo della configurazione del raccoglitore. Di solito è meglio sovrascrivere per evitare di sovrascrivere accidentalmente tutti i dati. Per sovrascrivere campi specifici, fornisci una FieldMask alla richiesta di aggiornamento.
Per fornire una maschera di campo al fine di aggiornare il nome visualizzato di un raccoglitore, Deve fornire 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 (in la posizione esatta).
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 in Google SecOps a riga di comando. |
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 raccoglitore aggiornamenti 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
della richiesta
del testo.
Campo | Tipo | Obbligatorio | Descrizione |
---|---|---|---|
log_type | stringa | Obbligatorio | Un tipo di log supportato (che può essere importato da Google SecOps). Per un elenco di
tipi di log supportati per i quali Google SecOps dispone di un parser, consulta le
alla colonna Etichetta di importazione nella sezione App predefinita supportata
dei parser. 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 da questo raccoglitore. Nota: questa è un'impostazione globale che si applica agli il server di inoltro e i raccoglitori del mittente, a meno che non venga sostituito 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 nel
configurazione del raccoglitore. Nota: questa è un'impostazione globale che si applica agli il server di inoltro e i raccoglitori del mittente, a meno che non venga sostituito a livello di 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. Valori validi sono:
|
disk_buffer.state | enum | Facoltativo | Specifica lo stato di buffering del disco per il raccoglitore. I valori validi sono:
|
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": { I tipi di raccoglitore e i relativi campi sono elencati nelle righe successive di questa tabella. I tipi di raccoglitore disponibili sono:
|
|
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 chiamata si connetta
completato. 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 per aggiungere un nuovo broker, specifica tutti i broker esistenti tra i vari broker 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
vedi 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
vedi 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:
|
syslog_settings.address | stringa | Facoltativo | L'indirizzo IP o il nome host di destinazione in cui risiede il raccoglitore e rimane in ascolto dei dati syslog. |
syslog_settings.port | numero intero | Facoltativo | La porta di destinazione in cui si trova il raccoglitore e rimane in ascolto di syslog e i dati di Google Cloud. |
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 . |