> ## 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. # Audit Logging e Monitoraggio > La traccia di audit di Switchbord per le operazioni rilevanti per la sicurezza, lo stack di osservabilità, gli avvisi sull'account e le funzionalità pianificate di rilevamento e notifica delle violazioni. ## Architettura del Log di Audit Switchbord mantiene una tabella `audit_logs` che registra le operazioni rilevanti per la sicurezza eseguite all'interno di ciascun workspace. La traccia di audit è progettata per rispondere alla domanda: *chi ha fatto cosa, a quale oggetto, in quale 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), -- null for system-initiated actions entity_type text NOT NULL, -- e.g. 'contact', 'workspace_member', 'api_key', 'secret' entity_id text NOT NULL, -- ID of the affected entity action text NOT NULL, -- e.g. 'gdpr_erasure', 'member_removed', 'secret_updated' metadata jsonb, -- action-specific context (sanitized, no PII values) created_at timestamptz NOT NULL DEFAULT now() ); ``` Tutte le query sul log di audit sono filtrate per `workspace_id`, garantendo che l'isolamento del workspace si estenda alla traccia di audit stessa. ## Cosa Viene Registrato ### Attualmente Implementato | Evento | Tipo di Entità | Azione | Attivato Da | | ---------------------------------- | ------------------ | -------------------------- | ---------------------------------------------------------------------- | | Membro del workspace rimosso | `workspace_member` | `member_removed` | Admin/owner che rimuove un membro | | Richiesta di cancellazione GDPR | `contact` | `gdpr_erasure` | Endpoint di cancellazione `DELETE /api/contacts/[id]/gdpr` | | Esportazione dati GDPR | `contact` | `gdpr_export` | Endpoint di esportazione `GET /api/contacts/[id]/gdpr` | | Segreto creato/aggiornato | `secret` | `secret_updated` | Admin del workspace che aggiorna un segreto Vault | | Errore di validazione del segreto | `secret` | `secret_validation_failed` | Segreto non valido o malformato rifiutato in scrittura | | API key creata | `api_key` | `api_key_created` | Developer che crea una nuova API key | | API key revocata | `api_key` | `api_key_revoked` | Developer/admin che revoca una chiave | | Impostazioni del canale aggiornate | `channel_settings` | `channel_settings_updated` | Admin del workspace che modifica la configurazione del canale WhatsApp | | Evento di consenso (opt-in) | `consent` | `consent_opt_in` | Il contatto effettua l'opt-in via WhatsApp | | Evento di consenso (opt-out) | `consent` | `consent_opt_out` | Il contatto effettua l'opt-out via WhatsApp | | Avviso sull'account attivato | `account_alert` | `alert_triggered` | Il sistema rileva un superamento di soglia o un'anomalia (BORD-189) | ### Scrittura di una Registrazione nel Log di Audit ```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, // never include raw PII values }); ``` Le registrazioni nel log di audit vengono scritte in modo sincrono all'interno della stessa transazione del database dell'operazione che registrano, ove possibile. Ciò garantisce che la traccia di audit rifletta le operazioni effettivamente eseguite, non solo quelle tentate. ## Miglioramenti Pianificati al Log di Audit ### Logging degli Accessi in Lettura (BORD-168) Attualmente, vengono registrate solo le operazioni di scrittura (mutazioni, eliminazioni). Il lavoro pianificato include la registrazione dell'accesso in lettura alle tabelle PII — in particolare il tracciamento di quali utenti hanno accesso a quali record di contatto e quando. Questo è richiesto per la piena conformità a HIPAA §164.312(b). ### Catena di Hash a Prova di Manomissione (BORD-168) Ogni registrazione nel log di audit includerà un hash crittografico della voce precedente nella catena di log del workspace. Ciò crea una struttura a prova di manomissione in cui la modifica di una voce passata invalida tutti gli hash successivi. L'implementazione pianificata utilizza il chaining SHA-256. ``` entry_n.hash = SHA256(entry_(n-1).hash || entry_n.data) ``` ### Esportazione Immutabile su Object Storage (BORD-168) I log di audit verranno periodicamente esportati su object storage write-once (ad es. Supabase Storage con politica di bucket immutabile) per fornire un backup che non può essere modificato nemmeno dagli amministratori del database. ## Stack di Osservabilità ### Monitoraggio degli Errori: Sentry Switchbord si integra con Sentry per il monitoraggio degli errori in tempo reale su tutte le superfici applicative. Sentry rileva: * Eccezioni non gestite nelle route API * Fallimenti dei job del worker * Errori JavaScript lato frontend Le segnalazioni di errore vengono sanificate per evitare di catturare PII negli stack trace. Configurato tramite `packages/observability`. ### Aggregazione dei Log: Better Stack I log applicativi da Vercel e Railway vengono aggregati in Better Stack (precedentemente Logtail). I log strutturati includono ID di richiesta per la correlazione tra i servizi. ### Monitoraggio dello Stato di Salute Gli endpoint `/api/health` e `/api/ready` sono pubblicamente accessibili e monitorati da servizi di uptime per rilevare il degrado della disponibilità. ### Avvisi sull'Account (BORD-189) Switchbord fornisce avvisi in tempo reale a livello di account che segnalano agli operatori del workspace eventi operativi e rilevanti per la sicurezza: * **Avvisi sullo stato di salute dell'API WhatsApp** — notifiche quando l'API Meta restituisce tassi di errore elevati, risposte di rate-limit o fallimenti di consegna dei webhook per i numeri di telefono di un workspace * **Avvisi di scadenza dei segreti** — avvertimenti quando token o API key memorizzati in Vault si stanno approssimando alla scadenza * **Avvisi sulla soglia di consenso** — notifiche quando il tasso di opt-out di un workspace supera una soglia configurabile, indicando un potenziale rischio di conformità * **Avvisi di anomalia di utilizzo** — segnalazioni per picchi anomali del volume di messaggi, operazioni massive sui contatti o pattern di utilizzo delle API key Gli avvisi vengono consegnati tramite il feed di notifiche in-app e possono essere reindirizzati a Slack o a endpoint webhook. Tutti gli eventi di avviso vengono registrati nella tabella `audit_logs` sotto il tipo di entità `account_alert`. ## Pianificato: Rilevamento degli Incidenti di Sicurezza (BORD-166) Le seguenti funzionalità sono pianificate come parte di BORD-166: * **Rilevamento delle anomalie:** segnalare pattern inusuali come esportazioni massive di contatti, volumi elevati di utilizzo delle API key o accessi da intervalli IP inattesi * **Monitoraggio degli eventi di sicurezza:** avvisi dedicati per eventi rilevanti per la sicurezza (raffiche di autenticazioni fallite, anomalie di sessioni concorrenti, tentativi di escalation dei privilegi) * **Integrazione degli avvisi:** avvisi basati su webhook verso Slack, PagerDuty o endpoint configurati dall'operatore ## Pianificato: Workflow di Notifica delle Violazioni (BORD-166) L'Art.33 GDPR richiede la notifica all'autorità di controllo entro **72 ore** dalla presa di conoscenza di una violazione dei dati personali. L'Art.34 può richiedere la notifica agli interessati coinvolti. Funzionalità pianificate per supportare questo obbligo: 1. **Trigger di rilevamento degli incidenti** che creano un record dell'incidente con timestamp di rilevamento 2. **Workflow di valutazione della violazione** — domande guidate per determinare l'ambito della notifica 3. **Generazione di bozze di notifica** — modelli pre-popolati per la presentazione al DPA 4. **Timer di conto alla rovescia di 72 ore** — visibile nell'interfaccia admin una volta dichiarato un incidente 5. **Determinazione dell'ambito di workspace e contatti coinvolti** — identificare i dati di quali contatti potrebbero essere stati coinvolti Il workflow di notifica delle violazioni entro 72 ore è attualmente **pianificato** (BORD-166). Le organizzazioni con requisiti di conformità immediati dovrebbero stabilire una procedura manuale di risposta agli incidenti finché questa funzionalità non sarà implementata. ## Conservazione dei Log di Audit I log di audit sono conservati per il periodo `data_retention_days` configurato dal workspace, con una conservazione minima di **365 giorni** indipendentemente dall'impostazione del workspace. Ciò garantisce che le tracce di audit rimangano disponibili per le indagini post-incidente e gli audit di conformità. Le richieste di cancellazione GDPR **non** eliminano le registrazioni nel log di audit. Le voci che registrano il fatto di una cancellazione vengono esse stesse conservate come prova di conformità. ## Mappatura della Conformità | Standard | Controllo | Implementazione | | --------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | ISO 27001 | A.12.4.1 — Registrazione degli eventi | Tabella `audit_logs` per le operazioni di scrittura (rilasciato BORD-158) | | ISO 27001 | A.12.4.2 — Protezione delle informazioni di log | Con ambito workspace, in lettura solo per gli admin (catena a prova di manomissione pianificata) | | ISO 27001 | A.12.4.3 — Log di amministratori e operatori | Rimozione di membri, modifiche ai segreti, impostazioni del canale, eventi di consenso registrati | | HIPAA | §164.312(b) — Controlli di audit | Traccia di audit per le operazioni di scrittura; logging degli accessi in lettura pianificato BORD-168 | | GDPR | Art.33 — Notifica delle violazioni all'autorità di controllo | Workflow di 72h pianificato BORD-166 | | GDPR | Art.34 — Notifica delle violazioni agli interessati | Valutazione dell'ambito pianificata BORD-166 | | SOC 2 | CC7.1 — Monitoraggio del sistema | Sentry, Better Stack, endpoint di stato di salute, avvisi sull'account (BORD-189) | | SOC 2 | CC7.2 — Valutazione dell'attività anomala | Rilevamento delle anomalie pianificato BORD-166 | Per la mappatura completa dei controlli di conformità, vedi la [Matrice di Conformità](/it/security/compliance-matrix).