Exportar registros brutos para um bucket autogerenciado do Google Cloud Storage

Compatível com:

A API Data Export 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 sobre a referência da API, consulte API Data Export (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 Data Export 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 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 de forma automática. 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 evitar 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 períodos específicos 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 com 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 dataExportId exclusivo.
  • 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 que pertence ao usuário e 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/FILE_SHARD_NAME.csv

Em que:

  • GCS_BUCKET_NAME: refere-se ao nome do bucket do Google Cloud Storage.
  • EXPORT_JOB_NAME: refere-se ao nome exclusivo do job de exportação.
  • LOGTYPE: refere-se ao nome do tipo de registro dos dados exportados.
  • EVENT_TIME_BUCKET: refere-se ao intervalo de horas dos carimbos de data/hora do evento dos registros exportados. O formato é um carimbo de data/hora UTC: year/month/day/UTC-timestamp, em que UTC-timestamp é hour/minute/second. Por exemplo, 2025/08/25/01/00/00 se refere a UTC 01:00:00 AM, August 25, 2025.
  • EPOCH_EXECUTION_TIME: refere-se ao valor de tempo da época Unix, indicando quando o job de exportação começou.
  • FILE_SHARD_NAME: refere-se ao nome dos arquivos fragmentados que contêm registros brutos. Cada fragmento de arquivo tem um limite de tamanho de 100 MB.

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.
    • Compactação de dados: a API exporta dados como texto não compactado.

Pré-requisitos e arquitetura

Nesta seção, descrevemos a arquitetura do sistema e os requisitos necessários para usar a API Data Export, 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 Data Export, conclua as seguintes etapas de pré-requisito para configurar seu destino do Google Cloud Storage e conceder as permissões necessárias:

  1. Conceder permissões ao usuário. Para usar a API Data Export, você precisa das seguintes permissões no projeto BYOP Google Cloud vinculado ao seu locatário do Google SecOps:

    Essas permissões fazem parte dos seguintes papéis predefinidos do IAM:

  2. 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:

    1. Verifique se os escopos de RBAC de dados que você quer aplicar já foram criados na interface do Google SecOps em Configurações > Configurações do SIEM > Acesso a dados > Escopos. Anote o nome completo de cada escopo que você pretende atribuir ao usuário.

    2. Crie um papel personalizado 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 um papel personalizado adaptado para gerenciar exportações de dados em um contexto com escopo:

      1. No console do Google Cloud , acesse IAM e administrador > Papéis.
      2. Clique em + Criar papel.
      3. Digite um título (por exemplo, SecOps Scoped Data Export User).
      4. Insira um ID (por exemplo, secopsScopedDataExportUser).
      5. Clique em + Adicionar permissões.
      6. Filtre as permissões do Chronicle e adicione as permissões relevantes listadas na primeira etapa (Conceder permissões ao usuário da API).
      7. Clique em Criar.

  3. 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:

    1. Acesse IAM e administrador > IAM.
    2. Clique em + Conceder acesso.
    3. Em Novos principais, digite o endereço de e-mail do usuário.

    4. Faça o seguinte para atribuir papéis:

      1. Adicione o papel personalizado que você criou (por exemplo, SecOps Scoped Data Export User).
      2. Clique em + Adicionar outro papel e adicione o papel Acesso restrito a dados na API Chronicle (restrictedDataAccess). Essa função é fundamental para marcar o usuário como sujeito aos escopos de dados.

  4. 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:

    1. Clique em Adicionar condição do IAM.
    2. 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ção resource.name.endsWith("/dataAccessScopes/scope_test").

    Para saber mais sobre como o RBAC de dados é implementado para a API Data Export, consulte Como o RBAC de dados se aplica à API Data Export.

  5. 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 mais detalhes, consulte Criar um bucket.

  6. 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:

    1. Chame o endpoint de API FetchServiceAccountForDataExport para 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"
}

    2. 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.

  7. Conclua a autenticação. A API Data Export autentica suas chamadas. Para configurar essa autenticação, siga as instruções nas seções abaixo:

    1. Métodos de autenticação para serviços do Google Cloud
    2. Application Default Credentials

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 POST ao endpoint dataExports.create. Para saber mais, consulte o endpoint CreateDataExport.

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 RBAC de dados se aplica à API Data Export

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 permitido pelo escopo de acesso, a API vai excluir automaticamente esses dados ao executar o 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.