Coletar registros da Área 1

Versão do analisador: 3.0

Compatível com:

Google SecOps SIEM

Neste documento, explicamos como ingerir registros do Area 1 Email Security (da Cloudflare) no Google Security Operations usando o AWS S3. O analisador processa os registros no formato JSON. Ele extrai campos relevantes da estrutura JSON aninhada, os mapeia para o modelo de dados unificado (UDM) e enriquece os dados com informações geográficas e detalhes de segurança, como hashes de anexos e disposição.

Antes de começar

Verifique se você tem os pré-requisitos a seguir:

• Instância do Google SecOps
• Um host do Windows 2016 ou mais recente ou do Linux com systemd
• Se estiver em execução atrás de um proxy, as portas do firewall estão abertas
• Acesso privilegiado ao Area 1 Email Security (da Cloudflare)

Configurar o IAM da AWS e o bucket do S3

1. Crie um bucket do Amazon S3 seguindo este guia do usuário: Como criar um bucket.
2. Faça login no Console da AWS.
3. Acesse S3 > Criar bucket.
4. Insira um nome para o bucket (por exemplo, area1-security-logs).
5. Mantenha os outros padrões (ou configure a criptografia e o controle de versões, se necessário).
6. Clique em Criar.
7. Salve o Nome e a Região do bucket para referência futura.
8. Crie um usuário seguindo este guia do usuário: Como criar um usuário do IAM.
9. Selecione o Usuário criado.
10. Selecione a guia Credenciais de segurança.
11. Clique em Criar chave de acesso na seção Chaves de acesso.
12. Selecione Serviço de terceiros como Caso de uso.
13. Clique em Próxima.
14. Opcional: adicione uma tag de descrição.
15. Clique em Criar chave de acesso.
16. Clique em Fazer o download do arquivo CSV e armazene a chave de acesso e a chave de acesso secreta para referência futura.
17. Clique em Concluído.
18. Selecione a guia Permissões.
19. Em Políticas de permissões, clique em Adicionar permissões.
20. Selecione Anexar políticas diretamente.
21. Pesquise a política AmazonS3FullAccess.
22. Selecione a política.
23. Clique em Próxima.
24. Clique em Adicionar permissões

Gerar credenciais de API da Area 1

1. Faça login no painel do Area 1 Security (Cloudflare).
2. Acesse Configurações > Acesso à API.
3. Gere a chave de API (token).
4. Copie e salve o token em um local seguro.

Configurar os pacotes Python necessários

1. Faça login no host de coleta de registros (por exemplo, uma VM da AWS) e execute o seguinte para configurar as credenciais da AWS:

   pip install boto3 requests
   aws configure
   

Criar o script do extrator de registros da Área 1

1. Crie o arquivo a seguir inserindo sudo vi area1_to_s3.py e, em seguida, copie o código abaixo:

   • Ajuste o seguinte:

   #!/usr/bin/env python3
   import os
   import requests
   import boto3
   import datetime
   import json
   
   # Configuration
   AREA1_API_TOKEN = os.environ.get("AREA1_API_TOKEN")  # Load securely from env
   AWS_PROFILE = os.environ.get("AWS_PROFILE", None)    # Optional, for named profiles
   S3_BUCKET_NAME = "area1-security-logs"
   LOG_TYPE = "events"
   
   # Time range
   end_time = datetime.datetime.utcnow()
   start_time = end_time - datetime.timedelta(days=1)
   
   def fetch_area1_logs():
       url = f"https://api.area1security.com/v1/{LOG_TYPE}"
       headers = {
           "Authorization": f"Bearer {AREA1_API_TOKEN}",
           "Accept": "application/json"
       }
       params = {
           "startDate": start_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
           "endDate": end_time.strftime("%Y-%m-%dT%H:%M:%SZ")
       }
       response = requests.get(url, headers=headers, params=params)
       response.raise_for_status()
       return response.json()
   
   def upload_to_s3(data):
       filename = f"area1_{LOG_TYPE}_{start_time.strftime('%Y%m%d')}.json"
   
       session = boto3.Session(profile_name=AWS_PROFILE) if AWS_PROFILE else boto3.Session()
       s3 = session.client("s3")
   
       s3.put_object(
           Bucket=S3_BUCKET_NAME,
           Key=f"logs/{filename}",
           Body=json.dumps(data).encode("utf-8"),
           ContentType="application/json"
       )
       print(f"[✓] Uploaded {filename} to s3://{S3_BUCKET_NAME}/logs/")
   
   if __name__ == "__main__":
       logs = fetch_area1_logs()
       upload_to_s3(logs)
   

