Coletar registros da plataforma MuleSoft Anypoint
Neste documento, explicamos como ingerir eventos de trilha de auditoria dos registros da plataforma MuleSoft Anypoint para o Google Security Operations usando o Cloud Storage.
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 funções do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
- Permissões para criar contas de serviço
- Acesso privilegiado à plataforma Anypoint da MuleSoft
Encontrar o ID da organização do MuleSoft
- Faça login na Anypoint Platform.
- Acesse Gerenciamento de acesso > Organizações.
- Na tabela Grupos por unidade da empresa, clique no nome da sua organização.
- Copie o ID da organização (por exemplo,
0a12b3c4-d5e6-789f-1021-1a2b34cd5e6f).
Como alternativa, acesse MuleSoft Business Groups e copie o ID do URL.
Criar o app conectado do MuleSoft
- Faça login na Anypoint Platform.
- Acesse Gerenciamento de acesso > Apps conectados > Criar app.
- Informe os seguintes detalhes de configuração:
- Nome do app: insira um nome exclusivo (por exemplo,
Google SecOps export). - Selecione O app age em nome próprio (credenciais do cliente).
- Nome do app: insira um nome exclusivo (por exemplo,
- Clique em Adicionar escopos > Visualizador de registros de auditoria > Próxima.
- Selecione todos os grupos de unidades da empresa que têm os registros que você precisa.
- Clique em Próxima > Adicionar escopos.
Clique em Salvar e copie o ID do cliente e a chave secreta do cliente.
Criar um 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, mulesoft-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.
Criar uma conta de serviço para a função do Cloud Run
A função do Cloud Run requer uma conta de serviço com permissões para gravar no bucket do Cloud Storage.
Criar a 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
mulesoft-logs-collector-sa. - Descrição da conta de serviço: insira
Service account for Cloud Run function to collect MuleSoft Anypoint logs.
- Nome da conta de serviço: insira
- Clique em Criar e continuar.
- Na seção Conceda a essa conta de serviço acesso ao projeto:
- 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 as permissões write no bucket do Cloud Storage da seguinte maneira:
- 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: insira o e-mail da conta de serviço (por exemplo,
mulesoft-logs-collector-sa@PROJECT_ID.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 um tópico do 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 da seguinte maneira:
- 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
mulesoft-audit-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 MuleSoft Anypoint e gravá-los no Cloud Storage.
- No Console do GCP, acesse o Cloud Run.
- Clique em Escrever uma função.
Na seção Configurar, forneça os seguintes detalhes de configuração:
Configuração Valor Nome do serviço mulesoft-audit-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, clique em Adicionar gatilho e selecione Gatilho do Pub/Sub.
No painel Gatilho do Eventarc, forneça os seguintes detalhes de configuração:
- Nome do gatilho: mantenha o nome gerado ou insira um nome para o gatilho.
- Tipo de gatilho: selecione Origens do Google.
- Provedor de eventos: selecione Pub/Sub.
- Tipo de evento: selecione google.cloud.pubsub.topic.v1.messagePublished.
- Selecione um tópico do Cloud Pub/Sub: escolha o tópico
mulesoft-audit-trigger. - Região: selecione a mesma região da função.
- Conta de serviço: selecione a conta de serviço
mulesoft-logs-collector-sa.
Clique em Salvar acionador.
Na seção Autenticação:
- Selecione Exigir autenticação.
- Verifique o Identity and Access Management (IAM).
Acesse e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço
mulesoft-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_BUCKETmulesoft-audit-logsNome do bucket do Cloud Storage GCS_PREFIXmulesoft-auditPrefixo para arquivos de registro STATE_KEYmulesoft-audit-state.jsonCaminho do estado, fora do prefixo do registro MULE_ORG_IDyour_org_idID da organização do MuleSoft CLIENT_IDyour_client_idID do cliente do app conectado CLIENT_SECRETyour_client_secretChave secreta do cliente do app conectado MAX_RECORDS10000Máximo de registros por execução PAGE_SIZE200Entradas por página (o máximo da API é 200) LOOKBACK_HOURS24Período de lookback inicial na primeira execução Navegue até a guia Variáveis e secrets e acesse 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:
Acesse 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 o 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 from google.cloud.exceptions import NotFound import hashlib import json import os import urllib3 from urllib.parse import urlencode 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() # MuleSoft API endpoints TOKEN_URL = "https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token" AUDIT_URL = "https://anypoint.mulesoft.com/audit/v2/organizations/{org_id}/query?cursorPagination=true" # Environment variables GCS_BUCKET = os.environ.get('GCS_BUCKET') GCS_PREFIX = os.environ.get('GCS_PREFIX', 'mulesoft-audit') # STATE_KEY must stay OUTSIDE GCS_PREFIX. The feed ingests every object under # its bucket URI and, with a deletion option selected, deletes what it # transferred. A state file inside the prefix would be ingested as log data and # then deleted, resetting collection and re-ingesting duplicates. STATE_KEY = os.environ.get('STATE_KEY', 'mulesoft-audit-state.json') MULE_ORG_ID = os.environ.get('MULE_ORG_ID') CLIENT_ID = os.environ.get('CLIENT_ID') CLIENT_SECRET = os.environ.get('CLIENT_SECRET') MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000')) # The Audit Log Query API returns at most 200 entries per JSON query. PAGE_SIZE = min(int(os.environ.get('PAGE_SIZE', '200')), 200) LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24')) # The query re-reads this many minutes before the watermark so that events the # platform records late are still collected. Re-read events are removed by hash. OVERLAP_MINUTES = int(os.environ.get('OVERLAP_MINUTES', '2')) class FetchError(Exception): """Raised when the MuleSoft API call fails. The watermark must never advance on a failed fetch, otherwise the events in the failed window are skipped permanently. """ def to_unix_millis(dt: datetime) -> int: """Convert datetime to Unix epoch milliseconds.""" if dt.tzinfo is None: dt = dt.replace(tzinfo=timezone.utc) return int(dt.astimezone(timezone.utc).timestamp() * 1000) def parse_datetime(value: str) -> datetime: """Parse an ISO 8601 datetime string into an aware datetime.""" if value.endswith("Z"): value = value[:-1] + "+00:00" dt = datetime.fromisoformat(value) if dt.tzinfo is None: dt = dt.replace(tzinfo=timezone.utc) return dt def event_keys(event: dict) -> set: """Return the identity this event can be recognised by. Audit log entries carry no unique event ID, so a record counts as already collected when its full JSON content was seen before. The overlap window returns the same JSON again, which this catches without any knowledge of the payload schema. """ return {'sha256:' + hashlib.sha256( json.dumps(event, sort_keys=True, ensure_ascii=False).encode('utf-8') ).hexdigest()} def event_time(event: dict) -> str: """Return the event timestamp as an ISO 8601 string, or an empty string. Audit log entries carry the event time in `timestamp` as Unix milliseconds. """ raw = event.get('timestamp') if raw is None or raw == '': return '' try: return datetime.fromtimestamp(int(raw) / 1000, tz=timezone.utc).isoformat() except (TypeError, ValueError): return '' @functions_framework.cloud_event def main(cloud_event): """Fetch MuleSoft Anypoint audit logs and write them to Cloud Storage. Args: cloud_event: CloudEvent object containing the Pub/Sub message. """ if not all([GCS_BUCKET, MULE_ORG_ID, CLIENT_ID, CLIENT_SECRET]): # Raise rather than return: a bare return acks the Pub/Sub message and # reports the run as successful, silently discarding the schedule tick. raise RuntimeError('Missing required environment variables') bucket = storage_client.bucket(GCS_BUCKET) state = load_state(bucket, STATE_KEY) now = datetime.now(timezone.utc) watermark = None if state.get('last_event_time'): watermark = parse_datetime(state['last_event_time']) seen_keys = set(state.get('seen_keys', [])) if watermark is None: start_time = now - timedelta(hours=LOOKBACK_HOURS) else: start_time = watermark - timedelta(minutes=OVERLAP_MINUTES) print(f"Fetching audit logs from {start_time.isoformat()} to {now.isoformat()}") token = get_token(CLIENT_ID, CLIENT_SECRET) # A FetchError here propagates: the run fails, the watermark is untouched, # and the next invocation retries the same window. records, newest_event_time = fetch_audit( org_id=MULE_ORG_ID, token=token, start_time=start_time, end_time=now, page_size=PAGE_SIZE, max_records=MAX_RECORDS, ) # Remove events already written by an earlier run. Without this, the overlap # window re-emits its events on every invocation. fresh = [r for r in records if not (event_keys(r) & seen_keys)] print(f"Fetched {len(records)} records, {len(fresh)} new after deduplication") if not fresh: print("No new audit log records found. Watermark left unchanged.") return if not newest_event_time: # A watermark that cannot be derived from the data is not a watermark. # Advancing on wall-clock here would skip every late-recorded event. raise FetchError('Records were returned but no event timestamp could be parsed') timestamp = now.strftime('%Y%m%dT%H%M%SZ') object_key = f"{GCS_PREFIX}/audit_{timestamp}.ndjson" blob = bucket.blob(object_key) ndjson = '\n'.join(json.dumps(record, ensure_ascii=False) for record in fresh) + '\n' blob.upload_from_string(ndjson, content_type='application/x-ndjson') print(f"Wrote {len(fresh)} records to gs://{GCS_BUCKET}/{object_key}") # Advance the watermark only after the data is durably written. new_watermark = parse_datetime(newest_event_time) if watermark and new_watermark < watermark: new_watermark = watermark # Retain only the hashes still inside the overlap window, so the state file # stays small while covering every event the next query can re-read. cutoff = new_watermark - timedelta(minutes=OVERLAP_MINUTES) retained = set() for record in records: stamp = event_time(record) if not stamp: continue if parse_datetime(stamp) >= cutoff: retained.update(event_keys(record)) save_state(bucket, STATE_KEY, { 'last_event_time': new_watermark.isoformat(), 'seen_keys': sorted(retained), }) print(f"Successfully processed {len(fresh)} records") def load_state(bucket, key): """Read the collector state from Cloud Storage. Only a missing object is treated as a cold start. Any other error is raised: swallowing it would silently reset collection to the full lookback window and re-ingest that entire period. """ blob = bucket.blob(key) try: return json.loads(blob.download_as_text()) except NotFound: print('No state file found. Starting from the lookback window.') return {} def save_state(bucket, key, state: dict): """Write the collector state to Cloud Storage. Failures are raised, not logged. If the state write fails after the data was uploaded, the next run repeats the same window and duplicates it. """ blob = bucket.blob(key) blob.upload_from_string( json.dumps(state, indent=2), content_type='application/json', ) print(f"Saved state: last_event_time={state.get('last_event_time')}") def retry_after_seconds(response, backoff: float) -> int: """Parse Retry-After defensively; it may be an HTTP date, which int() cannot parse.""" raw = response.headers.get('Retry-After') try: return int(raw) if raw else int(backoff) except (TypeError, ValueError): return int(backoff) def get_token(client_id: str, client_secret: str) -> str: """Get an OAuth 2.0 access token from MuleSoft using client credentials.""" body = urlencode({ 'grant_type': 'client_credentials', 'client_id': client_id, 'client_secret': client_secret, }).encode('utf-8') backoff = 1.0 for attempt in range(5): try: response = http.request( 'POST', TOKEN_URL, body=body, headers={'Content-Type': 'application/x-www-form-urlencoded'}, ) except Exception as e: raise FetchError(f'Token request failed: {e}') from e if response.status == 429: wait = retry_after_seconds(response, backoff) print(f"Rate limited (429) on token request. Retrying after {wait}s...") time.sleep(wait) backoff = min(backoff * 2, 30.0) continue if response.status != 200: raise FetchError(f'Failed to get token: HTTP {response.status} {response.data.decode("utf-8", "replace")}') try: return json.loads(response.data.decode('utf-8'))['access_token'] except (json.JSONDecodeError, KeyError) as e: raise FetchError(f'Malformed token response: {e}') from e raise FetchError('Rate limited repeatedly on token request; giving up without advancing the watermark') def fetch_audit(org_id: str, token: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int): """Fetch audit log entries from the MuleSoft Audit Log Query API. Uses cursor pagination. The API returns entries in ascending timestamp order, which a time watermark requires: with newest-first ordering a truncated run would advance the watermark past unread events. Returns: Tuple of (records list, newest_event_time ISO string). Raises: FetchError: on any API or transport failure, so that the caller does not mistake a failed fetch for an empty result and advance the watermark. """ endpoint = AUDIT_URL.format(org_id=org_id) headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json', 'Accept': 'application/json', } records = [] newest_time = None cursor = None page_num = 0 backoff = 1.0 rate_limit_retries = 0 MAX_RATE_LIMIT_RETRIES = 5 while True: page_num += 1 if len(records) >= max_records: # Stop cleanly. The remaining events stay ahead of the watermark and # are collected by the next run. print(f"Reached max_records limit ({max_records})") break # Rebuild the full query on every page; the time window must never be dropped. body = { 'startDate': to_unix_millis(start_time), 'endDate': to_unix_millis(end_time), 'limit': page_size, 'ascending': True, } if cursor: body['cursor'] = cursor try: response = http.request( 'POST', endpoint, body=json.dumps(body).encode('utf-8'), headers=headers, ) except Exception as e: raise FetchError(f'Request to {endpoint} failed: {e}') from e if response.status == 429: rate_limit_retries += 1 if rate_limit_retries > MAX_RATE_LIMIT_RETRIES: raise FetchError('Rate limited repeatedly; giving up without advancing the watermark') wait = retry_after_seconds(response, backoff) print(f"Rate limited (429). Retrying after {wait}s...") time.sleep(wait) backoff = min(backoff * 2, 30.0) continue backoff = 1.0 rate_limit_retries = 0 if response.status != 200: raise FetchError(f'HTTP {response.status} from {endpoint}: {response.data.decode("utf-8", "replace")}') try: data = json.loads(response.data.decode('utf-8')) except json.JSONDecodeError as e: raise FetchError(f'Malformed JSON response from {endpoint}: {e}') from e page_results = data.get('data') or [] if not page_results: print("No more results (empty page)") break print(f"Page {page_num}: Retrieved {len(page_results)} entries") records.extend(page_results) for event in page_results: stamp = event_time(event) if not stamp: continue if newest_time is None or parse_datetime(stamp) > parse_datetime(newest_time): newest_time = stamp cursor = data.get('cursor') if not cursor: break print(f"Retrieved {len(records)} total entries 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).
Considerações importantes
Limitação de taxa: o endpoint de consulta do registro de auditoria aplica limites de taxa por IP nos três planos de controle. O plano de controle dos EUA permite 700 solicitações por minuto por IP, enquanto os planos de controle da UE e do Gov permitem 40 solicitações por minuto por IP. A função implementa a espera exponencial para lidar com a limitação de taxa automaticamente.
Expiração do token: os tokens de acesso geralmente expiram cerca de 30 a 60 minutos após a emissão. A função solicita um novo token para cada execução, o que está dentro dessa janela.
Eliminação de duplicação e estado: a função mantém uma marca-d'água do horário do evento mais recente e os hashes de eventos dentro da janela de sobreposição no arquivo de estado. Cada execução lê novamente dois minutos antes da marca-d'água para capturar entradas registradas com atraso e descarta as que já foram gravadas. Assim, uma nova tentativa, uma execução manual ou um atraso do programador não produzem eventos duplicados. Uma chamada de API com falha interrompe a execução e deixa a marca-d'água inalterada. Assim, a próxima execução tenta novamente a mesma janela.
Retenção de registros de auditoria: os registros de auditoria têm um período de armazenamento padrão de um ano. Se a organização foi criada antes de 10 de julho de 2023 e você não mudou manualmente o período de armazenamento, ele é de seis anos. Baixe os registros periodicamente se precisar mantê-los além do período de armazenamento configurado.
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 GCP, acesse o Cloud Scheduler.
- Clique em Criar job.
Informe os seguintes detalhes de configuração:
Configuração Valor Nome mulesoft-audit-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 mulesoft-audit-trigger.Corpo da mensagem {}(objeto JSON vazio)Clique em Criar.
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 > mulesoft-audit-collector > Registros.
- Verifique se a função foi executada com sucesso.
- Verifique o bucket do Cloud Storage para confirmar se os registros foram gravados.
Configure um feed no Google SecOps para ingerir os registros do MuleSoft.
- 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,
MuleSoft Logs). - Selecione Google Cloud Storage V2 como o Tipo de origem.
- Selecione Mulesoft 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 Cloud Storage:
gs://mulesoft-audit-logs/- Substitua
mulesoft-audit-logspelo nome real do bucket.
- Substitua
Opção de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência:
- Nunca excluir arquivos: nunca exclua arquivos da origem (recomendado para testes).
- Excluir arquivos transferidos e diretórios vazios: exclua arquivos e diretórios vazios da origem após a conclusão de uma busca.
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 de dois papéis no bucket do Cloud Storage: Leitor de objetos do Storage para ler os objetos de registro e um papel no nível do bucket para ler os metadados do bucket.
- 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: cole o e-mail da conta de serviço do Google SecOps.
- Atribuir papéis: selecione as duas opções a seguir:
- Leitor de objetos do Storage: lê os objetos de registro.
- Leitor de bucket legado do Storage: lê os metadados do bucket. Se você selecionou a opção de exclusão Excluir arquivos transferidos e diretórios vazios, selecione Gravador de bucket legado do Storage, que também concede a permissão de exclusão.
Clique em Salvar.
Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.