API Forwarder Management

Puedes usar la API Google Security Operations Forwarder Management para hacer lo siguiente de forma programática:

• Crear y gestionar reenviadores.
• Crear y gestionar colectores.
• Obtiene el contenido de los archivos de configuración (.conf) y autenticación (_auth.conf) de un reenviador de Google SecOps.

Los reenviadores se componen de uno o varios recolectores. La configuración de cada recopilador especifica su mecanismo de ingestión (por ejemplo, File, Kafka, PCAP, Splunk o Syslog) y su tipo de registro.

Si se cumplen los requisitos de hardware, puedes usar muchos colectores en el mismo reenviador para ingerir datos de varios mecanismos y tipos de registro. Por ejemplo, puede instalar un reenviador con dos colectores syslog que escuchen datos de PAN_FIREWALL y CISCO_ASA_FIREWALL en puertos independientes, respectivamente.

La API te permite crear reenviadores y sus colectores en tu instancia de Google SecOps. Una vez que se haya creado un reenviador, puedes usar el endpoint Generate Forwarder Files para obtener el contenido de los archivos (como carga útil JSON) de configuración (.conf) y autenticación (_auth.conf) de un reenviador. Estos contenidos se pueden escribir en sus respectivos archivos .conf para implementarlos con el servicio Google SecOps Forwarder en un sistema Windows o Linux.

Para ver ejemplos de Python que usan la API Forwarder Management, consulta el repositorio de GitHub.

Crear un reenviador y sus recopiladores

Se debe crear un reenviador antes de que se pueda crear cualquiera de sus colectores.

Para crear un reenviador y sus colectores, sigue estos pasos:

1. Crea un reenviador.
2. Crea un recopilador para el reenviador.
3. (Opcional) Repite el paso 2 para añadir más recolectores.

Autenticar con la API Chronicle

En este documento se describe cómo usa la API de Chronicle el protocolo OAuth 2.0 para la autenticación y la autorización. Tu aplicación puede gestionar esta situación con uno de los siguientes métodos:

• Usa la biblioteca de cliente de la API de Chronicle para tu lenguaje de programación.

• Interactuar directamente con el sistema OAuth 2.0 mediante HTTP.

Consulta la documentación de referencia de la biblioteca de autenticación de Google en Python.

Las bibliotecas de autenticación de Google son un subconjunto de las bibliotecas de cliente de la API Chronicle. Consulta otras implementaciones de idiomas.

Obtener credenciales de autenticación de la API

Tu representante de Google Security Operations te proporcionará una credencial de cuenta de servicio de desarrollador de Google para que el cliente de la API pueda comunicarse con ella.

También debes proporcionar el ámbito de autenticación al inicializar tu cliente de API. OAuth 2.0 usa un permiso para limitar el acceso de una aplicación a una cuenta. Cuando una aplicación solicita un ámbito, el token de acceso que se le emite se limita al ámbito concedido.

Usa el siguiente ámbito para inicializar tu cliente de la API Chronicle:

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

Ejemplo de Python

En el siguiente ejemplo de Python se muestra cómo usar las credenciales de OAuth2 y el cliente HTTP con google.oauth2 y 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 the Google Developer Service Account Credential and Chronicle 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/

Límites de consultas de la API Chronicle

La API de Chronicle aplica límites al volumen de solicitudes que puede realizar cualquier cliente en la plataforma de Google SecOps. Si alcanzas o superas el límite de consultas, el servidor de la API de Chronicle devuelve el error HTTP 429 (RESOURCE_EXHAUSTED) a la persona que llama. Cuando desarrolles aplicaciones para la API Chronicle, Google te recomienda que apliques límites de frecuencia en tu sistema para evitar que se agoten los recursos. Estos límites se aplican a todas las APIs de Chronicle, incluidas las APIs Search, Forwarder Management y Tooling.

Consulta la lista detallada de las cuotas de la API Chronicle.

Se aplica el siguiente límite a la API de gestión de Chronicle Forwarder, que se mide en consultas por segundo (CPS):

Referencia de la API Forwarder

En esta sección se describen los endpoints para crear y gestionar reenviadores. Para consultar los endpoints para crear y gestionar colectores, consulta la referencia de la API Collector.

Crear reenviador

