Criar uma integração personalizada

Compatível com:

SecOps do Google SOAR

Este documento explica como criar integrações personalizadas no ambiente de desenvolvimento integrado (IDE) usando a mesma estrutura das integrações comerciais. Você pode encontrar e configurar integrações personalizadas no Google Security Operations Marketplace para vários ambientes. Depois, você pode usá-los em playbooks, ações manuais e agentes remotos. A capacidade de importar e exportar também é compatível, assim como outros itens do ambiente de desenvolvimento integrado.

Criar uma integração personalizada no ambiente de desenvolvimento integrado

É possível criar uma integração personalizada para o produto Armis e um gerenciador com uma ação de Ping. Para este procedimento, é necessário ter conhecimento de Python e programação orientada a objetos.

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 > Ambiente de desenvolvimento integrado.
2. Clique em Criar novo item e selecione Integração.
3. Digite um nome e clique em Criar.

A integração agora aparece na opção configurações Configurações, indicando que é uma integração personalizada.

Clique em settings Configurações para mostrar as configurações de integração, onde é 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 que a integração personalizada precisa importar. As dependências podem ser adicionadas como arquivos `.WHL`, `.TAR`, `.GZ` ou `.PY`. Cada integração é executada em um ambiente virtual próprio, permitindo que você use diferentes versões de biblioteca, mesmo que uma já esteja instalada no sistema. Por exemplo, para usar uma versão diferente da biblioteca de solicitações, faça o download dela de uma fonte confiável, como PyPI ou GitHub, e adicione-a como uma dependência de script. Se não estiver instalada no ambiente virtual, a integração vai voltar para a versão do sistema.

Criar um gerenciador personalizado

Os gerentes são wrappers para APIs de ferramentas de terceiros. Embora não seja obrigatório, recomendamos o uso deles para integrações que interagem com ferramentas externas. Os gerentes não devem importar do SDK. Depois da criação, importe-os para conectores, ações e jobs.

Para criar um gerente personalizado, siga estas etapas:

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

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) The response to validate
       :param error_msg: (str) The error message to display
       """
       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 gerente 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 Marketplace e ação de ping

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

• Raiz da API: o URL base do serviço a que você está se conectando.
• Secret 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 da conexão com o servidor da 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 de ping. O botão Testar executa essa ação para validar a conectividade.

Se a ação Ping não estiver disponível, 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. Uma chave verde confirma o sucesso. As credenciais do Marketplace 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. Se preferir, 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 Marketplace.

Ver integrações personalizadas

Acesse o Google SecOps Marketplace e pesquise a integração personalizada que você criou. Se você não criou uma imagem durante a configuração inicial, a imagem personalizada padrão será atribuída a ela. As atualizações do Google SecOps Marketplace 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 vai aparecer no IDE e no Google SecOps Marketplace.
2. Clique em Importar. A integração aparece no IDE e no Marketplace.
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 baixar o pacote.

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