API Forwarder Management

Use a API Google Security Operations Forwarder Management para fazer o seguinte de maneira programática:

  • Crie e gerencie encaminhadores.
  • Criar e gerenciar coletores.
  • Receba o conteúdo dos arquivos de configuração (.conf) e autenticação (_auth.conf) de um encaminhador das Operações de Segurança do Google.

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

Supondo que os requisitos de hardware sejam atendidos, é possível usar muitos coletores no mesmo encaminhador para ingerir dados de diversos mecanismos e tipos de registro. Por exemplo, você pode instalar um encaminhador com dois coletores syslog detectando dados PAN_FIREWALL e CISCO_ASA_FIREWALL em portas separadas, respectivamente.

A API permite que você crie encaminhadores e coletores na sua instância das Operações de Segurança do Google. Depois que um encaminhador é criado, é possível usar o endpoint "Gerar arquivos do encaminhador" para acessar o conteúdo (como payload JSON) dos arquivos de configuração (.conf) e de autenticação (_auth.conf) de um encaminhador. Esse conteúdo pode ser gravado nos respectivos arquivos .conf para implantação com o serviço encaminhador de operações de segurança do Google em um sistema Windows ou Linux.

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

Criar um encaminhador e os coletores dele

É preciso criar um encaminhador antes de criar qualquer um dos coletores.

Para criar um encaminhador e os coletores dele:

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

Como autenticar com a API Google Security Operations[:#authenticate]

Esta API de Operações de Segurança do Google usa o protocolo OAuth 2.0 para autenticação e autorização. Seu aplicativo pode concluir essas tarefas usando uma das seguintes implementações:

  • Usar a biblioteca de cliente de APIs do Google na linguagem do seu computador.

  • Interface direta com o sistema OAuth 2.0 usando HTTP.

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

As bibliotecas de autenticação do Google são um subconjunto das bibliotecas de cliente das APIs do Google. Consulte implementações em outras linguagens.

Como conseguir credenciais de autenticação da API

Seu representante de operações de segurança do Google fornecerá a você uma credencial de conta de serviço de desenvolvedor do Google para permitir que o cliente da API se comunique com a API.

Também é necessário fornecer o escopo do Auth ao inicializar o cliente de API. O OAuth 2.0 usa um escopo para limitar o acesso de um aplicativo a uma conta. Quando um aplicativo solicita um escopo, o token de acesso emitido para o aplicativo é limitado ao escopo concedido.

Use o escopo a seguir para inicializar seu cliente da API do Google:

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

Exemplo do Python

O exemplo em Python a seguir demonstra como usar as credenciais OAuth2 e o cliente HTTP usando 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>

Limites de consulta da API Chronicle

A API Chronicle impõe limites ao volume de solicitações que podem ser feitas por qualquer cliente na plataforma de operações de segurança do Google. Se você atingir ou exceder o limite de consultas, o servidor da API Chronicle retornará HTTP 429 (RESOURCE_EXHAUSTED) ao autor da chamada. Ao desenvolver aplicativos para a API Chronicle, o Google recomenda que você aplique limites de taxa no seu sistema para evitar o esgotamento de recursos. Esses limites se aplicam a todas as APIs Chronicle, incluindo as APIs Search, Forwarder Management e Tooling.

O limite a seguir para a API Chronicle Forwarder Management está sendo aplicado e é medido em consultas por segundo (QPS):

API Chronicle Endpoint da API Limite
Gerenciamento de encaminhamento Criar encaminhador 1 QPS
Avançar 1 QPS
Encaminhadores de lista 1 QPS
Atualizar encaminhador 1 QPS
Excluir encaminhador 1 QPS
Gerenciamento de coletor Criar coletor 1 QPS
Acessar coletor 1 QPS
Listar coletores 1 QPS
Atualizar coletor 1 QPS
Excluir coletor 1 QPS

Referência da API Forwarder

Nesta seção, descrevemos os endpoints para criar e gerenciar encaminhadores. No caso de endpoints para criar e gerenciar coletores, consulte a Referência da API Collector.

Criar encaminhador

Cria um novo encaminhador na instância de SecOps do Google. O novo encaminhador vai incluir os valores de configuração de forwarder fornecidos no corpo da solicitação. Os valores de configuração para coletores precisam ser especificados usando a opção "Criar coletor" depois de usar a opção "Criar encaminhador".

Para determinadas configurações, os valores de configuração ausentes ou com valor zero no corpo da solicitação são definidos como valores padrão. Saiba mais sobre os campos e valores do encaminhador em Campos de configuração do encaminhador.

Solicitação

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

Corpo da solicitação
{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}
Parâmetros do corpo
Campo Tipo Obrigatório Descrição
display_name string Obrigatório O nome do encaminhador. Esse nome é exibido na interface do Google SecOps.
config objeto Opcional As definições de configuração deste encaminhador. Consulte Campos de configuração do encaminhador.
Exemplo de solicitação

Este exemplo mostra os pares de chave-valor obrigatórios em uma solicitação "Criar encaminhador". Se um campo não for especificado na solicitação e tiver um valor padrão, esse valor será aplicado durante a criação do encaminhador. Saiba mais sobre os valores padrão em Campos de configuração do encaminhador.

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

Resposta

Se a solicitação for bem-sucedida, a resposta retornará um código de status HTTP 200 (OK).

A resposta mostra os valores de configuração aplicados durante a criação do encaminhador. Os valores de configuração padrão serão aplicados a determinadas configurações durante a criação do recurso se esses campos estiverem ausentes ou com valor zero no corpo da solicitação. Saiba mais em Campos de configuração do encaminhador.

Campos de resposta

Além dos campos especificados na solicitação e dos campos a que são aplicados valores padrão, a resposta inclui os seguintes campos gerados e somente saída.

Campo Tipo Descrição
nome string O ID do recurso do encaminhador. O formato é "forwarders/forwarderID". Por exemplo:

forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
state enum

Especifica o estado atual do encaminhador. Os valores válidos são:

  • ACTIVE: o encaminhador tem permissão para fazer o upload de dados.
  • SUSPENDED: o encaminhador não tem permissão para fazer o upload de dados.

O valor padrão é ACTIVE.
Exemplo de resposta

Este é um exemplo da resposta retornada para o exemplo de solicitação 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"
}

