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.
- 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.
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.
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 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 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 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:
- Crea un forwarder.
- Crea un raccoglitore per l'utente che esegue l'inoltro.
- (Facoltativo) Ripeti il passaggio 2 per aggiungere altri collezionisti.
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:
Utilizza la libreria client dell'API di Google per il tuo linguaggio di programmazione.
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 altre implementazioni linguistiche.
Recupero delle credenziali di autenticazione 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. 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 di Python
Il seguente esempio di 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 applica limiti sul volume di richieste che possono essere effettuate a un cliente sulla 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 API Search, Forwarder Management e Tooling.
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 dello strumento di inoltro | Crea inoltro | 1 QPS |
| Installa forwarding | 1 QPS | |
| Elenco forwarder | 1 QPS | |
| Aggiorna forwarding | 1 QPS | |
| Elimina forwarding | 1 QPS | |
| Gestione dei raccoglitori | 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 server di inoltro. Per gli endpoint per la creazione e la gestione dei collector, consulta il riferimento all'API Collector.
Crea inoltro
Crea un nuovo forwarding nell'istanza Google SecOps. Il nuovo forwarder 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 dell'inoltro. Questo nome viene visualizzato in Google SecOps a riga di comando. |
| config | object | Facoltativo | Le impostazioni di configurazione per questo forwarding. Consulta Campi di configurazione del forwarder. |
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 riesce, la risposta restituisce un codice di stato HTTP 200 (OK).
La risposta mostra i valori di configurazione applicati durante la creazione dell'oggetto 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, 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 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:
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"
}
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 forwarding
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 dell'inoltro. Questo nome viene visualizzato in Google SecOps a riga di comando. |
| 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
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) del forwarder.
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 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 dello strumento di forwarding
La seguente tabella elenca le impostazioni di configurazione del forwarder che puoi specificare utilizzando Crea forwarder e Aggiorna forwarder. Se non specifichi un valore per un'impostazione quando utilizzi Crea inoltro, viene applicato il valore predefinito dell'impostazione (mostrato di seguito).
I seguenti campi possono essere forniti nell'oggetto config del corpo della richiesta.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| upload_compression | bool | Facoltativo | Se true, i batch di dati vengono compressi prima del caricamento.Il valore predefinito è false. |
| metadata.asset_namespace | stringa | Facoltativo | Lo spazio dei nomi per identificare i log dal forwarding. 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 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: 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. Valori validi sono:
|
| server_settings | oggetto | Facoltativo | Impostazioni che configurano il server HTTP integrato del forwarder, che può essere utilizzato per configurare le opzioni di bilanciamento del carico e 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:
|
| server_settings.graceful_timeout | integer | Facoltativo | Il numero di secondi dopo i quali lo strumento di inoltro restituisce un messaggio
controllo di idoneità/integrità e accetta ancora 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 | numero intero | 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à
dal 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, 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 | integer | 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 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 alla ricezione di un controllo di attività e
servizio di inoltro di Google Cloud. 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 all'API Collector
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. 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:
|
Esempio di richiesta
Questo esempio mostra le coppie chiave:valore necessarie in una richiesta Crea raccoglitore. 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, 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 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, 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 il 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. 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 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 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 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 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 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 dei
tipi di log supportati per i quali Google SecOps dispone di un parser, consulta la colonna
Etichetta di importazione nella pagina Parser predefiniti supportati. Per ottenere un
elenco completo dei tipi di log supportati, utilizza l'endpoint logtypes.
|
| metadata.asset_namespace | oggetto | Facoltativo | Lo spazio dei nomi per identificare i log di questo raccoglitore. Nota: questa è un'impostazione globale che si applica 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 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. 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 | integer | Facoltativo | La dimensione massima del file presente nel 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 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, il campo file_settings.file_path deve essere aggiunto alla configurazione e deve essere assegnato 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 collezionisti 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 i dati dagli argomenti Kafka. |
| kafka_settings.group_id | stringa | Facoltativo | Un ID gruppo. |
| kafka_settings.timeout | integer | 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, abilita 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 | 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 Splunk. |
| splunk_settings.minimum_window_size | integer | 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 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 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 ascolta i dati syslog. |
| syslog_settings.port | numero intero | Facoltativo | La porta di destinazione in cui risiede il raccoglitore e che ascolta i 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 | 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, consente la verifica della certificazione SSL.Il valore predefinito è false. |