Coletar registros do Tenable CSPM
Este documento explica como ingerir registros do Tenable CSPM no Google Security Operations usando o Google Cloud Storage V2.
O Tenable CSPM (gerenciamento de postura de segurança na nuvem) é uma plataforma de segurança na nuvem para detecção de configurações incorretas e monitoramento de conformidade em ambientes de nuvem. Uma função do Cloud Run consulta a API Tenable CSPM de acordo com uma programação, grava as descobertas em um bucket do GCS no formato NDJSON, e o Google SecOps as ingere por um feed do GCS V2.
Antes de começar
Verifique se você atende aos 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 console do Tenable Cloud Security com permissões de administrador
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 globalmente exclusivo (por exemplo, tenable-cspm-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 Tenable CSPM
Gerar chaves de API
- Faça login no console do Tenable Cloud Security como administrador.
- Acesse Configurações > Chaves de API.
- Clique em Gerar para criar um novo par de chaves de API.
- Copie e salve os seguintes detalhes em um local seguro:
- Chave de acesso: a chave de acesso da API para autenticação.
- Chave secreta: a chave secreta da API para autenticação.
Verifique as permissões
Para verificar se a conta tem as permissões necessárias:
- Faça login no console do Tenable Cloud Security.
- Acesse Descobertas ou Conformidade > Relatórios.
- Se você conseguir ver os dados das descobertas, significa que tem as permissões necessárias.
- Se essa opção não estiver disponível, entre em contato com o administrador do Tenable para receber acesso de administrador.
Testar o acesso à API
Teste suas credenciais antes de prosseguir com a integração:
# Replace with your actual credentials ACCESS_KEY="your-access-key" SECRET_KEY="your-secret-key" # Test API access curl -v -H "X-ApiKeys: accessKey=${ACCESS_KEY};secretKey=${SECRET_KEY}" \ "https://cloud.tenable.com/cspm/v1/findings?limit=1"
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
tenable-cspm-collector-sa. - Descrição da conta de serviço: insira
Service account for Cloud Run function to collect Tenable CSPM 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: gravar registros no bucket do GCS e gerenciar 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 à conta de serviço permissões de gravação no bucket do GCS:
- Acesse Cloud Storage > Buckets.
- Clique no nome do bucket (por exemplo,
tenable-cspm-logs). - Acesse a guia Permissões.
- Clique em Conceder acesso.
- Informe os seguintes detalhes de configuração:
- Adicionar participantes: insira o e-mail da conta de serviço (por exemplo,
tenable-cspm-collector-sa@your-project.iam.gserviceaccount.com). - Atribuir papéis: selecione Administrador de objetos do Storage.
- Adicionar participantes: 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 GCP, acesse Pub/Sub > Tópicos.
- Selecione Criar tópico.
- Informe os seguintes detalhes de configuração:
- ID do tópico: insira
tenable-cspm-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 descobertas da API Tenable CSPM e gravá-las 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 tenable-cspm-collectorRegião Selecione a região correspondente ao bucket do GCS (por exemplo, us-central1).Ambiente de execução Selecione Python 3.12 ou mais recente. Na seção Acionador (opcional):
- Clique em + Adicionar gatilho.
- Selecione Cloud Pub/Sub.
- Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico
tenable-cspm-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
tenable-cspm-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_BUCKETtenable-cspm-logsNome do bucket do GCS GCS_PREFIXtenable-cspmPrefixo para arquivos de registro STATE_KEYtenable-cspm/state.jsonCaminho do arquivo de estado TENABLE_ACCESS_KEYyour-access-keyChave de acesso da API Tenable TENABLE_SECRET_KEYyour-secret-keyChave secreta da API Tenable MAX_RECORDS10000Máximo de registros por execução PAGE_SIZE1000Registros por página LOOKBACK_HOURS24Período de lookback inicial Role para baixo na guia Variáveis e secrets até Solicitações:
- Tempo limite da solicitação: insira
600segundos (10 minutos).
- Tempo limite da solicitação: insira
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.
- Na seção Recursos:
Role para baixo 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).
- 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 em Ponto de entrada da função.
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 # 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', 'tenable-cspm') STATE_KEY = os.environ.get('STATE_KEY', 'tenable-cspm/state.json') ACCESS_KEY = os.environ.get('TENABLE_ACCESS_KEY') SECRET_KEY = os.environ.get('TENABLE_SECRET_KEY') MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000')) PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000')) LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24')) API_BASE = 'https://cloud.tenable.com' 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) @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch Tenable CSPM findings and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ if not all([GCS_BUCKET, ACCESS_KEY, SECRET_KEY]): 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"]) 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 findings from {last_time.isoformat()} to {now.isoformat()}") # Fetch findings records, newest_event_time = fetch_findings( start_time=last_time, end_time=now, page_size=PAGE_SIZE, max_records=MAX_RECORDS, ) if not records: print("No new findings 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}/findings_{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 findings: {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_findings(start_time: datetime, end_time: datetime, page_size: int, max_records: int): """ Fetch findings from Tenable CSPM API with pagination and rate limiting. Args: start_time: Start time for findings query end_time: End time for findings 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) """ endpoint = f"{API_BASE}/cspm/v1/findings" headers = { 'X-ApiKeys': f'accessKey={ACCESS_KEY};secretKey={SECRET_KEY}', 'Accept': 'application/json', 'User-Agent': 'GoogleSecOps-TenableCSPMCollector/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 current_limit = min(page_size, max_records - len(records)) url = f"{endpoint}?limit={current_limit}&offset={offset}" 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 if isinstance(data, list) else data.get('findings', data.get('data', [])) if not page_results: print(f"No more results (empty page)") break # Filter by time window filtered = [] for finding in page_results: status_time = finding.get('statusUpdateTime') or finding.get('createdAt') or finding.get('updatedAt') if status_time: try: finding_dt = parse_datetime(status_time) if finding_dt >= start_time and finding_dt <= end_time: filtered.append(finding) except Exception: filtered.append(finding) else: filtered.append(finding) print(f"Page {page_num}: Retrieved {len(page_results)} findings, {len(filtered)} in time window") records.extend(filtered) # Track newest event time for finding in filtered: try: event_time = finding.get('statusUpdateTime') or finding.get('createdAt') or finding.get('updatedAt') if event_time: 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 if len(page_results) < page_size: print(f"Reached last page (size={len(page_results)} < limit={page_size})") break offset += len(page_results) except Exception as e: print(f"Error fetching findings: {e}") return [], None print(f"Retrieved {len(records)} total findings from {page_num} pages") return records, newest_time- Segundo arquivo: requirements.txt::
functions-framework==3.* google-cloud-storage==2.* urllib3>=2.0.0Clique em Implantar para salvar e implantar a função.
Aguarde a conclusão da implantação (2 a 3 minutos).
Criar o 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 GCP, acesse o Cloud Scheduler.
- Clique em Criar job.
Informe os seguintes detalhes de configuração:
Configuração Valor Nome tenable-cspm-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 tenable-cspm-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 (
tenable-cspm-collector-hourly). - Clique em Forçar execução para acionar manualmente.
- Aguarde alguns segundos e acesse Cloud Run > Serviços > tenable-cspm-collector > Registros.
Verifique se a função foi executada com sucesso. Procure por:
Fetching findings from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00 Page 1: Retrieved X findings, Y in time window Wrote X records to gs://tenable-cspm-logs/tenable-cspm/findings_YYYYMMDD_HHMMSS.ndjson Successfully processed X recordsVerifique o bucket do GCS (
tenable-cspm-logs) para confirmar se as descobertas foram gravadas.
Se você encontrar erros nos registros:
- HTTP 401: verifique as chaves de API nas variáveis de ambiente.
- HTTP 403: verifique se a conta tem permissões de administrador no console do Tenable Cloud Security.
- 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 de CSPM do Tenable
- 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,
Tenable CSPM Logs). - Selecione Google Cloud Storage V2 como o Tipo de origem.
- Selecione Tenable CSPM 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. Você vai usá-la na próxima etapa.
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://tenable-cspm-logs/tenable-cspm/- Substitua:
tenable-cspm-logs: o nome do bucket do GCS.tenable-cspm/: caminho do prefixo/pasta em que os registros são armazenados.
- 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 nos últimos dias (o padrão é 180 dias).
Namespace do recurso: o namespace do recurso.
Rótulos de ingestão: o rótulo a ser aplicado aos eventos desse feed.
Clique em Próxima.
Revise a configuração do novo 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 Leitor de objetos do Storage no bucket do GCS.
- Acesse Cloud Storage > Buckets.
- Clique no nome do bucket (
tenable-cspm-logs). - 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 |
|---|---|---|
| statusUpdateTime, starred, remediation.console.steps, compliances, labels, serviceNowIncidentUrls, ticketLinks, findingType, identityProviderAccount, status, subStatus, title, type, sentBy | additional.fields | Mesclado com rótulos de chave-valor de statusUpdateTime, starred, remediation.console.steps, cada item na matriz de conformidades, cada item na matriz de rótulos, cada item na matriz serviceNowIncidentUrls, cada item na matriz ticketLinks, findingType, identityProviderAccount, status, subStatus, title, type e sentBy se principal_user não estiver vazio |
| descrição | metadata.description | Valor copiado diretamente |
| has_user, has_target_resource | metadata.event_type | Definido como "USER_RESOURCE_ACCESS" se has_user e has_target_resource forem verdadeiros. Caso contrário, "GENERIC_EVENT" |
| ID | metadata.product_log_id | Valor copiado diretamente |
| metadata.product_name | Defina como "Tenable CSPM" | |
| metadata.vendor_name | Defina como "Tenable CSPM" | |
| link | network.http.referral_url | Valor copiado diretamente |
| source | principal.resource.attribute.labels | Mesclado com o rótulo de chave-valor da origem |
| resourceOwnerPrincipals.0.principal.mail | principal.user.email_addresses | Valor copiado diretamente |
| description, sentBy | principal.user.userid | Valor de principal_user extraído da descrição usando grok se não estiver vazio, caso contrário, sentBy |
| categoria | security_result.category_details | Valor copiado diretamente |
| policyName | security_result.rule_name | Valor copiado diretamente |
| gravidade, | security_result.severity | Defina como LOW se a gravidade for "Low", MEDIUM se for "Medium", HIGH se for "High" e CRITICAL se for "Critical" |
| cloudProvider | target.cloud.environment | Defina como MICROSOFT_AZURE se cloudProvider == "Azure", AMAZON_WEB_SERVICES se "AWS" |
| accountName, accountPath, resourceEnvironment, resourceOwner, resources | target.resource.attribute.labels | Mesclado com rótulos de chave-valor de accountName, accountPath, cada item na matriz resourceEnvironment, cada item na matriz resourceOwner, cada item na matriz resources |
| accountId | target.resource.id | Valor copiado diretamente |
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.