Coletar registros JSON do Box

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros JSON do Box no Google Security Operations usando o Google Cloud Storage. O analisador processa registros de eventos do Box no formato JSON, mapeando-os para um modelo de dados unificado (UDM). Ele extrai campos relevantes dos registros brutos, realiza transformações de dados, como renomeação e fusão, e enriquece os dados com informações intermediárias antes de gerar os dados de eventos estruturados.

Antes de começar

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

Uma instância do Google SecOps
Um projeto do GCP com a API Cloud Storage ativada
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 serviços do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
Acesso privilegiado ao Box (Admin Console e Developer Console)

Configurar o Box Developer Console (credenciais do cliente)

Faça login no Box Developer Console.
Crie um app personalizado com autenticação de servidor (concessão de credenciais do cliente).
Defina Acesso ao aplicativo = Acesso ao app + Enterprise.
Em Escopos do aplicativo, ative Gerenciar propriedades empresariais.
No Admin Console > Apps > Gerenciador de apps personalizados, autorize o app usando o ID do cliente.
Copie e salve o ID do cliente e a chave secreta do cliente em um local seguro.
Acesse Admin Console > Conta e faturamento > Informações da conta.
Copie e salve o ID da empresa em um local seguro.

Criar um bucket do Google Cloud Storage

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, `box-collaboration-logs`.
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.

Criar uma conta de serviço para a função do Cloud Run

A função do Cloud Run precisa de uma conta de serviço com permissões para gravar no bucket do GCS e ser invocada pelo Pub/Sub.

Criar conta de serviço

No Console do GCP, acesse IAM e administrador > Contas de serviço.
Clique em Criar conta de serviço.
Informe os seguintes detalhes de configuração:
- Nome da conta de serviço: insira box-collaboration-collector-sa.
- Descrição da conta de serviço: insira Service account for Cloud Run function to collect Box Collaboration logs.
Clique em Criar e continuar.
Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis:
1. Clique em Selecionar papel.
2. Pesquise e selecione Administrador de objetos do Storage.
3. Clique em + Adicionar outro papel.
4. Pesquise e selecione Invocador do Cloud Run.
5. Clique em + Adicionar outro papel.
6. Pesquise e selecione Invocador do Cloud Functions.
Clique em Continuar.
Clique em Concluído.

Esses papéis são necessários para:

Administrador de objetos do Storage: grava registros em um bucket do GCS e gerencia arquivos de estado.
Invocador do Cloud Run: permite que o Pub/Sub invoque a função
Invocador do Cloud Functions: permite a invocação de funções

Conceder permissões do IAM no bucket do GCS

