Vai al contenuto

Funzionalità

Registri di audit

Chi ha fatto cosa in un workspace: membri, permessi, API Key, integrazioni, impostazioni e modifiche ai contenuti, con l'indirizzo di provenienza e se l'azione era consentita. Registro in sola aggiunta, esportabile, con un periodo di conservazione che decidi tu.

Panoramica

Il registro di audit annota ogni azione del piano di controllo eseguita su un deployment: un membro invitato, un insieme di permessi modificato, una API Key creata, un’integrazione modificata, un template salvato, un broadcast programmato, un contatto eliminato, la licenza installata.

Ogni voce indica l’autore, l’azione, il suo obiettivo, l’indirizzo IP e lo user agent di provenienza, l’id della richiesta e se l’azione è riuscita, è fallita o è stata rifiutata. Le azioni sensibili per la sicurezza riportano anche lo stato prima e dopo la modifica, con ogni segreto oscurato.

Non annota mai il piano dei dati (upsert dei contatti, invii, tracciamento, eventi personalizzati), che può arrivare a migliaia di richieste al minuto e ha il suo posto nei Log.

I registri di audit sono una funzionalità soggetta a licenza (Enterprise): la registrazione avviene solo mentre è installata una chiave di licenza che copre audit_logs. Leggere, esportare e configurare la conservazione non richiedono mai la licenza, quindi la pagina funziona in qualsiasi stato della licenza su ciò che è stato registrato. Vedi Chiavi di licenza.

Su Notifuse Cloud la chiave è gestita per te, e i registri di audit vengono registrati nel piano Business. Vedi Su Notifuse Cloud.

Nota

Niente viene rifiutato, niente viene nascosto. Un deployment senza licenza non scrive alcuna voce e non riceve alcun avviso. Un deployment la cui chiave scade smette di registrare dopo il periodo di tolleranza di 30 giorni e scrive una voce di segnalazione, licence.recordingStopped, così l’interruzione resta visibile. Se installi di nuovo una chiave, viene scritto licence.recordingResumed.

Dove trovarlo

Log → Registro di audit in un workspace mostra le voci di quel workspace, accanto ai log dei messaggi e dei webhook. Un utente root (un ROOT_EMAIL) può passare la stessa scheda a Intero deployment: tutti i workspace più le voci a livello di deployment che non appartengono ad alcun workspace (accessi, licenza, impostazioni di sistema).

I proprietari vedono sempre la scheda. Un membro o una API Key la vedono solo se hanno il permesso di lettura Registri di audit. Questo permesso va concesso esplicitamente e non fa mai parte dell‘“accesso completo”, perché l’accesso completo non dovrebbe implicare la lettura dell’indirizzo email, dell’indirizzo IP e delle azioni rifiutate di ogni collega. Un membro che ha solo questo permesso vede la voce di menu Log e soltanto questa scheda.

Ogni voce si legge come una frase, per esempio “Ha invitato ann@example.com”, accanto all’autore, alla risorsa e, quando la richiesta non è riuscita, al suo esito. Cliccando una voce la apri in un pannello laterale con l’azione, l’esito e lo stato HTTP, l’autore, l’obiettivo, l’indirizzo IP, lo user agent, l’id della richiesta, lo stato prima e dopo la modifica, i metadati e la voce grezza.

Scheda del registro di audit nella sezione Log Una voce del registro di audit aperta nel pannello laterale: azione, esito, autore, obiettivo, indirizzo IP, user agent, id della richiesta e metadati

Impostazioni → Registro di audit è dove un proprietario imposta la conservazione del workspace, e dove compare l’avviso sulla licenza quando non viene registrato nulla.

Cosa contiene una voce

CampoSignificato
occurred_atQuando l’azione è stata completata, in UTC.
actionLa route RPC che l’ha eseguita, testuale: workspaces.inviteMember, templates.update, contacts.delete.
categoryUn raggruppamento per i filtri: auth, licence, system, workspaces, members, api_keys, integrations, webhooks, templates, broadcasts, automations, lists, segments, transactional, blog, contacts, audit.
outcomesuccess, failure (la richiesta è stata rifiutata per un altro motivo, oppure un accesso non è riuscito) o denied (403 o 402).
status_codeLo stato HTTP con cui ha risposto la richiesta.
actor_type, actor_id, actor_email, actor_name, actor_roleChi l’ha fatto: un user, una api_key, il system (pulizie della conservazione, voci di segnalazione della licenza) o anonymous (un accesso non riuscito). Il ruolo è owner, member o root.
auth_methodsession, api_key, magic_code, sso o root_password.
target_type, target_id, target_nameSu cosa è stata eseguita l’azione.
ip_address, user_agent, request_idDa dove è arrivata. L’id della richiesta viene restituito in ogni risposta dell’API come X-Request-ID, così puoi collegare una voce a una riga del log della tua applicazione.
changesStato prima e dopo dei campi modificati, nella forma { "field": { "old": …, "new": … } }. Password, segreti, token e chiavi vengono sostituiti da [redacted] su entrambi i lati; resta traccia del fatto che sono cambiati.
metadataDettagli liberi: l’ambito del permesso concesso, il numero di contatti importati, il motivo per cui un accesso non è riuscito.

