Crie uma integração personalizada

Suportado em:

Google secops SOAR

Este documento explica como criar integrações personalizadas no ambiente de desenvolvimento integrado (IDE) usando a mesma estrutura que as integrações comerciais. Pode encontrar e configurar integrações personalizadas no centro de conteúdo para vários ambientes. Em seguida, pode usá-los em manuais de estratégias, ações manuais e agentes remotos. A capacidade de importação e exportação também é suportada, de forma semelhante a outros itens do IDE.

Nota: para ver uma estrutura de desenvolvimento padronizada, diretrizes de garantia de qualidade e práticas recomendadas para criar e enviar integrações personalizadas, consulte as práticas recomendadas.

Crie uma integração personalizada no IDE

Pode criar uma integração personalizada para o produto Armis e criar um gestor juntamente com uma ação Ping. Para este procedimento, pressupõe-se que tem conhecimentos de Python e programação orientada para objetos.

Exemplo de utilização: crie uma integração personalizada da Armis

Para criar a integração personalizada no IDE, siga estes passos:

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

A integração é agora apresentada com a opção definições Definições, o que indica que se trata de uma integração personalizada.

Clique em settings Settings para apresentar as definições de integração, onde pode definir o ícone, a descrição, as dependências do Python e os parâmetros de integração.

Nota: as dependências de scripts são bibliotecas Python necessárias para a sua integração personalizada. As dependências podem ser carregadas como ficheiros .WHL, .TAR, .GZ ou .PY. Cada integração é executada no seu próprio ambiente virtual, o que lhe permite usar versões específicas da biblioteca, independentemente do que está instalado no sistema subjacente. Por exemplo, para usar uma versão diferente da biblioteca de pedidos, transfira-a de uma origem fidedigna, como o PyPI ou o GitHub, e adicione-a como uma dependência de script.
Para dependências que requerem uma roda binária pré-compilada (como pacotes com extensões C), a plataforma SOAR usa o cpython padrão criado com base na arquitetura manylinux_2_17_x86_64. Quando selecionar um ficheiro .WHL, verifique se é compatível com esta etiqueta.
Se uma biblioteca não estiver instalada no ambiente virtual, a integração reverte para a versão instalada no sistema.

Se um pacote de dependências não tiver um ficheiro de roda pré-compilado (.WHL) disponível para a arquitetura manylinux_2_17_x86_64 ou se precisar de uma versão específica do código fonte, pode fornecer um URL direto para o código fonte (por exemplo, um ficheiro .tar.gz). O resolvedor de dependências da plataforma, uv, suporta a definição destes URLs de origem na tabela [tool.uv.sources] no seu ficheiro pyproject.toml. Por 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 ver mais detalhes sobre a definição de diferentes tipos de dependências através de uv, consulte a documentação do uv sobre a gestão de dependências.

Crie um gestor personalizado

Os gestores são wrappers para APIs de ferramentas de terceiros. Embora não seja obrigatório, recomendamos que os use para integrações que interagem com ferramentas externas. Os gestores não devem importar do SDK. Após a criação, importe-os para conetores, ações e tarefas.

Para criar um gestor personalizado, siga estes passos:

1. No IDE, clique em Create New Item e selecione Manager.
2. Selecione a integração Armis e introduza o nome de um gestor.
   
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) 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
           ))

Nota: não é necessário um gestor para ações básicas. No entanto, recomendamos que crie um quando agrupar ações pequenas para a análise e a transformação de dados.

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

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

• Raiz da API: o URL base do serviço ao qual está a estabelecer ligação.
• Segredo da API: uma chave confidencial usada para autenticar a sua aplicação junto do serviço.
• Caixa de verificação Validar SSL: se estiver ativada, verifica se o certificado SSL para a ligação ao servidor Armis é válido.
• Caixa de verificação Executar remotamente: uma definição que determina se o código ou a tarefa vai ser executada num servidor remoto em vez de localmente. Quando esta 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 estes passos:

1. Introduza as credenciais corretas.
2. Clique em Guardar > Testar.

Nota: clique sempre em Guardar após atualizar as credenciais. Todas as integrações de terceiros têm de implementar uma ação Ping. O botão Testar executa esta ação para validar a conetividade.

Se a ação Ping estiver em falta, o botão Testar falha e apresenta um X vermelho.

Implemente 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 Action na integração do Armis com o nome Ping.
2. Use o método ArmisManager auth para validar a autenticação.

Ative a integração

Para ativar a integração, siga estes passos:

1. Em Resposta > IDE, clique no botão Ativar/Desativar para a posição ATIVADO.
2. Clique em Guardar. Um botão verde confirma o êxito. As credenciais do Content Hub são transmitidas ao ArmisManager. Se a auth for concluída sem erros, o botão Testar apresenta uma marca de verificação verde.

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

Veja integrações personalizadas

Aceda ao centro de conteúdo e pesquise a integração personalizada que criou. Se não criou uma imagem durante a configuração inicial, é-lhe atribuída a imagem personalizada predefinida. Tenha em atenção que as atualizações do centro de conteúdo não substituem nem eliminam integrações personalizadas.

Exporte e importe no IDE

Realize uma das seguintes ações:

• Para importar integrações, faça o seguinte:
1. Carregue um ficheiro ZIP com a estrutura de pastas correta. A integração aparece no IDE e no Content Hub.
2. Clique em Importar. A integração aparece no IDE e no centro de conteúdo.
3. O sistema gera um ficheiro ZIP com a definição, os scripts e a configuração. A pasta Gestores não é incluída automaticamente.
• Para exportar integrações, faça o seguinte:
• Clique em Exportar para transferir o pacote.

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