Audit Log - C-Suite

Visão Geral

Este documento descreve o sistema de audit log centralizado para registrar todas as ações importantes no ecossistema C-Suite: quem fez o quê, quando, e com quais dados.

Módulo de Audit Log

Localização

O módulo principal está em: common_audit.py (raiz do projeto)

Características

Logging imutável: Registros não podem ser alterados ou deletados
Centralizado: Todos os logs em uma única tabela
Rastreabilidade: Correlação com trace IDs
Detalhes completos: IP, user agent, detalhes da ação
Middleware automático: Logging automático de requests HTTP
Integração: Com logging centralizado e autenticação

Setup

1. Criar Tabela de Audit Logs

# Executar schema SQL
mysql -u root -p csuite < schema_audit_logs.sql

2. Configuração

# Habilitar/desabilitar audit log
AUDIT_LOG_ENABLED=true

# Nome da tabela (opcional, padrão: audit_logs)
AUDIT_LOG_TABLE=audit_logs

Uso Básico

1. Logging Manual

from common_audit import audit_log

# Log de criação de política
audit_log(
    action="policy_created",
    user_id="123",
    org_id=1,
    resource_type="policy",
    resource_id="min_margin",
    details={"value": 0.15, "previous_value": None},
    ip_address="192.168.1.1",
    success=True
)

# Log de atualização
audit_log(
    action="policy_updated",
    user_id="123",
    org_id=1,
    resource_type="policy",
    resource_id="min_margin",
    details={"old_value": 0.15, "new_value": 0.20},
    success=True
)

# Log de erro
audit_log(
    action="policy_update_failed",
    user_id="123",
    org_id=1,
    resource_type="policy",
    resource_id="min_margin",
    success=False,
    error_message="Valor inválido: deve ser entre 0 e 1"
)

2. Middleware Automático

from fastapi import FastAPI
from common_audit import create_audit_middleware

app = FastAPI()

# Adiciona middleware para logar todos os requests
app.middleware("http")(create_audit_middleware(
    log_requests=True,
    log_responses=False,  # Apenas requests por padrão
    exclude_paths=["/health", "/ready"]  # Paths a excluir
))

3. Usando Enum de Ações

from common_audit import audit_log, AuditAction

audit_log(
    action=AuditAction.POLICY_CREATED,
    user_id="123",
    org_id=1,
    resource_type="policy",
    resource_id="min_margin"
)

Ações Auditáveis

Políticas

policy_created - Política criada
policy_updated - Política atualizada
policy_deleted - Política removida

Decisões

decision_made - Decisão tomada
decision_rejected - Decisão rejeitada

Autenticação

login - Login realizado
logout - Logout realizado
login_failed - Tentativa de login falhou

Dados

data_created - Dados criados
data_updated - Dados atualizados
data_deleted - Dados removidos
data_viewed - Dados visualizados

HTTP

http_get, http_post, http_put, http_patch, http_delete - Requests HTTP

Integração com Apps

Policy Engine

from common_audit import audit_log

def create_policy(org_id: int, rule_key: str, value: Any, user_id: str):
    # Cria política
    policy = db.create_policy(org_id, rule_key, value)

    # Loga ação
    audit_log(
        action="policy_created",
        user_id=user_id,
        org_id=org_id,
        resource_type="policy",
        resource_id=rule_key,
        details={"rule_key": rule_key, "value": value},
        success=True
    )

    return policy

Decision API

from common_audit import audit_log

async def decide(customer_id: int, org_id: int, user_id: str):
    # Toma decisão
    decision = await make_decision(customer_id, org_id)

    # Loga decisão
    audit_log(
        action="decision_made",
        user_id=user_id,
        org_id=org_id,
        resource_type="decision",
        resource_id=str(decision.id),
        details={
            "customer_id": customer_id,
            "offer_id": decision.offer_id,
            "intent_score": decision.intent_score
        },
        success=True
    )

    return decision

Autenticação

from common_audit import audit_log

async def login(email: str, password: str, ip_address: str):
    user = verify_credentials(email, password)

    if user:
        audit_log(
            action="login",
            user_id=str(user.id),
            org_id=user.org_id,
            ip_address=ip_address,
            success=True
        )
        return create_token(user)
    else:
        audit_log(
            action="login_failed",
            details={"email": email},
            ip_address=ip_address,
            success=False,
            error_message="Credenciais inválidas"
        )
        raise HTTPException(status_code=401, detail="Credenciais inválidas")

