API Forwarder Management

Pode usar a API Google Security Operations Forwarder Management para fazer o seguinte de forma programática:

• Crie e faça a gestão de encaminhadores.
• Crie e faça a gestão de coletores.
• Obtenha o conteúdo dos ficheiros de configuração (.conf) e autenticação (_auth.conf) de um encaminhador do Google SecOps.

Os encaminhadores são compostos por um ou mais coletores. A configuração de cada coletor especifica o respetivo mecanismo de carregamento (por exemplo, ficheiro, Kafka, PCAP, Splunk ou Syslog) e tipo de registo.

Partindo do princípio de que os requisitos de hardware são cumpridos, pode usar muitos coletores no mesmo encaminhador para carregar dados de vários mecanismos e tipos de registos. Por exemplo, pode instalar um encaminhador com dois coletores syslog a ouvir dados de PAN_FIREWALL e CISCO_ASA_FIREWALL em portas separadas, respetivamente.

A API permite-lhe criar encaminhadores e os respetivos coletores na sua instância do Google SecOps. Depois de criar um encaminhador, pode usar o ponto final Generate Forwarder Files para obter o conteúdo dos ficheiros (como payload JSON) para os ficheiros de configuração (.conf) e autenticação (_auth.conf) de um encaminhador. Em seguida, estes conteúdos podem ser escritos nos respetivos ficheiros .conf para implementação com o serviço Google SecOps Forwarder num sistema Windows ou Linux.

Para ver exemplos de Python que usam a API Forwarder Management, consulte o repositório do GitHub.

Crie um encaminhador e os respetivos coletores

Tem de criar um encaminhador antes de poder criar qualquer um dos respetivos coletores.

Para criar um encaminhador e os respetivos coletores:

1. Crie um encaminhador.
2. Crie um coletor para o encaminhador.
3. (Opcional) Repita o passo 2 para adicionar mais coletores.

Autentique com a API Chronicle

Este documento descreve como a API Chronicle usa o protocolo OAuth 2.0 para autenticação e autorização. A sua aplicação pode processar esta situação através de um dos seguintes métodos:

• Use a biblioteca cliente da API Chronicle para a sua linguagem de programação.

• Interagir diretamente com o sistema OAuth 2.0 através de HTTP.

Consulte a documentação de referência da biblioteca de autenticação Google em Python.

As bibliotecas de autenticação Google são um subconjunto das bibliotecas cliente da API Chronicle. Consulte outras implementações de idiomas.

Obtenha credenciais de autenticação da API

O representante do Google Security Operations vai fornecer-lhe uma credencial de conta de serviço do Google Developer para permitir que o cliente da API comunique com a API.

Também tem de fornecer o âmbito de autorização quando inicializa o cliente da API. O OAuth 2.0 usa um âmbito para limitar o acesso de uma aplicação a uma conta. Quando uma aplicação pede um âmbito, o token de acesso emitido para a aplicação está limitado ao âmbito concedido.

Use o seguinte âmbito para inicializar o cliente da API Chronicle:

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

Exemplo de Python

O exemplo de Python seguinte demonstra como usar as credenciais do OAuth2 e o cliente HTTP com 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 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/

Limites de consultas da API Chronicle

A API Chronicle aplica limites ao volume de pedidos que podem ser feitos por qualquer cliente à plataforma Google SecOps. Se atingir ou exceder o limite de consultas, o servidor da API Chronicle devolve HTTP 429 (RESOURCE_EXHAUSTED) ao autor da chamada. Ao desenvolver aplicações para a API Chronicle, a Google recomenda que aplique limites de taxa no seu sistema para evitar o esgotamento de recursos. Estes limites aplicam-se a todas as APIs Chronicle, incluindo as APIs de pesquisa, gestão de encaminhadores e ferramentas.

Consulte a lista detalhada das quotas da API Chronicle.

O seguinte limite para a API Chronicle Forwarder Management está a ser aplicado e é medido em consultas por segundo (CPS):

Referência da API Forwarder

Esta secção descreve os pontos finais para criar e gerir encaminhadores. Para ver pontos finais para criar e gerir coletores, consulte a referência da API Collector.

