Criar integrações personalizadas

Compatível com:

Google SecOps SOAR

Este documento explica os fluxos de trabalho para criar integrações personalizadas para o Google SecOps. A prática recomendada atual é desenvolver integrações localmente usando o ambiente de desenvolvimento integrado de sua preferência e gerenciá-las pelo GitHub usando fluxos de trabalho modernos do GitOps. Para ambientes legados ou protótipos rápidos, também é possível criar integrações diretamente no IDE integrado do SOAR.

Observação:para um framework de desenvolvimento padronizado, diretrizes de controle de qualidade e práticas recomendadas para criar e enviar integrações personalizadas, consulte o Guia de integrações personalizadas.

IDE local e fluxo de trabalho do GitHub (recomendado)

O fluxo de trabalho recomendado é desenvolver integrações localmente e gerenciá-las pelo GitHub. Essa abordagem se alinha às práticas modernas de GitOps, permitindo um melhor controle de versões, colaboração e gerenciamento automatizado de dependências.

Para ver etapas técnicas detalhadas, guias de instalação e comandos modernos usando a ferramenta CLI do Marketplace e o gerenciador de pacotes uv, consulte o repositório oficial do GitHub do Chronicle Content Hub.

Visão geral conceitual do fluxo de trabalho

Para desenvolver integrações personalizadas localmente, recomendamos que você siga este ciclo de vida do GitOps. Para ver a sintaxe exata e atualizada desses comandos, consulte a documentação oficial da CLI do MP no GitHub.

1. Bifurcar e clonar:clone o repositório oficial do content-hub na sua máquina de desenvolvimento local.
2. Instalar ferramentas:instale a ferramenta de CLI mp e o gerenciador de pacotes Python uv.
3. Autenticação:faça login no ambiente do Google SecOps pela CLI do MP usando o URL da instância e as chaves de API.
4. Desenvolva localmente:use seu ambiente de desenvolvimento integrado preferido (como VS Code ou PyCharm) para escrever o código de integração, aproveitando as ferramentas locais de depuração e teste.
5. Gerenciar dependências:use uv para declarar e gerenciar dependências (como TIPCommon) no arquivo pyproject.toml local.
6. Sincronizar:use os comandos mp pull e mp push para sincronizar o código local com a instância do Google SecOps para testes e implantação.

Alternativa: criar uma integração personalizada no ambiente de desenvolvimento integrado integrado

Se você estiver mantendo integrações legadas, testando um script rapidamente ou trabalhando em um ambiente em que o desenvolvimento local é restrito, use o IDE integrado.

Caso de uso: criar uma integração personalizada do Armis

Para criar a integração personalizada no ambiente de desenvolvimento integrado, siga estas etapas:

1. No menu principal, acesse Resposta > IDE.
2. Clique em Criar novo item e selecione Integração.
3. Digite um nome e clique em Criar.

A integração agora está listada com a opção configurações Configurações, indicando que é uma integração personalizada.

Clique em Configurações Configurações para exibir as configurações de integração, em que é possível definir o ícone, a descrição, as dependências do Python e os parâmetros de integração.

Observação:as dependências de script são bibliotecas Python exigidas pela integração personalizada. As dependências podem ser enviadas como arquivos .WHL, .TAR, .GZ ou .PY. Cada integração é executada no próprio ambiente virtual, permitindo que você use versões específicas de bibliotecas, independentemente do que está instalado no sistema subjacente.

Se você estiver usando um arquivo .WHL personalizado ou reservado (como TIPCommon) que exige subdependências aninhadas, faça upload manual de arquivos wheel individuais para toda a árvore de dependências antes de salvar. Se as dependências aninhadas não forem resolvidas, vai ocorrer uma falha genérica de errorCode: 2000. Para um rastreamento de dependências avançado, use o fluxo de trabalho do IDE local e do GitHub.

Criar um administrador personalizado

