Esta página foi traduzida pela API Cloud Translation.

API Forwarder Management

É possível usar a API Google Security Operations Forwarder Management para fazer o seguinte de maneira programática:

Crie e gerencie encaminhadores.
Criar e gerenciar coletores.
Acesse o conteúdo dos arquivos de configuração (.conf) e de 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, arquivo, 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 registros. Por exemplo, é possível instalar um forwarder com dois coletores de syslog que escutam dados PAN_FIREWALL e CISCO_ASA_FIREWALL em portas separadas, respectivamente.

A API permite criar encaminhadores e coletores na sua instância do Google Security Operations. Depois que um encaminhador é criado, é possível usar o endpoint "Generate Forwarder Files" para receber o conteúdo do arquivo (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 de encaminhamento de operações de segurança do Google em um sistema Windows ou Linux.

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

Criar um encaminhador e os coletores dele

Um encaminhador precisa ser criado antes que qualquer um dos coletores dele possa ser criado.

Para criar um encaminhador e os coletores dele:

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

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

Essa API do Google Security Operations usa o protocolo OAuth 2.0 para autenticação e autorização. O aplicativo pode concluir essas tarefas usando uma das seguintes implementações:

Usar a biblioteca de cliente da API do Google para sua linguagem de computador.
Interagir diretamente com o sistema OAuth 2.0 usando HTTP.

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

As bibliotecas do Google Authentication são um subconjunto das bibliotecas de cliente da API do Google. Veja outras implementações de linguagem.

Como receber credenciais de autenticação da API

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

Também é necessário informar o escopo do Auth ao inicializar o cliente da 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 de API do Google:

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

Exemplo do Python

O exemplo de Python a seguir demonstra como usar as credenciais do 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 a qualquer cliente contra a plataforma de Operações de Segurança do Google. Se você alcançar ou exceder o limite de consultas, o servidor do API Chronicle retornará HTTP 429 (RESOURCE_EXHAUSTED) ao autor da chamada. Ao desenvolver aplicativos para a API Chronicle, o Google recomenda que você aplique limitações de taxa em seu sistema para evitar exaustão. Esses limites se aplicam a todas as APIs Chronicle, incluindo as APIs Search, Forwarder Management e Tooling.

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

API Chronicle	Endpoint da API	Limite
Gerenciamento de encaminhadores	Criar encaminhador	1 QPS
	Acessar encaminhador	1 QPS
	Listar encaminhadores	1 QPS
	Atualizar encaminhador	1 QPS
	Excluir encaminhador	1 QPS
Gerenciamento de coletores	Criar coletor	1 QPS
	Acessar o coletor	1 QPS
	Listar coletores	1 QPS
	Atualizar coletor	1 QPS
	Excluir coletor	1 QPS

Referência da API Forwarder

Esta seção descreve os endpoints para criar e gerenciar encaminhadores. Para endpoints de criação e gerenciamento de coletores, consulte a referência da API Collector.

Criar encaminhador

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

Para algumas configurações, os valores de configuração que estão ausentes ou são iguais a zero no corpo da solicitação são definidos como valores padrão. Para detalhes sobre campos e valores do encaminhador, consulte 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 remetente. Esse nome é exibido na interface do Google SecOps.
config	objeto	Opcional	As definições de configuração para este encaminhador. Consulte Campos de configuração do encaminhador.

Exemplo de solicitação

Este exemplo mostra os pares de chave-valor necessários em uma solicitação de criação de encaminhador. Se um campo não estiver especificado na solicitação e tiver um valor padrão, o valor padrão é aplicado durante a criação do encaminhador. Para detalhes sobre os valores padrão, consulte 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 vai 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 são aplicados a determinadas configurações durante a criação de recursos se esses campos estiverem ausentes ou tiverem valor zero no corpo da solicitação. Para mais detalhes, consulte Campos de configuração do encaminhador.

Campos de resposta

Além dos campos especificados na solicitação e dos campos aos quais valores padrão forem aplicados, a resposta incluirá os seguintes valores gerados e somente de saída.

Campo	Tipo	Descrição
name	string	O ID do recurso do encaminhador. O formato é "encaminhadores/forwarderID". Por exemplo: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
estado	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. SUSPENSA: o remetente não tem permissão para fazer upload de dados. O valor padrão é ACTIVE.

Campo

Tipo

Descrição

name

string

O ID do recurso do encaminhador. O formato é "encaminhadores/forwarderID". Por exemplo:

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

estado

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.
SUSPENSA: o remetente não tem permissão para fazer 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"
}

Acessar encaminhador

Retorna um encaminhador.

Solicitação

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

Corpo da solicitação

Não inclua o corpo da 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"
}

Listar encaminhadores

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

Encaminhador de atualizações

