Coletar registros do Gmail

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros do Gmail no Google Security Operations usando o Google Cloud Storage V2.

O Gmail é o serviço de e-mail do Google Workspace que oferece e-mails seguros e inteligentes com proteção integrada contra spam e phishing. Os registros do Gmail capturam informações detalhadas sobre a entrega de e-mails, eventos de segurança e fluxo de mensagens na infraestrutura do Gmail.

Antes de começar

Verifique se você atende os seguintes pré-requisitos:

Uma instância do Google SecOps
Projeto do GCP com as APIs Cloud Storage e BigQuery ativadas
Conta do Google Workspace com a edição adequada (Enterprise Standard, Enterprise Plus, Education Standard ou Education Plus)
Acesso de superadministrador ao Admin Console do Google Workspace
Permissões para criar e gerenciar buckets do GCS
Permissões para gerenciar políticas do IAM em buckets do GCS
Permissões para criar consultas programadas do BigQuery
A conta de serviço gapps-reports@system.gserviceaccount.com precisa ter a função de editor no projeto do BigQuery.

Criar um bucket do Google Cloud Storage

Usando o console do Google Cloud

Acesse o Console do Google Cloud.
Selecione seu projeto ou crie um novo.
No menu de navegação, acesse Cloud Storage > Buckets.
Clique em Criar bucket.

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nomeie seu bucket	Insira um nome exclusivo globalmente, por exemplo, `gmail-logs-export`.
Tipo de local	Escolha com base nas suas necessidades (região, birregional, multirregional)
Local	Selecione o local (por exemplo, `us-central1`).
Classe de armazenamento	Padrão (recomendado para registros acessados com frequência)
Controle de acesso	Uniforme (recomendado)
Ferramentas de proteção	Opcional: ativar o controle de versões de objetos ou a política de retenção

Clique em Criar.

Como usar a ferramenta de linha de comando gcloud

Como alternativa, crie um bucket usando o comando gcloud:
```
gcloud storage buckets create gs://gmail-logs-export \
    --location=us-central1 \
    --default-storage-class=STANDARD
```
- Substitua:
  - gmail-logs-export: o nome de bucket desejado (globalmente exclusivo).
  - us-central1: sua região preferida (por exemplo, us-central1, europe-west1).

Configurar o Google Workspace para exportar registros para o BigQuery

Os registros do Google Workspace, incluindo os do Gmail, são exportados para o BigQuery usando o recurso unificado de registros e relatórios do Workspace.

Ativar o BigQuery Export para registros do Workspace

Faça login com uma conta de superadministrador no Google Admin Console.
Acesse Menu > Relatórios > Integrações de dados.
Aponte para o card BigQuery Export e clique em Editar.
Marque a caixa Ativar a exportação de dados do Google Workspace para o Google BigQuery.
Em Código do projeto do BigQuery, selecione o projeto em que os registros serão armazenados.
Em Novo conjunto de dados no projeto, digite o nome do conjunto de dados em que os registros serão armazenados (por exemplo, workspace_logs).
Opcional: marque a caixa Restringir o conjunto de dados a uma localização geográfica específica e selecione o local no menu.
Clique em Salvar.

Observação: a conta de serviço gapps-reports@system.gserviceaccount.com é adicionada automaticamente como editor ao conjunto de dados. Não remova essa conta de serviço.

Depois de ativar a exportação, os eventos do registro de atividades normalmente ficam disponíveis em até 10 minutos. Os dados são exportados para tabelas chamadas activity_YYYYMMDD no conjunto de dados especificado.

Criar uma consulta programada para exportar do BigQuery para o GCS

Para exportar automaticamente os registros do Gmail do BigQuery para o Cloud Storage em uma programação recorrente, crie uma consulta programada usando a instrução EXPORT DATA.

Como usar o console do BigQuery

No console do Google Cloud, acesse BigQuery.
Na navegação à esquerda, clique em Consultas programadas.
Clique em Criar consulta programada.

No Editor de consultas, insira o seguinte SQL:

EXPORT DATA OPTIONS(
    uri='gs://gmail-logs-export/gmail-logs/*.json',
    format='JSON',
    overwrite=false
) AS
SELECT 
    *
FROM 
    `PROJECT_ID.workspace_logs.activity_*`
WHERE 
    record_type = 'gmail'
    AND _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY))

Substitua:
- gmail-logs-export: o nome do seu bucket do GCS
- PROJECT_ID: ID do projeto do GCP.
- workspace_logs: nome do conjunto de dados do BigQuery

