Audit Trail

O Building Block Audit Trail fornece funcionalidades para rastreamento e auditoria de ações na Catalisa Platform.

Visão Geral

O Audit Trail é um módulo tenant-scoped, ou seja, requer um token com organizationId. Ele é responsável por:

• Registro automático de eventos via consumo de mensagens Redis
• Consulta de logs de auditoria com filtros avançados
• Timeline de recursos para visualizar histórico de mudanças
• Políticas de retenção configuráveis por organização
• Mascaramento de dados sensíveis em logs

Base URL

https://audit.stg.catalisa.app

Recursos

Recurso	Descrição
Logs	Consulta de logs e configuração

Permissões

Permissão	Descrição
AUDIT_LOGS_READ	Listar e visualizar logs de auditoria
AUDIT_CONFIG_MANAGE	Gerenciar configuração de retenção e cleanup

Exemplo Rápido

Consultando logs de auditoria e configurando retenção:

// 1. Listar logs de auditoria
const logsResponse = await fetch('https://audit.stg.catalisa.app/api/v1/logs?filter[action]=CREATE&filter[resourceType]=users', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data: logs, meta } = await logsResponse.json();
console.log(`Total de logs: ${meta.totalItems}`);

// 2. Ver timeline de um recurso específico
const timelineResponse = await fetch('https://audit.stg.catalisa.app/api/v1/logs/resource/users/550e8400-e29b-41d4-a716-446655440000', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data: timeline } = await timelineResponse.json();
timeline.forEach(log => {
  console.log(`${log.attributes.action} at ${log.attributes.createdAt}`);
});

// 3. Configurar política de retenção (90 dias)
await fetch('https://audit.stg.catalisa.app/api/v1/config/retention', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    retentionDays: 90,
  }),
});

// 4. Executar limpeza manual
const cleanupResponse = await fetch('https://audit.stg.catalisa.app/api/v1/cleanup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data: cleanup } = await cleanupResponse.json();
console.log(`Logs removidos: ${cleanup.attributes.deletedCount}`);

Arquitetura

Arquitetura do Audit Trail

O Audit Trail é composto pelos seguintes componentes:

Componente de Ingestão:

• Event Consumer (Consumidor de Eventos)
  • Conecta-se ao Redis Pub/Sub para receber eventos
  • Processa eventos recebidos de outros módulos
  • Aplica mascaramento de dados sensíveis
  • Armazena logs no banco de dados
  • Pipeline:
    1. Recebe evento do Redis Pub/Sub
    2. Processa evento e extrai informações
    3. Aplica mascaramento em campos sensíveis (password, apiKey, secret, token)
    4. Persiste log no banco de dados

Componentes de Consulta:

• Query Logs (Consulta de Logs)

  • Filtros avançados por ação, recurso, ator, data
  • Paginação de resultados
  • Ordenação por timestamp

• Timeline View (Visualização de Timeline)

  • Histórico completo de um recurso específico
  • Mostra todas as ações (CREATE, UPDATE, DELETE, ACCESS)
  • Ordenado cronologicamente

• Retention Policy (Política de Retenção)

  • Configuração de dias de retenção (padrão: 365 dias)
  • Cleanup automático de logs expirados
  • Cleanup manual via endpoint dedicado

Conceitos Importantes

Actions (Ações)

O Audit Trail registra os seguintes tipos de ações:

Action	Descrição
CREATE	Criação de recurso
UPDATE	Atualização de recurso
DELETE	Exclusão de recurso
LOGIN	Login de usuário
LOGOUT	Logout de usuário
ACCESS_DENIED	Tentativa de acesso negada
TOKEN_ISSUED	Token emitido
TOKEN_FAILED	Falha na emissão de token
RATE_LIMITED	Requisição bloqueada por rate limit
EXPORT	Exportação de dados
ACCESS	Acesso a recurso

Actor Types (Tipos de Ator)

Type	Descrição
user	Usuário humano autenticado
system	Ação automática do sistema
api_client	Cliente de API (integração)

Estrutura do Log

Cada log de auditoria contém:

Campo	Descrição
eventType	Tipo completo do evento (ex: iam.user.created)
action	Ação realizada (CREATE, UPDATE, etc)
actorId	ID do ator que realizou a ação
actorType	Tipo do ator
resourceType	Tipo do recurso afetado
resourceId	ID do recurso afetado
changes	Objeto com before e after (quando aplicável)
ipAddress	Endereço IP da requisição
userAgent	User-Agent do cliente
metadata	Dados adicionais do contexto
createdAt	Timestamp do evento

Registro Automático

O Audit Trail consome eventos publicados no Redis por outros módulos:

Fluxo de Registro de Eventos:

1. Módulos publicam eventos

• IAM Module: Publica eventos de autenticação e autorização
  • Exemplos: iam.user.created, iam.login.success, iam.token.issued
• Customers Module: Publica eventos de gestão de clientes
  • Exemplos: customers.person.created, customers.person.updated
• Products Module: Publica eventos de gestão de produtos
  • Exemplos: products.product.created, products.product.updated
• Todos os módulos usam event.publish() para enviar ao Redis

2. Redis Pub/Sub

• Recebe eventos de todos os módulos
• Distribui eventos para consumidores inscritos
• Canal: audit-events (ou configurável)

3. Audit Consumer processa eventos

• Parse event: Extrai informações do evento
  • eventType, action, actorId, resourceType, resourceId, changes
• Mask data: Mascara campos sensíveis
  • password, apiKey, secret, token → ***
• Store log: Persiste no banco de dados
  • Adiciona ipAddress, userAgent, metadata, createdAt

Mascaramento de Dados Sensíveis

Campos sensíveis são automaticamente mascarados nos logs:

Campo	Mascarado como
password	***
apiKey	***
secret	***
token	***
Campos em metadata	Preservados

Política de Retenção

• Padrão: 365 dias
• Mínimo: 1 dia
• Máximo: 3650 dias (10 anos)
• Logs expirados são removidos pelo job de cleanup
• Cleanup pode ser executado manualmente ou automaticamente

Compliance

O Audit Trail foi projetado para atender requisitos de:

• SOC 2 - Auditoria de ações e acessos
• LGPD - Rastreabilidade de processamento de dados pessoais
• PCI DSS - Logs de acesso e modificações