Visão geral
O log de auditoria registra cada ação do plano de controle feita em um deployment: um membro convidado, um conjunto de permissões alterado, uma chave API criada, uma integração editada, um template salvo, um broadcast agendado, um contato excluído, a licença instalada. Cada entrada indica o autor, a ação, o alvo, o endereço IP e o user agent de origem, o ID da requisição e se ela teve sucesso, falhou ou foi recusada. As ações sensíveis para a segurança também guardam o antes e o depois do que mudou, com todos os segredos ocultados.
Ele nunca registra o plano de dados (upserts de contatos, envios, rastreamento, eventos personalizados), que pode chegar a milhares de requisições por minuto e fica em Logs.
Os logs de auditoria são uma capacidade licenciada (Enterprise): o registro só acontece enquanto houver uma chave de licença instalada que cubra audit_logs. Ler, exportar e configurar a retenção nunca dependem da licença, então a página funciona em qualquer estado de licença com o que tiver sido registrado. Veja Chaves de licença.
No Notifuse Cloud, a chave é gerenciada para você, e os logs de auditoria são registrados no plano Business. Veja No Notifuse Cloud.
Nota
Nada é recusado, nada é escondido. Um deployment sem licença não grava nenhuma entrada e não recebe nenhum aviso. Um deployment cuja chave expira para de registrar depois do período de carência de 30 dias e grava uma entrada de marcação, licence.recordingStopped, para que a interrupção nunca passe despercebida. Instalar uma chave de novo grava licence.recordingResumed.
Onde encontrar
Logs → Log de auditoria, em um workspace, mostra as entradas desse workspace, ao lado dos logs de mensagens e de webhooks. Um usuário root (um ROOT_EMAIL) pode mudar a mesma aba para Todo o deployment: todos os workspaces, mais as entradas do nível do deployment que não pertencem a nenhum workspace (logins, a licença, as configurações do sistema).
Os proprietários sempre veem a aba. Um membro ou uma chave API só a vê quando recebe a permissão de leitura Logs de auditoria. Essa permissão precisa ser concedida de forma explícita e nunca faz parte do “acesso total”, porque o acesso total não deveria incluir ler o endereço de email, o endereço IP e as ações recusadas de cada colega. Um membro que só tem essa permissão vê o item Logs no menu e apenas esta aba.
Cada entrada é lida como uma frase, por exemplo “Convidou ann@example.com”, ao lado do autor, do recurso e, quando a requisição não teve sucesso, do resultado. Clicar em uma entrada abre um painel lateral com a ação, o resultado e o status HTTP, o autor, o alvo, o endereço IP, o user agent, o ID da requisição, o antes e o depois do que mudou, os metadados e a entrada bruta.
Configurações → Log de auditoria é onde um proprietário define a retenção do workspace e onde aparece o aviso de licença quando nada está sendo registrado.
O que uma entrada contém
| Campo | Significado |
|---|---|
occurred_at | Quando a ação terminou, em UTC. |
action | A rota RPC que a executou, tal como é: workspaces.inviteMember, templates.update, contacts.delete. |
category | Um agrupamento para filtrar: auth, licence, system, workspaces, members, api_keys, integrations, webhooks, templates, broadcasts, automations, lists, segments, transactional, blog, contacts, audit. |
outcome | success, failure (a requisição foi recusada por outro motivo, ou um login falhou) ou denied (403 ou 402). |
status_code | O status HTTP com que a requisição respondeu. |
actor_type, actor_id, actor_email, actor_name, actor_role | Quem fez: um user, uma api_key, o system (limpezas da retenção, marcações de licença) ou anonymous (um login que falhou). O papel é owner, member ou root. |
auth_method | session, api_key, magic_code, sso ou root_password. |
target_type, target_id, target_name | Sobre o que a ação foi feita. |
ip_address, user_agent, request_id | De onde veio. O ID da requisição volta em toda resposta da API como X-Request-ID, então uma entrada pode ser ligada a uma linha do log da sua aplicação. |
changes | O antes e o depois dos campos que mudaram, no formato { "field": { "old": …, "new": … } }. Senhas, segredos, tokens e chaves são substituídos por [redacted] dos dois lados; o fato de terem mudado fica registrado. |
metadata | Detalhes livres: o escopo de permissão concedido, o número de contatos importados, o motivo da falha de um login. |
O que é registrado
Cada rota POST /api/… abaixo é registrada com o próprio nome. As leituras não são registradas, com uma exceção: a exportação de contatos do console pede a primeira página de contacts.list com export=true, e essa requisição é registrada como contacts.export. Um cliente da API que percorre a lista por conta própria faz leituras comuns, que não são registradas.
| Categoria | Ações |
|---|---|
| auth | user.signin, user.verify, user.rootSignin, user.oidc.exchange, user.oidc.callback, user.logout, setup.initialize |
| licence | licence.set, licence.recordingStopped, licence.recordingResumed |
| system | settings.update |
| workspaces | workspaces.create, workspaces.update, workspaces.delete, workspaces.setBlogSettings, workspaces.setCustomFieldLabels, workspaces.setWebAnalyticsSettings, workspaces.setAuditLogSettings |
| members | workspaces.inviteMember, workspaces.acceptInvitation, workspaces.joinInvitation, workspaces.deleteInvitation, workspaces.removeMember, workspaces.setUserPermissions |
| api_keys | workspaces.createAPIKey, workspaces.connectZapier |
| integrations | workspaces.createIntegration, workspaces.updateIntegration, workspaces.deleteIntegration, ses.enableTenantIsolation, webhooks.register |
| webhooks | webhookSubscriptions.create, .update, .delete, .toggle, .regenerateSecret |
| templates | templates.create, .update, .delete, templateBlocks.create, .update, .delete |
| broadcasts | broadcasts.create, .update, .schedule, .pause, .resume, .cancel, .delete, .retryFailed, .selectWinner, .sendToIndividual |
| automations | automations.create, .update, .delete, .activate, .pause |
| lists, segments | lists.create, .update, .delete, segments.create, .update, .delete, .rebuild |
| transactional | transactional.create, .update, .delete |
| blog | blogPosts.*, blogCategories.*, blogThemes.* |
| contacts | contacts.delete, contacts.import, contacts.export, customEvents.import, annotations.*, webAnalytics.backfillStart, .backfillCancel |
| audit | auditLogs.export, audit.purged |
GET /api/auditLogs.actions retorna este catálogo, que é a base do filtro de ações do console.
As falhas também são registradas. Um login com um endereço desconhecido, um código errado ou expirado, uma tentativa barrada pelo limite de requisições: a resposta não revela nada, e a entrada diz o motivo (metadata.reason). Uma requisição recusada por uma verificação de permissão é registrada como denied, com o recurso e a permissão que faltavam; uma recusada pela licença é denied, com a funcionalidade que ela exigia.
Não são registrados: o plano de dados (contacts.upsert, customEvents.upsert, transactional.send, lists.subscribe e as outras rotas por contato), as leituras, os testes e as visualizações, os endpoints internos de tarefas e um broadcast pausado automaticamente pelo circuit breaker, porque isso roda no caminho de envio, que não tem nenhuma verificação de licença.
Filtros e exportação
A caixa de busca aceita um endereço IP, o email de um autor ou o ID de um alvo, e mostra por qual deles está buscando. Um endereço IP e um ID de alvo precisam corresponder exatamente; um email corresponde a qualquer parte dele.
Ao lado ficam os filtros de período (das últimas 24 horas aos últimos 90 dias, todo o período ou um intervalo personalizado), de autor (você mesmo, um membro ou uma chave na visão do workspace; qualquer chave API, o sistema ou um visitante sem login nas duas visões) e de recurso. + Filtro acrescenta a ação, o resultado, o email do autor, o ID do alvo e o endereço IP.
Todos os filtros ficam no link da página, então você pode compartilhar ou salvar nos favoritos uma visão filtrada. A API aceita os mesmos filtros, mais target_type. As páginas usam cursor, das mais recentes para as mais antigas, e na visão do workspace o rodapé da lista mostra por quanto tempo o workspace guarda as entradas.
Exportar baixa o filtro atual em CSV ou NDJSON, até 100 000 linhas. Uma exportação que atinge o limite termina com uma linha de marcação export.truncated que traz max_rows, para que um arquivo cortado nunca passe por completo; reduza o intervalo de datas e exporte de novo.
A própria exportação é registrada como auditLogs.export. Toda entrada tem um ID, e o botão Copiar link do painel lateral gera um link que abre a página nessa entrada, mesmo quando ela está bem abaixo na lista.
Retenção
As entradas mais antigas que a retenção são excluídas uma vez por dia. O padrão é 365 dias. O proprietário de um workspace pode definir a retenção do próprio workspace em Configurações → Log de auditoria (0 guarda todas as entradas para sempre; caso contrário, de 30 a 3650 dias).
Um usuário root define o padrão do deployment nas configurações do sistema. Esse padrão também vale para as entradas do nível do deployment e para as entradas de workspaces que não existem mais. Cada limpeza que removeu algo é registrada como audit.purged, com a contagem.
A retenção roda em qualquer estado de licença: excluir dados nunca depende da licença.
Integridade
A tabela é somente de acréscimo: um trigger do banco de dados recusa todo UPDATE e TRUNCATE, e todo DELETE que não venha da função de retenção. Nenhum caminho de código do Notifuse reescreve o histórico, e uma instrução SQL avulsa executada pelo papel de banco de dados dele também não consegue.
O que isso não impede: o dono do banco de dados, ou um superusuário, pode desativar o trigger ou apagar a tabela. A garantia é “a aplicação não consegue alterar o log”, e não “ninguém consegue”. Se você precisa provar isso a um auditor, faça backup da tabela por fora, com uma frequência que ele aceite.
As entradas ficam no banco de dados do sistema, e não no banco de dados do workspace. Por isso, excluir um workspace não apaga nada do log: o registro de quem o excluiu, e do que essa pessoa fez antes, continua lá.
API
Os quatro endpoints estão documentados na referência da API: auditLogs.list, auditLogs.get, auditLogs.actions e auditLogs.export. Uma chave API pode chamá-los quando recebe a permissão de leitura Logs de auditoria; é assim que um SIEM busca o log em intervalos regulares.
A retenção é definida pela API com workspaces.setAuditLogSettings, que só o proprietário do workspace pode chamar: nenhuma permissão dá esse acesso.
