Exportar registros brutos para um bucket autogerenciado do Google Cloud Storage
A API de Exportação de dados facilita a exportação em massa dos seus dados de segurança do Google Security Operations para um bucket do Google Cloud Storage que você controla. Esse recurso é compatível com a retenção de dados críticos de longo prazo, a análise forense histórica e os requisitos de conformidade rigorosos (como SOX e GDPR).
Para informações detalhadas de referência da API, consulte Exportação de dados da API (aprimorada).
A API Data Export oferece uma solução escalonável e confiável para exportações de dados pontuais e processa solicitações de até 100 TB.
Como um pipeline gerenciado, ele oferece recursos essenciais de nível empresarial, incluindo:
- Novas tentativas automatizadas em erros temporários
- Monitoramento abrangente do status do job
- Uma trilha de auditoria completa para cada job de exportação
A API particiona logicamente os dados exportados por data e hora no bucket do Google Cloud Storage.
Com esse recurso, é possível criar fluxos de trabalho de transferência de dados em grande escala. O Google SecOps gerencia a complexidade do processo de exportação para fornecer estabilidade e desempenho.
Principais vantagens
A API Exportação de dados oferece uma solução resiliente e auditável para gerenciar o ciclo de vida dos seus dados de segurança, com os seguintes benefícios principais:
- Confiabilidade: o serviço lida com transferências de dados em grande escala. O sistema
usa uma estratégia de espera exponencial para repetir automaticamente os jobs de exportação que
encontram problemas temporários (por exemplo, problemas de rede temporários), tornando-o
resiliente. Se o job de exportação falhar devido a um erro temporário, ele
vai tentar novamente várias vezes. Se um job falhar permanentemente após todas as
novas tentativas, o sistema vai atualizar o status para
FINISHED_FAILURE, e a resposta da API para esse job vai conter uma mensagem de erro detalhada que explica a causa. Auditabilidade abrangente: para atender a padrões rigorosos de conformidade e segurança, o sistema captura todas as ações relacionadas a um job de exportação em uma trilha de auditoria imutável. Essa trilha inclui a criação, o início, o sucesso ou a falha de cada job, além do usuário que iniciou a ação, um carimbo de data/hora e os parâmetros do job.
Otimizada para desempenho e escalonamento: a API usa um sistema robusto de gerenciamento de jobs. Esse sistema inclui filas e priorização para fornecer estabilidade à plataforma e impedir que um único locatário monopolize os recursos.
Maior integridade e acessibilidade dos dados: o sistema organiza automaticamente os dados em uma estrutura de diretório lógica no bucket do Google Cloud Storage, o que ajuda a localizar e consultar janelas de tempo específicas para análise histórica.
Segurança: a API foi projetada para ser totalmente compatível com chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) (segurança de confiança zero) e RBAC de dados (acesso de privilégio mínimo). Os jobs de exportação herdam o escopo de visibilidade de dados do usuário que aciona a solicitação para evitar a extração de dados não autorizada. O pipeline de exportação também é totalmente integrado ao Google Cloud Key Management Service, e os dados permanecem criptografados em repouso no bucket do Google Cloud Storage usando suas próprias chaves.
Principais termos e conceitos
- Job de exportação: uma única operação assíncrona para exportar um período específico de dados de registro para um bucket do Google Cloud Storage. O sistema rastreia cada
job com um
dataExportIdexclusivo. - Status do job: o estado atual de um job de exportação no ciclo de vida dele (por
exemplo,
IN_QUEUE,PROCESSING,FINISHED_SUCCESS). - Bucket do Google Cloud Storage: um bucket do Google Cloud Storage de propriedade do usuário que serve como destino para os dados exportados.
- Tipos de registro: as categorias específicas de registros que podem ser exportadas (por exemplo,
NIX_SYSTEM,WINDOWS_DNS,CB_EDR). Para mais detalhes, consulte a lista de todos os tipos de registro compatíveis.
Entender a estrutura de dados exportada
Quando um job é concluído com sucesso, o sistema grava os dados no bucket do Cloud Storage. Ele usa uma estrutura de diretório particionada específica para simplificar o acesso e a consulta de dados.
Estrutura do caminho do diretório: gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/logdata-SHARD_INDEX.csv
Em que:
- GCS_BUCKET_NAME: refere-se ao nome do bucket do Google Cloud Storage.
- EXPORT_JOB_NAME: refere-se ao UUID
dataExportIdexclusivo do job de exportação (sem hifens no caminho do objeto). - LOGTYPE: refere-se ao nome do tipo de registro dos dados exportados (por exemplo,
GCP_DNSouWINDOWS_DNS). - EVENT_TIME_BUCKET: refere-se ao intervalo de horas dos carimbos de data/hora de eventos dos registros exportados, arredondado para o início da hora UTC (
YYYY/MM/DD/HH/00/00). Por exemplo,2025/08/25/01/00/00contém registros com carimbos de data/hora de eventos entre01:00:00 UTCe01:59:59 UTCem 25 de agosto de 2025. - EPOCH_EXECUTION_TIME: refere-se ao carimbo de data/hora da época Unix de 20 dígitos preenchido com zeros em microssegundos, indicando quando a execução do job de exportação começou (por exemplo,
00001756083600000000). logdata-SHARD_INDEX.csv: refere-se aos arquivos fragmentados indexados em 0 que contêm registros brutos (por exemplo,logdata-0.csvelogdata-1.csv). Cada fragmento de arquivo tem um tamanho aproximado de 100 MB.
Exemplo de caminho de objeto exportado:
gs://my-archive-bucket/b4a3c2d1e8f76a5b4c3d2e1f0a9b8c7d/GCP_DNS/2025/08/25/01/00/00/00001756083600000000/logdata-0.csv
Manifesto de conclusão da exportação (exported_paths.txt):
Quando um job de exportação é concluído com o status FINISHED_SUCCESS e grava pelo menos um arquivo de registro, o pipeline também grava um arquivo de manifesto em gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/exported_paths.txt. Se nenhum registro corresponder aos filtros de exportação ou ao período, nenhum arquivo de manifesto será gravado e dataExportStatus.exportedGlobPatterns ficará vazio. Cada linha em exported_paths.txt lista um padrão glob usando o prefixo /bigstore/ (/bigstore/GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/*, que é mapeado para gs://GCS_BUCKET_NAME/.../*) para um diretório de partição por hora gravado pelo job. Os jobs de automação ou compactação downstream podem ler esse manifesto para enumerar todas as partições exportadas sem listar todo o bucket.
Desempenho e limitações
O serviço tem os seguintes limites específicos para garantir a estabilidade da plataforma e a alocação justa de recursos:
- Volume máximo de dados por job: cada job de exportação individual pode solicitar até 100 TB de dados. Para conjuntos de dados maiores, o Google recomenda dividir a exportação em vários jobs com períodos menores.
- Jobs simultâneos: cada locatário do cliente pode executar ou colocar em fila no máximo três jobs de exportação simultaneamente. O sistema rejeita qualquer solicitação de criação de job que exceda esse limite.
- Tempos de conclusão do job: o volume de dados exportados determina os tempos de conclusão do job. Um único job pode levar até 18 horas.
- Formato de exportação e escopo de dados: a API é compatível com exportações em massa e pontuais, com as seguintes limitações e recursos:
- Somente registros brutos: só é possível exportar registros brutos (não registros de UDM, eventos de UDM ou detecções). Para saber como exportar dados do UDM, consulte Exportar para um projeto autogerenciado do BigQuery.
- Formato do arquivo e compactação de dados: a API exporta dados como strings de registro brutas não compactadas e delimitadas por nova linha em arquivos chamados
logdata-SHARD_INDEX.csv(com um tamanho aproximado de 100 MB por fragmento). Apesar da extensão de nome de arquivo CSV, os arquivos não são formatados como colunas separadas por vírgulas: cada entrada de registro bruta (por exemplo, um objeto JSON bruto, uma linha de syslog ou um registro CEF) é gravada literalmente, seguida por um caractere de nova linha (\n) sem escapar de novas linhas incorporadas. Assim, os registros brutos de várias linhas (como payloads XML ou stack traces) podem abranger várias linhas em um arquivo de fragmento. O formato do arquivo de saída não pode ser alterado pela API. Para armazenar arquivos em formatos colunares compactados, como o Apache Parquet, execute uma etapa de compactação downstream depois que o job de exportação atingirFINISHED_SUCCESS.
Pré-requisitos e arquitetura
Nesta seção, descrevemos a arquitetura do sistema e os requisitos necessários para usar a API de Exportação de dados, além de detalhar a arquitetura do sistema. Use essas informações para verificar se o ambiente está configurado corretamente.
Antes de usar a API Exportação de dados, conclua as seguintes etapas de pré-requisito para configurar seu destino do Google Cloud Storage e conceder as permissões necessárias:
Conceder permissões ao usuário. Para usar a API Exportação de dados, você precisa das seguintes permissões no projeto BYOP Google Cloud vinculado ao seu locatário do Google SecOps:
- chronicle.dataExports.fetchServiceAccountForDataExport
- chronicle.dataExports.create
- chronicle.dataExports.cancel
- chronicle.dataExports.get
- chronicle.dataExports.list
Essas permissões fazem parte dos seguintes papéis predefinidos do IAM:
- Administrador da API Chronicle: concede permissões completas para criar, atualizar, cancelar e visualizar jobs de exportação usando a API. Esse papel concede acesso global.
- Leitor da API Chronicle: concede acesso somente leitura para visualizar as configurações e o histórico de jobs usando a API. Sem o papel
restrictedDataAccess, um usuário com esse papel pode visualizar todos os dados (consulte a etapa + Adicionar outro papel e adicione uma condição).
Aplicar escopos de RBAC de dados a um usuário. Para restringir um usuário a escopos específicos de acesso a dados, faça o seguinte:
- Verifique se os escopos de RBAC de dados que você quer aplicar já foram criados em Configurações > Gerenciamento de acesso > Acesso a dados > Escopos. Anote o nome completo de cada escopo que você pretende atribuir ao usuário.
Crie uma função personalizada do Identity and Access Management (IAM) para gerenciar a exportação de dados. Como os papéis predefinidos podem conceder acesso excessivo ou não ter a combinação específica de permissões, faça o seguinte para criar uma função personalizada adaptada para gerenciar exportações de dados em um contexto com escopo:
- No console do Google Cloud , acesse IAM e administrador > Papéis.
- Clique em + Criar papel.
- Digite um título (por exemplo,
SecOps Scoped Data Export User). - Insira um ID (por exemplo,
secopsScopedDataExportUser). - Clique em + Adicionar permissões.
- Filtre as permissões do Chronicle e adicione as permissões relevantes listadas na primeira etapa (Conceder permissões ao usuário da API).
- Clique em Criar.
Conceda papéis do IAM ao usuário. Na página do IAM, faça o seguinte para atribuir os papéis necessários ao usuário:
- Acesse IAM e administrador > IAM.
- Clique em + Conceder acesso.
- Em Novos principais, digite o endereço de e-mail do usuário.
Para atribuir papéis, faça o seguinte:
- Adicione a função personalizada que você criou (por exemplo,
SecOps Scoped Data Export User). - Clique em + Adicionar outro papel e adicione o papel Acesso restrito a dados na API Chronicle (
restrictedDataAccess). Esse papel é fundamental para marcar o usuário como sujeito aos escopos de dados.
- Adicione a função personalizada que você criou (por exemplo,
Adicione uma condição do IAM à vinculação de papel
Chronicle API Restricted Data Access. Para vincular o usuário a escopos de dados específicos, faça o seguinte:- Clique em Adicionar condição do IAM.
- Use o Criador de condições ou o Editor de condições para definir os escopos permitidos, usando o nome do escopo criado na primeira etapa como o nome do recurso. Por exemplo, para usar um escopo chamado
scope_test, defina a condiçãoresource.name.endsWith("/dataAccessScopes/scope_test").
Para saber mais sobre como o controle de acesso baseado em função (RBAC) de dados é implementado para a API de Exportação de dados, consulte Como o controle de acesso baseado em função (RBAC) de dados se aplica à API de Exportação de dados.
Crie um bucket do Google Cloud Storage. No projeto do Google Cloud, crie um novo bucket do Google Cloud Storage (o destino dos dados exportados) na mesma região do locatário do Google SecOps. Defina-o como particular para impedir o acesso não autorizado. Para arquivamento de longo prazo, configure o bucket com a classe de armazenamento padrão
STANDARDpara gravações e verificação de exportação inicial (ou compactação Parquet downstream opcional) e use o Gerenciamento do ciclo de vida de objetos (regrasSetStorageClass) para fazer a transição de objetos para o armazenamentoCOLDLINEouARCHIVE. Para mais detalhes, consulte Criar um bucket.Conceda as permissões à conta de serviço. Para conceder à conta de serviço do Google SecOps, que está vinculada ao seu locatário do Google SecOps, os papéis do IAM necessários para gravar dados no bucket, faça o seguinte:
Chame o endpoint de API
FetchServiceAccountForDataExportpara identificar a conta de serviço exclusiva da sua instância do Google SecOps. A API retorna o e-mail da conta de serviço.Exemplo de solicitação:
{ "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }Exemplo de resposta:
{ "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com" }Conceda ao principal da conta de serviço do Google SecOps os seguintes papéis do IAM para o bucket do Cloud Storage de destino do Google Cloud Storage, que permitem que o serviço do Google SecOps grave arquivos de dados exportados no bucket do Cloud Storage do Google Cloud Storage:
Storage object administrator (roles/storage.objectAdmin)Legacy bucket reader (roles/storage.legacyBucketReader)
Para mais detalhes, consulte Conceder acesso à conta de serviço do Google SecOps.
Conclua a autenticação. A API de Exportação de dados autentica suas chamadas. Para configurar essa autenticação, siga as instruções nas seções abaixo:
Principais casos de uso e fluxo de trabalho principal
A API Data Export oferece um conjunto de endpoints para criar jobs de exportação de dados e gerenciar todo o ciclo de vida da exportação de dados em massa. Todas as interações são feitas usando chamadas de API.
Os casos de uso a seguir descrevem como criar, monitorar e gerenciar jobs de exportação de dados.
Criar um job de exportação de dados
O sistema armazena as especificações do job de exportação de dados na instância do Google SecOps do recurso pai. Essa instância é a origem dos dados de registro do job de exportação.
Para saber como identificar a conta de serviço exclusiva da sua instância do Google SecOps, consulte FetchServiceAccountForDataExports.
Para iniciar uma nova exportação, envie uma solicitação
POSTao endpointdataExports.create. Para saber mais, consulte o endpointCreateDataExport.
Monitorar o status do job de exportação de dados
É possível ver os detalhes e o status de um job de exportação de dados específico ou configurar um filtro para ver determinados tipos de jobs.
Para saber como visualizar um job de exportação específico, consulte GetDataExport.
Para saber como listar determinados tipos de jobs de exportação de dados usando um filtro, consulte ListDataExport.
Cancelar jobs em fila
É possível cancelar um job quando o status dele é IN_QUEUE.
Para saber como cancelar um job na fila, consulte CancelDataExport.
Como o controle de acesso baseado em função (RBAC) de dados se aplica à API Exportação de dados
Os jobs de exportação herdam o escopo de RBAC de dados dos usuários que os criam, o que impede a extração de dados não autorizada.
Se você tentar exportar dados que estão além do que seu escopo de acesso permite, a API vai excluir automaticamente esses dados no momento da execução do job de exportação. O valor do campo dataRbacFiltered nos metadados de jobs concluídos (ou seja, jobs com o status FINISHED_SUCCESS) indica se os dados foram excluídos. Se dataRbacFiltered for true, alguns ou todos os dados selecionados para o job de exportação foram excluídos porque estavam fora dos escopos de RBAC de dados aplicáveis ao criador do job. Se dataRbacFiltered for false, o job de exportação não foi afetado pelas restrições de escopo do RBAC de dados, e todos os dados incluídos como parte do job foram exportados.
A API aplica os escopos de RBAC de dados que são aplicáveis ao criador no momento da criação do job. As mudanças nos escopos do RBAC de dados não se aplicam retroativamente aos jobs que já foram criados.
Para saber mais sobre o RBAC de dados, consulte Visão geral do RBAC de dados.
Resolver problemas comuns
A API fornece mensagens de erro detalhadas para ajudar a diagnosticar problemas.
| Código canônico | Mensagem de erro |
|---|---|
INVALID_ARGUMENT |
INVALID_REQUEST: Invalid request parameter PARAMETER_1, PARAMETER_2, ... PARAMETER_N. Please fix the request parameters and try again. |
PERMISSION_DENIED |
INSUFFICIENT_PERMISSIONS: Unable to validate request with the current CMEK key. Please fix the CMEK key and try again |
NOT_FOUND |
BUCKET_NOT_FOUND: The destination Google Cloud Storage bucket BUCKET_NAME does not exist. Please create the destination Google Cloud Storage bucket and try again. |
NOT_FOUND |
REQUEST_NOT_FOUND: The dataExportId:DATA_EXPORT_ID does not exist. Please add a valid dataExportId and try again. |
FAILED_PRECONDITION |
BUCKET_INVALID_REGION: The Google Cloud Storage bucket BUCKET_ID's region:REGION_1 is not the same region as the SecOps tenant region:REGION_2. Please create the Google Cloud Storage bucket in the same region as SecOps tenant and try again. |
FAILED_PRECONDITION |
INSUFFICIENT_PERMISSIONS: The Service Account P4SA does not have storage.objects.create, storage.objects.get and storage.buckets.get permissions on the destination Google Cloud Storage bucket BUCKET_NAME. Please provide the required access to the Service Account and try again. |
FAILED_PRECONDITION |
INVALID_CANCELLATION: The request status is in the STATUS stage and can't be cancelled. You can only cancel the request if the status is in the IN_QUEUE stage. |
RESOURCE_EXHAUSTED |
CONCURRENT_REQUEST_LIMIT_EXCEEDED: Maximum concurrent requests limit LIMIT reached for the request size SIZE_LIMIT. Please wait for the existing requests to complete and try again. |
RESOURCE_EXHAUSTED |
REQUEST_SIZE_LIMIT_EXCEEDED: The estimated export volume: ESTIMATED_VOLUME for the request is greater than maximum allowed export volume: ALLOWED_VOLUME per request. Please try again with a request within the allowed export volume limit. |
INTERNAL |
INTERNAL_ERROR: An Internal error occurred. Please try again. |
Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.