# Política de Auditoria — Mud Sentinel

**Documento:** `operacao/02-auditoria.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Propósito

Garantir **não-repúdio**, **rastreabilidade** e **capacidade de reconstrução** de ações relevantes para compliance, suporte, forense e confiança do cliente.

Auditoria no Mud Sentinel é **capacidade de produto**, não log de aplicação.

---

## 2. Princípios

1. **Append-only lógico** — eventos de auditoria não são editados nem apagados por fluxo normal.
2. **Separação** — audit ≠ application log.
3. **Completeness over chatty** — o que importa para accountability; não cada hover de mouse.
4. **Minimização** — sem segredos; PII só se necessário ao evento.
5. **Tenant-scoped** — eventos de negócio carregam `tenant_id`.

---

## 3. O que deve ser auditado (obrigatório)

| Categoria | Exemplos |
|-----------|----------|
| Identidade | Login sucesso/falha, logout, MFA challenge, reset de credencial |
| Autorização | Elevação de papel, grants/revokes, criação de API keys |
| Dados sensíveis de cliente | Export de dossiê, download de artefato, compartilhamento |
| Casos | Criação, mudança de estado, exclusão/arquivamento |
| Configuração de risco | Ativar regra, mudar peso/limiar |
| Ingestão (ops) | Publish de run, reprocessamento, alteração de conector crítico |
| IA | Solicitação de completion em contexto de caso (metadados); acesso a saída armazenada |
| Admin plataforma | Impersonation (se existir), feature flags globais, acesso a dados cross-tenant de suporte |
| Billing | Mudança de plano, alterações de quota |

---

## 4. O que não é auditoria

- Debug traces.
- Métricas de performance.
- Logs de access HTTP verbosos (podem complementar, mas não substituem).

---

## 5. Schema mínimo do AuditEvent

```text
audit_id          UUID
occurred_at       timestamptz
tenant_id         UUID | null
actor_type        user | system | m2m | support
actor_id          string
actor_roles       string[] | snapshot
action            string  (namespaced: cases.case.export)
resource_type     string
resource_id       string | null
outcome           success | failure | denied
ip                hashed/truncated when stored (política)
user_agent        truncated
correlation_id    UUID
before            json | null  (diff mínimo)
after             json | null
metadata          json     (não-sensível)
integrity_hash    string   (opcional fase 1; obrigatório evolução)
```

**Justificativa dos campos:** permitem responder *quem fez o quê, em qual tenant, com qual resultado, sob qual correlação de request*.

---

## 6. Armazenamento

**MVP:** tabela particionada por tempo em PostgreSQL, escritas apenas via serviço `audit`, permissões DB sem UPDATE/DELETE para a role da aplicação.

**Evolução:** WORM storage / Object Lock para exports legais; hash encadeado (hash chain) se requisito forense aumentar.

| Abordagem | Vantagens | Desvantagens |
|-----------|-----------|--------------|
| Tabela PG append-only | Simples, queryável | DBA privilegiado ainda pode alterar — mitigar com controles e backups imutáveis |
| SIEM externo | Correlação segurança | Custo; ainda precisa fonte confiável |

---

## 7. Retenção

| Classe | Retenção mínima sugerida |
|--------|--------------------------|
| Authn/Authz | 12 meses |
| Exports e acessos a dossiê | 24 meses ou conforme contrato |
| Admin/plataforma | 24 meses |
| Ingestão ops | 12 meses |

Retenções finais alinhadas a DPO/contratos; exclusões LGPD de dados pessoais **não** apagam a existência do evento — anonimizam atores quando legalmente exigido (procedimento controlado).

---

## 8. Acesso

| Papel | Acesso |
|-------|--------|
| Auditor do tenant | Leitura dos eventos do próprio tenant |
| Admin tenant | Leitura (possivelmente redacted) |
| Analista | Sem acesso amplo à trilha completa |
| Plataforma (suporte) | Break-glass com MFA + audit do próprio acesso |
| Engenharia prod | Sem SELECT ad-hoc em produção sem processo |

---

## 9. Integridade e monitoramento

- Alerta se taxa de falhas de escrita de audit > limiar.
- Job de verificação de partições / gaps de sequência (quando aplicável).
- Testes automatizados garantindo emissão em use cases sensíveis.

---

## 10. Relação com produto

Exportações (UC-011) devem incluir **manifesto** referenciando `audit_id` da geração e hashes de artefatos — evidência defensável ao cliente.