Audit Logs no Node.js

Audit logs registram quem realizou uma ação importante, sobre qual recurso, quando, por qual canal e com qual resultado. Diferentemente de logs operacionais, eles existem para responsabilização, segurança, conformidade e investigação.

Em aplicações Node.js, auditoria deve ser estruturada, resistente a alteração, separada de logs de debug e cuidadosa com dados pessoais.

Eventos que devem ser auditados

• login, logout e falhas relevantes;
• mudança de senha e MFA;
• criação, rotação e revogação de credenciais;
• alteração de papéis e permissões;
• acesso administrativo;
• exportação e exclusão de dados;
• mudanças financeiras ou de configuração;
• aprovações e rejeições;
• uso de acesso emergencial.

Modelo de evento

const event = {
  eventId: crypto.randomUUID(),
  occurredAt: new Date().toISOString(),
  action: 'user.role.changed',
  actor: {
    type: 'user',
    id: req.auth.userId,
  },
  target: {
    type: 'user',
    id: targetUser.id,
  },
  tenantId: req.auth.tenantId,
  outcome: 'success',
  requestId: req.id,
  sourceIp: req.ip,
  metadata: {
    fromRole: previousRole,
    toRole: nextRole,
  },
};

Use nomes estáveis, IDs e campos documentados. Evite texto livre como única representação.

Antes ou depois da transação

Para ações críticas, o evento deve refletir o resultado real. Uma opção é gravar o evento na mesma transação do domínio:

await database.transaction(async (tx) => {
  await tx.users.updateRole(userId, role);
  await tx.auditEvents.insert(event);
});

Quando o destino de auditoria é externo, use outbox transacional para evitar perder eventos após commit.

Outbox

Grave o evento em uma tabela junto à mudança. Um worker publica depois e marca como enviado. Defina idempotência pelo eventId.

Falhas

Decida quais ações devem falhar se auditoria não puder ser persistida. Alterações de permissão e transferências podem exigir fail closed; eventos menos críticos podem usar fila local ou outbox.

Imutabilidade

Usuários comuns e administradores da aplicação não devem editar ou excluir eventos. Use armazenamento append-only, permissões separadas, retenção protegida e, quando necessário, hashes encadeados ou armazenamento WORM.

Integridade por hash

const canonical = stableStringify(event);
const digest = crypto
  .createHmac('sha256', auditIntegrityKey)
  .update(canonical)
  .digest('hex');

Proteja a chave fora do banco e defina processo para verificação. HMAC não impede exclusão de eventos, apenas ajuda a detectar alteração.

Actor e subject

Diferencie quem iniciou, em nome de quem e qual serviço executou. Em impersonation, registre usuário administrador e usuário representado.

Dados antes e depois

Não copie objetos completos. Registre campos relevantes ou diff redigido:

changes: {
  status: { from: 'pending', to: 'approved' },
}

Nunca inclua senha, token, cookie, segredo, documento completo ou conteúdo sensível sem necessidade legal clara.

IP e User-Agent

São sinais, não identidades. Respeite proxy confiável, privacidade, retenção e truncamento. User-Agent pode ser controlado pelo cliente.

Tempo

Use UTC e relógios sincronizados. Preserve timestamp da ocorrência e da ingestão. Não aceite horário do cliente como fonte principal.

Correlação

Inclua request ID, trace ID, job ID ou correlation ID. Isso permite relacionar auditoria a logs e traces sem copiar conteúdo.

Eventos de falha

Audite falhas relevantes como login bloqueado, tentativa de alterar permissão e uso de credencial revogada. Evite criar volume ilimitado; aplique agregação e rate limiting para ataques ruidosos.

Pino

Logs de auditoria podem usar Pino com stream separado, mas não dependa apenas do stdout se houver requisitos de retenção e imutabilidade.

Schema version

schemaVersion: 1

Versione o formato. Consumidores devem aceitar campos adicionais e tratar migrações.

Retenção

Defina prazo por categoria e obrigação legal. Retenção infinita aumenta custo e risco de privacidade. Implemente exclusão controlada e documentada quando permitida.

Acesso aos logs

O painel de auditoria também é um recurso sensível. Aplique RBAC, MFA, exportação limitada e auditoria do próprio acesso.

Busca

Indexe tenant, actor ID, target ID, action, outcome e período. Evite indexar campos sensíveis ou metadata arbitrária sem limite.

Exportação

Grandes exportações devem ser assíncronas, limitadas e protegidas. Gere arquivo temporário criptografado, URL de curta duração e evento de auditoria para a própria exportação.

Alertas

Auditoria pode alimentar detecção:

• múltiplas elevações de privilégio;
• criação de muitas API keys;
• exportação fora do horário esperado;
• replays de refresh token;
• uso de conta emergencial;
• mudança de configuração crítica.

Testes

Teste sucesso, falha, rollback, indisponibilidade do destino, outbox duplicada, redaction, tenant, impersonation e consulta por período.

Erros comuns

• misturar auditoria com debug;
• registrar secrets;
• permitir edição;
• evento fora da transação;
• não versionar schema;
• usar texto livre;
• não auditar acesso administrativo;
• retenção sem política;
• não separar ator e alvo.

Fluxo recomendado

1. defina eventos críticos;
2. crie schema estruturado;
3. redija dados sensíveis;
4. grave com a transação ou outbox;
5. proteja integridade;
6. restrinja acesso;
7. defina retenção;
8. monitore eventos de risco;
9. teste recuperação.

Combine auditoria com RBAC, ABAC, Pino, Idempotency Keys e Secret Management.

Consulte o guia de logging da OWASP e a documentação oficial de crypto.