Avançar

Retorna um encaminhador.

Solicitação

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

Corpo da solicitação

Não inclua um corpo de solicitação.

Exemplo de solicitação
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"
}

Encaminhadores de lista

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

Solicitação

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

Exemplo de solicitação

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

Resposta

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

Atualizar encaminhador

É possível atualizar um encaminhador usando o parâmetro de consulta de URL updateMask para especificar os campos a serem atualizados.

Por exemplo, para atualizar o nome de exibição, use o parâmetro de consulta updateMask da seguinte maneira na solicitação de patch:

?updateMask=displayName

O corpo da solicitação precisa conter apenas os campos que você quer atualizar (na localização exata deles).

Solicitação

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}?updateMask=<field_1,field_2>
Corpo da solicitação
{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  },
}
Parâmetros do corpo
Campo Tipo Obrigatório Descrição
display_name string Obrigatório O nome do encaminhador. Esse nome é exibido na interface do Google SecOps.
config objeto Opcional As definições de configuração deste encaminhador. Consulte Campos de configuração do encaminhador.
Exemplo de solicitação

Este é um exemplo de solicitação de encaminhador de atualização em que a solicitação especifica novos valores para displayName e adiciona um rótulo 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 retornada para o exemplo de solicitação acima.

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

Excluir encaminhador

Exclui um encaminhador.

Solicitação

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}
Corpo da solicitação

Não inclua um corpo de solicitação.

Exemplo de solicitação
DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56
Exemplo de resposta

Se a operação for bem-sucedida, o encaminhamento de exclusão vai retornar uma resposta vazia com um código de status HTTP 200 (OK).

{}

Gerar arquivos encaminhadores

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

Solicitação

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}:generateForwarderFiles
Corpo da solicitação

Não inclua um corpo de solicitação.

Exemplo de solicitação
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56:generateForwarderFiles
Exemplo de resposta

