Documentazione

CSP Reports — Guida all'installazione e all'integrazione

SiteGuardian include un endpoint di ingest integrato per le violazioni di Content-Security-Policy e gli eventi Reporting-API. Punta la tua CSP verso di esso e le violazioni segnalate dal browser confluiscono nella dashboard del tuo monitor in pochi secondi.

1. Abilitalo su un monitor

Nella pagina di dettaglio del monitor, apri la scheda CSP Reports e clicca Abilita. Generiamo un nuovo URL firmato con HMAC e uno snippet di header pronto da copiare e incollare.

2. Incolla gli header

Lo snippet contiene tre header. I browser gestiscono il fallback in modo trasparente — puoi distribuirli tutti e tre insieme.

nginx

add_header Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp" always;
add_header Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"' always;
add_header Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}' always;

Apache

Header always set Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
Header always set Reporting-Endpoints 'sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"'
Header always set Report-To '{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}'

Caddy

header {
    Content-Security-Policy "default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}; report-to sg-csp"
    Reporting-Endpoints `sg-csp="https://reports.siteguardian.io/r/{monitor_id}/{hmac}"`
    Report-To `{"group":"sg-csp","max_age":10886400,"endpoints":[{"url":"https://reports.siteguardian.io/r/{monitor_id}/{hmac}"}]}`
}

3. Verifica

Carica il tuo sito in un browser reale. Entro pochi secondi la scheda CSP Reports mostra il primo bucket. Se la scheda rimane vuota, la prossima scansione degli header confermerà comunque — appare un badge verde quando rileviamo che la tua CSP annuncia il nostro endpoint.

Modalità Report-Only

CSP nuova di zecca? Distribuiscila prima in modalità Report-Only — nulla viene effettivamente bloccato, ma le violazioni vengono segnalate. Sostituisci il nome dell'header e mantieni le stesse direttive:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri https://reports.siteguardian.io/r/{monitor_id}/{hmac}

Cosa memorizziamo — e cosa no

• Gli IP dei client vengono sottoposti ad hash con un salt ruotato ogni giorno. Conserviamo solo un prefisso di 16 caratteri.
• Query string e frammenti vengono rimossi da ogni URL prima della memorizzazione.
• Le stringhe User-Agent vengono ridotte a una famiglia (chrome/firefox/safari/edge/opera/altro).
• Ogni bucket conserva al massimo 3 campioni grezzi e 10 URI di documento interessati.
• Conservazione: 180 giorni (Compliance), 365 giorni (Enterprise). Dopo tale periodo, i bucket scadono tramite un indice TTL. L'ingest CSP richiede un piano Compliance o superiore.

Limiti di frequenza e auto-pausa

nginx applica un rate limit all'edge di 200 req/s per IP di origine. Ogni monitor ha un tetto soft di 10.000 report/minuto; tre minuti consecutivi sopra la soglia mettono automaticamente in pausa l'ingest per un'ora e inviano un'email al proprietario del monitor. La rotazione dell'URL dell'endpoint è un pulsante d'emergenza a un clic nella scheda.

Altri tipi di report

Lo stesso endpoint accetta report NEL (Network Error Logging), Deprecation, Intervention ed Expect-CT dalla Reporting API del browser. Nessuna configurazione aggiuntiva — basta aggiungerli al tuo gruppo Report-To.

Endpoint API

Accesso programmatico per dashboard e CI:

• POST /api/v1/monitors/{id}/csp-reports/enable
• POST /api/v1/monitors/{id}/csp-reports/regenerate
• POST /api/v1/monitors/{id}/csp-reports/disable
• GET /api/v1/monitors/{id}/csp-reports?hours=24
• GET /api/v1/monitors/{id}/csp-reports/{bucket_id}
• GET /api/v1/monitors/{id}/csp-reports/trend/hourly?hours=24
• GET /api/v1/monitors/{id}/csp-reports/recommendations