2. Salve e saia de vi: clique em esc e digite :wq.

Armazenar as variáveis de ambiente

1. Crie um arquivo seguro para armazenar variáveis de ambiente em /etc/area1.env (ou /home/user/.area1.env)

   export AREA1_API_TOKEN="your_actual_area1_api_token"
   export AWS_PROFILE="<your_aws_programmatic_username>"
   

2. Verifique se o arquivo está seguro:

   chmod 600 /etc/area1.env
   

Executar e testar o script

1. Execute o script a seguir:

   python3 area1_to_s3.py
   

2. Você verá:

   Uploaded area1_events_20250701.json to s3://area1-security-logs/logs/
   

Automatizar com o Cron

1. Crie um script de wrapper para o Cron executando sudo vi /usr/local/bin/run_area1.sh e copie o seguinte código:

   #!/usr/bin/env bash
   set -euo pipefail
   
   source /etc/area1.env
   /usr/bin/python3 /opt/scripts/area1_to_s3.py
   

2. Torne o arquivo executável:

   chmod +x /usr/local/bin/run_area1.sh
   

3. Definido para execução diária à 1h UTC:

   crontab -e
   0 1 * * * /usr/local/bin/run_area1.sh >> /var/log/area1_to_s3.log 2>&1
   

Configurar feeds

Há dois pontos de entrada diferentes para configurar feeds na plataforma do Google SecOps:

• Configurações > Gerenciamento de dados > Feeds > Adicionar novo feed (na plataforma somente SIEM, Configurações > Feeds > Adicionar novo feed)
• Hub de conteúdo > Pacotes de conteúdo > Comece já

Observação: o Hub de conteúdo não está disponível na plataforma independente do SIEM. Para fazer upgrade, entre em contato com seu representante do Google SecOps.

Configure os feeds em Configurações > Gerenciamento de dados > Feeds.

Para configurar um feed, siga estas etapas:

1. Acesse Configurações > Gerenciamento de dados > Feeds. Se você estiver em uma plataforma somente SIEM, acesse Configurações > Feeds.
2. Clique em Adicionar novo feed.
3. Na página seguinte, clique em Configurar um único feed.
4. No campo Nome do feed, insira um nome para o feed (por exemplo, Area1 Logs).
5. Selecione Amazon S3 como o Tipo de origem.
6. Selecione Area1 Security como o Tipo de registro.
7. Clique em Próxima.

