Skip to content

Audit Log — Guia do Operador

Leia no seu idioma: English · Português · Español

Estado do escopo (pós-Scope-Freeze 2026-05-10) — A capacidade de audit log foi expandida para incluir a cadeia de hash tamper-evident do Self-Upgrade (scaffold SELFUP-7), eventos de telemetria do Lab Deployment Staging, transcrições de comandos de orquestração SSH/TELNET com redação (conforme SSH-7), e audit de ingress/egress do RELAY.Art (ADR 0020). O runbook de coleta de evidências para SOC 2 Type II vive em runbooks/soc2-evidence-collection.md.

Esta página descreve o audit logging que o Dashboard do TLSStress.Art mantém. Os audit logs são a evidência do operador de que a LICENSE + USAGE_POLICY estão sendo respeitadas; também constituem um registro forense útil ao investigar incidentes.

O que é auditado

Dois streams de auditoria distintos:

1. Auditoria de aceitação de licença — tabela audit_license_acceptance

Uma linha por par (operador, license_version). Todo usuário autenticado deve produzir uma linha antes que o Dashboard se torne utilizável. Consulte PRIVACY_POLICY.md para o schema e a justificativa.

Schema (migration Drizzle 0019_license_acceptance.sql):

audit_license_acceptance (
  id                       uuid        PRIMARY KEY,
  session_user             text        NOT NULL,           -- session cookie 'agentcluster_session' user
  role                     enum        NOT NULL,           -- employee | partner
  declared_email           text        NOT NULL,           -- lowercased
  declared_email_raw       text        NOT NULL,           -- original casing
  license_version          text        NOT NULL,
  usage_policy_version     text        NOT NULL,
  privacy_policy_version   text        NOT NULL,
  telemetry_consent        boolean     NOT NULL DEFAULT false,
  client_ip                text,                           -- X-Forwarded-For of acceptance request
  user_agent               text,                           -- HTTP User-Agent
  accept_language          text,                           -- HTTP Accept-Language
  admin_note               text,                           -- free-form, for admin remediation
  accepted_at              timestamptz NOT NULL DEFAULT now(),
  UNIQUE (session_user, license_version)
);

2. Auditoria de ações — tabela audit_log (existente)

Uma linha por ação não trivial (tentativas de login, mudanças de configuração, eventos de ciclo de vida de execução, decisões de scaling). Consulte dashboard/src/lib/audit.ts e dashboard/src/db/schema.ts.

Como consultar

Via a página do visualizador admin

Abra /admin/audit/license-acceptances no Dashboard (role de admin requerida — a mesma env var ADMIN_BASIC_AUTH que protege o restante da UI admin). Tabela paginada read-only com filtros por intervalo de datas, role, substring de email.

Via SQL

Conecte ao Postgres do cluster via psql (ou pgAdmin / DBeaver):

# Get the connection details from the running pod:
kubectl exec -n web-agents postgres-0 -- env | grep POSTGRES_

# Open psql:
kubectl exec -it -n web-agents postgres-0 -- psql -U $POSTGRES_USER $POSTGRES_DB

Consultas úteis:

-- Most recent acceptances (latest first):
SELECT accepted_at, session_user, role, declared_email, client_ip, license_version
  FROM audit_license_acceptance
  ORDER BY accepted_at DESC
  LIMIT 50;

-- All partner acceptances in the last 30 days:
SELECT *
  FROM audit_license_acceptance
  WHERE role = 'partner'
    AND accepted_at > now() - INTERVAL '30 days'
  ORDER BY accepted_at DESC;

-- Operators who haven't accepted the latest license version yet:
SELECT DISTINCT session_user
  FROM audit_log     -- pull the list of recently-active users from the action audit
  WHERE created_at > now() - INTERVAL '7 days'
  EXCEPT
SELECT session_user
  FROM audit_license_acceptance
  WHERE license_version = 'PolyForm-Noncommercial-1.0.0+AppendixA-2026-05-06';

-- Count of acceptances per role:
SELECT role, count(*)
  FROM audit_license_acceptance
  GROUP BY role;

-- Operators who consented to telemetry:
SELECT session_user, declared_email, accepted_at
  FROM audit_license_acceptance
  WHERE telemetry_consent = true;

Via API (somente admin)

A página do visualizador admin (/admin/audit/license-acceptances) lê GET /api/admin/audit/license-acceptances que retorna um array JSON. O endpoint requer o cookie agentcluster_session E autenticação admin.

