report-uri vs report-to, et comment migrer

Si vous avez une politique de sécurité du contenu (CSP), vous avez probablement vu à la fois report-uri et report-to dans des exemples et vous vous êtes demandé laquelle est correcte. Réponse courte : report-to est la directive moderne et report-uri est dépréciée. Le header Reporting-Endpoints est déjà multi-navigateurs, et la directive CSP report-to est récemment devenue multi-navigateurs elle aussi, vous pouvez donc utiliser report-to pour les navigateurs modernes et ne conserver report-uri que comme repli pour les très anciens. Cet article explique la différence, pourquoi les deux existent, et vous donne une politique à copier.

La différence en une ligne

report-uri fait pointer la CSP directement vers une URL. report-to la fait pointer vers un endpoint nommé, déclaré à part dans le header Reporting-Endpoints, qui fait partie de la Reporting API. Même objectif, faire parvenir les rapports de violation à votre serveur, mais une plomberie différente : l'un est autonome, l'autre sort la destination dans un endpoint nommé et réutilisable.

Content-Security-Policy: default-src 'self'; report-uri https://<Endpoint-ID>.report.centralcsp.com

L'indirection de la seconde forme est délibérée. Comme l'endpoint est nommé et déclaré une seule fois, chaque politique de la page (CSP, COOP, COEP et les autres) peut pointer sur le même endpoint, et le navigateur gère leur livraison à toutes par un mécanisme unique.

Envoyez les deux. Les navigateurs qui comprennent report-to ignorent report-uri, donc la paire ne coûte rien et couvre tous les navigateurs.

Pourquoi report-uri est déprécié

report-uri vient de l'époque où CSP était la seule chose à reporter. Il envoie par POST un objet JSON unique enveloppé dans une clé csp-report, avec Content-Type: application/csp-report. Cela fonctionnait, mais il aurait fallu, pour chaque nouvelle politique à reporter, une directive sur mesure et un format de payload à part.

La Reporting API a remplacé cela par un seul modèle pour toute la plateforme : un header pour déclarer les endpoints, un format de livraison pour chaque type de rapport, et une façon pour chaque politique de nommer un endpoint. C'est pourquoi le couple directive report-to et Reporting-Endpoints a supplanté la directive autonome. Les payloads diffèrent même par la casse : l'ancienne forme utilise du kebab-case (blocked-uri, effective-directive), et le report csp-violation moderne utilise du camelCase (blockedURL, effectiveDirective). Un endpoint qui accepte les deux doit aiguiller selon le Content-Type.

Pourquoi report-uri n'est plus qu'un repli

Pendant longtemps, le conseil pratique était d'envoyer les deux, car la livraison de la directive CSP report-to ne fonctionnait que dans Chromium. Cela a changé : le header Reporting-Endpoints est multi-navigateurs depuis un moment, et la directive CSP report-to est récemment devenue multi-navigateurs elle aussi, si bien qu'elle fonctionne aujourd'hui dans les navigateurs actuels, dont Chrome, Edge, Firefox et Safari. À lui seul, report-to couvre donc le trafic moderne.

Les deux coexistent toujours sans risque. Les navigateurs qui comprennent report-to ignorent report-uri quand les deux sont présents, donc ils ne rapportent jamais en double. Cela fait de report-uri un repli propre : ne le conservez que si vous devez couvrir des navigateurs très anciens et non mis à jour, antérieurs à cette prise en charge multi-navigateurs.

Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Content-Security-Policy:
    default-src 'self';
    report-uri https://<Endpoint-ID>.report.centralcsp.com;
    report-to csp-endpoint

Si vous n'avez pas besoin de prendre en charge ces anciens navigateurs, vous pouvez retirer report-uri et envoyer report-to seul. Conserver les deux ne coûte rien et ne perd aucun rapport.

Ne confondez pas les deux sens de report-to

L'expression « report-to » a un double sens, et c'est de là que vient l'essentiel de la confusion. D'un côté la directive CSP report-to (celle utilisée ci-dessus, à l'intérieur de la politique), de l'autre un header HTTP Report-To (le header de reporting déprécié de première génération, désormais remplacé par Reporting-Endpoints). Deux choses différentes, à deux couches différentes. La comparaison des headers est traitée dans Report-To vs Reporting-Endpoints ; cet article porte sur la directive CSP.

À la recherche d'une alternative à report-uri

Si vous cherchez un remplacement de report-uri, vous ne cherchez généralement pas une directive différente, vous cherchez où vont les rapports du navigateur et comment les recevoir sans construire ni exploiter un collecteur. C'est là le vrai coût : recevoir les POST est facile, mais les stocker, les dédupliquer, les regrouper et agir dessus est un service à part entière.

CentralCSP est cet endpoint hébergé. Il accepte à la fois l'ancien objet application/csp-report et le tableau moderne application/reports+json, les normalise en un seul modèle, regroupe les violations par directive et hôte bloqué, et les transforme en alertes et en preuves. Faites pointer les deux directives dessus, et c'est réglé.

Étapes suivantes

• Configurez le reporting de bout en bout dans Démarrer avec le reporting CSP.
• Lisez la signification des champs dans le rapport de violation CSP.
• Notez votre politique avec l'évaluateur CSP.

Envoyer les deux directives oblige votre collecteur à accepter deux formes de payload, l'objet csp-report seul et le tableau reports+json groupé, et à les traiter comme une même violation plutôt que comme deux. Un endpoint CentralCSP analyse les deux formats et les normalise en un seul flux de rapports par site, donc garder le repli ne coupe pas vos données en deux.

Commencez à collecter les rapports CSP.

Sources

• W3C, CSP Level 3 - directive report-to
• W3C, CSP Level 3 - directive report-uri
• W3C, Reporting API
• MDN, CSP report-to
• MDN, CSP report-uri