Migrar para a API Chronicle

Compatível com:

Google SecOps SOAR

Este documento é válido para quem chama a API SOAR de forma programática usando integrações, scripts personalizados ou ações personalizadas. Este documento descreve as etapas e considerações para ajudar você a atualizar as referências da API programáticas para os novos endpoints de API SOAR como parte da API Chronicle.

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

A API SOAR legada e as chaves de API vão estar disponíveis até 31 de março de 2027. Depois disso, elas vão deixar de funcionar.

Pré-requisitos

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

• Conclua o estágio 1 da migração.

Principais mudanças e melhorias

A tabela a seguir destaca as principais diferenças entre as superfícies de API antiga e nova:

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

Programação da descontinuação

A superfície da API antiga para SOAR será totalmente descontinuada em 31 de março de 2027. Recomendamos que você conclua a migração antes dessa data para evitar interrupções no serviço.

Etapas da migração

Nesta seção, descrevemos as etapas para migrar seus aplicativos para a API Chronicle:

Consulte a documentação

Conheça a documentação completa da nova API, incluindo o guia de referência da API Chronicle.

Mapear endpoints para a nova superfície da 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 as mudanças estruturais ou os 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 envie as mudanças para uma integração de teste primeiro. Esse processo permite que você teste 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 detalhes sobre o modo de testes de integração, consulte Testar integrações no modo de testes.

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. O Chronicle é um serviço regional e só aceita 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 o seguinte:

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

Em que:

• service_endpoint: um endereço de 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); o mesmo que os endpoints regionais.
• instance_id: o ID de cliente do SIEM do Google Security Operations.

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

• nós: https://chronicle.us.rep.googleapis.com

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

Por exemplo, para ver 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 o Google Cloud IAM para autenticação. Você precisará 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 está executando 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 os parâmetros do SOAR

Se você estiver usando uma conta de serviço ou uma federação de identidade de 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 aos papéis e ambientes do SOC.

Para conceder acesso à conta de serviço ou acesso à federação de identidade de carga de trabalho ao Google SecOps, é necessário mapear a identidade para os parâmetros de controle de acesso da plataforma. Esse mapeamento é uma etapa obrigatória para fornecer à identidade o acesso necessário aos papéis do SOC e aos ambientes necessários para realizar tarefas automatizadas ou operações de API.

Observação: conceder papéis do IAM do Google Cloud a uma conta de serviço ou principal é necessário, mas não suficiente para o acesso à API SOAR do Google SecOps. Se a conta de serviço não estiver explicitamente mapeada em Mapeamento de grupo, as solicitações de API vão falhar com um erro 401 UNAUTHENTICATED, mesmo quando todos os papéis do IAM necessários no nível do projeto estiverem configurados.

1. Acesse Configurações > Gerenciamento de acesso > Mapeamento de grupos.
2. Clique em add Adicionar.

3. Preencha os campos na caixa de diálogo Adicionar mapeamento para mapear a identidade aos parâmetros de controle de acesso da plataforma.

   1. No campo IdP / Grupo de usuários, insira uma das seguintes opções:
      • O endereço de e-mail completo da sua conta de serviço, se a identidade tiver sido configurada usando o Cloud Identity.
      • A string principal da Identidade da carga de trabalho, se a identidade tiver sido configurada usando a federação de identidade de colaboradores.

   2. Configure os seguintes campos de controle de acesso:

      Campo	Descrição
      Grupos de permissões	Selecione os grupos de permissões para definir quais módulos e submódulos a identidade pode acessar.
      Funções do SOC	Selecione as funções do SOC para definir o papel da identidade (como Nível 1).
      Ambientes	Selecione os ambientes ou grupos de ambientes que a identidade pode acessar (como Todos os ambientes).
      Participantes do grupo	Insira os e-mails dos usuários necessários, se aplicável. Pressione Enter depois de adicionar cada e-mail.
      Ações restritas	Selecione as ações restritas para limitar operações específicas nos módulos.

4. Clique em Adicionar.

Para mais informações sobre como mapear usuários e contas de serviço, consulte Mapear usuários na plataforma usando a 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 as estruturas de endpoint fornecidos na referência da API. Nem todos os métodos mudaram significativamente, e alguns códigos podem ser reutilizados. O objetivo principal é analisar 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: realize testes automatizados e manuais para confirmar a precisão e a validade.
3. Monitorar o desempenho: avalie o desempenho do aplicativo com a nova API.

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