Se a operação tiver êxito, ela retornará um código de status HTTP 200 (OK). Ela também retorna o conteúdo de um arquivo de configuração do encaminhador, incluindo os dados de configuração dos coletores do encaminhador, bem como o conteúdo do arquivo 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 a seguir lista as definições de configuração do encaminhador que podem ser especificadas usando "Criar encaminhador e atualizador de atualizações". Se você não especificar um valor para uma configuração ao usar "Criar encaminhador", o valor padrão da configuração (mostrado abaixo) será aplicado.

Os campos a seguir podem ser fornecidos no objeto config do corpo da solicitação.

Campo Tipo Obrigatório Descrição
upload_compression bool Opcional Se for true, os lotes de dados serão compactados antes do upload.

O padrão é false.
metadata.asset_namespace string Opcional O namespace para identificar registros desse encaminhador.

Observação:essa é uma configuração global que se aplica aos coletores do encaminhador e do encaminhador, a menos que seja substituída no nível do coletor. Para mais informações, acesse Configurar namespaces.
metadata.labels lista Opcional Uma lista de pares de chave-valor arbitrários que podem ser especificados na configuração do encaminhador.

Observação:essa é uma configuração global que se aplica aos coletores do encaminhador e do encaminhador, a menos que seja substituída no nível do coletor.
metadata.labels.key string Opcional A chave para um campo na lista de rótulos de metadados.
metadata.labels.value string Opcional Valor de um campo na lista de rótulos de metadados.
regex_filters.description string Opcional Descreve o que está sendo filtrado e o motivo.
regex_filters.regexp string Opcional A expressão regular usada para corresponder a cada linha recebida.
regex_filters.behavior enum Opcional

Especifica o estado da funcionalidade do servidor. Estes são os valores válidos:

  • ALLOW: este estado permite que a linha filtrada seja enviada.
  • BLOQUEAR: impede o upload da linha filtrada.
server_settings objeto Opcional Configurações que configuram o servidor HTTP integrado do encaminhador, que podem ser usados para configurar opções de balanceamento de carga e alta disponibilidade para coleta de syslog no Linux.
server_settings.state enum Opcional

Especifica o estado da funcionalidade do servidor. Estes são os valores válidos:

  • ACTIVE: nesse estado, as configurações do servidor são aplicadas conforme especificado.
  • SUSPENDED Neste estado, as configurações do servidor não são aplicadas.
server_settings.graceful_timeout número inteiro Opcional Após quantos segundos o encaminhador retorna uma verificação de prontidão/integridade inválida e ainda aceita novas conexões. Esse também é o tempo de espera entre o recebimento de um sinal para interromper e o início do desligamento do próprio servidor. Isso dá ao balanceador de carga tempo para remover o encaminhador do pool.

O valor padrão é 15.
server_settings.drain_timeout número inteiro Opcional O número de segundos após os quais o encaminhador aguarda até que as conexões ativas se fechem por conta própria antes de serem fechadas pelo servidor.

O valor padrão é 10.
server_settings.http_settings.port número inteiro Opcional O número da porta em que o servidor HTTP detecta verificações de integridade do balanceador de carga. Precisa estar entre 1024 e 65535.

O padrão é 8080.
server_settings.http_settings.host string Opcional O endereço IP, ou nome do host, que pode ser resolvido em endereços IP, que o servidor precisa detectar.

O valor padrão é 0.0.0.0 (o sistema local).
server_settings.http_settings.read_timeout número inteiro Opcional O número máximo de segundos permitidos para ler solicitações inteiras, o que inclui o cabeçalho e o corpo.

O valor padrão é 3.
server_settings.http_settings.read_header_timeout número inteiro Opcional O número máximo de segundos permitidos para ler cabeçalhos de solicitação.

O valor padrão é 3.
server_settings.http_settings.write_timeout número inteiro Opcional O número máximo de segundos permitidos para enviar uma resposta.

O valor padrão é 3.
server_settings.http_settings.idle_timeout número inteiro Opcional O número máximo de segundos de espera pela próxima solicitação quando as conexões inativas estão ativadas.

