Feat/issue 119 audit logs append only

[NdondaDaniel2020]

📌 Descrição & Motivação

Esta Pull Request implementa uma arquitetura de segurança em profundidade (Defense in Depth) e integridade criptográfica (Hash Chain) para a tabela audit_logs, assegurando que registros administrativos sensíveis sejam estritamente append-only e não possam ser alterados (UPDATE) ou removidos (DELETE), seja por falha lógica na aplicação ou por comandos SQL diretos.

Closes #119

---

🛠️ O que foi feito?

1. Integridade Criptográfica (Hash Chain SHA-256)

• app/models/audit_log.py:
  • Adicionadas as colunas previous_hash (VARCHAR(64), nullable para registro gênese) e hash (VARCHAR(64), non-nullable, indexada).
• app/core/security/audit.py:
  • Criada a função canônica determinística compute_audit_hash(...) utilizando SHA-256 sobre dados sensíveis (id, actor_user_id, action, resource_type, resource_id, result, details, created_at, previous_hash).
  • Normalização universal de timestamps para UTC ISO-8601, garantindo consistência entre dialetos (PostgreSQL e SQLite).

2. Repositório, Serviço & Verificação de Integridade

• app/repositories/audit_repository.py:
  • Sobrescritos os métodos herdados update() e delete() para lançar AuditImmutabilityError (AUDIT_LOG_IMMUTABLE).
  • Atualizado add_record() para resgatar o último hash e encadear deterministicamente o novo registro.
  • Implementado list_all_chronological() para recuperação sequencial da trilha.
• app/services/audit_service.py:
  • Criada a função verify_audit_trail_integrity(db) para auditoria em lote, detectando imediatamente quebras de elo (previous_hash) ou divergência de payload (hash mismatch).

3. Triggers no SGBD & Permissões RBAC SQL

• Triggers em Nível de Banco:
  • PostgreSQL: Trigger Function block_audit_log_mutation() e Trigger prevent_audit_log_mutation abortando transações de UPDATE e DELETE.
  • SQLite: Triggers DDL locais via SQLAlchemy com RAISE(ABORT, ...) para manter a semântica em ambientes de teste.
  • Eventos ORM: Decoradores @event.listens_for(AuditLog, 'before_update') e before_delete interceptando mutações via session antes do flush.
• Migração Alembic (migrations/versions/e8b9c0d1e2f3_audit_logs_append_only_and_hash_chain.py):
  • Adição segura de colunas e índices.
  • Criação da function e triggers PL/pgSQL com downgrade() limpo.
  • Concessão estrita de permissões (REVOKE ALL; GRANT INSERT, SELECT ON audit_logs TO app_user).

4. Documentação Técnica & Armazenamento WORM

• docs/audit-immutability-worm.md:
  • Guia técnico completo documentando as 4 camadas de defesa.
  • Desenho de arquitetura para off-loading em storage imutável (WORM) com AWS S3 Object Lock em Compliance Mode e streaming de eventos via broker (RabbitMQ / Kafka).

---

📦 Commits Atômicos

c42d28e feat(audit): adicionar colunas hash e previous_hash no modelo audit_log
a161c61 feat(audit): implementar calculo de hash chain e servico de verificacao de integridade
ab5aa98 feat(db): adicionar migracao alembic e triggers de imutabilidade append-only
468f5da test(audit): adicionar testes para triggers append-only e integridade de hash chain
79ad09e docs(audit): documentar arquitetura append-only e off-loading para armazenamento worm
deb0397 feat(audit): garantir imutabilidade append-only na tabela audit_logs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
auth	Ready	Preview	Sep 4, 2026 7:26pm UTC