Conceda permissões de gravação à conta de serviço no bucket do GCS:

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 principais: insira o e-mail da conta de serviço (box-collaboration-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
- Atribuir papéis: selecione Administrador de objetos do Storage.
Clique em Salvar.

Criar tópico Pub/Sub

Crie um tópico do Pub/Sub em que o Cloud Scheduler vai publicar e a função do Cloud Run vai se inscrever.

No Console do GCP, acesse Pub/Sub > Tópicos.
Selecione Criar tópico.
Informe os seguintes detalhes de configuração:
- ID do tópico: insira box-collaboration-trigger.
- Não altere as outras configurações.
Clique em Criar.

Criar uma função do Cloud Run para coletar registros

A função do Cloud Run é acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar registros da API Box e gravá-los no GCS.

No console do GCP, acesse o Cloud Run.
Clique em Criar serviço.
Selecione Função (use um editor in-line para criar uma função).

Na seção Configurar, forneça os seguintes detalhes de configuração:

Configuração	Valor
Nome do serviço	`box-collaboration-collector`
Região	Selecione a região que corresponde ao seu bucket do GCS (por exemplo, `us-central1`).
Ambiente de execução	Selecione Python 3.12 ou uma versão mais recente.

Na seção Acionador (opcional):
1. Clique em + Adicionar gatilho.
2. Selecione Cloud Pub/Sub.
3. Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico do Pub/Sub (box-collaboration-trigger).
4. Clique em Salvar.
Na seção Autenticação:
1. Selecione Exigir autenticação.
2. Verifique o Identity and Access Management (IAM).
Observação: o Pub/Sub processa automaticamente a autenticação ao invocar a função.
Role a tela para baixo e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço (box-collaboration-collector-sa).

Acesse a guia Contêineres:

Clique em Variáveis e secrets.
Clique em + Adicionar variável para cada variável de ambiente:

Nome da variável	Valor de exemplo
`GCS_BUCKET`	`box-collaboration-logs`
`GCS_PREFIX`	`box/collaboration/`
`STATE_KEY`	`box/collaboration/state.json`
`BOX_CLIENT_ID`	Insira o ID do cliente do Box
`BOX_CLIENT_SECRET`	Insira a chave secreta do cliente do Box
`BOX_ENTERPRISE_ID`	Insira o ID corporativo do Box
`STREAM_TYPE`	`admin_logs_streaming`
`LIMIT`	`500`

Na seção Variáveis e secrets, role a tela para baixo até Solicitações:
- Tempo limite da solicitação: insira 600 segundos (10 minutos).
Acesse a guia Configurações:
- Na seção Recursos:
  - Memória: selecione 512 MiB ou mais.
  - CPU: selecione 1.
Na seção Escalonamento de revisão:
- Número mínimo de instâncias: insira 0.
- Número máximo de instâncias: insira 100 ou ajuste com base na carga esperada.
Clique em Criar.
Aguarde a criação do serviço (1 a 2 minutos).
Depois que o serviço é criado, o editor de código inline é aberto automaticamente.

Adicionar código da função

Insira main em Ponto de entrada da função.

No editor de código em linha, crie dois arquivos:

Primeiro arquivo: main.py::

import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone
import base64

# Initialize HTTP client with timeouts
http = urllib3.PoolManager(
    timeout=urllib3.Timeout(connect=5.0, read=30.0),
    retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

TOKEN_URL = "https://api.box.com/oauth2/token"
EVENTS_URL = "https://api.box.com/2.0/events"

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch Box enterprise events and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """

    # Get environment variables
    bucket_name = os.environ.get('GCS_BUCKET')
    prefix = os.environ.get('GCS_PREFIX', 'box/collaboration/')
    state_key = os.environ.get('STATE_KEY', 'box/collaboration/state.json')

    client_id = os.environ.get('BOX_CLIENT_ID')
    client_secret = os.environ.get('BOX_CLIENT_SECRET')
    enterprise_id = os.environ.get('BOX_ENTERPRISE_ID')
    stream_type = os.environ.get('STREAM_TYPE', 'admin_logs_streaming')
    limit = int(os.environ.get('LIMIT', '500'))

    if not all([bucket_name, client_id, client_secret, enterprise_id]):
        print('Error: Missing required environment variables')
        return

    try:
        # Get GCS bucket
        bucket = storage_client.bucket(bucket_name)

        # Get OAuth token
        token = get_token(client_id, client_secret, enterprise_id)

        # Load state (stream position)
        state = load_state(bucket, state_key)
        stream_position = state.get('stream_position')

        print(f'Processing events from stream position: {stream_position}')

        total_events = 0
        idx = 0

        while True:
            # Fetch events page
            page = fetch_events(token, stream_type, limit, stream_position)
            entries = page.get('entries') or []

            if not entries:
                next_pos = page.get('next_stream_position') or stream_position
                if next_pos and next_pos != stream_position:
                    save_state(bucket, state_key, {'stream_position': next_pos})
                break

            # Write page to GCS
            timestamp = datetime.now(timezone.utc).strftime('%Y/%m/%d/%H%M%S')
            blob_name = f"{prefix}{timestamp}-box-events-{idx:03d}.json"
            blob = bucket.blob(blob_name)
            blob.upload_from_string(
                json.dumps(page, separators=(',', ':')),
                content_type='application/json'
            )

            idx += 1
            total_events += len(entries)
            stream_position = page.get('next_stream_position') or stream_position

            # Save state after each page
            if stream_position:
                save_state(bucket, state_key, {'stream_position': stream_position})

            # Break if fewer entries than limit (last page)
            if len(entries) < limit:
                break

        print(f'Successfully processed {total_events} events, final position: {stream_position}')

    except Exception as e:
        print(f'Error processing Box events: {str(e)}')
        raise

def get_token(client_id, client_secret, enterprise_id):
    """Get OAuth 2.0 access token using client credentials grant."""
    fields = {
        'grant_type': 'client_credentials',
        'client_id': client_id,
        'client_secret': client_secret,
        'box_subject_type': 'enterprise',
        'box_subject_id': enterprise_id
    }

    response = http.request(
        'POST',
        TOKEN_URL,
        fields=fields,
        headers={'Content-Type': 'application/x-www-form-urlencoded'}
    )

    token_data = json.loads(response.data.decode('utf-8'))
    return token_data['access_token']

def fetch_events(token, stream_type, limit, stream_position=None, timeout=60, max_retries=5):
    """Fetch events from Box API with retry logic."""
    params = {
        'stream_type': stream_type,
        'limit': str(limit),
        'stream_position': stream_position or 'now'
    }

    # Build query string
    query_string = '&'.join([f"{k}={v}" for k, v in params.items()])
    url = f"{EVENTS_URL}?{query_string}"

    attempt = 0
    backoff = 1.0

    while True:
        try:
            response = http.request(
                'GET',
                url,
                headers={'Authorization': f'Bearer {token}'},
                timeout=timeout
            )

            if response.status == 200:
                return json.loads(response.data.decode('utf-8'))
            elif response.status == 429 and attempt < max_retries:
                # Rate limited - retry with backoff
                retry_after = response.headers.get('Retry-After')
                delay = int(retry_after) if retry_after and retry_after.isdigit() else int(backoff)
                print(f'Rate limited, retrying after {delay} seconds')
                import time
                time.sleep(max(1, delay))
                attempt += 1
                backoff *= 2
                continue
            elif 500 <= response.status <= 599 and attempt < max_retries:
                # Server error - retry with backoff
                print(f'Server error {response.status}, retrying after {backoff} seconds')
                import time
                time.sleep(backoff)
                attempt += 1
                backoff *= 2
                continue
            else:
                raise Exception(f'Box API error: {response.status} {response.data.decode("utf-8")}')
        except Exception as e:
            if attempt < max_retries:
                print(f'Request error: {str(e)}, retrying after {backoff} seconds')
                import time
                time.sleep(backoff)
                attempt += 1
                backoff *= 2
                continue
            raise

def load_state(bucket, key):
    """Load state from GCS."""
    try:
        blob = bucket.blob(key)
        if blob.exists():
            state_data = blob.download_as_text()
            return json.loads(state_data)
    except Exception as e:
        print(f'Warning: Could not load state: {str(e)}')
    return {}

def save_state(bucket, key, state):
    """Save state to GCS."""
    try:
        blob = bucket.blob(key)
        blob.upload_from_string(
            json.dumps(state, separators=(',', ':')),
            content_type='application/json'
        )
    except Exception as e:
        print(f'Warning: Could not save state: {str(e)}')

Segundo arquivo: requirements.txt:

functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

Clique em Implantar para salvar e implantar a função.
Aguarde a conclusão da implantação (2 a 3 minutos).

Observação: a configuração do acionador do Pub/Sub cria automaticamente as assinaturas e permissões necessárias.

Criar o job do Cloud Scheduler

O Cloud Scheduler publica mensagens no tópico do Pub/Sub em intervalos regulares, acionando a função do Cloud Run.

No Console do GCP, acesse o Cloud Scheduler.
Clique em Criar job.

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nome	`box-collaboration-schedule-15min`
Região	Selecione a mesma região da função do Cloud Run
Frequência	`/15 * * *` (a cada 15 minutos)
Fuso horário	Selecione o fuso horário (UTC recomendado)
Tipo de destino	Pub/Sub
Tópico	Selecione o tópico do Pub/Sub (`box-collaboration-trigger`).
Corpo da mensagem	`{}` (objeto JSON vazio)

Clique em Criar.

Opções de frequência de programação

Escolha a frequência com base no volume de registros e nos requisitos de latência:

Frequência	Expressão Cron	Caso de uso
A cada 5 minutos	`/5 * * *`	Alto volume e baixa latência
A cada 15 minutos	`/15 * * *`	Volume médio (recomendado)
A cada hora	`0 * * * *`	Padrão
A cada 6 horas	`0 /6 * *`	Baixo volume, processamento em lote
Diário	`0 0 * * *`	Coleta de dados históricos

Testar a integração

No console do Cloud Scheduler, encontre seu job.
Clique em Executar à força para acionar o job manualmente.
Aguarde alguns segundos.
Acesse Cloud Run > Serviços.
Clique no nome da função (box-collaboration-collector).
Clique na guia Registros.

Verifique se a função foi executada com sucesso. Procure o seguinte:

Processing events from stream position: ...
Page 1: Retrieved X events
Wrote X records to gs://box-collaboration-logs/box/collaboration/...
Successfully processed X events

Acesse Cloud Storage > Buckets.
Clique no nome do bucket.
Navegue até a pasta de prefixo (box/collaboration/).
Verifique se um novo arquivo .json foi criado com o carimbo de data/hora atual.

Se você encontrar erros nos registros:

HTTP 401: verifique as credenciais da API Box nas variáveis de ambiente
HTTP 403: verifique se o app Box tem as permissões necessárias e está autorizado no Admin Console.
HTTP 429: limitação de taxa. A função vai tentar novamente automaticamente com espera.
Variáveis de ambiente ausentes: verifique se todas as variáveis necessárias estão definidas.

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.

Receber o e-mail da conta de serviço

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, Box Collaboration).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Caixa como o Tipo de registro.
Clique em Receber conta de serviço. Um e-mail exclusivo da conta de serviço será 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.

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.

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.

Observação: se você planeja usar a opção de exclusão "Excluir arquivos transferidos" ou "Excluir arquivos transferidos e diretórios vazios", conceda o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage.

Configurar um feed no Google SecOps para ingerir registros do Box

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, Box Collaboration).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Caixa como o Tipo de registro.
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://box-collaboration-logs/box/collaboration/
```
  - Substitua:
    - box-collaboration-logs: o nome do bucket do GCS.
    - box/collaboration/: prefixo/caminho da pasta onde os registros são armazenados.
  - Exemplos:
    - Bucket raiz: gs://company-logs/
    - Com prefixo: gs://company-logs/box-logs/
    - Com subpasta: gs://company-logs/box/collaboration/
  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.

Tabela de mapeamento do UDM

Campo de registro	Mapeamento do UDM	Lógica
additional_details.ekm_id	additional.fields	Valor extraído de "additional_details.ekm_id"
additional_details.service_id	additional.fields	Valor extraído de "additional_details.service_id"
additional_details.service_name	additional.fields	Valor extraído de additional_details.service_name
additional_details.shared_link_id	additional.fields	Valor extraído de "additional_details.shared_link_id"
additional_details.size	target.file.size	Valor extraído de "additional_details.size"
additional_details.version_id	additional.fields	Valor extraído de "additional_details.version_id"
created_at	metadata.event_timestamp	Valor extraído de "created_at"
created_by.id	principal.user.userid	Valor extraído de created_by.id
created_by.login	principal.user.email_addresses	Valor extraído de created_by.login
created_by.name	principal.user.user_display_name	Valor extraído de created_by.name
event_id	metadata.product_log_id	Valor extraído de event_id
event_type	metadata.product_event_type	Valor extraído de "event_type"
ip_address	principal.ip	Valor extraído de "ip_address"
source.item_id	target.file.product_object_id	Valor extraído de "source.item_id"
source.item_name	target.file.full_path	Valor extraído de source.item_name
source.item_type	Não mapeados
source.login	target.user.email_addresses	Valor extraído de "source.login"
source.name	target.user.user_display_name	Valor extraído de "source.name"
source.owned_by.id	target.user.userid	Valor extraído de source.owned_by.id
source.owned_by.login	target.user.email_addresses	Valor extraído de source.owned_by.login
source.owned_by.name	target.user.user_display_name	Valor extraído de source.owned_by.name
source.parent.id	Não mapeados
source.parent.name	Não mapeados
source.parent.type	Não mapeados
source.type	Não mapeados
tipo	metadata.log_type	Valor extraído do tipo
metadata.vendor_name		Valor fixado no código
metadata.product_name		Valor fixado no código
security_result.action		Derivado de "event_type". Se event_type for FAILED_LOGIN, será BLOCK. Se for USER_LOGIN, será ALLOW. Caso contrário, será UNSPECIFIED.
extensions.auth.type		Derivado de "event_type". Se event_type for USER_LOGIN ou ADMIN_LOGIN, MACHINE. Caso contrário, UNSPECIFIED.
extensions.auth.mechanism		Derivado de "event_type". Se event_type for USER_LOGIN ou ADMIN_LOGIN, será USERNAME_PASSWORD. Caso contrário, será UNSPECIFIED.

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