API Forwarder Management
É possível usar a API Google Security Operations Forwarder Management para fazer o seguinte de maneira programática:
- Criar e gerenciar encaminhadores.
- Criar e gerenciar coletores.
- Receba o conteúdo de arquivos de configuração (
.conf) e de autenticação (_auth.conf) de um forwarder do Google Security Operations.
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, você pode usar vários coletores no mesmo encaminhador para ingerir dados de vários mecanismos e tipos de registro. 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 acessar 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
Um encaminhador precisa ser criado antes que qualquer um dos coletores seja 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
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.
Fazer interface 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 de autenticação do Google são um subconjunto das bibliotecas de cliente das APIs do Google. Consulte outras implementações de idioma.
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.
Você também precisa fornecer o escopo de autenticação 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 seguinte escopo para inicializar o cliente da 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.auth.transport import requests
from google.oauth2 import service_account
SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']
# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'
# Create a credential using Google Developer Service Account Credential and Google Security Operations API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)
# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)
# Your endpoint GET|POST|PATCH|etc. code will vary below
# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'
# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints
# requests GET example
response = http_session.request("GET", url)
# POST example uses json
body = {
"foo": "bar"
}
response = http_session.request("POST", url, json=body)
# PATCH example uses params and json
params = {
"foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)
# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/
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ê alcançar ou exceder o limite de consultas, o servidor da API Chronicle retornará HTTP 429 (RESOURCE_EXHAUSTED) para o autor da chamada. Ao desenvolver aplicativos para a API Chronicle, o Google recomenda que você aplique limites de taxa no sistema para evitar o esgotamento de recursos. Esses limites se aplicam a todas as APIs Chronicle, incluindo as APIs Search, Forwarder Management e Tooling.
Consulte a lista detalhada dos limites de consulta da API Chronicle.
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 remetente | 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 dos coletores precisam ser especificados usando a opção "Criar coletor" depois de usar a opção "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 saber mais sobre os campos e valores do forwarder, consulte Campos de configuração do forwarder.
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 configurações deste 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 for especificado na solicitação e tiver um valor padrão, o valor padrão será 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 em que os valores padrão são aplicados, a resposta inclui os seguintes campos gerados e somente de saída.
| Campo | Tipo | Descrição |
|---|---|---|
| name | string | O ID do recurso do encaminhador. O formato é
"forwarders/forwarderID". Por exemplo: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56 |
| estado | enum | Especifica o estado atual do encaminhador. Os valores válidos são:
O valor padrão é ATIVADO. |
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 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"
}
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"
}
]
}
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 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 configurações deste encaminhador. Consulte Campos de configuração do encaminhador. |
Exemplo de solicitação
Este é um exemplo de solicitação de atualização do encaminhador 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 Delete Forwarder vai 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 de autenticação (_auth.conf) do forwarder.
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 for bem-sucedida, ela vai retornar um código de status HTTP 200 (OK). Ele
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 autenticação com
a 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 ao usar a opção "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 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 de chave-valor arbitrários que podem ser especificados na 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 fazer a correspondência com cada linha recebida. |
| regex_filters.behavior | enum | Opcional | Especifica o estado da funcionalidade do servidor. Os valores válidos são:
|
| server_settings | objeto | Opcional | Configurações que configuram o servidor HTTP integrado do forwarder, que pode ser usado para 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:
|
| server_settings.graceful_timeout | número inteiro | Opcional | O número de segundos após o forwarder retornar uma verificação de integridade/preparação incorreta e ainda aceitar novas conexões. Esse é
também o tempo de espera entre o recebimento de um sinal para parar 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 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 permitido 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 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 permitido 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 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 de pacote (pcap)
- Dados do Splunk
- Dados do Syslog
Para endpoints de trabalho 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 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 saber mais 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 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:
|
Exemplo de solicitação
Este exemplo mostra os pares de chave-valor obrigatórios em uma solicitação de criação de coletor. Para os campos que não são fornecidos, os valores padrão são aplicados durante a criação do coletor.
Neste exemplo, o tipo de coletor é file, então 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 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 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}". 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 o 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 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 campos específicos. Em geral, é melhor substituir campos específicos para evitar substituir acidentalmente todos os seus dados. Para substituir campos específicos, forneça uma FieldMask à sua 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 (nos 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 na interface do Google SecOps. |
| config | objeto | Opcional | As configurações deste 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 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 vai 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 aceito (que pode ser processado 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 conferir uma lista completa de tipos de registros aceitos, 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 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 de chave-valor arbitrários que podem ser especificados na 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 fazer a correspondência com cada linha recebida. |
| regex_filters.behavior | enum | Opcional | Especifica o estado da funcionalidade do servidor. Os valores válidos são:
|
| disk_buffer.state | enum | Opcional | Especifica o estado de bufferização do disco para o coletor. Os valores válidos são:
|
| 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": {Os tipos de coletor e os campos deles são listados nas linhas seguintes desta tabela. Os tipos de coletor disponíveis são:
|
|
| 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 corretores e adicionar um novo, especifique todos os corretores existentes e o novo. |
| 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 de arquivo da chave do 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
mais detalhes, consulte Coletar dados do Splunk. O padrão é 10. |
| splunk_settings.maximum_window_size | número inteiro | Opcional | O período 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 | 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 vai usar para detectar dados do syslog. Os valores válidos são:
|
| syslog_settings.address | string | Opcional | O endereço IP ou nome do host de destino em que o coletor reside e ouve dados do syslog. |
| syslog_settings.port | número inteiro | Opcional | A porta de destino em que o coletor reside e detecta dados do 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 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 de arquivo da chave do 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 de certificação SSL.O padrão é false. |