Coletar registros do D3 Banking
Versão do analisador: 2.0
Neste documento, explicamos como ingerir registros do D3 Banking no Google Security Operations usando o Cloud Storage V2.
O D3 Banking (agora NCR Voyix Digital Banking) é uma plataforma de internet banking hospedada na nuvem que gera registros de auditoria e transações para operações de internet banking, sessões de usuários e ações administrativas. A API REST do NCR Voyix Digital Banking oferece acesso programático a registros de auditoria e dados de eventos.
Antes de começar
Verifique se você tem os pré-requisitos a seguir:
- Uma instância do Google SecOps
- Um projeto do Google Cloud com a API Storage do Cloud Storage ativada.
- Permissões para criar e gerenciar buckets do Cloud Storage
- Permissões para gerenciar políticas do Identity and Access Management (IAM) em buckets do Cloud Storage
- Permissões para criar serviços do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
- Acesso privilegiado à plataforma D3 Banking (NCR Voyix) com função de administrador
- Credenciais do OAuth2 (ID do cliente e chave secreta do cliente) para a API NCR Voyix Digital Banking
criar o bucket do Cloud Storage
- Acesse o console doGoogle 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 globalmente exclusivo (por exemplo, d3-banking-audit-logs)Tipo de local Escolha de acordo com 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 D3 Banking
Conseguir credenciais do OAuth2
- Faça login no portal de administração do D3 Banking (NCR Voyix).
- Acesse Administração > Gerenciamento de APIs (ou Configurações > Integrações).
- Clique em Registrar aplicativo ou Criar cliente de API.
- Insira um nome para o aplicativo (por exemplo,
Google Security Operations Integration). - Anote as seguintes credenciais:
- ID do cliente: o identificador do cliente OAuth2.
- Chave secreta do cliente: a chave secreta do cliente OAuth2.
Anote o URL de base da API do seu locatário (por exemplo,
https://api.d3banking.com/v1ou um URL específico do locatário).
Verificar o acesso à API
Teste suas credenciais antes de prosseguir com a integração:
# Replace with your actual credentials CLIENT_ID="your-client-id" CLIENT_SECRET="your-client-secret" D3_BASE="https://api.d3banking.com/v1" # Obtain access token TOKEN=$(curl -s -X POST "${D3_BASE}/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}" \ | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])") # Test audit log access curl -s -H "Authorization: Bearer ${TOKEN}" \ "${D3_BASE}/audit-logs?limit=1" | head -c 500
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 Cloud Storage e ser invocada pelo Pub/Sub.
Criar a conta de serviço
- No console do Google Cloud , 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
d3-banking-logs-collector-sa. - Descrição da conta de serviço: insira
Service account for Cloud Run function to collect D3 Banking logs
- Nome da conta de serviço: insira
- Clique em Criar e continuar.
- Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis:
- Clique em Selecionar papel.
- Pesquise e selecione Administrador de objetos do Storage.
- Clique em + Adicionar outro papel.
- Pesquise e selecione Invocador do Cloud Run.
- Clique em + Adicionar outro papel.
- 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 no bucket do Cloud Storage 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 Cloud Storage
Conceda à conta de serviço permissões de gravação no bucket do Cloud Storage:
- Acesse Cloud Storage > Buckets.
- Clique no nome do bucket (por exemplo,
d3-banking-audit-logs). - 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,
d3-banking-logs-collector-sa@PROJECT_ID.iam.gserviceaccount.com) - Atribuir papéis: selecione Administrador de objetos do Storage.
- Adicionar principais: insira o e-mail da conta de serviço (por exemplo,
- 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 Google Cloud , acesse Pub/Sub > Tópicos.
- Selecione Criar tópico.
- Informe os seguintes detalhes de configuração:
- ID do tópico: insira
d3-banking-logs-trigger. - Não mude as outras configurações.
- ID do tópico: insira
- Clique em Criar.
Criar uma função do Cloud Run para coletar registros
A função do Cloud Run será acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar registros da API REST do NCR Voyix Digital Banking e gravá-los no Cloud Storage.
- No console do Google Cloud , 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 d3-banking-logs-collectorRegião Selecione a região correspondente ao bucket do Cloud Storage (por exemplo, us-central1)Ambiente de execução Selecione Python 3.12 ou mais recente. Na seção Gatilho (opcional):
- Clique em + Adicionar gatilho.
- Selecione Cloud Pub/Sub.
- Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico
d3-banking-logs-trigger. - Clique em Salvar.
Na seção Autenticação:
- Selecione Exigir autenticação.
- Verifique o Identity and Access Management (IAM).
Role para baixo e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço
d3-banking-logs-collector-sa.
- Conta de serviço: selecione a conta de serviço
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 Descrição GCS_BUCKETd3-banking-audit-logsNome do bucket do Cloud Storage GCS_PREFIXd3bankingPrefixo para arquivos de registro STATE_KEYd3banking/state.jsonCaminho do arquivo de estado D3_API_BASEhttps://api.d3banking.com/v1URL de base da API D3 Banking D3_CLIENT_IDyour-client-idID do cliente OAuth 2.0 D3_CLIENT_SECRETyour-client-secretChave secreta do cliente OAuth2 MAX_RECORDS5000Máximo de registros por execução PAGE_SIZE1000Registros por página LOOKBACK_HOURS24Período de lookback inicial Na seção Variáveis e secrets, role para baixo até Solicitações:
- Tempo limite da solicitação: insira
600segundos (10 minutos)
- Tempo limite da solicitação: insira
Acesse a guia Configurações:
- Na seção Recursos:
- Memória: selecione 512 MiB ou mais.
- CPU: selecione 1.
- Na seção Recursos:
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)
- Número mínimo de instâncias: insira
Clique em Criar.
Aguarde a criação do serviço (1 a 2 minutos).
Depois que o serviço for criado, o editor de código inline será aberto automaticamente.
Adicionar código da função
- Insira main no campo Ponto de entrada.
No editor de código inline, 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 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() # Environment variables GCS_BUCKET = os.environ.get('GCS_BUCKET') GCS_PREFIX = os.environ.get('GCS_PREFIX', 'd3banking') STATE_KEY = os.environ.get('STATE_KEY', 'd3banking/state.json') D3_API_BASE = os.environ.get('D3_API_BASE', 'https://api.d3banking.com/v1') D3_CLIENT_ID = os.environ.get('D3_CLIENT_ID') D3_CLIENT_SECRET = os.environ.get('D3_CLIENT_SECRET') MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000')) PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000')) LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24')) def to_unix_millis(dt: datetime) -> int: """Convert datetime to Unix epoch milliseconds.""" if dt.tzinfo is None: dt = dt.replace(tzinfo=timezone.utc) dt = dt.astimezone(timezone.utc) return int(dt.timestamp() * 1000) def parse_datetime(value: str) -> datetime: """Parse ISO datetime string to datetime object.""" if value.endswith("Z"): value = value[:-1] + "+00:00" return datetime.fromisoformat(value) def get_access_token(): """ Obtain an OAuth2 access token using client credentials. """ api_base = D3_API_BASE.rstrip('/') token_url = f"{api_base}/oauth/token" headers = { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' } body = f"grant_type=client_credentials&client_id={D3_CLIENT_ID}&client_secret={D3_CLIENT_SECRET}" backoff = 1.0 for attempt in range(3): response = http.request('POST', token_url, body=body, headers=headers) if response.status == 429: retry_after = int(response.headers.get('Retry-After', str(int(backoff)))) print(f"Rate limited (429) on token request. Retrying after {retry_after}s...") time.sleep(retry_after) backoff = min(backoff * 2, 30.0) continue if response.status != 200: raise RuntimeError(f"Failed to get access token: {response.status} - {response.data.decode('utf-8')}") data = json.loads(response.data.decode('utf-8')) return data['access_token'] raise RuntimeError("Failed to get access token after 3 retries") @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch D3 Banking audit logs and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ if not all([GCS_BUCKET, D3_CLIENT_ID, D3_CLIENT_SECRET]): print('Error: Missing required environment variables') return try: bucket = storage_client.bucket(GCS_BUCKET) # Load state state = load_state(bucket, STATE_KEY) # Determine time window now = datetime.now(timezone.utc) last_time = None if isinstance(state, dict) and state.get("last_event_time"): try: last_time = parse_datetime(state["last_event_time"]) # Overlap by 2 minutes to catch any delayed events last_time = last_time - timedelta(minutes=2) except Exception as e: print(f"Warning: Could not parse last_event_time: {e}") if last_time is None: last_time = now - timedelta(hours=LOOKBACK_HOURS) print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}") # Get access token token = get_access_token() # Fetch audit logs records, newest_event_time = fetch_logs( token=token, start_time=last_time, end_time=now, page_size=PAGE_SIZE, max_records=MAX_RECORDS, ) if not records: print("No new log records found.") save_state(bucket, STATE_KEY, now.isoformat()) return # Write to GCS as NDJSON timestamp = now.strftime('%Y%m%d_%H%M%S') object_key = f"{GCS_PREFIX}/logs_{timestamp}.ndjson" blob = bucket.blob(object_key) ndjson = '\n'.join([json.dumps(record, ensure_ascii=False) for record in records]) + '\n' blob.upload_from_string(ndjson, content_type='application/x-ndjson') print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}") # Update state with newest event time if newest_event_time: save_state(bucket, STATE_KEY, newest_event_time) else: save_state(bucket, STATE_KEY, now.isoformat()) print(f"Successfully processed {len(records)} records") except Exception as e: print(f'Error processing logs: {str(e)}') 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: {e}") return {} def save_state(bucket, key, last_event_time_iso: str): """Save the last event timestamp to GCS state file.""" try: state = {'last_event_time': last_event_time_iso} blob = bucket.blob(key) blob.upload_from_string( json.dumps(state, indent=2), content_type='application/json' ) print(f"Saved state: last_event_time={last_event_time_iso}") except Exception as e: print(f"Warning: Could not save state: {e}") def fetch_logs(token: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int): """ Fetch audit logs from NCR Voyix Digital Banking REST API with pagination and rate limiting. Args: token: OAuth2 access token start_time: Start time for log query end_time: End time for log query page_size: Number of records per page max_records: Maximum total records to fetch Returns: Tuple of (records list, newest_event_time ISO string) """ api_base = D3_API_BASE.rstrip('/') endpoint = f"{api_base}/audit-logs" headers = { 'Authorization': f'Bearer {token}', 'Accept': 'application/json', 'User-Agent': 'GoogleSecOps-D3BankingCollector/1.0' } records = [] newest_time = None page_num = 0 backoff = 1.0 offset = 0 while True: page_num += 1 if len(records) >= max_records: print(f"Reached max_records limit ({max_records})") break # Build query parameters params = { 'startDate': start_time.strftime('%Y-%m-%dT%H:%M:%SZ'), 'endDate': end_time.strftime('%Y-%m-%dT%H:%M:%SZ'), 'limit': min(page_size, max_records - len(records)), 'offset': offset } query_string = '&'.join(f"{k}={v}" for k, v in params.items()) url = f"{endpoint}?{query_string}" try: response = http.request( 'GET', url, headers=headers ) # Handle rate limiting with exponential backoff if response.status == 429: retry_after = int(response.headers.get('Retry-After', str(int(backoff)))) print(f"Rate limited (429). Retrying after {retry_after}s...") time.sleep(retry_after) backoff = min(backoff * 2, 30.0) continue backoff = 1.0 if response.status != 200: print(f"HTTP Error: {response.status}") response_text = response.data.decode('utf-8') print(f"Response body: {response_text}") return [], None data = json.loads(response.data.decode('utf-8')) page_results = data.get('auditLogs', data.get('events', data.get('data', []))) if not page_results: print(f"No more results (empty page)") break print(f"Page {page_num}: Retrieved {len(page_results)} events") records.extend(page_results) # Track newest event time for event in page_results: try: event_ts = event.get('timestamp') or event.get('created') or event.get('eventDate') if event_ts: if isinstance(event_ts, (int, float)): event_dt = datetime.fromtimestamp(event_ts / 1000, tz=timezone.utc) event_time = event_dt.isoformat() else: event_time = str(event_ts) if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time): newest_time = event_time except Exception as e: print(f"Warning: Could not parse event time: {e}") # Check for more results offset += len(page_results) if len(page_results) < page_size: print("No more pages (partial page received)") break except Exception as e: print(f"Error fetching logs: {e}") return [], None print(f"Retrieved {len(records)} total records from {page_num} pages") return records, newest_timeSegundo 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).
Criar um job do Cloud Scheduler
O Cloud Scheduler vai publicar mensagens no tópico do Pub/Sub em intervalos regulares, acionando a função do Cloud Run.
- No console do Google Cloud , acesse o Cloud Scheduler.
- Clique em Criar job.
Informe os seguintes detalhes de configuração:
Configuração Valor Nome d3-banking-logs-collector-hourlyRegião Selecione a mesma região da função do Cloud Run Frequência 0 * * * *(de hora em hora)Fuso horário Selecione o fuso horário (UTC recomendado) Tipo de destino Pub/Sub Tópico Selecione o tópico d3-banking-logs-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 * * * |
Processamento em lote de baixo volume |
| Diário | 0 0 * * * |
Coleta de dados históricos |
Testar a integração
- No console do Cloud Scheduler, encontre seu job.
- Clique em Forçar execução para acionar o job manualmente.
- Aguarde alguns segundos.
- Acesse Cloud Run > Serviços.
- Clique em
d3-banking-logs-collector. - Clique na guia Registros.
Verifique se a função foi executada com sucesso. Procure por:
Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00 Page 1: Retrieved X events Wrote X records to gs://d3-banking-audit-logs/d3banking/logs_YYYYMMDD_HHMMSS.ndjson Successfully processed X recordsAcesse Cloud Storage > Buckets.
Clique no nome do bucket (
d3-banking-audit-logs).Navegue até a pasta
d3banking/.Verifique se um novo arquivo
.ndjsonfoi criado com o carimbo de data/hora atual.
Se você encontrar erros nos registros:
- HTTP 401: verifique as credenciais do OAuth2 nas variáveis de ambiente.
- HTTP 403: verifique se a conta tem as permissões de administrador necessárias no portal de administração do D3 Banking.
- HTTP 429: limitação de taxa. A função vai tentar novamente de forma automática com espera
- Variáveis de ambiente ausentes: verifique se todas as variáveis necessárias estão definidas.
Configurar um feed no Google SecOps para ingerir registros do D3 Banking
- Acesse Configurações > Gerenciamento de dados > Feeds. Se você estiver em uma plataforma somente SIEM, acesse Configurações > 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,
D3 Banking Logs). - Selecione Google Cloud Storage V2 como o Tipo de origem.
- Selecione D3 Banking como o Tipo de registro.
Clique em Get Service Account. Um e-mail exclusivo da conta de serviço será exibido, por exemplo:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.comCopie o endereço de e-mail.
Clique em Próxima.
Especifique valores para os seguintes parâmetros de entrada:
URL do bucket de armazenamento: insira o URI do bucket do Cloud Storage com o caminho do prefixo:
gs://d3-banking-audit-logs/d3banking/- Substitua:
d3-banking-audit-logs: o nome do bucket do Cloud Storage.d3banking: prefixo/caminho de pasta opcional em que os registros são armazenados (deixe em branco para a raiz).
- Substitua:
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 arquivos após a transferência.
Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência.
Idade máxima do arquivo: inclua arquivos modificados no último número de dias (o padrão é 180 dias).
Namespace do recurso: o namespace do recurso
Rótulos de ingestão: o rótulo que será aplicado aos eventos desse feed.
Clique em Próxima.
Revise a configuração do seu novo feed de notícias 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 bucket do Cloud Storage.
- Acesse Cloud Storage > Buckets.
- Clique no nome do seu bucket.
- Acesse a guia Permissões.
- Clique em Conceder acesso.
- Informe os seguintes detalhes de configuração:
- Adicionar principais: cole o e-mail da conta de serviço do Google SecOps.
- Atribuir papéis: selecione Leitor de objetos do Storage.
- Clique em Salvar.
Tabela de mapeamento de UDM
| Campo de registro | Mapeamento de UDM | Lógica |
|---|---|---|
USER_DEVICE_TOKEN_label |
additional.fields |
Mesclado |
actingProfileType_label |
additional.fields |
Mesclado |
companyId_label |
additional.fields |
Mesclado |
component_label |
additional.fields |
Mesclado |
deleted_label |
additional.fields |
Mesclado |
enrolledInBiometricAuth_label |
additional.fields |
Mesclado |
errors_label |
additional.fields |
Mesclado |
eventClass_label |
additional.fields |
Mesclado |
issue_label |
additional.fields |
Mesclado |
q_status_label |
additional.fields |
Mesclado |
settingsSecQuest_label |
additional.fields |
Mesclado |
shadowAssistUserId_label |
additional.fields |
Mesclado |
shadowAssistUsername_label |
additional.fields |
Mesclado |
source_label |
additional.fields |
Mesclado |
status_label |
additional.fields |
Mesclado |
topic_label |
additional.fields |
Mesclado |
mechanism |
extensions.auth.mechanism |
Mesclado |
LOGIN_SESSION_TYPE |
extensions.auth.type |
Mapeado diretamente |
defined.message |
metadata.description |
Mapeado diretamente |
@timestamp |
metadata.event_timestamp |
Analisado como ISO8601 |
event_type |
metadata.event_type |
Mapeado diretamente |
auditId |
metadata.product_event_type |
Mapeado diretamente |
messageId |
metadata.product_event_type |
Mapeado diretamente |
@version |
metadata.product_version |
Mapeado diretamente |
http |
network.http |
Renomeado/mapeado |
sessionId |
network.session_id |
Mapeado diretamente |
clientIp |
principal.ip |
Mesclado |
userClass |
principal.user.group_identifiers |
Mesclado |
username |
principal.user.user_display_name |
Mapeado diretamente |
userId |
principal.user.userid |
Mapeado diretamente |
sec_result |
security_result |
Mesclado |
application |
target.application |
Mapeado diretamente |
deviceUuid |
target.asset_id |
Mapeado diretamente |
subcomponent |
target.file.names |
Mesclado |
producerHostname |
target.hostname |
Mapeado diretamente |
producerIp |
target.ip |
Mesclado |
fullAddress |
target.location.name |
Mapeado diretamente |
resource |
target.resource |
Renomeado/mapeado |
userId |
target.user.userid |
Mapeado diretamente |
| N/A | extensions.auth.type |
Constante: AUTHTYPE_UNSPECIFIED |
| N/A | metadata.event_type |
Constante: GENERIC_EVENT |
| N/A | metadata.product_name |
Constante: D3_BANKING |
| N/A | metadata.vendor_name |
Constante: D3_BANKING |
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.