Coletar registros do BeyondTrust Endpoint Privilege Management (EPM)

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros do BeyondTrust Endpoint Privilege Management (EPM) no Google Security Operations usando o Google Cloud Storage. O analisador se concentra em transformar dados de registro JSON brutos do BeyondTrust Endpoint em um formato estruturado de acordo com o UDM do Chronicle. Primeiro, ele inicializa os valores padrão para vários campos e, em seguida, analisa o payload JSON, mapeando campos específicos do registro bruto para os campos correspondentes da UDM no objeto event.idm.read_only_udm.

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 locatário ou à API do BeyondTrust Endpoint Privilege Management

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, `beyondtrust-epm-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.

Coletar credenciais da API BeyondTrust EPM

Faça login no console da Web do BeyondTrust Privilege Management como administrador.
Acesse Configuração > Configurações > Configurações de API.
Clique em Criar uma conta de API.
Informe os seguintes detalhes de configuração:
- Nome: insira Google SecOps Collector.
- Acesso à API: ative Auditoria (leitura) e outros escopos conforme necessário.
Copie e salve o ID do cliente e a chave secreta do cliente.
Copie o URL de base da API. Normalmente, ele é https://<your-tenant>-services.pm.beyondtrustcloud.com. Use-o como BPT_API_URL.

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 beyondtrust-epm-collector-sa.
- Descrição da conta de serviço: insira Service account for Cloud Run function to collect BeyondTrust EPM 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 (por exemplo, beyondtrust-epm-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 beyondtrust-epm-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 EPM do BeyondTrust 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	`beyondtrust-epm-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 beyondtrust-epm-trigger.
4. Clique em Salvar.
Na seção Autenticação:
1. Selecione Exigir autenticação.
2. Confira 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 beyondtrust-epm-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`	`beyondtrust-epm-logs`
`GCS_PREFIX`	`beyondtrust-epm/`
`STATE_KEY`	`beyondtrust-epm/state.json`
`BPT_API_URL`	`https://yourtenant-services.pm.beyondtrustcloud.com`
`CLIENT_ID`	`your-client-id`
`CLIENT_SECRET`	`your-client-secret`
`OAUTH_SCOPE`	`management-api`
`RECORD_SIZE`	`1000`
`MAX_ITERATIONS`	`10`

Role a tela para baixo na guia Variáveis e secrets até Solicitações:
- Tempo limite da solicitação: insira 600 segundos (10 minutos).
Acesse a guia Configurações em Contêineres:
- Na seção Recursos:
  - Memória: selecione 512 MiB ou mais.
  - CPU: selecione 1.
- Clique em Concluído.
Role até Ambiente de execução:
- Selecione Padrão (recomendado).
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, timedelta
import time

# Initialize HTTP client
http = urllib3.PoolManager()

# Initialize Storage client
storage_client = storage.Client()

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch logs from BeyondTrust EPM API 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', 'beyondtrust-epm/')
    state_key = os.environ.get('STATE_KEY', 'beyondtrust-epm/state.json')

    # BeyondTrust EPM API credentials
    api_url = os.environ.get('BPT_API_URL')
    client_id = os.environ.get('CLIENT_ID')
    client_secret = os.environ.get('CLIENT_SECRET')
    oauth_scope = os.environ.get('OAUTH_SCOPE', 'management-api')
    record_size = int(os.environ.get('RECORD_SIZE', '1000'))
    max_iterations = int(os.environ.get('MAX_ITERATIONS', '10'))

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

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

        # Load state (last processed timestamp)
        state = load_state(bucket, state_key)
        last_timestamp = state.get('last_timestamp', (datetime.utcnow() - timedelta(hours=24)).strftime("%Y-%m-%dT%H:%M:%SZ"))

        print(f'Processing logs since {last_timestamp}')

        # Get OAuth access token
        token = get_oauth_token(api_url, client_id, client_secret, oauth_scope)

        # Fetch audit events
        events = fetch_audit_events(api_url, token, last_timestamp, record_size, max_iterations)

        if events:
            # Store events in GCS
            current_timestamp = datetime.utcnow()
            filename = f"{prefix}beyondtrust-epm-events-{current_timestamp.strftime('%Y%m%d_%H%M%S')}.json"
            store_events_to_gcs(bucket, filename, events)

            # Update state with latest timestamp
            latest_timestamp = get_latest_event_timestamp(events)
            save_state(bucket, state_key, {'last_timestamp': latest_timestamp, 'updated_at': datetime.utcnow().isoformat() + 'Z'})

            print(f'Successfully processed {len(events)} events and stored to {filename}')
        else:
            print('No new events found')

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

