Desenvolver sua primeira integração personalizada

Compatível com:

Google SecOps SOAR

Importante:este documento explica como criar integrações personalizadas usando o ambiente de desenvolvimento integrado integrado. Embora ainda seja compatível com protótipos rápidos, esse é considerado um fluxo de trabalho legado. A prática recomendada atual é desenvolver integrações localmente usando seu próprio ambiente de desenvolvimento integrado e gerenciá-las pelo GitHub. Para mais informações sobre o fluxo de trabalho moderno do GitOps, consulte Criar integrações personalizadas.

Neste documento, explicamos como criar uma integração personalizada no ambiente de desenvolvimento integrado (IDE) com a mesma estrutura das integrações comerciais. As integrações personalizadas aparecem no Content Hub, onde você pode configurá-las para diferentes ambientes para uso em playbooks, ações manuais e agentes remotos. Também é possível importá-los e exportá-los, como outros itens do ambiente de desenvolvimento integrado.

Neste exemplo de integração personalizada, você vai criar uma integração personalizada para o produto API XML do WHOIS. Comece criando sua primeira integração, incluindo o processo de registro no produto WHOIS, que envolve se inscrever no produto e criar a chave de API necessária.

Escolha o produto para integração

1. Neste exemplo, você vai fazer a integração com o produto API XML do WHOIS, uma ferramenta de código aberto sem custo financeiro que fornece acesso de API a dados de domínio, incluindo nome do responsável pelo registro, organização, endereço de e-mail, endereço de registro, informações do registrador, datas de criação, expiração e atualização do domínio, disponibilidade e idade do domínio.
2. Acesse WHOIS XML API e faça o registro.
3. Depois de fazer login, acesse a chave de API na página da sua conta: https://user.whoisxmlapi.com/products
4. Use essa chave de API nos parâmetros de integração.

Crie a primeira integração personalizada no ambiente de desenvolvimento integrado

Para criar sua primeira integração personalizada no ambiente de desenvolvimento integrado, siga estas etapas:

1. Na página Resposta > IDE, clique em Adicionar para adicionar um novo item de ambiente de desenvolvimento integrado.
2. Selecione o botão de opção Integração e insira um nome para a integração.
3. Clique em Criar. A integração aparece com um ícone de integração personalizada.
4. Clique em Configurações.
5. Na caixa de diálogo de integração, defina o Ícone, a Descrição, as Dependências do Python e os Parâmetros de integração.
   Neste exemplo, aparecem os seguintes detalhes:
• Uma imagem do logotipo da API XML do Whois é enviada. Essa imagem aparece no Hub de conteúdo com a integração.
• Um ícone SVG foi adicionado ao lado da integração no ambiente de desenvolvimento integrado com uma breve descrição e um parâmetro, a chave de API. Esse é o parâmetro que o produto API XML do Whois exige para a configuração da integração.
• Não é necessário usar outras bibliotecas Python para essa integração. Por padrão, a integração é configurada para ser executada no Python 3.11, e é possível mudar a versão em Configurações.
Observação: as dependências de script são bibliotecas Python que sua integração personalizada precisa importar. É possível adicioná-las em formatos como arquivos Wheel (`WHL`), tarballs (`TAR`), arquivos Gzip (`GZ`) ou arquivos Python (`PY`). Cada integração é executada em um ambiente virtual próprio, permitindo incluir versões específicas da biblioteca, mesmo que uma versão diferente já esteja instalada no sistema. Por exemplo, se você precisar de uma versão específica da biblioteca de solicitações, faça o download dela de uma fonte confiável (como PyPI ou GitHub) e adicione-a às dependências do script. Se a dependência não estiver no ambiente virtual, a integração vai usar a versão instalada no sistema.

Configure a instância padrão

Depois de criar a integração, ela vai aparecer nas integrações de resposta do Google SecOps (pesquise o nome da integração na barra de pesquisa ou filtre o tipo de integração por Integrações personalizadas) com a imagem, a descrição e o parâmetro que você definiu para a integração.

1. Clique em Configurações > Configurar uma instância padrão.
2. Insira sua chave de API e clique em Salvar.
3. Opcional: para configurar a integração para outro ambiente (não o padrão), clique na guia Configurar e defina os parâmetros para essa instância.
Observação: é necessário criar uma ação de ping para que o botão de teste integrado funcione.

Crie uma ação de ping

1. Em Resposta > IDE, clique em Adicionar > Adicionar novo item do IDE.
2. Selecione o botão de opção Ação, insira um nome e selecione a integração.
3. Clique em Criar. Revise o modelo de código gerado.
4. Copie o código a seguir para a ação Ping. A ação Ping usa o parâmetro API Key que você configurou para a integração e o coloca no URL fornecido pelo produto para fins de teste. Para mais detalhes, consulte Criar ações personalizadas.

from SiemplifyAction import SiemplifyAction
from SiemplifyUtils import output_handler
import requests

INTEGRATION_NAME = "My first Integration - Whois XML API"
SCRIPT_NAME = "Whois XML API Ping"

@output_handler
def main():
    siemplify = SiemplifyAction()
    siemplify.script_name = SCRIPT_NAME

    api_key = siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
                                                    param_name="API Key")
    url = "https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&domainName=google.com".format(api_key=api_key)

    res = requests.get(url)
    res.raise_for_status()

    if "ApiKey authenticate failed" in res.content.decode("utf-8"):
        raise Exception("Error, bad credentials")

    siemplify.end("Successful Connection", True)
if __name__ == "__main__":
    main() 

5. Clique no botão acima da ação e em Salvar para testar a conexão com o produto.
6. Acesse o Google SecOps Marketplace, clique em Configurar instância padrão e verifique se a integração está configurada e salva.
7. Clique em Testar para testar a integração. Uma conexão bem-sucedida exibe uma marca de seleção verde. Uma conexão com falha exibe um X com o erro associado.
8. Depois de concluir a autenticação, crie sua primeira ação personalizada na integração personalizada. Para mais detalhes, consulte Criar ações personalizadas.

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