Consultando Audit Logs

Queries Úteis

-- Todas as ações de um usuário
SELECT * FROM audit_logs 
WHERE user_id = '123' 
ORDER BY created_at DESC;

-- Todas as ações de uma organização
SELECT * FROM audit_logs 
WHERE organization_id = 1 
ORDER BY created_at DESC;

-- Ações de um tipo específico
SELECT * FROM audit_logs 
WHERE action = 'policy_created' 
ORDER BY created_at DESC;

-- Ações de um recurso específico
SELECT * FROM audit_logs 
WHERE resource_type = 'policy' 
  AND resource_id = 'min_margin'
ORDER BY created_at DESC;

-- Ações recentes (últimas 24h)
SELECT * FROM audit_logs 
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY created_at DESC;

-- Ações que falharam
SELECT * FROM audit_logs 
WHERE success = 0 
ORDER BY created_at DESC;

-- Estatísticas por ação
SELECT 
    action,
    COUNT(*) as count,
    SUM(success = 1) as successful,
    SUM(success = 0) as failed
FROM audit_logs
GROUP BY action
ORDER BY count DESC;

Boas Práticas

Logue todas as ações importantes: Criação, atualização, deleção de recursos
Inclua contexto: user_id, org_id, resource_type, resource_id
Detalhes relevantes: Valores antigos/novos, parâmetros importantes
Logue erros: Ações que falharam também devem ser logadas
Não logue dados sensíveis: Senhas, tokens, PII completo
Use trace IDs: Para correlacionar com logs de aplicação
Retenção: Defina política de retenção (ex: 1 ano)

Segurança

Imutabilidade

Os logs são imutáveis por design:
- Não há UPDATE ou DELETE na tabela
- Apenas INSERT é permitido
- Timestamps automáticos

Privacidade

Não logue senhas ou tokens
Mascare PII quando necessário
Use data masking para campos sensíveis

Acesso

Apenas leitura para usuários
Apenas sistema pode inserir logs
Logs não podem ser alterados

Retenção e Arquivamento

Política de Retenção

-- Mover logs antigos (> 1 ano) para arquivo
CREATE TABLE audit_logs_archive LIKE audit_logs;

-- Mover logs antigos
INSERT INTO audit_logs_archive
SELECT * FROM audit_logs
WHERE created_at < DATE_SUB(NOW(), INTERVAL 1 YEAR);

-- Deletar logs arquivados (após backup)
DELETE FROM audit_logs
WHERE created_at < DATE_SUB(NOW(), INTERVAL 1 YEAR);

Monitoramento

Alertas

Muitas ações falhadas em pouco tempo
Ações suspeitas (ex: muitas deleções)
Ações fora do horário normal

Dashboards

Ações por tipo
Ações por usuário
Taxa de sucesso/falha
Ações por organização

Troubleshooting

Logs não aparecem

Verifique se AUDIT_LOG_ENABLED=true
Verifique conexão com banco de dados
Verifique se tabela existe
Verifique logs de erro do aplicativo

Performance

Índices estão criados corretamente
Considere particionamento por data
Considere arquivamento de logs antigos

Próximos Passos

✅ Módulo de audit log criado
✅ Schema de banco criado
⏳ Executar migration SQL
⏳ Integrar em todos os apps
⏳ Configurar retenção e arquivamento
⏳ Criar dashboards de monitoramento

Audit Log - C-Suite

Visão Geral

Módulo de Audit Log

Localização

Características

Setup

1. Criar Tabela de Audit Logs

2. Configuração

Uso Básico

1. Logging Manual

2. Middleware Automático

3. Usando Enum de Ações

Ações Auditáveis

Políticas

Decisões

Autenticação

Dados

HTTP

Integração com Apps

Policy Engine

Decision API

Autenticação

Consultando Audit Logs

Queries Úteis

Boas Práticas

Segurança

Imutabilidade

Privacidade

Acesso

Retenção e Arquivamento

Política de Retenção

Monitoramento

Alertas

Dashboards

Troubleshooting

Logs não aparecem

Performance

Próximos Passos

🔊 Text-to-Speech