Pular para o conteúdo

Recursos

Logs de auditoria

Quem fez o quê em um workspace: membros, permissões, chaves API, integrações, configurações e alterações de conteúdo, com o endereço de origem e se a ação foi permitida. Somente acréscimo, exportável, com uma retenção que você controla.

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.

Aba Log de auditoria na seção Logs Uma entrada do log de auditoria aberta no painel lateral: ação, resultado, autor, alvo, endereço IP, user agent, ID da requisição e metadados

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

CampoSignificado
occurred_atQuando a ação terminou, em UTC.
actionA rota RPC que a executou, tal como é: workspaces.inviteMember, templates.update, contacts.delete.
categoryUm agrupamento para filtrar: auth, licence, system, workspaces, members, api_keys, integrations, webhooks, templates, broadcasts, automations, lists, segments, transactional, blog, contacts, audit.
outcomesuccess, failure (a requisição foi recusada por outro motivo, ou um login falhou) ou denied (403 ou 402).
status_codeO status HTTP com que a requisição respondeu.
actor_type, actor_id, actor_email, actor_name, actor_roleQuem 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_methodsession, api_key, magic_code, sso ou root_password.
target_type, target_id, target_nameSobre o que a ação foi feita.
ip_address, user_agent, request_idDe 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.
changesO 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.
metadataDetalhes 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.

CategoriaAções
authuser.signin, user.verify, user.rootSignin, user.oidc.exchange, user.oidc.callback, user.logout, setup.initialize
licencelicence.set, licence.recordingStopped, licence.recordingResumed
systemsettings.update
workspacesworkspaces.create, workspaces.update, workspaces.delete, workspaces.setBlogSettings, workspaces.setCustomFieldLabels, workspaces.setWebAnalyticsSettings, workspaces.setAuditLogSettings
membersworkspaces.inviteMember, workspaces.acceptInvitation, workspaces.joinInvitation, workspaces.deleteInvitation, workspaces.removeMember, workspaces.setUserPermissions
api_keysworkspaces.createAPIKey, workspaces.connectZapier
integrationsworkspaces.createIntegration, workspaces.updateIntegration, workspaces.deleteIntegration, ses.enableTenantIsolation, webhooks.register
webhookswebhookSubscriptions.create, .update, .delete, .toggle, .regenerateSecret
templatestemplates.create, .update, .delete, templateBlocks.create, .update, .delete
broadcastsbroadcasts.create, .update, .schedule, .pause, .resume, .cancel, .delete, .retryFailed, .selectWinner, .sendToIndividual
automationsautomations.create, .update, .delete, .activate, .pause
lists, segmentslists.create, .update, .delete, segments.create, .update, .delete, .rebuild
transactionaltransactional.create, .update, .delete
blogblogPosts.*, blogCategories.*, blogThemes.*
contactscontacts.delete, contacts.import, contacts.export, customEvents.import, annotations.*, webAnalytics.backfillStart, .backfillCancel
auditauditLogs.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.