Migrar da API de SIEM legada para a API Chronicle

Compatível com:

Este documento ajuda você a gerenciar aplicativos que chamam qualquer uma das APIs de SIEM legadas (API Backstory e API Ingestion). Ele descreve as etapas que você precisa seguir para configurar o acesso programático e atualizar todas as referências dos endpoints da API de SIEM legada para os endpoints da API Chronicle moderna.

Para uma visão geral rápida do processo de migração, assista o vídeo incorporado.

A superfície da API Chronicle apresenta várias melhorias projetadas para simplificar o processo de desenvolvimento e se alinhar aos Google Cloud padrões de API para melhorar a confiabilidade, a segurança, o desempenho e a integração com os Registros de auditoria do Cloud, o Cloud Monitoring, o Cloud Identity e o Identity and Access Management (IAM). Ela também aborda muitas das limitações e complexidades das APIs legadas.

O que vai mudar

Todas as solicitações programáticas para endpoints legados da API Backstory e da API Ingestion precisam fazer a transição para a API Chronicle moderna. Se sua organização usa integrações personalizadas, scripts de automação ou ferramentas de terceiros que fazem chamadas para esses endpoints legados, é necessário atualizar essas cargas de trabalho para usar endpoints e fluxos de autenticação modernos antes de 20 de julho de 2027.

O que não vai mudar

As ações realizadas diretamente na interface do usuário (UI) do Google SecOps já invocam a API Chronicle moderna. Se sua organização interage apenas com o Google SecOps pela UI ou se as integrações já chamam endpoints da API Chronicle, não é necessário fazer nada.

Principais mudanças e melhorias

A tabela a seguir destaca as principais diferenças entre a API de SIEM legada e a API Chronicle:

Área do recurso API de SIEM legada API Chronicle Detalhes
Gerenciamento de credenciais Processo manual envolvendo representantes do Google Gerenciamento de autoatendimento de contas de serviço, credenciais e permissões do IAM O gerenciamento de credenciais e do IAM por autoatendimento simplifica a integração e remove a dependência de solicitações de suporte manual.
Padrões de compliance Suporte limitado Suporte integrado para controles de residência de dados, VPC Service Controls, transparência no acesso, CMEK e FedRAMP Os controles de infraestrutura integrados modernos atendem aos padrões regulamentares e de compliance do setor.
Geração de registros e auditoria Fluxos de auditoria legados Registros de auditoria do Cloud integrados ao seu Google Cloud projeto A integração direta fornece trilhas de auditoria e monitoramento centralizados.
Autenticação Token de API e credenciais da conta de serviço OAuth 2.0 com suporte para métodos de autenticação modernos, incluindo a federação de identidade da carga de trabalho e contas de serviço, conforme descrito em Autenticação para Google Cloud APIs e serviços Esses métodos de autenticação modernos oferecem segurança aprimorada e padronizam o fluxo de credenciais.
Modelos de dados e design de API Estruturas planas e proprietárias Design orientado a recursos, arquitetura RESTful e nomenclatura padronizada seguindo as AIPs Esse design moderno melhora a consistência dos dados, torna a API mais intuitiva 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.
Ecossistema Muito limitado Integração com MCP, Terraform, bibliotecas de cliente e SDKs Ampla compatibilidade com ferramentas de nuvem e frameworks de automação modernos.

Programação da descontinuação

A API de SIEM legada será desativada em 20 de julho de 2027. Recomendamos que você conclua a migração antes dessa data para evitar interrupções no serviço:

  • A partir de 26 de outubro de 2026, não será mais possível chamar APIs legadas (API Backstory e API Ingestion) de novas instâncias.
  • Até 20 de julho de 2027, é necessário migrar todas as instâncias atuais para a API Chronicle, já que as APIs legadas não estarão mais disponíveis.

Antes de começar

Antes de migrar para a API Chronicle, conclua as seguintes etapas:

Migrar para a API Chronicle

Migre seus scripts e integrações das APIs legadas para a API Chronicle seguindo estas etapas:

  1. Auditar o uso da API: identifique todos os scripts e integrações no seu ambiente que invocam endpoints legados.
  2. Configurar a autenticação e a autorização: configure seu ambiente para autenticar e autorizar solicitações para a API Chronicle.
  3. Mapear endpoints e atualizar URLs: substitua os endpoints legados pelos equivalentes regionais modernos.
  4. Atualizar a lógica da API: ajuste os payloads de solicitação e o tratamento de respostas para corresponder aos modelos de dados da API moderna.
  5. Testar sua integração: valide as mudanças em um ambiente de staging antes de implantar na produção.

Auditar o uso da API