def get_oauth_token(api_url, client_id, client_secret, scope):
    """
    Get OAuth access token using client credentials flow for BeyondTrust EPM.
    Uses the correct endpoint: /oauth/token
    """
    token_url = f"{api_url}/oauth/token"
    headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    body = f"grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope={scope}"

    response = http.request('POST', token_url, headers=headers, body=body, timeout=urllib3.Timeout(60.0))

    if response.status != 200:
        raise RuntimeError(f"Token request failed: {response.status} {response.data[:256]!r}")

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

def fetch_audit_events(api_url, access_token, last_timestamp, record_size, max_iterations):
    """
    Fetch audit events using the BeyondTrust EPM API endpoint: /management-api/v2/AuditEvents
    with query parameters for filtering and pagination
    """
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }

    all_events = []
    current_start_date = last_timestamp
    iterations = 0

    # Enforce maximum RecordSize limit of 1000 based on BeyondTrust documentation
    record_size_limited = min(record_size, 1000)

    while iterations < max_iterations:
        iterations += 1

        if len(all_events) >= 10000:
            print(f"Reached maximum events limit (10000)")
            break

        # Use the BeyondTrust EPM API endpoint for audit events
        query_url = f"{api_url}/management-api/v2/AuditEvents"
        params = {
            'StartDate': current_start_date,
            'RecordSize': record_size_limited
        }

        # Construct URL with query parameters
        query_string = '&'.join([f"{k}={v}" for k, v in params.items()])
        full_url = f"{query_url}?{query_string}"

        try:
            response = http.request('GET', full_url, headers=headers, timeout=urllib3.Timeout(300.0))

            # Handle rate limiting with exponential backoff
            if response.status == 429:
                retry_after = int(response.headers.get('Retry-After', '30'))
                print(f"Rate limited (429). Retrying after {retry_after}s...")
                time.sleep(retry_after)
                continue

            if response.status != 200:
                raise RuntimeError(f"API request failed: {response.status} {response.data[:256]!r}")

            response_data = json.loads(response.data.decode('utf-8'))
            events = response_data.get('events', [])

            if not events:
                break

            print(f"Page {iterations}: Retrieved {len(events)} events")
            all_events.extend(events)

            # If we got fewer events than RecordSize, we've reached the end
            if len(events) < record_size_limited:
                break

            # For pagination, update StartDate to the timestamp of the last event
            last_event = events[-1]
            last_timestamp = extract_event_timestamp(last_event)

            if not last_timestamp:
                print("Warning: Could not find timestamp in last event for pagination")
                break

            # Convert to datetime and add 1 second to avoid retrieving the same event again
            try:
                dt = parse_timestamp(last_timestamp)
                dt = dt + timedelta(seconds=1)
                current_start_date = dt.strftime("%Y-%m-%dT%H:%M:%SZ")
            except Exception as e:
                print(f"Error parsing timestamp {last_timestamp}: {e}")
                break

        except Exception as e:
            print(f"Error fetching page {iterations}: {e}")
            break

    return all_events

def extract_event_timestamp(event):
    """Extract timestamp from event, checking multiple possible fields"""
    # Check common timestamp fields
    timestamp_fields = ['event.dateTime', 'event.timestamp', 'timestamp', 'eventTime', 'dateTime', 'whenOccurred', 'date', 'time', 'event.ingested']

    # Try nested event.dateTime first (common in BeyondTrust)
    if isinstance(event, dict) and isinstance(event.get("event"), dict):
        ts = event["event"].get("dateTime")
        if ts:
            return ts
        ts = event["event"].get("timestamp")
        if ts:
            return ts

    # Fallback to other timestamp fields
    for field in timestamp_fields:
        if field in event and event[field]:
            return event[field]

    return None

def parse_timestamp(timestamp_str):
    """Parse timestamp string to datetime object, handling various formats"""
    if isinstance(timestamp_str, (int, float)):
        # Unix timestamp (in milliseconds or seconds)
        if timestamp_str > 1e12:  # Milliseconds
            return datetime.fromtimestamp(timestamp_str / 1000, tz=timezone.utc)
        else:  # Seconds
            return datetime.fromtimestamp(timestamp_str, tz=timezone.utc)

    if isinstance(timestamp_str, str):
        # Try different string formats
        try:
            # ISO format with Z
            if timestamp_str.endswith('Z'):
                return datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
            # ISO format with timezone
            elif '+' in timestamp_str or timestamp_str.endswith('00:00'):
                return datetime.fromisoformat(timestamp_str)
            # ISO format without timezone (assume UTC)
            else:
                dt = datetime.fromisoformat(timestamp_str)
                if dt.tzinfo is None:
                    dt = dt.replace(tzinfo=timezone.utc)
                return dt
        except ValueError:
            pass

    raise ValueError(f"Could not parse timestamp: {timestamp_str}")

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),
            content_type='application/json'
        )
    except Exception as e:
        print(f'Warning: Could not save state: {str(e)}')