É 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 deve conter apenas os campos que você quer atualizar (nos locais exatos).

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 remetente. Esse nome é exibido na interface do Google SecOps.
config	objeto	Opcional	As definições de configuração para este encaminhador. Consulte Campos de configuração do encaminhador.

Exemplo de solicitação

Este é um exemplo de solicitação de Update Forwarder 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 o corpo da 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, "Delete Forwarder" retornará uma resposta vazia com um código de status HTTP 200 (OK).

{}

Gerar arquivos de encaminhamento

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 o corpo da 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 for bem-sucedida, ela vai 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 o dados de configuração para os coletores do encaminhador, bem como o conteúdo o arquivo de autenticação (_auth.conf) que é usado pelo encaminhador para fazer a autenticação com instância do Google SecOps.

Campos de configuração do encaminhador

A tabela a seguir lista as configurações de encaminhamento que podem ser especificadas usando "Criar encaminhador" e "Atualizar encaminhador". Se você não especificar um valor para uma configuração quando você usa Criar encaminhador, o valor padrão da configuração (mostrado abaixo) será aplicada.

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 forwarder. Observação: essa é uma configuração global que se aplica ao forwarder e aos coletores dele, a menos que seja substituída no nível do coletor. Para mais informações, consulte Configurar namespaces.
metadata.labels	list	Opcional	Uma lista de pares chave-valor arbitrários que podem ser especificados no configuração do encaminhador. Observação: essa é uma configuração global que se aplica ao forwarder e aos coletores dele, a menos que seja substituída no nível do coletor.
metadata.labels.key	string	Opcional	A chave de um campo na lista de identificadores de metadados.
metadata.labels.value	string	Opcional	O valor de um campo na lista de rótulos de metadados.
regex_filters.description	string	Opcional	Descreve o que está sendo filtrado e por quê.
regex_filters.regexp	string	Opcional	A expressão regular usada para corresponder a cada linha de entrada.
regex_filters.behavior	enum	Opcional	Especifica o estado da funcionalidade do servidor. Os valores válidos são: PERMITIR: nesse estado, a linha filtrada pode ser enviada. BLOCK: esse estado impede que a linha filtrada seja enviada.
server_settings	objeto	Opcional	Configurações que configuram o servidor HTTP integrado do encaminhador, que pode ser usado a fim de configurar opções de balanceamento de carga e alta disponibilidade para a coleta de syslog no Linux.
server_settings.state	enum	Opcional	Especifica o estado da funcionalidade do servidor. Os valores válidos são: ACTIVE: neste 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	O número de segundos após os quais o encaminhador retorna um erro de prontidão/verificação de integridade 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 servidor. Isso permite que o balanceador de carga remova o encaminhador do pool. O valor padrão é `15`.
server_settings.drain_timeout	número inteiro	Opcional	O número de segundos após o qual o encaminhador aguarda o fechamento das conexões ativas 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 que o servidor HTTP detecta para verificações de integridade do balanceador de carga. Precisa estar entre 1024 e 65.535. O padrão é `8080`.
server_settings.http_settings.host	string	Opcional	o endereço IP ou nome do host que pode ser convertido em endereços IP; que o servidor deve ouvir. 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, 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 permitido 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 para aguardar a próxima solicitação quando as conexões inativas estiverem 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	O código de status retornado quando o encaminhador está pronto para aceitar 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 tráfego. O padrão é `503`.

Referência da API Collector

Esta seção descreve os endpoints para trabalhar com coletores.

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

Dados de arquivos de registro
Tópicos do Kafka
Dados do 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 dos coletores precisam ser especificados usando o recurso Criar coletor depois de usar o recurso Criar encaminhador.

Para determinadas configurações, os valores de configuração que estão ausentes ou são iguais a zero no corpo da solicitação são definidos como valores padrão. Para detalhes sobre 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 no console do SecOps interface gráfica do usuário.
config	objeto	Obrigatório	As configurações do coletor. Consulte Campos de configuração do coletor.
estado	enum	Opcional	Especifica o estado atual do coletor. Os valores válidos são: ACTIVE: o coletor tem permissão para aceitar dados. SUSPENSA: o coletor não tem permissão para aceitar dados.

Campo

Tipo

Obrigatório

Descrição

display_name

string

Obrigatório

O nome do coletor. Esse nome é exibido no console do SecOps interface gráfica do usuário.

config

objeto

Obrigatório

As configurações do coletor. Consulte Campos de configuração do coletor.

estado

enum

Opcional

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

ACTIVE: o coletor tem permissão para aceitar dados.
SUSPENSA: o coletor não tem permissão para aceitar dados.

Exemplo de solicitação

Este exemplo mostra os pares de chave-valor obrigató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 vai 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 são aplicados a determinados durante a criação de recursos se esses campos estiverem ausentes ou com valor zero do 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 para os quais os valores padrão são aplicados, a resposta inclui os seguintes campos:

