O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Migrar da API SIEM legada para a API Chronicle

Compatível com:

Google SecOps SIEM

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 as referências dos endpoints da API SIEM legada para os endpoints modernos da API Chronicle.

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

A superfície da API Chronicle apresenta várias melhorias projetadas para simplificar o processo de desenvolvimento e se alinhar aos padrões de API do Google Cloud 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 os endpoints legados da API Backstory e da API Ingestion precisam ser transferidas para a API Chronicle moderna. Se a sua organização usa integrações personalizadas, scripts de automação ou ferramentas de terceiros que fazem chamadas para esses endpoints legados, atualize essas cargas de trabalho para usar endpoints e fluxos de autenticação modernos antes de 20 de julho de 2027. Além disso, se a organização usa o Google Security Operations SOAR, é necessário atualizar as integrações e os conectores do SOAR (como a integração do Google Chronicle) para usar a API Chronicle. Para mais detalhes, consulte Migrar integrações do SOAR.

O que não vai mudar

As ações realizadas diretamente na interface do usuário (UI) do Google Security Operations já invocam a API Chronicle moderna. Se a sua organização só interage 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 SIEM legada e a API Chronicle:

Área do recurso	API 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 IAM de autoatendimento simplifica a integração e elimina a dependência de solicitações de suporte manuais.
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 regulatórios e de conformidade do setor.
Geração de registros e auditoria	Fluxos de auditoria legados	Registros de auditoria do Cloud integrados ao seu projeto do Google Cloud	A integração direta oferece 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 Identidade da carga de trabalho e contas de serviço, conforme descrito em Autenticação para APIs e serviços do Google Cloud	Esses métodos modernos de autenticação oferecem mais segurança 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 de acordo com as AIPs	Esse design moderno melhora a consistência dos dados, torna a API mais intuitiva e simplifica a manipulação de objetos.
Nomeação de endpoints	Inconsistente	RESTful e padronizado	Uma 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 modernas e frameworks de automação.
Autorização de parceiro	Token de parceiro ou chave de API usada diretamente nos códigos do cliente	Delegação do IAM entre projetos para recursos de locatário; métodos TenantService com escopo de parceiro	Os métodos TenantService são executados no projeto do parceiro. Todas as outras APIs de locatário exigem a delegação do IAM entre projetos concedida pelo locatário no projeto de locatário.

Autorização de parceiro

Para fluxos de trabalho de parceiros multilocatários, a autorização na API Chronicle depende da propriedade do recurso. O projeto que hospeda um recurso determina quais credenciais e permissões do IAM um parceiro precisa. O escopo das operações do locatário para credenciais delegadas pelo locatário está alinhado com o princípio de segurança principal de que os parceiros não podem acessar, recuperar ou modificar dados do locatário sem permissão explícita concedida pelo locatário. A tabela a seguir compara a autorização de parceiros na API Backstory legada e na API Chronicle:

API	Métodos	Escopo do recurso	Autorização
API Backstory legada	`/v1/partner/customer/*` endpoints	Todos os códigos de cliente do parceiro	Os parceiros chamam esses endpoints diretamente com os próprios tokens de parceiro ou chaves de API.
API Chronicle: `TenantService`	`CreateTenant`, `ListTenants` e `UpdateTenant`	Instância do parceiro: `projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*`	Os parceiros chamam esses métodos diretamente com as próprias contas de serviço ou credenciais que têm permissões `chronicle.googleapis.com/tenants.*` no projeto do parceiro.
API Chronicle: outros serviços, como `InstanceService` e `ForwarderService`	`GetInstance`, `UpdateInstance`, `GenerateForwarderFiles` e outros métodos com escopo de locatário	Instância do locatário: `projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...`	As credenciais do parceiro não podem acessar nem modificar os dados do locatário. O administrador do locatário precisa conceder papéis do IAM, como `roles/chronicle.admin`, `roles/chronicle.viewer` ou um papel personalizado, à conta de serviço do parceiro ou ao principal da federação de identidade da carga de trabalho no projeto do Google Cloud do locatário.

Programação da descontinuação

A API SIEM legada será desativada em 20 de julho de 2027. Recomendamos concluir 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, você precisa 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 o seguinte:

Implantar na infraestrutura moderna de SIEM:verifique se a instância está implantada no seu projeto ou no do seu parceiro MSSP Google Cloud usando a infraestrutura moderna de SIEM. Para instruções detalhadas, consulte Visão geral da migração do SIEM.
Ative a API Chronicle:no console do Google Cloud , acesse o projeto que hospeda sua instância e ative a API Chronicle (chronicle.googleapis.com). Para mais detalhes, consulte Como ativar uma API no projeto do Google Cloud .
Identifique as integrações do SOAR:se o ambiente conectar o SOAR do Google SecOps ao SIEM do Google Security Operations, verifique os conectores atuais. Para mais detalhes, consulte Migrar integrações do SOAR.

Migrar integrações do SOAR

Se a sua organização conecta o SOAR do Google SecOps ao SIEM do Google SecOps, você precisa migrar as integrações e os conectores do SOAR (como a integração do Google Chronicle) para usar a API Chronicle.

Para instruções detalhadas sobre como fazer upgrade da integração e dos conectores do Google Chronicle para usar a API Chronicle, incluindo como localizar a raiz da API Chronicle do seu ambiente e configurar as credenciais de autenticação, consulte Migração da API Backstory para a API Chronicle.

Migrar para a API Chronicle

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

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