Crie um encaminhador

Cria um novo encaminhador na instância do Google SecOps. O novo encaminhador vai incluir todos os valores de configuração do encaminhador fornecidos no corpo do pedido. Os valores de configuração dos coletores têm de ser especificados através da opção Criar coletor depois de usar a opção Criar encaminhador.

Para determinadas definições, os valores de configuração em falta ou com valor zero no corpo do pedido são definidos como valores predefinidos. Para ver detalhes sobre os campos e os valores do encaminhador, consulte o artigo Campos de configuração do encaminhador.

Pedido

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

Corpo do pedido

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

Parâmetros corporais

Exemplo de pedido

Este exemplo mostra os pares de chave:valor necessários num pedido Create Forwarder. Se um campo não for especificado no pedido e tiver um valor predefinido, o valor predefinido é aplicado durante a criação do encaminhador. Para ver detalhes sobre os valores predefinidos, consulte os campos de configuração do encaminhador.

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

Resposta

Se o pedido for bem-sucedido, a resposta devolve um código de estado HTTP de 200 (OK).

A resposta mostra os valores de configuração aplicados durante a criação do encaminhador. Os valores de configuração predefinidos são aplicados a determinadas definições durante a criação de recursos se esses campos estiverem em falta ou tiverem o valor zero no corpo do pedido. Para ver detalhes, consulte os campos de configuração do encaminhador.

Campos de resposta

Além dos campos especificados no pedido e dos campos aos quais são aplicados valores predefinidos, a resposta inclui os seguintes campos gerados e apenas de saída.

Exemplo de resposta

Este é um exemplo da resposta devolvida para o exemplo de pedido acima.

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

Obtenha o encaminhador

Devolve um encaminhador.

Pedido

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

Corpo do pedido

Não inclua um corpo do pedido.

Exemplo de pedido

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

Exemplo de resposta

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

Liste encaminhadores

Lista todos os encaminhadores de uma instância do Google SecOps.

Pedido

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

Exemplo de pedido

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

Resposta

Devolve uma lista de encaminhadores.

Exemplo de resposta

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

Atualize o encaminhador

Pode atualizar um encaminhador através do parâmetro de consulta de URL updateMask para especificar os campos a atualizar.

Por exemplo, para atualizar o nome a apresentar, usaria o parâmetro de consulta updateMask da seguinte forma no pedido de patch:

?updateMask=displayName

O corpo do pedido só deve conter os campos que quer atualizar (nas respetivas localizações exatas).

Pedido

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

Corpo do pedido

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

Parâmetros corporais

Exemplo de pedido

Este é um exemplo de um pedido de encaminhamento de atualização em que o pedido especifica novos valores para displayName e adiciona uma etiqueta de metadados.

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

Exemplo de resposta

Este é um exemplo da resposta devolvida para o exemplo de pedido acima.

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

Elimine o encaminhador

Elimina um encaminhador.

Pedido

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

Corpo do pedido

Não inclua um corpo do pedido.

Exemplo de pedido

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

Exemplo de resposta

Se a operação for bem-sucedida, Delete Forwarder devolve uma resposta vazia com um código de estado HTTP 200 (OK).

{}

Gere ficheiros de encaminhamento

Gera e devolve o conteúdo dos ficheiros de configuração (.conf) e autenticação (_auth.conf) do encaminhador.

Pedido

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

Corpo do pedido

Não inclua um corpo do pedido.

Exemplo de pedido

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

Exemplo de resposta

Se a operação for bem-sucedida, devolve um código de estado HTTP 200 (OK). Também devolve o conteúdo de um ficheiro de configuração do encaminhador, incluindo os dados de configuração dos coletores do encaminhador, bem como o conteúdo do ficheiro de autenticação (_auth.conf) usado pelo encaminhador para autenticar com a instância do Google SecOps.

Campos de configuração do encaminhador

A tabela seguinte apresenta as definições de configuração do encaminhador que pode especificar através das funções Create Forwarder e Update Forwarder. Se não especificar um valor para uma definição quando usa o criador de encaminhadores, é aplicado o valor predefinido da definição (mostrado abaixo).

