Migrar endpoints do SOAR para a API Chronicle

Compatível com:

Este documento descreve as etapas e considerações para migrar da plataforma da API SOAR descontinuada para a API Chronicle unificada. Este guia tem como objetivo ajudar você a fazer a transição de maneira tranquila e eficiente, minimizando interrupções e aproveitando as novas funcionalidades.

A plataforma da API Chronicle apresenta várias melhorias projetadas para simplificar o processo de desenvolvimento. Ela também aborda limitações e complexidades presentes na API mais antiga.

Pré-requisitos

Antes de realizar a migração da API SOAR, faça o seguinte:

Principais mudanças e melhorias

A tabela a seguir destaca as principais diferenças entre as plataformas de API antiga e nova

Área do recurso API antiga API nova Detalhes
Autenticação Token da API OAuth 2.0 O novo método de autenticação oferece maior segurança e padroniza o processo.
Modelos de dados Estruturas fixas Design voltado a recursos Esse novo design melhora a consistência dos dados e simplifica a manipulação de objetos.
Nomenclatura de endpoints Inconsistente RESTful e padronizada A nomenclatura consistente torna a API mais intuitiva e fácil de integrar.

Programação da descontinuação

A plataforma da API antiga para SOAR será totalmente descontinuada em 30 de setembro de 2026. Recomendamos concluir a migração antes dessa data para evitar interrupções no serviço.

Etapas da migração

Esta seção descreve as etapas para migrar seus aplicativos para a API Chronicle:

Consulte a documentação

Familiarize-se com a documentação abrangente da nova API, incluindo o guia de referência da API Chronicle.

Mapear endpoints para a nova plataforma de API

Identifique os novos endpoints correspondentes para cada uma das chamadas de API antigas que seu aplicativo faz. Da mesma forma, mapeie os modelos de dados antigos para os novos, considerando mudanças estruturais ou novos campos. Para mais detalhes, consulte a tabela de mapeamento de endpoints de API.

Opcional: criar uma integração de preparo

Se você estiver editando uma integração personalizada ou um componente de uma integração comercial, recomendamos que você envie as mudanças para uma integração de preparo primeiro. Esse processo permite testar sem afetar os fluxos de automação de produção. Se você estiver migrando um aplicativo personalizado que usa a API SOAR, pule para a próxima etapa. Para mais detalhes sobre o preparo da integração, consulte Testar integrações no modo de preparo.

Atualizar o endpoint e os URLs do serviço

Um endpoint de serviço é o URL de base que especifica o endereço de rede de um serviço de API. Um único serviço pode ter vários endpoints de serviço. O Chronicle é um serviço regional e só oferece suporte a endpoints regionais.

Todos os novos endpoints usam um prefixo consistente, tornando o endereço do endpoint final previsível. O exemplo a seguir mostra a nova estrutura de URL do endpoint:

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

Essa estrutura torna o endereço final do endpoint da seguinte maneira:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Em que:

  • service_endpoint: um endereço do serviço regional
  • api_version: a versão da API a ser consultada. Pode ser v1alpha, v1beta ou v1.
  • project_id: o ID do projeto (o mesmo que você definiu para as permissões do IAM)
  • location: o local do projeto (região), igual aos endpoints regionais
  • instance_id: o ID do cliente do Google Security Operations SIEM.

Endereços regionais:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

Por exemplo, para receber uma lista de todos os casos em um projeto nos EUA:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Atualizar o método de autenticação

A nova API usa Google Cloud oIAM para autenticação. Você precisa atualizar seu aplicativo ou integração de resposta para implementar esse novo fluxo de autenticação. Verifique se o usuário que executa o script tem as permissões corretas para os endpoints que está tentando acessar. Para implementar esse novo fluxo, atualize suas integrações ou aplicativos de resposta. Verifique se o usuário que executa o script tem as permissões necessárias para os endpoints de destino. Para instruções detalhadas, consulte a página Autenticar na API Chronicle.

Mapear a conta de serviço ou a identidade da carga de trabalho para parâmetros do SOAR

Se você estiver usando uma conta de serviço ou federação de identidade da carga de trabalho para autenticar na API Chronicle, autorize-a na plataforma para garantir que ela possa se comunicar com o Google SecOps. Esse mapeamento é necessário para fornecer à conta de serviço ou à identidade da carga de trabalho o acesso necessário a papéis e ambientes do SOC.

Para mapear sua conta de serviço:

  1. Acesse Configurações do SOAR > Avançado > Mapeamento de grupos.

  2. Clique em add Adicionar.

  3. Na caixa de diálogo Adicionar papel, insira o endereço de e-mail completo da sua conta de serviço ou a string principal da identidade da carga de trabalho no campo Papel do IAM / grupo do IdP

  4. Selecione os papéis do SOC e os ambientes adequados.

  5. Clique em Adicionar.

Para mais informações sobre o mapeamento de usuários e contas de serviço, consulte Mapear usuários na plataforma usando uma identidade de terceiros ou Mapear usuários na plataforma usando o Cloud Identity.

Atualizar a lógica da API

Analise os novos modelos de dados e estruturas de endpoint fornecidos na referência da API. Nem todos os métodos mudaram significativamente, e alguns códigos atuais podem ser reutilizados. O objetivo principal é revisar a nova documentação de referência e, para cada caso de uso específico, identificar e implementar as mudanças necessárias nos nomes de campos e nas estruturas de dados na lógica do aplicativo.

Testar sua integração

Teste o aplicativo atualizado em uma integração de preparo antes de implantar na produção:

  1. Crie um plano de teste: defina casos de teste que cubram todas as funcionalidades migradas.
  2. Executar testes: execute testes automatizados e manuais para confirmar a precisão e a validade.
  3. Monitore a performance: avalie a performance do aplicativo com a nova API.

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