O padrão é 3.
server_settings.http_settings.route_settings.available_status_code número inteiro Opcional O código de status retornado quando uma verificação de atividade é recebida e o encaminhador está disponível.

O padrão é 204.
server_settings.http_settings.route_settings.ready_status_code número inteiro Opcional Código de status retornado quando o encaminhador está pronto para aceitar o tráfego.

O padrão é 204.
server_settings.http_settings.route_settings.unready_status_code número inteiro Opcional O código de status retornado quando o encaminhador não está pronto para aceitar o tráfego.

O padrão é 503.

Referência da API Collector

Nesta seção, descrevemos os endpoints para trabalhar com coletores.

Ao criar e atualizar coletores, observe que cada configuração de coletor pode especificar configurações de processamento para um dos seguintes itens, mas não mais de um:

  • Dados do arquivo de registro
  • Tópicos do Kafka
  • Dados de pacote (pcap)
  • Dados do Splunk
  • Dados syslog

Para endpoints para trabalhar com encaminhadores, consulte a Referência da API Forwarder.

Criar coletor

Cria um novo coletor na conta do Google SecOps. Os valores de configuração para coletores precisam ser especificados usando a opção "Criar coletor" depois de usar a opção "Criar encaminhador".

Para determinadas configurações, os valores de configuração que estão faltando ou com valor zero no corpo da solicitação são definidos como valores padrão. Para detalhes sobre os campos e valores de configuração do coletor, consulte Campos de configuração do coletor.

Solicitação

POST https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Corpo da solicitação
{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  }
  "state": enum
}
Parâmetros do corpo
Campo Tipo Obrigatório Descrição
display_name string Obrigatório O nome do coletor. Esse nome é exibido na interface do Google SecOps.
config objeto Obrigatório As definições de configuração deste coletor. Consulte Campos de configuração do coletor.
state enum Opcional

Especifica o estado atual do coletor. Os valores válidos são:

  • ACTIVE: o coletor tem permissão para aceitar dados.
  • SUSPENDED: o coletor não tem permissão para aceitar dados.
Exemplo de solicitação

Este exemplo mostra os pares de chave-valor necessários em uma solicitação "Criar coletor". Para os campos que não forem fornecidos, os valores padrão serão aplicados durante a criação do coletor.

Neste exemplo, o tipo de coletor é file. Portanto, a configuração do coletor inclui file_settings para indicar o tipo de coletor e as configurações dele. Se o tipo de coletor for syslog, a configuração do coletor incluirá syslog_settings. Para mais informações, consulte 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 a solicitação for bem-sucedida, a resposta retornará um código de status HTTP 200 (OK).

A resposta mostra os valores de configuração aplicados durante a criação do coletor. Os valores de configuração padrão serão aplicados a determinadas configurações durante a criação do recurso se esses campos estiverem ausentes ou com valor zero no corpo da solicitação. Para mais detalhes, consulte Campos de configuração do coletor.

Campos de resposta

Além dos campos especificados na solicitação e dos campos a que são aplicados valores padrão, a resposta inclui os seguintes campos:

Campo Tipo Descrição
nome string O ID do recurso do coletor. O formato é "forwarders/{forwarderID}/collectors/{collectorID}". Por exemplo:

forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Exemplo de resposta

Este é um exemplo da resposta retornada para o exemplo de solicitação acima.

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

Acessar coletor

Retorna um coletor.

Solicitação

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Corpo da solicitação

Não inclua um corpo de solicitação.

Exemplo de solicitação
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 atuais do encaminhador especificado.

Solicitação

GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Exemplo de solicitação
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors

Resposta

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

Atualizar coletor

Ao atualizar um coletor com a API, é possível substituir toda a configuração dele ou apenas campos específicos da configuração dele. Geralmente, é melhor substituir campos específicos para evitar a substituição acidental de todos os seus dados. Para substituir campos específicos, forneça um FieldMask à solicitação de atualização.

Para fornecer um FieldMask para atualizar o nome de exibição de um coletor, forneça o parâmetro de consulta do URL updateMask na solicitação de patch. Exemplo:

?updateMask=displayName

O corpo da solicitação precisa conter apenas os campos que você quer atualizar (na localização exata deles).

Solicitação

PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}?updateMask=<field_1,field_2>
Corpo da solicitação
{
  "display_name": string,
  "config": {
    object (CollectorConfig)
  },
}
Parâmetros do corpo
Campo Tipo Obrigatório Descrição
displayName string Obrigatório O nome do coletor. Esse nome é exibido na interface do Google SecOps.
config objeto Opcional As definições de configuração deste encaminhador. Consulte Campos de configuração do coletor.
Exemplo de solicitação

Este é um exemplo de uma solicitação do Coletor de atualizações em que ela especifica novos valores para displayName, logType, assetNamespace e protocolo.

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 retornada para o exemplo de solicitação 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"
}

Excluir coletor

Exclui um coletor.

Solicitação

DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Corpo da solicitação

Não inclua um corpo de solicitação.

Exemplo de solicitação
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 Delete Collector retornará uma resposta vazia com um código de status HTTP 200 (OK).

{}

Campos de configuração do coletor

Os campos a seguir podem ser fornecidos no objeto config do corpo da solicitação.

Campo Tipo Obrigatório Descrição
log_type string Obrigatório Um tipo de registro com suporte (que pode ser ingerido pelo Google SecOps). Para conferir uma lista de tipos de registro compatíveis com um analisador do Google SecOps, consulte a coluna "Rótulo de ingestão" na página analisadores padrão compatíveis. Para conferir uma lista completa dos tipos de registro compatíveis, use o endpoint logtypes.
metadata.asset_namespace objeto Opcional O namespace para identificar registros desse coletor.

Observação:essa é uma configuração global que se aplica aos coletores do encaminhador e do encaminhador, a menos que seja substituída no nível do coletor. Para mais informações, acesse Configurar namespaces.
metadata.labels lista Opcional Uma lista de pares de chave-valor arbitrários que podem ser especificados na configuração do coletor.

Observação:essa é uma configuração global que se aplica aos coletores do encaminhador e do encaminhador, a menos que seja substituída no nível do coletor.
metadata.labels.key string Opcional A chave para um campo na lista de rótulos de metadados.
metadata.labels.value string Opcional Valor de um campo na lista de rótulos de metadados.
regex_filters.description string Opcional Descreve o que está sendo filtrado e o motivo.
regex_filters.regexp string Opcional A expressão regular usada para corresponder a cada linha recebida.
regex_filters.behavior enum Opcional

Especifica o estado da funcionalidade do servidor. Estes são os valores válidos:

  • ALLOW: este estado permite que a linha filtrada seja enviada.
  • BLOQUEAR: impede o upload da linha filtrada.
disk_buffer.state enum Opcional

Especifica o estado de armazenamento em buffer do disco para o coletor. Os valores válidos são:

  • ACTIVE: o armazenamento em buffer está ativado.
  • SUSPENDED: o armazenamento em buffer está desativado.
disk_buffer.directory_path string Opcional O caminho do diretório para os arquivos gravados.
disk_buffer.max_file_buffer_bytes número inteiro Opcional O tamanho máximo do arquivo armazenado em buffer.
max_seconds_per_batch número inteiro Opcional O número de segundos entre os lotes.

O padrão é 10.
max_bytes_per_batch número inteiro Opcional O número de bytes na fila antes do upload em lote do encaminhador.

O padrão é 1048576.
<collector_type>_settings.<campos> Obrigatório Especifica um tipo de coletor e as configurações dele. Cada coletor precisa especificar um tipo de coletor e os campos dele. Por exemplo, para usar o tipo de coletor file, é preciso adicionar o campo file_settings.file_path à configuração e receber um valor. Por exemplo:

"file_settings": {
  "file_path": "/opt/chronicle/edr/output/sample.txt",
}

Os tipos de coletores e os campos deles são listados nas linhas subsequentes dessa tabela. Os tipos de coletor disponíveis são:
  • file
  • kafka
  • pcap
  • splunk
  • syslog