Crea un nuevo reenviador en la instancia de Google SecOps. El nuevo reenviador incluirá los valores de configuración de reenviador proporcionados en el cuerpo de la solicitud. Los valores de configuración de los collectors se deben especificar mediante Create Collector después de usar Create Forwarder.

En el caso de algunos ajustes, los valores de configuración que faltan o que son cero en el cuerpo de la solicitud se definen como valores predeterminados. Para obtener información sobre los campos y valores de los reenviadores, consulta Campos de configuración de reenviadores.

Solicitud

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

Cuerpo de la solicitud

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

Parámetros del cuerpo

Ejemplo de solicitud

En este ejemplo se muestran los pares clave-valor necesarios en una solicitud Create Forwarder. Si no se especifica un campo en la solicitud y tiene un valor predeterminado, se aplicará este valor durante la creación del reenviador. Para obtener más información sobre los valores predeterminados, consulta Campos de configuración de reenviador.

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

Respuesta

Si la solicitud se realiza correctamente, la respuesta devuelve un código de estado HTTP 200 (OK).

La respuesta muestra los valores de configuración aplicados durante la creación del reenviador. Se aplican valores de configuración predeterminados a determinados ajustes durante la creación de recursos si faltan esos campos o tienen el valor cero en el cuerpo de la solicitud. Para obtener más información, consulta Campos de configuración de reenviadores.

Campos de respuesta

Además de los campos especificados en la solicitud y los campos a los que se aplican valores predeterminados, la respuesta incluye los siguientes campos generados y de solo salida.

Ejemplo de respuesta

Este es un ejemplo de la respuesta devuelta a la solicitud de ejemplo anterior.

{
  "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"
}

Obtener reenviador

Devuelve un reenviador.

Solicitud

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

Cuerpo de la solicitud

No incluyas el cuerpo de la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "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"
}

Mostrar reenviadores

Enumera todos los reenviadores de una instancia de Google SecOps.

Solicitud

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

Ejemplo de solicitud

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

Respuesta

Devuelve una lista de reenviadores.

Ejemplo de respuesta

{
  "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"
    }
  ]
}

Actualizar reenviador

Para actualizar un reenvío, usa el parámetro de consulta de URL updateMask para especificar los campos que quieres actualizar.

Por ejemplo, para actualizar el nombre visible, usarías el parámetro de consulta updateMask de la siguiente manera en la solicitud PATCH:

?updateMask=displayName

El cuerpo de la solicitud solo debe contener los campos que quieras actualizar (en sus ubicaciones exactas).

Solicitud

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

Cuerpo de la solicitud

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

Parámetros del cuerpo

Ejemplo de solicitud

Este es un ejemplo de una solicitud Update Forwarder en la que se especifican nuevos valores para displayName y se añade una etiqueta de metadatos.

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",
        }
      ]
    }
  }
}

Ejemplo de respuesta

Este es un ejemplo de la respuesta devuelta a la solicitud de ejemplo anterior.

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

Eliminar reenviador

Elimina un reenviador.

Solicitud

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

Cuerpo de la solicitud

No incluyas el cuerpo de la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

Si la operación se realiza correctamente, Delete Forwarder devuelve una respuesta vacía con el código de estado HTTP 200 (OK).

{}

Generar archivos de reenvío

Genera y devuelve el contenido de los archivos de configuración (.conf) y autenticación (_auth.conf) del reenviador.

Solicitud

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

Cuerpo de la solicitud

No incluyas el cuerpo de la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

Si la operación se realiza correctamente, devuelve un código de estado HTTP 200 (OK). También devuelve el contenido de un archivo de configuración de un reenviador, incluidos los datos de configuración de los colectores del reenviador, así como el contenido del archivo de autenticación (_auth.conf) que utiliza el reenviador para autenticarse con la instancia de Google SecOps.

Campos de configuración del reenviador

En la siguiente tabla se enumeran los ajustes de configuración de reenviador que puede especificar mediante Create Forwarder y Update Forwarder. Si no especifica un valor para un ajuste al usar Create Forwarder, se aplicará el valor predeterminado del ajuste (que se muestra a continuación).

Los siguientes campos se pueden proporcionar en el objeto config del cuerpo de la solicitud.

