Criar integrações personalizadas

Compatível com:

Google SecOps SOAR

Este documento explica como criar integrações personalizadas no ambiente de desenvolvimento integrado (IDE, na sigla em inglês) usando a mesma estrutura das integrações comerciais. É possível encontrar e configurar integrações personalizadas no Hub de conteúdo para vários ambientes. Depois, você pode usá-las em playbooks, ações manuais e agentes remotos. A capacidade de importação e exportação também é compatível, assim como outros itens do IDE.

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.

Criar uma integração personalizada no IDE

É 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 IDE, 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 settings Configurações, indicando que é uma integração personalizada.

Clique em settings Configurações para mostrar 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 necessárias para sua 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 da biblioteca, independentemente do que estiver instalado no sistema subjacente. 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.
Para dependências que exigem uma roda binária pré-compilada (como pacotes com extensões C), a plataforma SOAR usa o cpython padrão criado na manylinux_2_17_x86_64 arquitetura. Ao selecionar um arquivo .WHL, verifique se ele é compatível com essa tag.
Se uma biblioteca não estiver instalada no ambiente virtual, a integração vai voltar para a versão instalada no sistema.

Se você estiver usando um arquivo .WHL personalizado ou proprietário (como TIPCommon) que exige subdependências aninhadas, será necessário fazer o upload manual de arquivos de roda individuais para toda a árvore de dependências (por exemplo: anyio, certifi, httpx, idna, ou sniffio) antes de salvar. Não resolver dependências aninhadas vai resultar em uma falha genérica errorCode: 2000 falha. Para uma lista completa de bibliotecas de plataforma necessárias, consulte o Guia da comunidade sobre como recuperar o TIPCommon.

Se um pacote de dependência não tiver um arquivo de roda pré-compilado (.WHL) disponível para a arquitetura manylinux_2_17_x86_64 ou se você precisar de uma versão específica do código-fonte, poderá fornecer um URL direto para o código-fonte (por exemplo, um arquivo .tar.gz). O resolvedor de dependências da plataforma, uv, oferece suporte à definição desses URLs de origem na tabela [tool.uv.sources] no arquivo pyproject.toml file. Exemplo:

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Para mais detalhes sobre como definir diferentes tipos de dependências usando uv, consulte a documentação uv sobre como gerenciar dependências.

Fluxo de trabalho recomendado: gerenciamento avançado de dependências usando a CLI mp

Para integrações que exigem bibliotecas externas complexas ou de várias camadas, como TIPCommon, o Google recomenda ignorar os uploads manuais do IDE e desenvolver essas integrações localmente usando a ferramenta CLI do Marketplace (mp). Essa ferramenta rastreia e empacota automaticamente dependências aninhadas usando o uv gerenciador de pacotes.

Pré-requisitos

• Python 3.11 ou mais recente instalado na máquina de desenvolvimento local.
• O gerenciador de pacotes Python uv instalado (consulte o uv guia de instalação).

Configuração inicial

1. Ramifique e clone o repositório oficial do Hub de conteúdo para seu ambiente local.
2. Instale a ferramenta mp usando uv:

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. Faça login no ambiente do Google SecOps usando o URL raiz da instância e a chave de API legada:

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   Observação: a ferramenta de CLI exige o URL da instância legada do SOAR e o formato da chave de API para autenticação.
4. Configure o caminho do repositório raiz local:

   mp config --root-path /path/to/cloned/content-hub

5. Crie um subdiretório personalizado para suas integrações proprietárias no layout do repositório em: content-hub/content/response_integrations/custom/

Como adicionar TIPCommon ou dependências complexas a uma integração

Se você tiver uma integração criada no IDE que precisa de TIPCommon ou outras bibliotecas de várias camadas, use o fluxo de trabalho local a seguir para gerenciar as dependências com segurança:

1. Navegue até o diretório de integração personalizada no repositório clonado:

   cd content-hub/content/response_integrations/custom/

2. Extraia a estrutura de integração atual da instância do Google SecOps:

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. Altere o diretório para a pasta de integração recém-extraída:

   cd {INTEGRATION_NAME}

4. Use uv para injetar o pacote de arquivos de roda TIPCommon necessário. Isso rastreia e faz o download automaticamente das rodas de subdependência aninhadas na configuração do pacote de ambiente local:

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. Envie a integração totalmente compilada com a árvore de dependências recém-rastreada de volta para a instância do Google SecOps:

   mp push --type integration --name "{INTEGRATION_NAME}"

Como verificar a instalação

Para confirmar que as dependências foram empacotadas sem encontrar um errorCode: 2000 loop, faça o seguinte:

• Abra sua integração personalizada no IDE.
• Adicione uma linha de teste para importar um módulo do pacote, como: from TIPCommon.extraction import extract_action_param
• Clique no botão Testar/Reproduzir para depurar a execução. Se o script for compilado sem gerar um ModuleNotFoundError, as dependências aninhadas serão resolvidas corretamente.

Criar um gerenciador personalizado

Os gerenciadores 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 gerenciadores não devem importar do SDK. Após a criação, importe-os para conectores, ações e jobs.

Para criar um gerenciador personalizado, siga estas etapas:

1. No IDE, clique em Criar novo item e selecione Gerenciador.
2. Selecione a integração Armis e insira o nome de um gerenciador.
   
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 gerenciador não é necessário para ações básicas. No entanto, recomendamos criar um ao agrupar ações pequenas para análise e transformação de dados.

Parâmetros, configuração do Google SecOps Content Hub e a ação de 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 base do serviço a que 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: quando ativada, verifica se o certificado SSL da 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 > Testar.

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 de 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 de ping funciona como uma autenticação bem-sucedida.

Para implementar uma ação de ping, faça o seguinte:

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

Ativar a integração

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

1. Em Resposta > IDE, clique na opção Ativar/Desativar para a posição ATIVADO.
2. Clique em Salvar. Uma opção verde confirma o sucesso. As credenciais do Hub de conteúdo 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 de ping sempre deve usar parâmetros de configuração, já que eles são testados pelo Hub de conteúdo.

Ver integrações personalizadas

Acesse o Hub de conteúdo 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. Observe que as atualizações do Hub de conteúdo não substituem nem excluem integrações personalizadas.

Exportar e importar no IDE

Execute uma das seguintes ações:

• Para importar integrações, faça o seguinte:
1. Faça o upload de um arquivo ZIP com a estrutura de pastas correta. A integração aparece no IDE e no Hub de conteúdo.
2. Clique em Importar. A integração aparece no IDE e no Hub de conteúdo.
3. O sistema gera um arquivo ZIP contendo a definição, os scripts e a configuração. A pasta Gerenciadores 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.