Tarefas operacionais

Atualizando versões de license / privacy policy

Quando for feita uma mudança material em LICENSE ou em qualquer arquivo *_POLICY.md:

  1. Atualize a constante correspondente em dashboard/src/lib/license-versions.ts: 
    export const LICENSE_VERSION = 'PolyForm-Noncommercial-1.0.0+AppendixA-2026-XX-XX';
  2. Faça build + deploy do Dashboard — o próximo carregamento de página de cada operador dispara o License Acceptance Modal porque a linha de aceitação existente é de um license_version mais antigo.
  3. As linhas antigas PERMANECEM na tabela de auditoria (o histórico de auditoria é imutável por design).

Removendo a autorização de um operador

Se um operador deve perder acesso (saiu da empresa, parceria encerrada, etc.):

  1. Revogue a credencial do Dashboard (rotacione ADMIN_BASIC_AUTH ou atualize o SSO).
  2. Opcionalmente, retenha a linha para o histórico de auditoria (recomendado) — ele não consegue usar o sistema sem uma sessão de qualquer forma.
  3. Para sinalizar explicitamente "não mais autorizado" sem deletar a linha: 
    UPDATE audit_license_acceptance
   SET admin_note = 'Authorisation revoked on 2026-XX-XX by <admin>: <reason>'
 WHERE session_user = '<username>';

Limpando o banco de dados para handover

Ao doar o cluster para outra equipe:

TRUNCATE audit_license_acceptance, audit_log;

Após o truncate: - Todo operador precisa re-aceitar a licença (comportamento correto para um handover) - O histórico de auditoria passado é perdido (intencional — a nova equipe começa do zero)

Se for necessário preservar o histórico de auditoria antes do handover, faça dump primeiro:

kubectl exec -n web-agents postgres-0 -- pg_dump --table audit_license_acceptance --table audit_log $POSTGRES_DB > audit-backup-$(date +%F).sql

Sealed audit log — WORM hash-chain & RFC 5424 (SaaS control plane)

O control plane comercial adiciona um audit trail tamper-evident além da tabela legada audit_log (audit epic, 2026-06). Resumo para o operador:

  • WORM (write-once). admin_audit_events é append-only: um trigger de DB rejeita qualquer UPDATE e qualquer DELETE antes da janela de retenção. As linhas carregam um seq monotônico, o prev_hash da linha anterior, e o hash SHA-256 desta linha sobre seu canonical JSON — uma hash chain.
  • Verificar a chain. O admin console expõe um verifier; programaticamente, re-hash cada linha e confirme hash[n] == H(prev_hash[n] || canonical(row[n])) e prev_hash[n] == hash[n-1]. Qualquer quebra localiza a linha adulterada.
  • Signed export. O export produz um stream syslog RFC 5424 mais uma assinatura destacada para um auditor verificar a integridade offline. Field- length ceilings mantêm conformidade.
  • Forwarding & retenção. Configure forwarding syslog + retenção via customer_audit_forward_config. Target de forwarding, formato (RFC 5424) e janela de retenção são definidos pelo operador.

Follow-ups externos conhecidos: registrar um IANA Private Enterprise Number (o SD-ID usa um placeholder PEN) e habilitar mTLS/CA-bundle no canal de forwarding.

Postura de compliance

A tabela de auditoria satisfaz os seguintes requisitos de compliance:

Requisito Fonte Como audit_license_acceptance satisfaz
Registros de consentimento GDPR Art. 7(1), LGPD Art. 8 §6 Cada linha É um registro de consentimento — o que foi aceito, quando, por quem
Base legal demonstrável GDPR Art. 6, LGPD Art. 7 A linha de aceitação + este PRIVACY_POLICY.md estabelecem a base
Trilha de auditoria de acesso SOC 2 CC6, ISO 27001 A.12.4 Combinada com a tabela audit_log, histórico completo de ações
Direito de acesso (titular dos dados) GDPR Art. 15 O operador pode fazer self-query filtrando por seu próprio session_user
Direito ao apagamento GDPR Art. 17 DELETE contra a linha quando um operador requisitar

Este projeto NÃO é um provedor SaaS; os dados vivem na infraestrutura do próprio operador, de modo que a maior parte das obrigações de compliance recai sobre o operador (dono do cluster) e não sobre o licenciante. Esta página documenta como cumpri-las.

Relacionados