Criar integrações personalizadas

Compatível com:

Google SecOps SOAR

Neste documento, explicamos como criar integrações personalizadas no ambiente de desenvolvimento integrado (IDE) 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, é possível usá-los em playbooks, ações manuais e agentes remotos. A capacidade de importação e exportação também é compatível, assim como em outros itens do ambiente de desenvolvimento integrado.

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 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 > IDE.
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 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 de bibliotecas, independentemente do que está 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 um wheel binário pré-compilado (como pacotes com extensões C), a plataforma SOAR usa o cpython padrão criado para a arquitetura manylinux_2_17_x86_64. 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 usar a versão instalada no sistema.

Se você estiver usando um arquivo .WHL personalizado ou reservado (como TIPCommon) que exija subdependências aninhadas, faça upload manual de arquivos wheel 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. Para uma lista completa das 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 wheel 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, forneça um URL direto para o código-fonte (por exemplo, um arquivo .tar.gz). O resolvedor de dependências da plataforma, uv, permite definir esses URLs de origem na tabela [tool.uv.sources] do arquivo pyproject.toml. 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 do uv sobre Gerenciamento de 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 multicamadas, como TIPCommon, o Google recomenda ignorar os uploads manuais do ambiente de desenvolvimento integrado e desenvolver localmente usando a ferramenta CLI do Marketplace (mp). Essa ferramenta rastreia e empacota automaticamente dependências aninhadas usando o gerenciador de pacotes uv.

Pré-requisitos

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

Configuração inicial

1. Copie e clone o repositório oficial do Content Hub no 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 sua 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 reservadas no layout do repositório em: content-hub/content/response_integrations/custom/

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

Se você tiver uma integração criada no ambiente de desenvolvimento integrado que precise de TIPCommon ou outras bibliotecas de várias camadas, use o seguinte fluxo de trabalho local 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 sua instância do Google SecOps:

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

3. Mude 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 wheel TIPCommon necessário. Isso rastreia e faz o download automático das rodas de subdependência aninhadas para a configuração do pacote do ambiente local:

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

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

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

Como verificar a instalação

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

• Abra sua integração personalizada no ambiente de desenvolvimento integrado.
• 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 compilar sem gerar um ModuleNotFoundError, suas 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 sejam obrigatórias, recomendamos usá-las em integrações que interagem com ferramentas externas. Os gerentes não devem importar do SDK. Depois de criá-las, importe-as 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:não é necessário ter um gerente 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çã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 de 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: se ativada, verifica se o certificado SSL da conexão com o servidor do 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 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 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.

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 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. 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 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. Vale lembrar que as atualizações da Central de conteúdo não substituem nem excluem nenhuma integração personalizada.

Exportar e importar no IDE

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 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 baixar o pacote.

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