Os seguintes campos podem ser fornecidos no objeto config do corpo do pedido.

Referência da API Collector

Esta secção descreve os pontos finais para trabalhar com coletores.

Quando criar e atualizar coletores, tenha em atenção que cada configuração de coletor pode especificar definições de carregamento para um, mas não mais do que um, dos seguintes:

• Dados do ficheiro de registo
• Tópicos do Kafka
• Dados de pacotes (pcap)
• Dados do Splunk
• Dados Syslog

Para ver os pontos finais para trabalhar com encaminhadores, consulte a referência da API Forwarder.

Crie um coletor

Cria um novo coletor na conta do Google SecOps. Os valores de configuração dos coletores têm de ser especificados através de Create Collector após usar Create Forwarder.

Para determinadas definições, os valores de configuração que estão em falta ou têm o valor zero no corpo do pedido são definidos como valores predefinidos. Para ver detalhes sobre os campos e os valores de configuração do coletor, consulte o artigo Campos de configuração do coletor.

Pedido

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

Corpo do pedido

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

Parâmetros corporais

Exemplo de pedido

Este exemplo mostra os pares de chave:valor necessários num pedido Create Collector. Para todos os campos que não forem fornecidos, os valores predefinidos são aplicados durante a criação do coletor.

Neste exemplo, o tipo de coletor é file, pelo que a configuração do coletor inclui file_settings para indicar o tipo de coletor e as respetivas definições. Se o tipo de coletor for syslog, a configuração do coletor inclui syslog_settings. Para mais informações, consulte os campos de configuração do coletor.

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

Resposta

Se o pedido for bem-sucedido, a resposta devolve um código de estado HTTP de 200 (OK).

A resposta mostra os valores de configuração aplicados durante a criação do coletor. Os valores de configuração predefinidos são aplicados a determinadas definições durante a criação de recursos se esses campos estiverem em falta ou tiverem o valor zero no corpo do pedido. Para ver detalhes, consulte os Campos de configuração do coletor.

Campos de resposta

Além dos campos especificados no pedido e dos campos aos quais são aplicados valores predefinidos, a resposta inclui os seguintes campos:

Exemplo de resposta

Este é um exemplo da resposta devolvida para o exemplo de pedido acima.

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

Obtenha o coletor

Devolve um coletor.

Pedido

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

Corpo do pedido

Não inclua um corpo do pedido.

Exemplo de pedido

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

Exemplo de resposta

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

Listar coletores

Lista os coletores existentes para o encaminhador especificado.

Pedido

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

Exemplo de pedido

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

Resposta

Devolve vários coletores.

Exemplo de resposta

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

Atualize o coletor

Quando atualiza um coletor com a API, pode optar por substituir toda a configuração do coletor ou substituir apenas campos específicos da configuração do coletor. Normalmente, é melhor substituir campos específicos para evitar substituir acidentalmente todos os seus dados. Para substituir campos específicos, forneça um FieldMask ao seu pedido de atualização.

Para fornecer um FieldMask para atualizar o nome a apresentar de um coletor, forneça o parâmetro de consulta do URL updateMask no pedido de patch. Por exemplo:

?updateMask=displayName

O corpo do pedido só deve conter os campos que quer atualizar (nas respetivas localizações exatas).

Pedido

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

Corpo do pedido

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

Parâmetros corporais

Exemplo de pedido

Este é um exemplo de um pedido de atualização do coletor em que o pedido especifica novos valores para 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",
      }
    }
  }

Exemplo de resposta

Este é um exemplo da resposta devolvida para o exemplo de pedido acima.

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

Elimine o coletor

Elimina um coletor.

Pedido

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

Corpo do pedido

Não inclua um corpo do pedido.

Exemplo de pedido

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

Exemplo de resposta

Se a operação for bem-sucedida, o eliminador devolve uma resposta vazia com um código de estado HTTP 200 (OK).

{}

Campos de configuração do coletor

Os seguintes campos podem ser fornecidos no objeto config do corpo do pedido.