def store_events_to_gcs(bucket, key, events):
    """Store events as JSONL (one JSON object per line) in GCS"""
    # Convert to JSONL format (one JSON object per line)
    jsonl_content = '\n'.join(json.dumps(event, default=str) for event in events)

    blob = bucket.blob(key)
    blob.upload_from_string(jsonl_content, content_type='application/x-ndjson')

def get_latest_event_timestamp(events):
    """Get the latest timestamp from the events for state tracking"""
    if not events:
        return datetime.utcnow().isoformat() + 'Z'

    latest = None
    for event in events:
        timestamp = extract_event_timestamp(event)
        if timestamp:
            try:
                event_dt = parse_timestamp(timestamp)
                event_iso = event_dt.isoformat() + 'Z'
                if latest is None or event_iso > latest:
                    latest = event_iso
            except Exception as e:
                print(f"Error parsing event timestamp {timestamp}: {e}")
                continue

    return latest or datetime.utcnow().isoformat() + 'Z'

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	`beyondtrust-epm-collector-hourly`
Região	Selecione a mesma região da função do Cloud Run
Frequência	`0 * * * *` (a cada hora, na hora)
Fuso horário	Selecione o fuso horário (UTC recomendado)
Tipo de destino	Pub/Sub
Tópico	Selecione o tópico `beyondtrust-epm-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
A cada hora	`0 * * * *`	Padrão (recomendado)
A cada 6 horas	`0 /6 * *`	Baixo volume, processamento em lote
Diário	`0 0 * * *`	Coleta de dados históricos

Testar o job do programador

No console do Cloud Scheduler, encontre seu job.
Clique em Forçar execução para acionar manualmente.
Aguarde alguns segundos e acesse Cloud Run > Serviços > beyondtrust-epm-collector > Registros.
Verifique se a função foi executada com sucesso.
Verifique o bucket do GCS para confirmar se os registros foram gravados.

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, BeyondTrust EPM logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione BeyondTrust Endpoint Privilege Management 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 BeyondTrust EPM

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, BeyondTrust EPM logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione BeyondTrust Endpoint Privilege Management 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://beyondtrust-epm-logs/beyondtrust-epm/
```
  - Substitua:
    - beyondtrust-epm-logs: o nome do bucket do GCS.
    - beyondtrust-epm/: prefixo/caminho da pasta opcional onde os registros são armazenados (deixe em branco para a raiz).
  - Exemplos:
    - Bucket raiz: gs://beyondtrust-epm-logs/
    - Com prefixo: gs://beyondtrust-epm-logs/beyondtrust-epm/
  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
agent.id	principal.asset.attribute.labels.value	Mapeado para o rótulo com a chave agent_id
agent.version	principal.asset.attribute.labels.value	Mapeado para o rótulo com a chave agent_version
ecs.version	principal.asset.attribute.labels.value	Mapeado para o rótulo com a chave ecs_version
event_data.reason	metadata.description	Descrição do evento do registro bruto
event_datas.ActionId	metadata.product_log_id	Identificador de registro específico do produto.
file.path	principal.file.full_path	Caminho completo do arquivo do evento
headers.content_length	additional.fields.value.string_value	Mapeado para o rótulo com o comprimento de conteúdo principal
headers.content_type	additional.fields.value.string_value	Mapeado para o rótulo com a chave content_type
headers.http_host	additional.fields.value.string_value	Mapeado para o rótulo com a chave http_host
headers.http_version	network.application_protocol_version	Versão do protocolo HTTP
headers.request_method	network.http.method	Método de solicitação HTTP
host.hostname	principal.hostname	Nome do host principal
host.hostname	principal.asset.hostname	Nome do host do recurso principal
host.ip	principal.asset.ip	Endereço IP do recurso principal
host.ip	principal.ip	Endereço IP principal
host.mac	principal.mac	Endereço MAC principal
host.os.platform	principal.platform	Definido como MAC se for igual a macOS
host.os.version	principal.platform_version	Versão do sistema operacional
labels.related_item_id	metadata.product_log_id	Identificador de item relacionado
process.command_line	principal.process.command_line	Linha de comando do processo
process.name	additional.fields.value.string_value	Mapeado para o rótulo com a chave process_name
process.parent.name	additional.fields.value.string_value	Mapeado para o rótulo com a chave process_parent_name
process.parent.pid	principal.process.parent_process.pid	PID do processo pai convertido em string
process.pid	principal.process.pid	PID do processo convertido em string
user.id	principal.user.userid	Identificador do usuário
user.name	principal.user.user_display_name	Nome de exibição do usuário
N/A	metadata.event_timestamp	Carimbo de data/hora do evento definido como o carimbo de data/hora da entrada de registro
N/A	metadata.event_type	GENERIC_EVENT se não houver principal, caso contrário, STATUS_UPDATE
N/A	network.application_protocol	Definido como HTTP se o campo "http_version" contiver HTTP

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