Documentación

CSP Reports — guía de configuración e integración

SiteGuardian incluye un endpoint de ingesta integrado para violaciones de Content-Security-Policy y eventos de la Reporting-API. Apunta tu CSP hacia él y las violaciones reportadas por el navegador llegarán al panel de tu monitor en segundos.

1. Habilítalo en un monitor

En la página de detalle del monitor, abre la pestaña CSP Reports y haz clic en Habilitar. Generamos una URL firmada con HMAC recién creada y un fragmento de cabeceras listo para copiar y pegar.

2. Pega las cabeceras

El fragmento contiene tres cabeceras. Los navegadores las gestionan con retrocompatibilidad — puedes publicar las tres a la vez.

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

Carga tu sitio en un navegador real. En cuestión de segundos, la pestaña CSP Reports mostrará el primer bucket. Si la pestaña queda vacía, nuestro siguiente escaneo de cabeceras también lo confirmará — aparece una insignia verde cuando detectamos que tu CSP anuncia nuestro endpoint.

Modo Report-Only

¿CSP recién estrenada? Publícala primero en modo Report-Only — no se bloquea nada, pero las violaciones se reportan. Cambia el nombre de la cabecera y mantén las mismas directivas:

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

Qué almacenamos — y qué no

• Las IPs de cliente se hashean con un salt que rota a diario. Conservamos solo un prefijo de 16 caracteres.
• Las query strings y fragmentos se eliminan de cada URL antes de almacenarla.
• Las cadenas User-Agent se reducen a una familia (chrome/firefox/safari/edge/opera/other).
• Cada bucket conserva como máximo 3 muestras en bruto y 10 URIs de documento afectadas.
• Retención: 180 días (Compliance), 365 días (Enterprise). Pasado ese plazo, los buckets expiran mediante un índice TTL. La ingesta CSP requiere un plan Compliance o superior.

Límites de tasa y pausa automática

nginx limita la tasa en el edge a 200 req/s por IP de origen. Cada monitor tiene un límite blando de 10 000 reportes/minuto; tres minutos consecutivos por encima del límite pausan automáticamente la ingesta durante una hora y envían un correo al propietario del monitor. Rotar la URL del endpoint es un botón nuclear de un solo clic en la pestaña.

Otros tipos de reporte

El mismo endpoint acepta reportes NEL (Network Error Logging), Deprecation, Intervention y Expect-CT de la Reporting API del navegador. Sin configuración adicional — solo añádelos a tu grupo Report-To.

Endpoints de la API

Acceso programático para paneles y 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