Na seção Opções de programação, faça o seguinte:
- Repetir: selecione Horas.
- Todos: insira 1.
- Data e hora de início: selecione a data e a hora atuais.
Na seção Destino para os resultados da consulta:
- Conjunto de dados: selecione um conjunto de dados para metadados de consulta (não os dados exportados).
Clique em Salvar.

Como usar a ferramenta de linha de comando bq

Ou crie uma consulta programada usando o comando bq:

bq mk \
    --transfer_config \
    --project_id=PROJECT_ID \
    --data_source=scheduled_query \
    --display_name='Gmail Logs Export to GCS' \
    --schedule='every 1 hours' \
    --params='{
        "query":"EXPORT DATA OPTIONS(uri=\"gs://gmail-logs-export/gmail-logs/*.json\", format=\"JSON\", overwrite=false) AS SELECT * FROM `PROJECT_ID.workspace_logs.activity_*` WHERE record_type = \"gmail\" AND _TABLE_SUFFIX = FORMAT_DATE(\"%Y%m%d\", DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY))",
        "destination_table_name_template":"gmail_export_metadata",
        "write_disposition":"WRITE_TRUNCATE"
    }'

Substitua:
- PROJECT_ID: ID do projeto do GCP.
- gmail-logs-export: o nome do seu bucket do GCS
- workspace_logs: nome do conjunto de dados do BigQuery

Recuperar a conta de serviço do Google SecOps

O Google SecOps usa uma conta de serviço exclusiva para ler dados do seu bucket do GCS. Você precisa conceder a essa conta de serviço acesso ao seu bucket.

Configurar um feed no Google SecOps para ingerir registros do Gmail

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, Gmail Logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Registros do GMAIL como o Tipo de registro.
Clique em Receber conta de serviço. Um e-mail exclusivo da conta de serviço é exibido, por exemplo:
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
Copie esse endereço de e-mail para usar na próxima etapa.

Observação: cada instância do Google SecOps tem uma conta de serviço exclusiva. Não use contas de serviço de outras documentações ou exemplos.
Clique em Próxima.
Especifique valores para os seguintes parâmetros de entrada:
- URL do bucket de armazenamento: insira o URI do bucket do GCS com o caminho do prefixo:
```
 gs://gmail-logs-export/gmail-logs/
```
  - Substitua:
    - gmail-logs-export: o nome do seu bucket do GCS
    - gmail-logs: o prefixo/caminho da pasta em que os registros são armazenados.
Observação: sempre inclua a barra (/) no final do URI.
- Opção de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência:
  - Nunca: nunca exclui arquivos após as transferências (recomendado para testes).
  - Excluir arquivos transferidos: exclui os arquivos após a transferência bem-sucedida.
  - Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência bem-sucedida.
    
    Observação: se você selecionar uma opção de exclusão, a conta de serviço precisará ter o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage. Atualize as permissões do IAM de acordo com a necessidade.
- Idade máxima do arquivo: inclui arquivos modificados no último número de dias. O padrão é de 180 dias.
- Namespace do recurso: o namespace do recurso.
- Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed.
Clique em Próxima.
Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Conceder permissões do IAM à conta de serviço do Google SecOps

A conta de serviço do Google SecOps precisa do papel de Leitor de objetos do Storage no seu bucket do GCS.

Usando o console do Google Cloud

Acesse Cloud Storage > Buckets.
Clique no nome do bucket.
Acesse a guia Permissões.
Clique em Conceder acesso.
Informe os seguintes detalhes de configuração:
- Adicionar participantes: cole o e-mail da conta de serviço do Google SecOps.
- Atribuir papéis: selecione Leitor de objetos do Storage.
Clique em Salvar.

Como usar a ferramenta de linha de comando gcloud

Outra opção é conceder permissões usando o comando gcloud:

gcloud storage buckets add-iam-policy-binding gs://gmail-logs-export \
    --member="serviceAccount:SECOPS_SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Substitua:
- gmail-logs-export: o nome do bucket.
- SECOPS_SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço do Google SecOps.

Como usar a ferramenta de linha de comando gsutil (legado)

Conceda à conta de serviço do SecOps acesso de leitor de objetos ao bucket de exportação de registros do Gmail.
```
gsutil iam ch serviceAccount:SECOPS_SERVICE_ACCOUNT_EMAIL:objectViewer \
    gs://gmail-logs-export
```

Verifique as permissões