Campo	Tipo	Descrição
name	string	O ID do recurso do coletor. O formato é "forwarders/{forwarderID}/collectors/{collectorID}". Para 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 o corpo da 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 existentes para o 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, você pode optar por substituir toda a configuração do coletor ou apenas substituir somente da configuração do coletor. Em geral, é melhor substituir campos específicos para evitar substituir acidentalmente todos os seus dados. Para substituir campos específicos, forneça um FieldMask à solicitação de atualização.

Para fornecer uma FieldMask e 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 deve conter apenas os campos que você quer atualizar (em os locais exatos).

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 no console do SecOps interface gráfica do usuário.
config	objeto	Opcional	As definições de configuração para este encaminhador. Consulte Campos de configuração do coletor.

Exemplo de solicitação

Este é um exemplo de solicitação de atualização do coletor em que a solicitação 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 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 o corpo da 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, "Excluir coletor" 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 possa ser ingerido pelo Google SecOps). Para conferir uma lista de tipos de registro com suporte para os quais o Google SecOps tem um analisador, consulte a coluna "Ingestion Label" na página Analisadores padrão compatíveis. Para receber lista completa de tipos de registro com suporte, 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 encaminhador e seus coletores, a menos que seja substituído em no nível do coletor. Para mais informações, consulte Configurar namespaces.
metadata.labels	list	Opcional	Uma lista de pares chave-valor arbitrários que podem ser especificados no configuração do coletor. Observação: essa é uma configuração global que se aplica ao forwarder e aos coletores dele, a menos que seja substituída no nível do coletor.
metadata.labels.key	string	Opcional	A chave de um campo na lista de identificadores de metadados.
metadata.labels.value	string	Opcional	O valor de um campo na lista de rótulos de metadados.
regex_filters.description	string	Opcional	Descreve o que está sendo filtrado e por quê.
regex_filters.regexp	string	Opcional	A expressão regular usada para corresponder a cada linha de entrada.
regex_filters.behavior	enum	Opcional	Especifica o estado da funcionalidade do servidor. Os valores válidos são: PERMITIR: nesse estado, a linha filtrada pode ser 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. SUSPENSO: o buffer está desativado.
disk_buffer.directory_path	string	Opcional	O caminho do diretório para arquivos gravados.
disk_buffer.max_file_buffer_bytes	número inteiro	Opcional	O tamanho máximo do arquivo 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 forwarder. O padrão é `1048576`.
<collector_type>_settings.<fields>		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`, o campo `file_settings.file_path` precisa ser adicionado à configuração e receber um valor. Por exemplo: `"file_settings": { "file_path": "/opt/chronicle/edr/output/sample.txt", }` Os tipos de coletor e seus campos são listados nas linhas subsequentes desta 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 de onde os dados serão ingeridos. Para mais detalhes, consulte Coletar dados de tópicos do Kafka.
kafka_settings.group_id	string	Opcional	Um ID de grupo.
kafka_settings.timeout	número inteiro	Opcional	O número máximo de segundos que uma discagem vai aguardar para que uma conexão seja concluída. O padrão é `60`.
kafka_settings.brokers	string	Opcional	Uma string repetida que lista 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 e adicionar um novo, especifique todos os corretores e o novo agente.
kafka_settings.tls_settings.certificate	string	Opcional	O caminho e o nome do arquivo do certificado. Por exemplo: `/path/to/cert.pem`
kafka_settings.tls_settings.certificate_key	string	Opcional	O caminho e o nome do 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 de 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 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 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 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 detalhes, consulte Coletar dados do Splunk. O padrão é `30`.
splunk_settings.query_string	string	Opcional	A consulta usada para filtrar registros no Splunk. Por exemplo: `search index=* sourcetype=dns`
splunk_settings.query_mode	string	Opcional	O modo de consulta do Splunk. Por exemplo: `realtime`
splunk_settings.cert_ignored	bool	Opcional	Se `true`, o certificado será ignorado.
syslog_settings.protocol	enum	Opcional	Especifica o protocolo que o coletor usará para detectar dados de syslog. Os valores válidos são: `TCP` `UDP`
syslog_settings.address	string	Opcional	O endereço IP ou o nome do host de destino em que o coletor está localizado e ouve dados de syslog.
syslog_settings.port	número inteiro	Opcional	A porta de destino em que o coletor reside e detecta o syslog dados.
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 o qual a conexão TCP é encerrada. O padrão é `60`.
syslog_settings.tls_settings.certificate	string	Opcional	O caminho e o nome do arquivo do certificado. Por exemplo: `/path/to/cert.pem`
syslog_settings.tls_settings.certificate_key	string	Opcional	O caminho e o nome do 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 de TLS.
syslog_settings.tls_settings.insecure_skip_verify	bool	Opcional	Se `true`, ativa a verificação de certificação SSL. O padrão é `false`.