8. Especifique valores para os seguintes parâmetros de entrada:

   • Região: a região em que o bucket do Amazon S3 está localizado.
   • URI do S3: o URI do bucket (o formato precisa ser: s3://<your-log-bucket-name>). Substitua o seguinte:
     • your-log-bucket-name: o nome do bucket
   • O URI é um: selecione Diretório que inclui subdiretórios.
   • Opções de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência.
   Observação: se você selecionar a opção Delete transferred files ou Delete transferred files and empty directories, verifique se concedeu as permissões adequadas à conta de serviço.
   • ID da chave de acesso: a chave de acesso do usuário com acesso ao bucket do s3.
   • Chave de acesso secreta: a chave secreta do usuário com acesso ao bucket do S3.

9. Clique em Próxima.

10. Revise a configuração do novo feed na tela Finalizar e clique em Enviar.

Configurar feeds do Hub de Conteúdo

Especifique valores para os seguintes campos:

• Região: a região em que o bucket do Amazon S3 está localizado.

  • URI do S3: o URI do bucket (o formato precisa ser: s3://<your-log-bucket-name>). Substitua o seguinte:
    • your-log-bucket-name: o nome do bucket
  • O URI é um: selecione Diretório que inclui subdiretórios.
  • Opções de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência.
  Observação: se você selecionar a opção Delete transferred files ou Delete transferred files and empty directories, verifique se concedeu as permissões adequadas à conta de serviço.
  • ID da chave de acesso: a chave de acesso do usuário com acesso ao bucket do s3.
  • Chave de acesso secreta: a chave secreta do usuário com acesso ao bucket do S3.§

Opções avançadas

• Nome do feed: um valor predefinido que identifica o feed.
• Tipo de origem: método usado para coletar registros no Google SecOps.
• Namespace do recurso: namespace associado ao feed.
• Rótulos de ingestão: rótulos aplicados a todos os eventos desse feed.

Tabela de mapeamento de UDM

Campo de registro	Mapeamento de UDM	Lógica
alert_id	security_result.rule_id	O valor é extraído do campo alert_id.
alert_reasons	security_result.description	O valor é extraído do campo alert_reasons.
attachments.att_size	security_result.about.file.size	O valor é extraído do campo attachments.att_size e convertido em um número inteiro sem sinal.
attachments.disposition	security_result.about.user.attribute.labels.value	O valor é extraído do campo attachments.disposition.
attachments.extension	security_result.about.file.mime_type	O valor é extraído do campo attachments.extension.
attachments.md5	security_result.about.file.md5	O valor é extraído do campo attachments.md5.
attachments.name	security_result.about.file.full_path	O valor é extraído do campo attachments.name.
attachments.sha1	security_result.about.file.sha1	O valor é extraído do campo attachments.sha1.
attachments.sha256	security_result.about.file.sha256	O valor é extraído do campo attachments.sha256.
attachments.ssdeep	security_result.about.file.ssdeep	O valor é extraído do campo attachments.ssdeep.
delivery_mode	security_result.detection_fields.value	O valor é extraído do campo delivery_mode.
envelope_from	principal.user.email_addresses, network.email.from	O valor é extraído do campo envelope_from.
envelope_to	network.email.to, target.user.email_addresses	O valor é extraído do campo envelope_to.
final_disposition	security_result.category_details	O valor é extraído do campo final_disposition.
message_id	metadata.product_log_id	O valor é extraído do campo message_id após a remoção dos caracteres "<" e ">".
replyto	network.email.bounce_address	O valor é extraído do campo replyto.
smtp_helo_server_ip	principal.ip	O valor é extraído do campo smtp_helo_server_ip.
smtp_helo_server_ip_as_name	principal.location.name	O valor é extraído do campo smtp_helo_server_ip_as_name.
smtp_helo_server_ip_as_number	principal.asset_id	O valor é extraído do campo smtp_helo_server_ip_as_number e precedido por asset_id:.
smtp_helo_server_ip_geo	principal.location.country_or_region, principal.location.state, principal.location.city	O valor é extraído do campo smtp_helo_server_ip_geo usando um padrão Grok.
smtp_helo_server_name	principal.administrative_domain	O valor é extraído do campo smtp_helo_server_name.
source	metadata.vendor_name	O valor é extraído do campo source. Se o campo estiver vazio, o valor será definido como area1security.
subject	network.email.subject	O valor é extraído do campo subject.
tempo	metadata.event_timestamp	O valor é extraído do campo time e convertido em um carimbo de data/hora.
	metadata.event_type	O valor é definido como EMAIL_TRANSACTION.
	metadata.product_name	O valor é definido como AREA1.
	metadata.log_type	O valor é definido como AREA1.
	security_result.about.user.attribute.labels.key	O valor é definido como disposition.
	security_result.category	O valor é definido como SOFTWARE_MALICIOUS.
	security_result.detection_fields.key	O valor é definido como delivery_mode.
envelope_to.0" instead of "replyto	network.email.to	Mapeado do registro de alterações

Registro de alterações

Confira o registro de alterações deste analisador

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