Para verificar se as permissões foram concedidas corretamente:

gcloud storage buckets get-iam-policy gs://gmail-logs-export \
    --flatten="bindings[].members" \
    --filter="bindings.role:roles/storage.objectViewer"

O e-mail da conta de serviço do Google SecOps vai aparecer na saída.

Tabela de mapeamento do UDM

Campo de registro	Mapeamento do UDM	Lógica
attachment.file_extension_type, attachment.sha256, attachment.file_name, domains	sobre	Mesclado com detalhes de anexos e domínios de links
message_info.post_delivery_info.action_type, gmail.message_info.post_delivery_info.action_type, event_info.mail_event_type, gmail.event_info.mail_event_type, tok.product_bucket, tok.scope_name, record_type, token.client_type, message_info.num_message_attachments, gmail.message_info.num_message_attachments	additional.fields	Combinados com vários campos de metadados adicionais
action_type, description, rule_id	metadata.description	Definido como descrições específicas com base nos valores de "action_type", na descrição ou em "Conteúdo censurável" se "rule_id" == 7
	metadata.event_type	Defina como "EMAIL_TRANSACTION".
event_name	metadata.product_event_type	Valor copiado diretamente
	metadata.product_name	Definido como "GMAIL"
	metadata.vendor_name	Defina como "Google".
__incoming_message, __outcoming_message	network.direction	Definido como "INBOUND" se uma mensagem recebida for detectada e "OUTBOUND" se for enviada.
destination.address	network.email.cc	Unidos de endereços de destino em que o índice é > 0
message_info.source.from_header_address, message_info.source.address	network.email.from	Valor de from_header_address se não estiver vazio, caso contrário, de source.address
message_info.rfc2822_message_id, gmail.message_info.rfc2822_message_id	network.email.mail_id	Extraído de rfc2822_message_id, removendo < >, usando grok
message_info.subject, gmail.message_info.subject	network.email.subject	Valor de message_info.subject se não estiver vazio, caso contrário, gmail.message_info.subject
destination.address	network.email.to	Unido do primeiro endereço de destino
	network.ip_protocol	Definido como "TCP"
_payload_size	network.received_bytes	Definido como _payload_size se a mensagem for recebida
_payload_size	network.sent_bytes	Definido como _payload_size se a mensagem for de saída
token.app_name, message_info.source.service, message_info.source.selector, gmail.message_info.source.service, gmail.message_info.source.selector	principal.application	Valor de token.app_name se não estiver vazio. Caso contrário, será concatenado de source.service e source.selector.
message_info.connection_info.client_host_zone, gmail.message_info.connection_info.client_host_zone	principal.asset.hostname	Valor de client_host_zone
client_ip	principal.asset.ip	Valor copiado diretamente
message_info.connection_info.client_host_zone, gmail.message_info.connection_info.client_host_zone	principal.hostname	Valor de client_host_zone
client_ip	principal.ip	Valor copiado diretamente
message_info.connection_info.ip_geo_country, gmail.message_info.connection_info.ip_geo_country	principal.location.country_or_region	Valor de ip_geo_country
email, source_address	principal.user.email_addresses	Unido de "email_address" e "source_address"
token.client_id	principal.user.group_identifiers	Valor copiado diretamente
message_info.source.from_header_displayname, gmail.message_info.source.from_header_displayname	principal.user.user_display_name	Valor de from_header_displayname
source_address	principal.user.userid	Valor copiado diretamente
ação	security_result.action	Valor copiado diretamente
categoria	security_result.category	Valor copiado diretamente
category_details	security_result.category_details	Valor copiado diretamente
message_info.connection_info.smtp_response_reason, gmail.message_info.connection_info.smtp_response_reason, rule_description, reason	security_result.description	Definido como motivo da resposta SMTP, descrição da regra ou motivo da classificação
stringMatch.predefined_detector_name, stringMatch.matched_string, stringMatch.match_expression, stringMatch.source, stringMatch.type	security_result.detection_fields	Mesclado com objetos de campo de detecção
rule_id	security_result.rule_id	Valor copiado diretamente
rule_name	security_result.rule_name	Valor copiado diretamente
_err_summary, rule_id, description	security_result.summary	Definido como resumo do erro, resumo específico da regra ou descrição
_target_host	target.administrative_domain	Valor copiado diretamente
message_info.destination.0.service, message_info.destination.0.selector, gmail.message_info.destination.0.service, gmail.message_info.destination.0.selector	target.application	Concatenado do serviço e do seletor

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