API Forwarder Management

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

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

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

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

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

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

Crea un forwarder e i relativi collector

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

Per creare un forwarder e i relativi collector:

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

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

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

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

• Interfacciarsi direttamente con il sistema OAuth 2.0 utilizzando HTTP.

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

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

Ottenere le credenziali di autenticazione dell'API

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

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

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

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

Esempio di Python

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

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.auth.transport import requests
from google.oauth2 import service_account

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

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

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

# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)

# Your endpoint GET|POST|PATCH|etc. code will vary below

# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

# requests GET example
response = http_session.request("GET", url)

# POST example uses json
body = {
  "foo": "bar"
}
response = http_session.request("POST", url, json=body)

# PATCH example uses params and json
params = {
  "foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)

# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/

Limiti di query dell'API Chronicle

L'API Chronicle applica limiti al volume di richieste che un singolo cliente può effettuare alla piattaforma Google Security Operations. Se raggiungi o superi il limite di query, il server dell'API Chronicle restituisce HTTP 429 (RESOURCE_EXHAUSTED) all'autore della chiamata. Quando sviluppi applicazioni per l'API Chronicle, Google consiglia di applicare limiti di frequenza all'interno del sistema per evitare l'esaurimento delle risorse. Questi limiti si applicano a tutte le API Chronicle, tra cui le API di ricerca, di gestione dei forwarder e di strumenti.

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

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

Riferimento all'API Forwarder

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

Crea inoltro

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

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

Richiesta

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

Corpo della richiesta

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

Parametri del corpo

Esempio di richiesta

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

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

Risposta

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

La risposta mostra i valori di configurazione applicati durante la creazione del forwarder. I valori di configurazione predefiniti vengono applicati per determinate impostazioni durante la creazione della risorsa se questi campi mancano o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, consulta Campi di configurazione del forwarder.

Campi di risposta

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

Esempio di risposta

Questo è un esempio della risposta restituita per l'esempio di richiesta riportato sopra.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

Recupera forwarder

Restituisce un mittente.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
  "displayName": "chronicle_forwarder",
  "config": {
    "uploadCompression": "false",
    "serverSettings": {
      "gracefulTimeout": 15,
      "drainTimeout": 10,
      "httpSettings": {
        "port": "8080",
        "host": "0.0.0.0",
        "readTimeout": "3",
        "readHeaderTimeout": "3",
        "writeTimeout": "3",
        "idleTimeout": "3"
        "routeSettings": {
          "availableStatusCode": "204",
          "readyStatusCode": "204",
          "unreadyStatusCode": "503"
        },
      },
    },
  },
  "state": "ACTIVE"
}

Elenca i forwarder

Elenca tutti i forwarder per un'istanza Google SecOps.

Richiesta

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

Esempio di richiesta

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

Risposta

Restituisce un elenco di inoltratori.

Esempio di risposta

{
  "forwarders": [
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
      "displayName": "chronicle_forwarder_1",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
          ...
         },
      },
      "state": "ACTIVE"
    },
    {
      "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde57",
      "displayName": "chronicle_forwarder_2",
      "config": {
        "uploadCompression": "false",
        "serverSettings": {
          "gracefulTimeout": 15,
       ...
       },
      },
      "state": "ACTIVE"
    }
  ]
}

Aggiorna mittente

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

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

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi da aggiornare (nelle rispettive posizioni esatte).

Richiesta

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

Corpo della richiesta

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

Parametri del corpo

Esempio di richiesta

Questo è un esempio di richiesta di aggiornamento del forwarder in cui vengono specificati nuovi valori per displayName e viene aggiunta un'etichetta dei metadati.

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56?updateMask=displayName,config.metadata.labels
{
  "display_name": "UpdatedForwarder",
  "config": {
    "metadata": {
      "labels": [
        {
          "key": "office",
          "value": "corporate",
        }
      ]
    }
  }
}

Esempio di risposta

Questo è un esempio della risposta restituita per l'esempio di richiesta riportato sopra.

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

Elimina mittente

Consente di eliminare un forwarder.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

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

{}

Genera file di inoltro

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

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

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

Campi di configurazione del forwarder

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

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

Riferimento all'API Collector

Questa sezione descrive gli endpoint per lavorare con i collezionisti.

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

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

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

Crea raccoglitore

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

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

Richiesta

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

Corpo della richiesta

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

Parametri del corpo

Esempio di richiesta

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

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

POST https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors
{
  "display_name": "abc_collector",
  "config" {
    "log_type": "CS_EDR"
    "file_settings": {
      "file_path": "/opt/chronicle/edr/output/sample.txt",
    }
  }
}

Risposta

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

La risposta mostra i valori di configurazione applicati durante la creazione del raccoltore. I valori di configurazione predefiniti vengono applicati per determinate impostazioni durante la creazione della risorsa se questi campi mancano o hanno valore zero nel corpo della richiesta. Per maggiori dettagli, consulta Campi di configurazione del raccoglitore.

Campi di risposta

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

Esempio di risposta

Questo è un esempio della risposta restituita per l'esempio di richiesta riportato sopra.

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

Recupera il raccoglitore

Restituisce un raccoglitore.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

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

Elenco raccoglitori

Elenca i collector esistenti per il forwarder specificato.

Richiesta

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

Esempio di richiesta

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

Risposta

Restituisce più raccoglitori.

Esempio di risposta

{
  "collectors": [
    {
      "name": "?",
      "displayName": "abc_collector_1",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    },
    {
      "name": "?",
      "displayName": "abc_collector_2",
      "config": {
        "logType": "tomcat",
        "maxSecondsPerBatch": "10",
        "maxBytesPerBatch": "1048576"
      }
    }
  ]
}

Aggiorna raccoglitore

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

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

?updateMask=displayName

Il corpo della richiesta deve contenere solo i campi da aggiornare (nelle rispettive posizioni esatte).

Richiesta

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

Corpo della richiesta

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

Parametri del corpo

Esempio di richiesta

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

PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56?updateMask=displayName,config.logType,config.metadata.assetNamespace,config.syslogSettings.protocol
{
  "display_name": "UpdatedCollector"
  "config": {
    "metadata": {
      "asset_namespace": "COLLECTOR",
      },
      "log_type": "CISCO_ASA_FIREWALL",
      "syslog_settings": {
        "protocol": "TCP",
      }
    }
  }

Esempio di risposta

Questo è un esempio della risposta restituita per l'esempio di richiesta riportato sopra.

{
  "name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
  "displayName": "UpdatedCollector",
  "config": {
    "logType": "CISCO_ASA_FIREWALL",
    "metadata": {
      "assetNamespace": "COLLECTOR"
    },
    "maxSecondsPerBatch": 10,
    "maxBytesPerBatch": "1048576",
    "syslogSettings": {
      "protocol": "TCP",
      "address": "0.0.0.0",
      "port": 10514,
    }
  },
  "state": "ACTIVE"
}

Elimina raccoglitore

Consente di eliminare un raccoglitore.

Richiesta

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

Corpo della richiesta

Non includere un corpo della richiesta.

Esempio di richiesta

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

Esempio di risposta

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

{}

Campi di configurazione del raccoglitore

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