Audite seu ambiente para identificar scripts ou integrações que invocam backstory.googleapis.com ou malachiteingestion-pa.googleapis.com. É possível identificar essas integrações revisando a base de código, os scripts de automação e as ferramentas de terceiros.

Configurar a autenticação e a autorização

Configure seu ambiente para autenticar e autorizar solicitações para a API Chronicle:

  1. Escolha um método de autenticação:escolha como suas cargas de trabalho são autenticadas na API Chronicle usando um dos métodos listados. Recomendamos o uso da federação de identidade da carga de trabalho para melhorar a segurança, já que ela evita o gerenciamento e o armazenamento de chaves de conta de serviço de longa duração. Para cenários de autenticação avançados (como identidade temporária de conta de serviço), consulte Autenticar na API Chronicle.

  2. Conceder permissões do IAM:conceda as permissões do IAM necessárias à identidade (a conta de serviço ou a principal de identidade externa) usada para autenticação. Atribua os papéis do IAM necessários à sua identidade, dependendo do nível de acesso necessário. Consulte Gerenciar o acesso a projetos, pastas e organizações para mais detalhes. Os papéis predefinidos incluem o seguinte:

    Recomendamos usar o princípio de privilégio mínimo para conceder apenas as permissões necessárias para suas automações, aproveitando papéis do IAM personalizados ou predefinidos.

  3. Definir a variável de ambiente de credenciais:configure o ambiente de execução para usar as credenciais com o Application Default Credentials (ADC) definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Essa variável precisa apontar para o arquivo JSON da chave da conta de serviço transferida por download ou para o arquivo de configuração de credenciais da federação de identidade da carga de trabalho. As Google Cloud bibliotecas de cliente detectam automaticamente essa variável para autenticar solicitações:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

  4. Atualizar escopos do OAuth:atualize a string de escopo se os scripts de integração legados solicitaram explicitamente escopos do OAuth para geração de tokens. O escopo legado não concede acesso à superfície da API moderna:

    • Escopo legado do Backstory:https://www.googleapis.com/auth/chronicle-backstory
    • Escopo do Chronicle:https://www.googleapis.com/auth/chronicle (ou o escopo mais amplo https://www.googleapis.com/auth/cloud-platform).

Mapear endpoints e atualizar URLs

Conheça a superfície da API Chronicle, mapeie suas chamadas legadas e atualize os endpoints de serviço no aplicativo.

Revisar a documentação de referência

Conheça a documentação abrangente da API Chronicle.

Mapear endpoints para a API Chronicle

Identifique os endpoints modernos correspondentes para cada uma das chamadas de API legadas que seu aplicativo faz. Da mesma forma, mapeie seus modelos de dados atuais para as estruturas modernas, considerando todas as mudanças de esquema ou campos adicionais. Para detalhes em todos os endpoints de SIEM, consulte Mapeamento endpoint de API de SIEM. Se o fluxo de trabalho também interage com endpoints SOAR, consulte a tabela de mapeamento de endpoint de API SOAR.

Atualizar o endpoint de serviço

Atualize o URL de base das chamadas de API para apontar para o endpoint de serviço regional correto. A API Chronicle é um serviço regional. Portanto, é necessário chamar o endpoint de serviço regional que corresponde ao local da instância do Google SecOps.

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

[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), o mesmo que os endpoints regionais.
  • instance_id: o ID do cliente do Google Security Operations SIEM.

Endereços regionais:

  • africa-south1: https://africa-south1-chronicle.googleapis.com ou https://chronicle.africa-south1.rep.googleapis.com
  • asia-northeast1: https://asia-northeast1-chronicle.googleapis.com ou https://chronicle.asia-northeast1.rep.googleapis.com
  • asia-south1: https://asia-south1-chronicle.googleapis.com ou https://chronicle.asia-south1.rep.googleapis.com
  • asia-southeast1: https://asia-southeast1-chronicle.googleapis.com ou https://chronicle.asia-southeast1.rep.googleapis.com
  • asia-southeast2: https://asia-southeast2-chronicle.googleapis.com ou https://chronicle.asia-southeast2.rep.googleapis.com
  • australia-southeast1: https://australia-southeast1-chronicle.googleapis.com ou https://chronicle.australia-southeast1.rep.googleapis.com
  • europe-west12: https://europe-west12-chronicle.googleapis.com ou https://chronicle.europe-west12.rep.googleapis.com
  • europe-west2: https://europe-west2-chronicle.googleapis.com ou https://chronicle.europe-west2.rep.googleapis.com
  • europe-west3: https://europe-west3-chronicle.googleapis.com ou https://chronicle.europe-west3.rep.googleapis.com
  • europe-west6: https://europe-west6-chronicle.googleapis.com ou https://chronicle.europe-west6.rep.googleapis.com
  • europe-west9: https://europe-west9-chronicle.googleapis.com ou https://chronicle.europe-west9.rep.googleapis.com
  • me-central1: https://me-central1-chronicle.googleapis.com ou https://chronicle.me-central1.rep.googleapis.com
  • me-central2: https://me-central2-chronicle.googleapis.com ou https://chronicle.me-central2.rep.googleapis.com
  • me-west1: https://me-west1-chronicle.googleapis.com ou https://chronicle.me-west1.rep.googleapis.com
  • northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com ou https://chronicle.northamerica-northeast2.rep.googleapis.com
  • southamerica-east1: https://southamerica-east1-chronicle.googleapis.com ou https://chronicle.southamerica-east1.rep.googleapis.com
  • Estados Unidos (us): https://us-chronicle.googleapis.com ou https://chronicle.us.rep.googleapis.com
  • Europa (eu): https://eu-chronicle.googleapis.com ou https://chronicle.eu.rep.googleapis.com