Cosa viene registrato

Ogni route POST /api/… qui sotto viene registrata con il proprio nome. Le letture non vengono registrate, con un’eccezione: l’esportazione dei contatti della console chiede la prima pagina di contacts.list con export=true, e quella richiesta viene registrata come contacts.export. Un client API che scorre da sé le pagine dell’elenco fa letture normali, che non vengono registrate.

CategoriaAzioni
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 restituisce questo catalogo, da cui la console costruisce il filtro per azione.

Anche i fallimenti vengono registrati. Un accesso con un indirizzo sconosciuto, un codice errato o scaduto, un tentativo bloccato dal limite di frequenza: la risposta non rivela nulla, e la voce dice il perché (metadata.reason). Una richiesta rifiutata da un controllo dei permessi viene registrata come denied con la risorsa e il permesso mancanti; una rifiutata dalla licenza è denied con la funzionalità che le serviva.

Non registrati: il piano dei dati (contacts.upsert, customEvents.upsert, transactional.send, lists.subscribe e le altre route per singolo contatto), le letture, i test e le anteprime, gli endpoint interni delle attività, e un broadcast messo in pausa automaticamente dal circuit breaker, perché questo avviene nel percorso di invio, che non contiene alcun controllo di licenza.

Filtri ed esportazione

La casella di ricerca accetta un indirizzo IP, l’email di un autore o l’id di un obiettivo, e mostra in base a quale dei tre sta cercando. Un indirizzo IP e un id di obiettivo devono corrispondere esattamente; un’email corrisponde anche in parte.

Accanto ci sono i filtri per il periodo (dalle ultime 24 ore agli ultimi 90 giorni, tutto il periodo o un intervallo personalizzato), per l’autore (tu, un membro o una chiave nella vista del workspace; qualsiasi API Key, il sistema o un visitatore non connesso in entrambe le viste) e per la risorsa. + Filtro aggiunge l’azione, l’esito, l’email dell’autore, l’id dell’obiettivo e l’indirizzo IP.

Ogni filtro resta nel link della pagina, così puoi condividere o salvare tra i preferiti una vista filtrata. L’API accetta gli stessi filtri più target_type. Le pagine si basano su un cursore, dalla più recente, e nella vista del workspace il fondo dell’elenco indica per quanto tempo il workspace conserva le sue voci.

Esporta scarica il filtro corrente in CSV o NDJSON, fino a 100 000 righe. Un’esportazione che raggiunge il limite termina con una riga di segnalazione export.truncated che riporta max_rows, così un file troncato non passa mai per completo; restringi l’intervallo di date ed esporta di nuovo.

L’esportazione stessa viene registrata come auditLogs.export. Ogni voce ha un id, e il pulsante Copia link del pannello laterale ti dà un link che apre la pagina su quella voce, anche quando si trova molto in basso nell’elenco.

Conservazione

Le voci più vecchie del periodo di conservazione vengono eliminate una volta al giorno. Il valore predefinito è 365 giorni. Un proprietario del workspace può impostare la conservazione propria del workspace in Impostazioni → Registro di audit (0 conserva ogni voce per sempre, altrimenti da 30 a 3650 giorni).

Un utente root imposta il valore predefinito del deployment nelle impostazioni di sistema; questo vale anche per le voci a livello di deployment e per quelle dei workspace che non esistono più. Ogni pulizia che ha rimosso qualcosa viene registrata come audit.purged, con il conteggio.

La conservazione funziona in qualsiasi stato della licenza: l’eliminazione dei dati non dipende mai dalla licenza.

Integrità

La tabella è in sola aggiunta (append-only): un trigger del database rifiuta ogni UPDATE e TRUNCATE, e ogni DELETE tranne quelli eseguiti dalla funzione di conservazione. Nessun percorso del codice di Notifuse riscrive lo storico, e nemmeno un’istruzione SQL lanciata per errore con il suo ruolo di database può farlo.

Cosa non impedisce: il proprietario del database, o un superuser, può disattivare il trigger o eliminare la tabella. La garanzia è “l’applicazione non può alterare il registro”, non “nessuno può farlo”. Se devi dimostrarlo a un revisore, fai un backup della tabella fuori banda, con una frequenza che il revisore accetta.

Le voci sono salvate nel database di sistema, non nel database del workspace, quindi eliminare un workspace non cancella nulla dal registro: resta traccia di chi l’ha eliminato e di cosa aveva fatto prima.

API

I quattro endpoint sono documentati nel riferimento API: auditLogs.list, auditLogs.get, auditLogs.actions e auditLogs.export. Una API Key può chiamarli se ha il permesso di lettura Registri di audit, ed è così che un SIEM recupera il registro a intervalli regolari.

La conservazione si imposta via API con workspaces.setAuditLogSettings, che solo un proprietario del workspace può chiamare: nessun permesso lo consente.