Documentation

CSP Reports — guide d'installation et d'intégration

SiteGuardian intègre un endpoint d'ingestion pour les violations Content-Security-Policy et les événements Reporting-API. Dirigez votre CSP vers cet endpoint et les violations signalées par le navigateur apparaissent dans le tableau de bord de votre monitor en quelques secondes.

1. Activer sur un monitor

Sur la page de détail du monitor, ouvrez l'onglet CSP Reports et cliquez sur « Activer ». Nous générons une nouvelle URL signée HMAC et un extrait d'en-tête prêt à copier-coller.

2. Coller les en-têtes

L'extrait contient trois en-têtes. Les navigateurs s'adaptent automatiquement — vous pouvez tous les trois les livrer en même temps.

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. Vérifier

Chargez votre site dans un vrai navigateur. En quelques secondes, l'onglet CSP Reports affiche le premier bucket. Si l'onglet reste vide, notre prochain scan des en-têtes confirmera également — un badge vert apparaît lorsque nous détectons que votre CSP annonce notre endpoint.

Mode Report-Only

CSP toute neuve ? Livrez-la d'abord en mode Report-Only — rien n'est réellement bloqué, mais les violations sont signalées. Changez le nom de l'en-tête et conservez les mêmes directives :

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

Ce que nous stockons — et ce que nous ne stockons pas

• Les adresses IP clientes sont hachées avec un sel rotatif quotidien. Nous ne conservons qu'un préfixe de 16 caractères.
• Les chaînes de requête et fragments sont supprimés de toutes les URL avant stockage.
• Les chaînes User-Agent sont réduites à une famille (chrome/firefox/safari/edge/opera/autre).
• Chaque bucket conserve au maximum 3 échantillons bruts et 10 URI de documents concernés.
• Rétention : 180 jours (Compliance), 365 jours (Enterprise). Ensuite, les buckets expirent via un index TTL. L'ingestion CSP nécessite un forfait Compliance ou supérieur.

Limites de débit et pause automatique

nginx applique une limite en périphérie de 200 req/s par IP source. Chaque monitor dispose d'un plafond souple de 10 000 rapports/minute ; trois minutes consécutives au-dessus du plafond mettent l'ingestion en pause automatique pendant une heure et envoient un e-mail au propriétaire du monitor. La rotation de l'URL de l'endpoint se fait en un clic via le bouton d'urgence de l'onglet.

Autres types de rapports

Le même endpoint accepte les rapports NEL (Network Error Logging), Deprecation, Intervention et Expect-CT provenant de la Reporting API du navigateur. Aucune configuration supplémentaire — ajoutez-les simplement à votre groupe Report-To.

Endpoints API

Accès programmatique pour les tableaux de bord et la 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