Registros de auditoria
Consulte um histórico imutável das ações que alteram o estado da sua organização, com evidências de possíveis adulterações — quem fez o quê, quando e de onde.
Os registros de auditoria oferecem uma linha do tempo com busca e filtros para as ações administrativas registradas na sua organização, incluindo atribuições de funções, edições de engines e emissão de chaves de API. Consulte as limitações de cobertura. Disponível no plano Enterprise, assim como Funções e permissões.
No banco de dados, o registro permite apenas adicionar entradas: a conexão da aplicação não pode atualizar, excluir nem truncar linhas de auditoria. O que foi gravado permanece gravado.
O que é registrado #
Cada evento registra o autor, a ação, o alvo e o contexto HTTP em que a solicitação foi recebida.
| Campo | Observações |
|---|---|
| Autor | O usuário ou a chave de API que realizou a ação |
| Ação | Um valor tipado, como engine.created ou member.role_changed |
| Alvo | A entidade afetada (por exemplo, um engine, uma função ou um item do glossário) |
| Metadados | IDs de entidades relacionadas — nunca nomes, e-mails ou trechos de conteúdo |
| Contexto da solicitação | request_id, endereço IP, agente do usuário — registrados quando a chamada foi recebida via HTTP |
| Data e hora | UTC e um número de sequência monotônico para detectar lacunas |
Apenas IDs, por escolha de projeto
A coluna de metadados armazena IDs, não valores legíveis por pessoas. A interface associa esses IDs aos nomes atuais no momento da leitura, então renomear um engine ou usuário não reescreve o histórico. Isso também evita conflitos entre as linhas de auditoria e o direito ao apagamento previsto no GDPR — não há conteúdo a suprimir.
Ações registradas #
Os eventos são agrupados em categorias que correspondem ao filtro do painel.
| Categoria | Ações registradas atualmente |
|---|---|
| Organização | org.created, org.settings_updated, org.deleted |
| Membros | member.invited, member.removed, member.role_changed |
| Funções | role.created, role.updated, role.deleted |
| Engines | engine.created, engine.updated, engine.deleted |
| Chaves de API | api_key.created, api_key.revoked |
| Conteúdo | glossary_item.*, instruction.*, brand_voice.* (apenas operações individuais) |
Como acessar o registro #
A opção Registro de auditoria sempre aparece em Configurações, na seção Administração. Se o plano não der acesso ao recurso, a página mostra "O Registro de auditoria não está disponível no seu plano" em vez da linha do tempo. Na página, você encontra:
- Lista com filtros — filtre por Ação, Autor e Período (uma opção predefinida, como Últimos 7 dias, ou um intervalo de datas De / Até). Datas futuras são bloqueadas.
- Carregar eventos anteriores — os eventos mais recentes aparecem primeiro; clique em Carregar eventos anteriores no final da lista para carregar a próxima página.
- Detalhes do evento — clique em qualquer linha para expandi-la ali mesmo e ver todos os metadados, o ID da solicitação, o IP e o agente do usuário.
- Visualizações compartilháveis — os filtros e o evento aberto ficam registrados na URL, permitindo compartilhar qualquer visualização.
Quem pode visualizar #
Dois requisitos controlam o acesso à página:
- Disponibilidade no plano — o recurso de registros de auditoria deve estar habilitado para a organização (plano Enterprise).
- Permissão — a função de quem acessa deve incluir
org:view_audit_logs. A função Acesso total, criada inicialmente, inclui essa permissão por padrão; os proprietários sempre têm essa permissão.
Membros sem a permissão veem uma página de "sem acesso" em vez da linha do tempo. Membros de uma organização cujo plano não dá acesso ao recurso veem uma tela de bloqueio que exige a contratação de um plano.
Se o seu plano Enterprise expirar
O acesso aos registros de auditoria depende da mesma habilitação do nível de RBAC. Os eventos anteriores permanecem no banco de dados, mas a página mostra "O Registro de auditoria não está disponível no seu plano" e os endpoints de leitura retornam 403 até que o plano seja restabelecido.
Evidências de adulteração #
Os registros de auditoria não são apenas um histórico — são realmente difíceis de alterar depois de gravados.
- Apenas adição de entradas no banco de dados. A migração que instala a tabela executa
REVOKE UPDATE, DELETE, TRUNCATEna função da API. Qualquer caminho de execução futuro — um erro, um novo endpoint, até mesmo uma injeção de SQL — é rejeitado pelo Postgres antes que possa alterar uma linha. - Sequência monotônica. Cada linha contém uma coluna
seqcom valores estritamente crescentes. Ao examinar a sequência, um auditor pode detectar exclusões pelas lacunas.
Isso é suficiente para controles do tipo SOC 2. Não protege contra um invasor com credenciais de acesso direto ao banco de dados de produção — medidas mais robustas (função de proprietário separada, espelho WORM) estão disponíveis mediante solicitação.
Retenção #
Por padrão, os eventos de auditoria são mantidos indefinidamente. Períodos de retenção personalizados — normalmente de 1, 3 ou 7 anos — estão disponíveis no Enterprise. Entre em contato se precisar de uma política de retenção específica para atender a requisitos de conformidade ou a questionários de segurança.
O que não é coberto #
Conheça algumas limitações intencionais da v1:
- Emissão por melhor esforço, não transacional. A emissão transacional está prevista para breve. O evento de auditoria é gravado após a ação que descreve — não na mesma transação do banco de dados. Em casos raros de falha (quando a ação é concluída, mas a inserção do registro de auditoria falha em seguida), a ação pode ocorrer sem um evento correspondente.
- Alguns tipos de ação ainda não geram registros. Alterações nos membros de engines, conexão / atualização / desconexão de integrações, edições nas configurações de modelos, alterações na assinatura de cobrança e operações de conteúdo em massa (envio de CSV,
createMany/updateMany/deleteMany) ainda não produzem eventos. Os identificadores dessas ações já estão reservados para que elas apareçam nas categorias de filtro existentes assim que o registro for implementado. - Leituras não são auditadas. Visualizar o próprio registro de auditoria, consultar os registros de solicitações do engine ou baixar um glossário não gera eventos. Apenas ações que alteram o estado geram eventos.
- Ainda não há exportações. Os dados de auditoria são exibidos no painel. Exportação em CSV, webhook para SIEM e espelho no S3 estão no planejamento — avise se precisar desses recursos.
- Sem visualização por engine. Todos os eventos de auditoria da organização ficam em uma única linha do tempo. Filtre por ação ou autor para restringir os resultados.
- Sem acompanhamento em tempo real. Não há botão Atualizar nem transmissão via WebSocket — recarregue a página para ver os eventos mais recentes.