APIGoogle Cloud
Este documento fornece orientações para ajudar você a configurar e integrar a APIGoogle Cloud ao Google Security Operations SOAR.
Versão da integração: 4.0
Integrar a API Google Cloud ao SOAR do Google SecOps
A integração requer os seguintes parâmetros:
| Parâmetros | Descrição |
|---|---|
Test URL |
Opcional Um URL de teste para validar a autenticação na API Google Cloud . Esse parâmetro usa uma solicitação GET. |
Service Account Json File Content |
Opcional O conteúdo do arquivo JSON da chave da conta de serviço. Você pode configurar este parâmetro, o parâmetro Para configurar esse parâmetro, forneça todo o conteúdo do arquivo JSON da chave da conta de serviço que você baixou ao criar uma conta de serviço. Para mais informações sobre o uso de contas de serviço como um método de autenticação, consulte Visão geral das contas de serviço e Representação de conta de serviço. Nessa integração, a autenticação com o arquivo JSON da chave da conta de serviço tem prioridade sobre o e-mail da identidade da carga de trabalho. |
Organization ID |
Opcional O ID da organização a ser usado na integração. Para extrair o valor desse parâmetro durante a execução da ação,
defina o seguinte marcador de posição: |
Project ID |
Opcional O ID do projeto a ser usado na integração. Para extrair o valor desse parâmetro durante a execução da ação,
defina o seguinte marcador de posição:
|
Quota Project ID |
Opcional O ID do projeto Google Cloud que você usa para
APIs Google Cloud e faturamento. Para usar esse parâmetro, conceda o papel A integração anexa esse valor de parâmetro a todas as solicitações de API. Se você não definir um valor para esse parâmetro, a integração vai recuperar o ID do projeto da sua conta de serviço do Google Cloud . |
Workload Identity Email |
Opcional O endereço de e-mail do cliente da sua conta de serviço. É possível configurar este parâmetro ou o Nessa integração, a autenticação com o arquivo JSON da chave da conta de serviço tem prioridade sobre o e-mail da identidade da carga de trabalho. Para representar contas de serviço com a Identidade da carga de trabalho,
conceda o papel |
OAuth Scopes |
Opcional Uma lista separada por vírgulas de escopos do OAuth necessários para executar as solicitações da API Google Cloud . |
Verify SSL |
Obrigatório Se selecionada, a integração verifica se o certificado SSL para conexão com o serviço Google Cloud é válido. Essa opção é selecionada por padrão. |
Para instruções sobre como configurar uma integração no Google SecOps, consulte Configurar integrações.
Você pode fazer mudanças mais tarde, se necessário. Depois de configurar uma instância de integração, você pode usá-la em playbooks. Para mais informações sobre como configurar e oferecer suporte a várias instâncias, consulte Suporte a várias instâncias.
Ações
Para mais informações sobre ações, consulte Responder a ações pendentes da sua mesa de trabalho e Realizar uma ação manual.
Executar solicitação HTTP
Use a ação Executar solicitação HTTP para criar e executar uma solicitação de API HTTP personalizada em um URL de destino.
Essa ação não é executada em entidades do Google SecOps.
Comportamento de ação
Essa ação oferece suporte a comportamentos complexos, incluindo pesquisas assíncronas, construção dinâmica de payloads e gerenciamento de arquivos.
Sondagem assíncrona
Quando Expected Response Values é fornecido, a
ação opera no modo assíncrono. Nesse modo, a ação pesquisa repetidamente o endpoint de destino para rastrear o estado de uma resposta (por exemplo, aguardando a conclusão de uma tarefa de longa duração).
A ação avalia o corpo da resposta em relação às condições JSON fornecidas no parâmetro e continua a execução até que as condições sejam atendidas ou a ação atinja o tempo limite.
Lógica de condição
A ação é compatível com a seguinte lógica para rastrear estados de resposta:
Correspondência de campo único: a ação aguarda um campo específico atingir um valor único.
{ "state": "finished" }Vários valores (lógica OR): a ação interrompe a execução se um campo corresponder a qualquer valor em uma lista fornecida. Isso é útil para interromper nos estados "sucesso" e "erro" e evitar pesquisas desnecessárias.
{ "state": ["finished", "error"] }Vários campos (lógica E): a ação aguarda até que todos os campos especificados correspondam aos respectivos valores simultaneamente.
{ "state": "finished", "percentage": "100" }Lógica combinada: é possível combinar várias condições no objeto JSON.
{ "state": ["finished", "error"], "percentage": "10" }
Comportamento de análise JSON
Ao avaliar condições, a ação segue estas regras:
Pesquisa global: a ação pesquisa em todo o objeto de resposta JSON as chaves especificadas. Forneça o nome da chave exatamente como ele aparece no JSON, sem adicionar nomes de objetos pai ou usar prefixos. Por exemplo, use
"state", não"data_state"ou"data-state".Várias chaves idênticas: se a resposta contiver várias chaves com o mesmo nome em diferentes níveis da hierarquia JSON, a saída esperada só será alcançada quando todos os nomes de chave correspondentes satisfizerem o valor esperado idêntico.
Por exemplo, para pesquisar o estado
finishedna resposta JSON e ignorar outros estados, defina todas as chavesstateemExpected Response Valuescomofinished:{ "data": { "state": "finished" }, "state": "finished" }
Construção do payload do corpo
A ação cria o corpo da solicitação com base no cabeçalho Content-Type
fornecido em Headers.
Esta é a entrada Body Payload usada para
os seguintes exemplos de construção:
{
"Id": "123123",
"sorting": "asc"
}
application/x-www-form-urlencoded: a ação gera o payload comoId=123123&sorting=asc.application/json: a ação gera o seguinte payload JSON:{ "Id": "123123", "sorting": "asc" }XML: se o produto de terceiros exigir XML, forneça uma entrada formatada em XML diretamente emBody Payload:<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="[http://schemas.xmlsoap.org/soap/envelope/](http://schemas.xmlsoap.org/soap/envelope/)"> <soap:Body> <NumberToWords xmlns="[http://www.dataaccess.com/webservicesserver/](http://www.dataaccess.com/webservicesserver/)"> <ubiNum>500</ubiNum> </NumberToWords> </soap:Body> </soap:Envelope>
Gerenciamento de arquivos
A ação é compatível com os seguintes fluxos de trabalho para gerenciar arquivos:
Como fazer o download de arquivos:
Para retornar dados de arquivo como parte do resultado JSON no formato base64, selecione
Base64 Output.Para salvar um arquivo diretamente no mural de casos como um arquivo ZIP, selecione
Save To Case Wall.
Upload de arquivos: para fazer upload de um arquivo, converta-o em uma string codificada em base64 e inclua-o como parte do valor
Body Payload.O exemplo a seguir mostra um arquivo de imagem convertido em uma string codificada em base64:
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ça: para arquivos sensíveis (como malware), selecione
Password Protect Zip. Isso criptografa automaticamente o arquivo ZIP salvo criado usandoSave To Case Wallcom a senhainfected.
Configuração do bloco de playbook
A configuração a seguir demonstra como usar a ação Executar solicitação HTTP em um bloco de playbook. Use este exemplo para entender como aplicar marcadores de posição e prefixos de entrada.
Ao usar entradas de bloco como marcadores de posição, inclua o prefixo Input. (por exemplo, [Input.comment]).
Método:
PUTCaminho do URL:
https://{API_URL}/[Input.table_name]/[Input.sys_id]Cabeçalhos:
{ "Content-type": "application/json; charset=utf-8", "Accept": "application/json", "User-Agent": "GoogleSecops" }Payload do corpo:
{ "work_notes": "[Input.comment]" }
Entradas de ação
A ação Executar solicitação HTTP exige os seguintes parâmetros:
| Parâmetro | Descrição |
|---|---|
Method |
Opcional Um método a ser usado na solicitação. O valor padrão é
|
URL Path |
Opcional Um URL a ser executado. O valor padrão é |
URL Params |
Opcional Os parâmetros de URL. A ação usa qualquer valor fornecido junto com os valores que você informou diretamente no parâmetro Caminho do URL. Esse parâmetro exige o formato de objeto JSON como entrada. O valor padrão é: {
"URL Field Name": "URL_FIELD_VALUE"
} |
Headers |
Opcional Cabeçalhos a serem usados na solicitação HTTP. Esse parâmetro exige o formato de objeto JSON como entrada. O valor padrão é: {
"Content-Type": "application/json; charset=utf-8",
"Accept": "application/json",
"User-Agent" : "GoogleSecOps"
} |
Cookie |
Opcional Os parâmetros a serem usados no cabeçalho Esse parâmetro substitui os cookies fornecidos no parâmetro Cabeçalhos. Esse parâmetro exige o formato de objeto JSON como entrada. O valor padrão é: {
"Cookie_1": "COOKIE_1_VALUE"
} |
|
Opcional
Um corpo para a solicitação HTTP. A ação cria diferentes payloads dependendo do valor do cabeçalho Esse parâmetro exige o formato de objeto JSON como entrada, exceto quando um produto de terceiros exige XML ou o conteúdo O valor padrão é: {
"Body Field Name": "BODY_FIELD_VALUE"
} |
Expected Response Values |
Opcional. O objeto JSON que contém os pares campo-valor que definem o estado obrigatório do corpo da resposta. |
Save To Case Wall |
Opcional Se selecionada, a ação salva o arquivo e o anexa ao Painel de Casos. O arquivo é arquivado com a extensão Não selecionada por padrão. |
Password Protect Zip |
Opcional Se selecionada, a ação adiciona uma senha ao
arquivo Use esse parâmetro ao trabalhar com arquivos suspeitos. Essa opção é selecionada por padrão. |
Follow Redirects |
Opcional Se selecionada, a ação segue os redirecionamentos. Essa opção é selecionada por padrão. |
Fail on 4xx/5xx |
Opcional Se selecionada, a ação falhará se o código de status da resposta for um erro 4xx ou 5xx. Essa opção é selecionada por padrão. |
Base64 Output |
Opcional Se selecionada, a ação converte a resposta para o formato base64. Use esse parâmetro ao baixar arquivos. O resultado JSON não pode exceder 15 MB. Não selecionada por padrão. |
Fields To Return |
Obrigatório Os campos a serem retornados. Os valores possíveis são:
|
Request Timeout |
Obrigatório Um período para aguardar o servidor enviar dados antes da falha da ação. O valor padrão é de 120 segundos. |
Saídas de ação
A ação Executar solicitação HTTP fornece as seguintes saídas:
| Tipo de saída da ação | Disponibilidade |
|---|---|
| Anexo do Painel de Casos | Indisponível |
| Link do Painel de Casos | Indisponível |
| Tabela do painel de casos | Indisponível |
| Tabela de enriquecimento | Indisponível |
| Resultado JSON | Disponível |
| Mensagens de saída | Disponível |
| Resultado do script | Disponível |
Resultado JSON
O exemplo a seguir descreve a saída do resultado JSON recebida ao usar a ação Executar solicitação HTTP:
{
"response_data": {
"data": {
"relationships": {
"comment": [
{
"name": "item",
"description": "Object to which the comment belongs to."
},
{
"name": "author",
"description": "User who wrote the comment."
}
]
}
}
},
"redirects": [],
"response_code": 200,
"cookies": {},
"response_headers": {
"Content-Type": "application/json",
"X-Cloud-Trace-Context": "VALUE",
"Date": "Fri, 03 Nov 2023 16:14:13 GMT",
"Server": "Google Frontend",
"Content-Length": "36084"
},
"apparent_encoding": "ascii"
}
Mensagens de saída
A ação Executar solicitação HTTP fornece as seguintes mensagens de saída:
| Mensagem de resposta | Descrição da mensagem |
|---|---|
|
A ação foi concluída. |
Failed to execute API request. Error:
ERROR_REASON |
A ação falhou. Verifique a conexão com o servidor, os parâmetros de entrada ou as credenciais. |
Resultado do script
A tabela a seguir descreve os valores da saída do resultado do script ao usar a ação Executar solicitação HTTP:
| Nome do resultado do script | Valor |
|---|---|
is_success |
True ou False |
Ping
Use a ação Ping para testar a conectividade com Google Cloud.
Essa ação não é executada em entidades do Google SecOps.
Entradas de ação
Nenhum.
Saídas de ação
A ação Ping fornece as seguintes saídas:
| Tipo de saída da ação | Disponibilidade |
|---|---|
| Anexo do Painel de Casos | Indisponível |
| Link do Painel de Casos | Indisponível |
| Tabela do painel de casos | Indisponível |
| Tabela de enriquecimento | Indisponível |
| Resultado JSON | Disponível |
| Mensagens de saída | Disponível |
| Resultado do script | Disponível |
Resultado JSON
O exemplo a seguir descreve a saída do resultado JSON recebida ao usar a ação Ping:
{
"endpoint": "TEST_URL"
}
Mensagens de saída
A ação Ping fornece as seguintes mensagens de saída:
| Mensagem de resposta | Descrição da mensagem |
|---|---|
Successfully tested connectivity. |
A ação foi concluída. |
Failed to test connectivity. |
A ação falhou. Verifique a conexão com o servidor, os parâmetros de entrada ou as credenciais. |
Resultado do script
A tabela a seguir descreve os valores da saída do resultado do script ao usar a ação Ping:
| Nome do resultado do script | Valor |
|---|---|
is_success |
True ou False |
Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.