Auditar o uso da API

Audite seu ambiente para identificar scripts ou integrações personalizados que invocam backstory.googleapis.com ou malachiteingestion-pa.googleapis.com. Para identificar essas integrações, revise sua base de código, scripts de automação e ferramentas de terceiros. Se a organização também usa o Google SecOps SOAR, consulte Migrar integrações do SOAR.

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

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

Escolha um método de autenticação:escolha como suas cargas de trabalho se autenticam na API Chronicle usando um dos métodos listados. Recomendamos usar a 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.
- Federação de Identidade da Carga de Trabalho (recomendado): configure a Federação de Identidade da Carga de Trabalho para permitir que as cargas de trabalho em execução fora do Google Cloud sejam autenticadas usando identidades externas.
- Contas de serviço:se você precisar usar contas de serviço, crie uma no projeto do Google Cloud e gere e faça o download de uma chave privada no formato JSON. Mantenha essa chave em segurança.
Conceder permissões do IAM:conceda as permissões do IAM necessárias à identidade (a conta de serviço ou o principal de identidade externa) usada para autenticação. Consulte o mapeamento endpoint de API SIEM para encontrar as permissões específicas do IAM necessárias para os endpoints modernos que substituem as chamadas legadas.
- Papel personalizado (recomendado): crie um papel personalizado do IAM com as permissões necessárias e conceda o papel personalizado à conta de serviço ou ao principal de identidade externa.
- Papel predefinido:conceda um papel predefinido do Google SecOps à conta de serviço ou ao principal de identidade externa. Isso provavelmente vai conceder mais acesso do que o necessário para uma automação específica.
- Delegação de parceiro multilocatário:se você for um MSSP ou parceiro que gerencia recursos de locatário fora do TenantService (como GetInstance, UpdateInstance ou GenerateForwarderFiles), o administrador do locatário precisará conceder explicitamente à sua conta de serviço ou ao principal da federação de identidade da carga de trabalho os papéis do IAM necessários no projeto do Google Cloud do locatário.
Defina 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 que foi baixado ou para o arquivo de configuração de credenciais da federação de identidade da carga de trabalho. As bibliotecas de cliente doGoogle Cloud detectam automaticamente essa variável para autenticar solicitações:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Atualizar escopos do OAuth:atualize a string de escopo se os scripts de integração legados tiverem solicitado explicitamente escopos do OAuth para a 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

Familiarize-se com a superfície da API Chronicle, mapeie suas chamadas legadas e atualize os endpoints de serviço no seu aplicativo.

Analisar 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 as mudanças de esquema ou os campos adicionais. Para detalhes sobre todos os endpoints do SIEM, consulte Mapeamento endpoint de API SIEM. Se o fluxo de trabalho também interagir com endpoints do SOAR, consulte a tabela de mapeamento de endpoint de API SOAR.

Atualizar o endpoint do 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 sua instância do Google SecOps.

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

[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), igual aos endpoints regionais.
instance_id: o ID de cliente do Google SecOps 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 completa 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 do SOAR, como casos, usando o alias do 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

Verificar a configuração do firewall

Se você usa firewalls ou proxies autenticados entre seu ambiente e a Internet, configure regras para permitir conexões HTTPS de saída na porta TCP 443. Permita o acesso aos seguintes hosts:

Endpoint de API Chronicle: <var>REGION</var>-chronicle.googleapis.com ou chronicle.<var>REGION</var>.rep.googleapis.com
Endpoints de autenticação do Google: oauth2.googleapis.com, www.googleapis.com e accounts.google.com (além de sts.googleapis.com e iamcredentials.googleapis.com se você usar a federação de identidade da carga de trabalho ou a identidade temporária de conta de serviço)

Para detalhes completos sobre endpoints, orientações sobre intervalos de IP do Google, opções de conectividade privada e etapas de verificação, consulte Verificar a configuração do firewall para a API Chronicle.

Atualizar a lógica da API

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

Usar as Google Cloud bibliotecas de cliente

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

Testar sua integração

Teste o aplicativo atualizado em um ambiente de teste antes de implantar na produção:

Crie um plano de teste:defina casos de teste que cubram todas as funcionalidades migradas.
Executar testes:faça testes automatizados e manuais para confirmar a precisão e a validade.
Monitorar o desempenho:avalie o desempenho do seu aplicativo com a API moderna.

Resolver problemas

Nesta seção, descrevemos 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 estiver usando a federação de identidade da carga de trabalho, verifique se o principal de identidade externa corresponde ao principal vinculado aos papéis do IAM no projeto.
- Se estiver usando uma conta de serviço, verifique se ela é a correta e se 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 o principal de identidade externa recebeu os papéis do IAM predefinidos ou personalizados necessários (como Chronicle API Viewer ou Chronicle API Editor) no projeto do Google Cloud . Para permissões de endpoint granulares, consulte Mapeamento endpoint de API SIEM.

HTTP 401 Não autorizado ou NÃO AUTENTICADO

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

Escopos do OAuth:verifique se os scripts personalizados 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 ou o arquivo de configuração da federação de identidade da carga de trabalho correto no ambiente de execução.

HTTP 404 não encontrado ou incompatibilidades regionais

Se as chamadas de API retornarem um HTTP 404 Not Found ou não se conectarem, 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 sua 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 vai resultar em erros. Para uma lista completa de endereços regionais, consulte Atualizar o endpoint de serviço ou a Referência oficial de endpoint de serviço.

A seguir

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