Panoramica

Snapp supporta integrazioni opzionali di terze parti che migliorano visibilità e sicurezza senza diventare dipendenze rigide.

Le integrazioni sono:

  • scoped per host
  • configurabili a runtime
  • completamente opzionali
  • non bloccanti per i redirect

Attualmente, Snapp fornisce supporto di primo livello per:

  • Umami — analytics operativi e di visita
  • VirusTotal API — reputazione dei domini e prevenzione degli abusi

Entrambe sono configurate per host tramite settings.yaml o la UI di amministrazione.

Principi di progettazione

Le integrazioni in Snapp seguono regole rigorose:

  • il flusso core di redirect deve continuare anche se un’integrazione non è disponibile
  • i fallimenti vengono loggati, mai considerati fatali
  • la configurazione è isolata per host (organizzazione)
  • nessuna integrazione può elevare privilegi o bypassare le policy

Snapp tratta le integrazioni come osservatori, non come autorità.

Integrazione Umami

Scopo

Umami è usato per analytics operativi, non come motore principale delle metriche.

Traccia:

  • redirect risolti
  • shortcode non validi
  • tentativi di segreto non valido
  • tentativi di login falliti
  • eventi di indisponibilità del database

Questo fornisce visibilità sul comportamento del sistema e sui pattern di abuso.

Come viene integrato Umami

Snapp utilizza il client ufficiale @umami/node.

Per ogni richiesta:

  1. Viene risolto l’host attivo
  2. Viene caricata la configurazione Umami dell’host
  3. Viene creato un client Umami scoped
  4. Gli eventi vengono inviati lato server (SSR)

Snapp non inietta alcuno script lato client.

Eventi tracciati

Esempi di eventi tracciati:

  • visite con redirect riuscito
  • shortcode 404
  • tentativi di password non validi su URL protetti
  • tentativi di autenticazione falliti
  • problemi di disponibilità del backend

Ogni evento include:

  • hostname
  • lingua
  • referrer
  • URL risolto
  • shortcode
  • website id

Il tracking è best-effort. I fallimenti vengono ignorati.

Correlazione delle visite

Quando un redirect ha successo:

  • Umami riceve un evento di tracking
  • Snapp scrive la propria riga di metrica

Questi sono percorsi indipendenti.

Se Umami non è disponibile:

  • le metriche di Snapp continuano a funzionare
  • il redirect avviene comunque

Configurazione

Per host:

thirdparty:
  umami:
    url: https://umami.example.org
    websiteId: <uuid>

Entrambi i campi devono essere presenti per abilitare Umami.

La rimozione della configurazione lo disabilita immediatamente.

Integrazione VirusTotal API

Scopo

VirusTotal è usato per validare i domini di destinazione in fase di redirect.

Previene:

  • domini noti come malevoli
  • destinazioni di phishing
  • URL segnalati da sistemi esterni di reputazione

VirusTotal non sostituisce le watchlist interne. Le completa.

Come vengono eseguiti i controlli

Durante la risoluzione del redirect:

  1. Viene estratto il dominio di destinazione
  2. Vengono valutate le watchlist locali
  3. Viene interrogata la reputazione VirusTotal (se abilitata)
  4. Viene presa una decisione prima del redirect

Se un dominio non supera la validazione:

  • il redirect viene bloccato
  • non viene scritta alcuna metrica
  • non viene registrata alcuna visita Umami

Gestione dei fallimenti

VirusTotal è trattato come advisory:

  • errori di rete non interrompono i redirect
  • i fallimenti API vengono loggati (in modalità debug)
  • l’assenza della API key disabilita i controlli in modo silenzioso

Snapp non effettua retry indefiniti né blocca l’avvio.

Configurazione

Per host:

thirdparty:
  vtapi:
    apikey: <la_tua_api_key>

La chiave è memorizzata cifrata a riposo e non viene mai esposta pubblicamente.

La rimozione della chiave disabilita immediatamente i controlli VirusTotal.

Comportamento scoped per host

Le integrazioni vengono risolte per host:

  • domini diversi possono usare istanze Umami diverse
  • alcuni host possono abilitare VirusTotal, altri no
  • le modifiche invalidano immediatamente le cache in memoria

Non esiste uno stato globale delle integrazioni.

Integrazione nella UI di amministrazione

Entrambe le integrazioni possono essere gestite dal pannello Impostazioni → Integrazioni.

Funzionalità:

  • abilitare / disabilitare integrazioni
  • aggiornare le credenziali
  • validare gli input
  • applicare le modifiche live
  • rimuovere le integrazioni in modo pulito

Tutte le modifiche vengono persistite in settings.yaml e ricaricate a runtime.

Sicurezza e isolamento

Le integrazioni:

  • non ricevono ID interni
  • non ricevono token di autenticazione
  • non possono modificare lo stato del database
  • non possono bypassare i confini organizzativi

Osservano solo eventi già consentiti dalle policy.

Cosa non fanno le integrazioni

  • Nessun redirect è delegato a terze parti
  • Nessuna autorità viene esternalizzata
  • Nessuna richiesta viene bloccata per downtime di un’integrazione
  • Nessun dato viene condiviso tra host

Snapp resta pienamente funzionante anche senza alcuna integrazione abilitata.