Os gerenciadores são wrappers para APIs de ferramentas de terceiros. Embora não sejam obrigatórios, recomendamos que sejam usados em integrações que interagem com ferramentas externas. Os gerenciadores não devem importar do SDK. Depois de criá-las, importe-as para conectores, ações e jobs.

Para criar um administrador personalizado, siga estas etapas:

1. No ambiente de desenvolvimento integrado, clique em Criar novo item e selecione Gerenciador.
2. Selecione a integração do Armis e insira o nome de um administrador.
   
3. Edite e execute o seguinte script:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) A resposta a ser validada
       :param error_msg: (str) A mensagem de erro a ser exibida
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Observação:um administrador não é necessário para ações básicas. No entanto, recomendamos criar um ao agrupar pequenas ações para análise e transformação de dados.

Parâmetros, configuração do Google SecOps Content Hub e a ação Ping

Os parâmetros definidos nas configurações de integração aparecem na configuração do Google SecOps Content Hub. Os parâmetros incluem:

• Raiz da API: o URL de base do serviço ao qual você está se conectando.
• Chave secreta da API: uma chave confidencial usada para autenticar seu aplicativo com o serviço.
• Caixa de seleção Verificar SSL: se ativada, verifica se o certificado SSL para a conexão com o servidor Armis é válido.
• Caixa de seleção Executar remotamente: uma configuração que determina se o código ou a tarefa será executada em um servidor remoto em vez de localmente. Quando essa opção está ativada, o sistema envia as instruções e os dados necessários para um servidor dedicado para processamento.

Para atualizar os parâmetros, siga estas etapas:

1. Digite as credenciais corretas.
2. Clique em Salvar > Teste.

Observação:sempre clique em Salvar depois de atualizar as credenciais. Todas as integrações de terceiros precisam implementar uma ação Ping. O botão Testar executa essa ação para validar a conectividade.

Se a ação Ping estiver ausente, o botão Testar vai falhar e mostrar um X vermelho.

Implementar uma ação de ping

A lógica da ação Ping funciona como uma autenticação bem-sucedida.

Para implementar uma ação Ping, faça o seguinte:

1. No ambiente de desenvolvimento integrado, crie uma nova ação na integração do Armis chamada Ping.
2. Use o método ArmisManager auth para verificar a autenticação.

Ative a integração

Para ativar a integração, siga estas etapas:

1. Em Resposta > IDE, clique no botão Ativar/Desativar para a posição ATIVADO.
2. Clique em Salvar. Um botão verde confirma o sucesso. As credenciais do Content Hub são transmitidas para o ArmisManager. Se auth for concluído sem erros, o botão Testar vai mostrar uma marca de seleção verde.

Use o método extract_configuration_param para importar parâmetros da configuração de integração. Como alternativa, use extract_action_param para definir parâmetros na própria ação. No entanto, a ação Ping sempre deve usar parâmetros de configuração, já que eles são testados pelo Content Hub.

Ver integrações personalizadas

Acesse o Content Hub e pesquise a integração personalizada que você criou. Se você não tiver criado uma imagem durante a configuração inicial, a imagem personalizada padrão será atribuída a ela. As atualizações do Content Hub não substituem nem excluem integrações personalizadas.

Exportar e importar no ambiente de desenvolvimento integrado

Execute uma das seguintes ações:

• Para importar integrações, faça o seguinte:
1. Faça upload de um arquivo ZIP com a estrutura de pastas correta. A integração aparece no ambiente de desenvolvimento integrado e no Hub de conteúdo.
2. Clique em Importar. A integração aparece no ambiente de desenvolvimento integrado e no Hub de conteúdo.
3. O sistema gera um arquivo ZIP com a definição, os scripts e a configuração. A pasta Administradores não é incluída automaticamente.
• Para exportar integrações, faça o seguinte:
• Clique em Exportar para fazer o download do pacote.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.