file_settings.file_path string Opcional O caminho do arquivo a ser monitorado.
kafka_settings.authentication.username string Opcional O nome de usuário de uma identidade usada para autenticação.
kafka_settings.authentication.password string Opcional A senha da conta identificada pelo nome de usuário.
kafka_settings.topic string Opcional O tópico do Kafka em que os dados serão ingeridos. Para mais detalhes, consulte Coletar dados dos tópicos do Kafka.
kafka_settings.group_id string Opcional Um ID do grupo.
kafka_settings.timeout número inteiro Opcional O número máximo de segundos que uma discagem aguardará até que uma conexão seja concluída.

O padrão é 60.
kafka_settings.brokers string Opcional Uma string repetida listando os agentes do Kafka. Por exemplo:

"broker-1:9092", "broker-2:9093"

Observação:todos os valores são substituídos durante uma operação de atualização. Portanto, para atualizar uma lista de agentes para adicionar um novo, especifique todos os corretores existentes e o novo.
kafka_settings.tls_settings.certificate string Opcional O caminho e o nome de arquivo do certificado. Por exemplo:

/path/to/cert.pem
kafka_settings.tls_settings.certificate_key string Opcional O caminho e o nome de arquivo da chave de certificado. Por exemplo:

/path/to/cert.key
kafka_settings.tls_settings.minimum_tls_version string Opcional A versão mínima do TLS.
kafka_settings.tls_settings.insecure_skip_verify bool Opcional Se true, ativa a verificação da certificação SSL.

O padrão é false.
pcap_settings.network_interface string Opcional A interface para detectar dados PCAP.
pcap_settings.bpf string Opcional O Filtro de Pacote de Berkeley (BPF) para pcap.
splunk_settings.authentication.username string Opcional O nome de usuário de uma identidade usada para autenticação.
splunk_settings.authentication.password string Opcional A senha da conta identificada pelo nome de usuário.
splunk_settings.host string Opcional O host ou o endereço IP da API REST do Splunk.
splunk_settings.port número inteiro Opcional A porta da API REST do Splunk.
splunk_settings.minimum_window_size número inteiro Opcional O intervalo de tempo mínimo em segundos para uma determinada pesquisa do Splunk. Para mais detalhes, consulte Coletar dados do Splunk.

O padrão é 10.
splunk_settings.maximum_window_size número inteiro Opcional O intervalo de tempo máximo em segundos para uma determinada pesquisa do Splunk. Para mais detalhes, consulte Coletar dados do Splunk.

O padrão é 30.
splunk_settings.query_string string Opcional Consulta usada para filtrar registros no Splunk.

Exemplo: search index=* sourcetype=dns
splunk_settings.query_mode string Opcional O modo de consulta para o Splunk.

Exemplo: realtime
splunk_settings.cert_ignored bool Opcional Se for true, o certificado será ignorado.
syslog_settings.protocol enum Opcional

Especifica o protocolo que o coletor usará para detectar dados syslog. Os valores válidos são:

  • TCP
  • UDP
syslog_settings.address string Opcional O endereço IP de destino ou o nome do host em que o coletor reside e detecta dados syslog.
syslog_settings.port número inteiro Opcional A porta de destino em que o coletor reside e detecta dados syslog.
syslog_settings.buffer_size número inteiro Opcional O tamanho em bytes do buffer do soquete TCP.

O padrão para TCP é 65536.
O padrão para UDP é 8192.
syslog_settings.connecton_timeout número inteiro Opcional O número de segundos de inatividade após os quais a conexão TCP é interrompida.

O padrão é 60.
syslog_settings.tls_settings.certificate string Opcional O caminho e o nome de arquivo do certificado. Por exemplo:

/path/to/cert.pem
syslog_settings.tls_settings.certificate_key string Opcional O caminho e o nome de arquivo da chave de certificado. Por exemplo:

/path/to/cert.key
syslog_settings.tls_settings.minimum_tls_version string Opcional A versão mínima do TLS.
syslog_settings.tls_settings.insecure_skip_verify bool Opcional Se true, ativa a verificação da certificação SSL.

O padrão é false.