Criar uma integração personalizada

Compatível com:

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 na Central de conteúdo 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.

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]
# The key (e.g., compressed-rtf) must match the dependency name
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.

Criar um gerenciador personalizado

Os gerentes são wrappers para APIs de ferramentas de terceiros. Embora não sejam obrigatórias, recomendamos o uso delas 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
           ))

Parâmetros, configuração do Hub de conteúdo do Google SecOps e ação de ping

Os parâmetros definidos nas configurações de integração aparecem na configuração do Content Hub do Google SecOps. 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.

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 da central 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. Se preferir, use extract_action_param para definir parâmetros na própria ação. No entanto, a ação Ping sempre usa parâmetros de configuração, já que eles são testados pela Central 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. As atualizações do hub de conteúdo 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 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 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.