Para uma lista abrangente de todos os endpoints compatíveis, consulte a referência oficial na documentação do endpoint de serviço da API Chronicle.

Por exemplo, para listar todas as regras de detecção de uma instância no local us, envie a seguinte solicitação:

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

Da mesma forma, para consultar recursos SOAR, como casos, usando o alias de endpoint regional (rep), envie a seguinte solicitação:

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

Atualizar a lógica da API

Revise a referência REST da API Chronicle para identificar e implementar mudanças nos nomes de campos e nas estruturas de dados do aplicativo. Embora alguns endpoints legados possam permanecer semelhantes, é necessário atualizar as integrações para corresponder aos modelos de dados e estruturas de endpoints mais recentes.

Usar Google Cloud bibliotecas de cliente

Simplifique a integração para processar automaticamente a autenticação, a atualização de tokens e os detalhes de transporte. Recomendamos o uso dasbibliotecas de cliente oficiais Google Cloud para fazer isso. O suporte da API Chronicle está disponível em oito linguagens de programação, incluindo Python, Go, Java, Node.js, e C#. Para detalhes de instalação e uso, consulte Bibliotecas de cliente e SDK.

Testar sua integração

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

  1. Criar 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. Monitorar o desempenho:avalie o desempenho do aplicativo com a API moderna.

Resolver problemas

Esta seção descreve como resolver erros comuns que podem ocorrer durante a migração.

HTTP 403 Forbidden ou PERMISSION_DENIED

Se as chamadas de API retornarem um erro HTTP 403 Forbidden ou PERMISSION_DENIED, verifique o seguinte:

  • Método de autenticação e principal:verifique se você está usando as credenciais corretas.
    • Se você estiver usando a federação de identidade da carga de trabalho, verifique se a principal de identidade externa corresponde à principal vinculada aos papéis do IAM no seu projeto.
    • Se você estiver usando uma conta de serviço, verifique se a conta de serviço correta está sendo usada e se ela não foi desativada. Não use contas de serviço legadas (que geralmente contêm bk ou malachite-cx no endereço de e-mail) para endpoints modernos da API Chronicle.
  • Papéis do IAM:verifique se a conta de serviço ou a principal de identidade externa recebeu os papéis do IAM predefinidos ou personalizados necessários (como Chronicle API Viewer ou Chronicle API Editor) no seu Google Cloud projeto. Para permissões granulares de endpoint, consulte Mapeamento endpoint de API SIEM.

HTTP 401 Unauthorized ou UNAUTHENTICATED

Se as chamadas de API falharem com HTTP 401 Unauthorized ou UNAUTHENTICATED, verifique o seguinte:

  • Escopos do OAuth:verifique se os scripts estão solicitando o escopo moderno: https://www.googleapis.com/auth/chronicle (ou o escopo mais amplo https://www.googleapis.com/auth/cloud-platform). O escopo legado (https://www.googleapis.com/auth/chronicle-backstory) não concede acesso à API Chronicle moderna.
  • Variável de ambiente:confirme se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida e aponta para o arquivo de chave JSON correto ou para o arquivo de configuração da federação de identidade da carga de trabalho no ambiente de execução.

HTTP 404 Not Found ou incompatibilidades regionais

Se as chamadas de API retornarem um erro HTTP 404 Not Found ou falharem ao se conectar, verifique os endpoints regionais:

  • Endpoint regional:a API Chronicle é um serviço regional. Verifique se você está chamando o endpoint que corresponde à região da instância do Google SecOps (por exemplo, https://europe-west3-chronicle.googleapis.com para uma instância em Frankfurt). O envio de solicitações para uma região diferente resultará em erros. Para uma lista completa de endereços regionais, consulte Atualizar o endpoint de serviço ou a referência oficial do endpoint de serviço.

A seguir

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