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://api.catalisa.io/audit

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://api.catalisa.io/audit/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://api.catalisa.io/audit/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://api.catalisa.io/audit/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://api.catalisa.io/audit/api/v1/cleanup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Arquitetura

┌─────────────────────────────────────────────────────────────────────┐
│                        Audit Trail                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    Event Consumer                              │   │
│  │                                                                │   │
│  │  Redis Pub/Sub  ──►  Process Event  ──►  Store in Database    │   │
│  │                           │                                    │   │
│  │                    ┌──────▼──────┐                             │   │
│  │                    │   Masking   │                             │   │
│  │                    │  Sensitive  │                             │   │
│  │                    │    Data     │                             │   │
│  │                    └─────────────┘                             │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │    Query     │    │   Timeline   │    │  Retention   │          │
│  │    Logs      │    │   View       │    │   Policy     │          │
│  │              │    │              │    │              │          │
│  │  - Filters   │    │  - Resource  │    │  - Days      │          │
│  │  - Pagination│    │  - History   │    │  - Cleanup   │          │
│  └──────────────┘    └──────────────┘    └──────────────┘          │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

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:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   IAM        │     │  Customers   │     │  Products    │
│   Module     │     │   Module     │     │   Module     │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       │    event.publish   │    event.publish   │
       ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────┐
│                    Redis Pub/Sub                        │
└─────────────────────────────┬───────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  Audit Consumer │
                    │                 │
                    │  - Parse event  │
                    │  - Mask data    │
                    │  - Store log    │
                    └─────────────────┘

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