Referencia de la API Collector

En esta sección se describen los endpoints para trabajar con colectores.

Cuando cree y actualice colectores, tenga en cuenta que cada configuración de colector puede especificar ajustes de ingestión para uno, pero no más de uno, de los siguientes elementos:

• Datos de archivo de registro
• Temas de Kafka
• Datos de paquetes (pcap)
• Datos de Splunk
• Datos de syslog

Para consultar los endpoints para trabajar con reenviadores, consulta la referencia de la API Forwarder.

Crear recopilador

Crea un nuevo recopilador en la cuenta de Google SecOps. Los valores de configuración de los collectors deben especificarse mediante Create Collector después de usar Create Forwarder.

En el caso de algunos ajustes, los valores de configuración que faltan o que son cero en el cuerpo de la solicitud se definen como valores predeterminados. Para obtener más información sobre los campos y valores de configuración de los colectores, consulta el artículo Campos de configuración de los colectores.

Solicitud

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

Cuerpo de la solicitud

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

Parámetros del cuerpo

Ejemplo de solicitud

En este ejemplo se muestran los pares clave-valor necesarios en una solicitud Create Collector. En el caso de los campos que no se proporcionen, se aplicarán los valores predeterminados durante la creación del recolector.

En este ejemplo, el tipo de recolector es file, por lo que la configuración del recolector incluye file_settings para indicar el tipo de recolector y sus ajustes. Si el tipo de recopilador es syslog, la configuración del recopilador incluye syslog_settings. Para obtener más información, consulta los campos de configuración del recolector.

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",
    }
  }
}

Respuesta

Si la solicitud se realiza correctamente, la respuesta devuelve un código de estado HTTP 200 (OK).

La respuesta muestra los valores de configuración aplicados durante la creación del colector. Se aplican valores de configuración predeterminados a determinados ajustes durante la creación de recursos si faltan esos campos o tienen el valor cero en el cuerpo de la solicitud. Para obtener más información, consulta Campos de configuración del recopilador.

Campos de respuesta

Además de los campos especificados en la solicitud y los campos a los que se aplican valores predeterminados, la respuesta incluye los siguientes campos:

Ejemplo de respuesta

Este es un ejemplo de la respuesta devuelta a la solicitud de ejemplo anterior.

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

Get Collector

Devuelve un recopilador.

Solicitud

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

Cuerpo de la solicitud

No incluyas el cuerpo de la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Mostrar recopiladores

Muestra los recopiladores del reenviador especificado.

Solicitud

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

Ejemplo de solicitud

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

Respuesta

Devuelve varios recopiladores.

Ejemplo de respuesta

{
  "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"
      }
    }
  ]
}

Actualizar recopilador

Cuando actualizas un recolector con la API, puedes sobrescribir toda la configuración del recolector o solo campos específicos de la configuración del recolector. Por lo general, es mejor sobrescribir campos específicos para evitar que se sobrescriban todos los datos por error. Para sobrescribir campos específicos, proporciona una FieldMask en tu solicitud de actualización.

Para proporcionar un FieldMask que actualice el nombre visible de un recopilador, proporcione el parámetro de consulta de URL updateMask en la solicitud PATCH. Por ejemplo:

?updateMask=displayName

El cuerpo de la solicitud solo debe contener los campos que quieras actualizar (en sus ubicaciones exactas).

Solicitud

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

Cuerpo de la solicitud

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

Parámetros del cuerpo

Ejemplo de solicitud

Este es un ejemplo de una solicitud Update Collector en la que se especifican nuevos valores para displayName, logType, assetNamespace y 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",
      }
    }
  }

Ejemplo de respuesta

Este es un ejemplo de la respuesta devuelta a la solicitud de ejemplo anterior.

{
  "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"
}

Eliminar recopilador

Elimina un recopilador.

Solicitud

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

Cuerpo de la solicitud

No incluyas el cuerpo de la solicitud.

Ejemplo de solicitud

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

Ejemplo de respuesta

Si la operación se realiza correctamente, Delete Collector devuelve una respuesta vacía con el código de estado HTTP 200 (OK).

{}

Campos de configuración del recopilador

Los siguientes campos se pueden proporcionar en el objeto config del cuerpo de la solicitud.