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 pointe une CSP directement vers une URL. report-to pointe une CSP vers un endpoint nommé qui est déclaré séparément, 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 extrait 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. Parce que 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 peut gérer la livraison de toutes via 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 chaque nouvelle politique voulant du reporting aurait eu besoin de sa propre directive sur mesure et de sa propre forme de payload.

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 par politique de nommer un endpoint. C'est pourquoi la directive report-to plus Reporting-Endpoints ont 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 brancher 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, elle fonctionne donc désormais dans les navigateurs actuels, dont Chrome, Edge, Firefox et Safari. report-to seul 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, ce qui explique l'essentiel de la confusion. Il y a la directive CSP report-to (utilisée ci-dessus, à l'intérieur de la politique) et un header HTTP Report-To (le header de reporting déprécié de première génération, désormais remplacé par Reporting-Endpoints). Ce sont des choses différentes, à des 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. Pointez les deux directives dessus et vous avez terminé.

É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