> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # Registro de Auditoria e Monitoramento > A trilha de auditoria da Switchbord para operações relevantes à segurança, stack de observabilidade, alertas de conta e capacidades planejadas de detecção e notificação de violações de dados. ## Arquitetura do Log de Auditoria A Switchbord mantém uma tabela `audit_logs` que registra operações relevantes à segurança realizadas em cada workspace. A trilha de auditoria foi projetada para responder: *quem fez o quê, a qual objeto, em qual workspace e quando.* ### Schema ```sql theme={null} CREATE TABLE audit_logs ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), workspace_id uuid NOT NULL REFERENCES workspaces(id), actor_user_id uuid REFERENCES auth.users(id), -- nulo para ações iniciadas pelo sistema entity_type text NOT NULL, -- ex.: 'contact', 'workspace_member', 'api_key', 'secret' entity_id text NOT NULL, -- ID da entidade afetada action text NOT NULL, -- ex.: 'gdpr_erasure', 'member_removed', 'secret_updated' metadata jsonb, -- contexto específico da ação (higienizado, sem valores de PII) created_at timestamptz NOT NULL DEFAULT now() ); ``` Todas as consultas de log de auditoria são filtradas por `workspace_id`, garantindo que o isolamento de workspace se estenda também à própria trilha de auditoria. ## O que é Registrado ### Atualmente Implementado | Evento | Tipo de Entidade | Ação | Acionado Por | | ---------------------------------- | ------------------ | -------------------------- | --------------------------------------------------------------- | | Membro do workspace removido | `workspace_member` | `member_removed` | Admin/owner removendo um membro | | Solicitação de exclusão GDPR | `contact` | `gdpr_erasure` | Endpoint de exclusão `DELETE /api/contacts/[id]/gdpr` | | Exportação de dados GDPR | `contact` | `gdpr_export` | Endpoint de exportação `GET /api/contacts/[id]/gdpr` | | Segredo criado/atualizado | `secret` | `secret_updated` | Admin do workspace atualizando segredo do Vault | | Falha na validação de segredo | `secret` | `secret_validation_failed` | Segredo inválido ou malformado rejeitado na gravação | | Chave de API criada | `api_key` | `api_key_created` | Developer criando uma nova chave de API | | Chave de API revogada | `api_key` | `api_key_revoked` | Developer/admin revogando uma chave | | Configurações de canal atualizadas | `channel_settings` | `channel_settings_updated` | Admin do workspace modificando a configuração do canal WhatsApp | | Evento de consentimento (opt-in) | `consent` | `consent_opt_in` | Contato opta por participar via WhatsApp | | Evento de consentimento (opt-out) | `consent` | `consent_opt_out` | Contato opta por sair via WhatsApp | | Alerta de conta acionado | `account_alert` | `alert_triggered` | Sistema detecta violação de limite ou anomalia (BORD-189) | ### Gravando uma Entrada de Log de Auditoria ```typescript theme={null} await writeAuditLog({ workspaceId: string, actorUserId: string | null, entityType: 'contact' | 'workspace_member' | 'api_key' | 'secret' | 'channel_settings' | 'consent' | 'account_alert', entityId: string, action: string, metadata?: Record, // nunca inclua valores brutos de PII }); ``` As entradas de log de auditoria são gravadas de forma síncrona dentro da mesma transação de banco de dados da operação que registram, sempre que possível. Isso garante que a trilha de auditoria reflita operações efetivamente realizadas, não apenas tentadas. ## Melhorias Planejadas no Log de Auditoria ### Registro de Acesso de Leitura (BORD-168) Atualmente, apenas operações de escrita (mutações, exclusões) são registradas. O trabalho planejado inclui o registro do acesso de leitura a tabelas de PII — especificamente rastreando quais usuários acessaram quais registros de contato e quando. Isso é necessário para a conformidade completa com o HIPAA §164.312(b). ### Cadeia de Hash à Prova de Adulteração (BORD-168) Cada entrada de log de auditoria incluirá um hash criptográfico da entrada anterior na cadeia de log do workspace. Isso cria uma estrutura à prova de adulteração em que a modificação de qualquer entrada passada invalida todos os hashes subsequentes. A implementação planejada usa encadeamento SHA-256. ``` entry_n.hash = SHA256(entry_(n-1).hash || entry_n.data) ``` ### Exportação Imutável para Object Storage (BORD-168) Os logs de auditoria serão periodicamente exportados para armazenamento de objetos write-once (por exemplo, Supabase Storage com política de bucket imutável) para fornecer um backup que não pode ser modificado nem mesmo por administradores de banco de dados. ## Stack de Observabilidade ### Monitoramento de Erros: Sentry A Switchbord se integra ao Sentry para monitoramento de erros em tempo real em todas as superfícies da aplicação. O Sentry captura: * Exceções não tratadas nas rotas de API * Falhas de jobs do worker * Erros de JavaScript no frontend Os relatórios de erro são higienizados para evitar a captura de PII nos stack traces. Configurado via `packages/observability`. ### Agregação de Logs: Better Stack Os logs de aplicação da Vercel e da Railway são agregados no Better Stack (anteriormente Logtail). Logs estruturados incluem IDs de requisição para correlação entre serviços. ### Monitoramento de Saúde Os endpoints `/api/health` e `/api/ready` são publicamente acessíveis e monitorados por serviços de uptime para detectar degradação de disponibilidade. ### Alertas de Conta (BORD-189) A Switchbord oferece alertas em tempo real no nível de conta que destacam eventos operacionais e relevantes à segurança para os operadores de workspace: * **Alertas de saúde da API do WhatsApp** — notificações quando a API da Meta retorna taxas de erro elevadas, respostas de limitação de taxa, ou falhas de entrega de webhook para os números de telefone do workspace * **Alertas de expiração de segredo** — avisos quando tokens ou chaves de API armazenados no Vault estão se aproximando da expiração * **Alertas de limite de consentimento** — notificações quando a taxa de opt-out de um workspace excede um limite configurável, indicando risco potencial de conformidade * **Alertas de anomalia de uso** — sinalizações para picos inusuais de volume de mensagens, operações em massa de contatos ou padrões de uso de chave de API Os alertas são entregues via o feed de notificações no app e podem ser encaminhados para o Slack ou endpoints de webhook. Todos os eventos de alerta são registrados na tabela `audit_logs` sob o tipo de entidade `account_alert`. ## Planejado: Detecção de Incidentes de Segurança (BORD-166) As seguintes capacidades estão planejadas como parte do BORD-166: * **Detecção de anomalias:** sinalizar padrões inusuais, como exportações em massa de contatos, alto volume de uso de chave de API ou acesso a partir de faixas de IP inesperadas * **Monitoramento de eventos de segurança:** alertas dedicados para eventos relevantes à segurança (picos de falhas de autenticação, anomalias de sessões concorrentes, tentativas de escalonamento de privilégio) * **Integração de alertas:** alertas baseados em webhook para Slack, PagerDuty ou endpoints configurados pelo operador ## Planejado: Fluxo de Notificação de Violação de Dados (BORD-166) O GDPR Art.33 exige a notificação à autoridade supervisora dentro de **72 horas** após tomar conhecimento de uma violação de dados pessoais. O Art.34 pode exigir a notificação aos titulares de dados afetados. A LGPD estabelece uma obrigação análoga de notificação de incidentes de segurança à Autoridade Nacional de Proteção de Dados (ANPD) e aos titulares, em prazo razoável. Capacidades planejadas para apoiar essa obrigação: 1. **Gatilhos de detecção de incidentes** que criam um registro de incidente com o timestamp da detecção 2. **Fluxo de avaliação de violação** — perguntas guiadas para determinar o escopo da notificação 3. **Geração de rascunho de notificação** — templates pré-preenchidos para submissão à DPA 4. **Contador regressivo de 72 horas** — visível na UI de administração uma vez declarado um incidente 5. **Delimitação de workspaces e contatos afetados** — identificar quais dados de contatos podem ter sido envolvidos O fluxo de notificação de violação de 72 horas está atualmente **planejado** (BORD-166). Organizações com requisitos de conformidade imediatos devem estabelecer um procedimento manual de resposta a incidentes até que essa capacidade seja implementada. ## Retenção dos Logs de Auditoria Os logs de auditoria são retidos pelo período `data_retention_days` configurado do workspace, com uma retenção mínima de **365 dias**, independentemente da configuração do workspace. Isso garante que as trilhas de auditoria permaneçam disponíveis para investigação pós-incidente e auditorias de conformidade. As solicitações de exclusão GDPR **não** excluem entradas de log de auditoria. As entradas que registram o fato de uma exclusão são, elas próprias, retidas como evidência de conformidade. ## Mapeamento de Conformidade | Padrão | Controle | Implementação | | --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | ISO 27001 | A.12.4.1 — Registro de eventos | Tabela `audit_logs` para operações de escrita (lançado no BORD-158) | | ISO 27001 | A.12.4.2 — Proteção da informação de log | Escopado por workspace, somente leitura por admin (cadeia à prova de adulteração planejada) | | ISO 27001 | A.12.4.3 — Logs de administrador e operador | Remoção de membro, alterações de segredo, configurações de canal, eventos de consentimento registrados | | HIPAA | §164.312(b) — Controles de auditoria | Trilha de auditoria de operações de escrita; registro de acesso de leitura planejado no BORD-168 | | GDPR | Art.33 — Notificação de violação à autoridade supervisora | Fluxo de 72h planejado no BORD-166 | | GDPR | Art.34 — Notificação de violação aos titulares de dados | Avaliação de escopo planejada no BORD-166 | | SOC 2 | CC7.1 — Monitoramento de sistema | Sentry, Better Stack, endpoints de saúde, alertas de conta (BORD-189) | | SOC 2 | CC7.2 — Avaliação de atividade anômala | Detecção de anomalias planejada no BORD-166 | Para o mapeamento completo de controles de conformidade, veja a [Matriz de Conformidade](/pt-BR/security/compliance-matrix).