Brancher les rapports navigateur avec Reporting-Endpoints

Le header de réponse HTTP Reporting-Endpoints est la façon d'indiquer au navigateur où envoyer les rapports. Vous donnez un nom à chaque destination, puis vous pointez votre politique de sécurité du contenu (CSP) et vos autres politiques vers ce nom. Un seul header, un seul endroit pour déclarer chaque endpoint, et le navigateur assure la livraison.

C'est la façon actuelle de câbler le reporting sur le web. Elle remplace l'ancien header Report-To, et elle fonctionne avec la directive CSP report-to pour collecter les rapports de violation, les avertissements de deprecation, les rapports d'intervention, et plus encore.

Cet article est le guide de câblage pratique. Pour la référence de spec champ par champ, voir la référence du header Reporting-Endpoints.

Ce que fait le header Reporting-Endpoints

Le header transporte une liste d'endpoints nommés. Chaque nom correspond à une seule URL vers laquelle le navigateur peut POST des rapports. Rien ne rapporte nulle part de soi-même : une politique doit référencer un nom d'endpoint avant que le navigateur ne lui envoie quoi que ce soit.

Voici la plus petite mise en place qui collecte les violations CSP :

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

Content-Security-Policy: default-src 'self'; report-to csp-endpoint

La première ligne déclare un endpoint appelé csp-endpoint. La deuxième ligne est une CSP normale, et sa directive report-to nomme cet endpoint. Quand la politique bloque quelque chose, le navigateur envoie un rapport de violation à l'URL derrière csp-endpoint.

Syntaxe du header

Chaque entrée est name="url" : un nom d'endpoint, un signe égal, et l'URL sous forme de chaîne entre guillemets. Le navigateur résout l'URL par rapport à la réponse sur laquelle elle est arrivée.

Vous pouvez déclarer plusieurs endpoints nommés dans un seul header, séparés par des virgules, et acheminer différents types de rapports vers eux par leur nom :

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

Puis une politique choisit le nom qu'elle veut :

Content-Security-Policy: default-src 'self'; report-to csp-endpoint

Quelques règles à connaître d'emblée :

Les URL d'endpoint doivent être potentiellement dignes de confiance, ce qui en pratique veut dire HTTPS. Un endpoint non sécurisé est silencieusement ignoré, pas signalé comme une erreur, donc une faute de frappe dans le schéma fait que les rapports partent discrètement dans le vide.
Un endpoint en v1 est une seule URL. Il n'y a ni pondération, ni priorité, ni liste de bascule, contrairement aux groupes Report-To plus anciens.
Les endpoints que vous déclarez s'appliquent à la ressource avec laquelle le header a été envoyé, pas à toute l'origine.

L'endpoint default

Certains types de rapports ne sont pas liés à un header qui nomme un endpoint. Les rapports de deprecation, d'intervention et de crash vont à un endpoint nommé default si vous en déclarez un :

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

Malgré son nom, default n'est pas un repli pour les autres endpoints. C'est l'endpoint spécifique que ces types de rapports sans étiquette recherchent. Si vous ne déclarez pas d'endpoint default, le navigateur génère quand même ces rapports, mais il n'a nulle part où les envoyer, ils sont donc abandonnés.

La directive CSP report-to

La directive report-to est le côté CSP de tout cela. Sa valeur est un nom d'endpoint, et ce nom doit exister dans un header Reporting-Endpoints sur la même réponse. La directive elle-même ne porte aucune URL ; elle ne fait que référencer un nom que vous avez déclaré dans le header.

Content-Security-Policy: default-src 'self';
                         script-src 'self';
                         report-to csp-endpoint

La directive est en CSP Level 3 et fonctionne uniquement en header. Elle ne marche pas dans un élément <meta>, cette partie du reporting doit donc être définie comme un vrai header de réponse.

report-to face à report-uri

La directive plus ancienne est report-uri, qui prend une URL directement au lieu d'un nom d'endpoint. Elle est dépréciée. Tout navigateur qui comprend report-to ignore entièrement report-uri. report-uri vs report-to compare les deux directives en détail.

Pendant la transition, vous pouvez spécifier les deux. Le navigateur utilise celle qu'il prend en charge et ignore l'autre, vous gardez donc les rapports qui affluent de chaque visiteur :

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

Un navigateur avec la prise en charge de report-to utilise le nom d'endpoint et ignore l'URL de report-uri. Un navigateur sans elle se rabat sur report-uri. Associez cela au header Reporting-Endpoints correspondant pour que le nom d'endpoint se résolve.

Où se place Report-To aujourd'hui

Le header Report-To est le prédécesseur de Reporting-Endpoints. Il est à la fois déprécié et non standard, et Reporting-Endpoints le remplace pour tout nouveau travail. Voir la référence du header Report-To pour son histoire, et Report-To vs Reporting-Endpoints pour la migration en détail.

Une exception pratique : Network Error Logging (NEL) s'appuie encore sur le header hérité Report-To et n'est pas couvert par Reporting-Endpoints v1. Si vous collectez des rapports NEL, vous continuez d'envoyer Report-To pour ce cas tout en utilisant Reporting-Endpoints pour tout le reste.

Prise en charge des navigateurs

Reporting-Endpoints a atteint Baseline en 2024 et est largement pris en charge par les navigateurs actuels. La directive CSP report-to est présente dans Chromium depuis des années ; son jalon Baseline multi-navigateurs arrive en 2026 à mesure que les moteurs restants rattrapent leur retard. Pour les nouveaux sites, écrivez Reporting-Endpoints plus report-to, et n'ajoutez report-uri que si vous devez encore couvrir des clients plus anciens pendant une transition.

Testez avant de faire confiance

Un header à défaillance silencieuse récompense une vérification rapide. Le moyen le plus rapide de confirmer que votre configuration s'analyse et se résout est le vérificateur Reporting API, qui lit vos headers de réponse en direct et vous dit si les noms d'endpoints et les URL correspondent.

Quand vous êtes prêt à démarrer en mode sûr, envoyez d'abord la politique comme un header Report-Only. Le navigateur rapporte ce que la politique bloquerait sans l'appliquer, vous ajustez donc face au trafic réel avant que quoi que ce soit ne casse. Pour le workflow complet de reporting, y compris à quoi ressemble un rapport de violation, voir Démarrer avec le reporting CSP.

Une fois les rapports arrivés, CentralCSP les collecte en un seul endroit, groupe le bruit, et transforme les contenus bruts en quelque chose sur quoi agir. Vous pouvez démarrer gratuitement et pointer votre header Reporting-Endpoints vers un endpoint CentralCSP pour voir de vrais rapports en quelques minutes.

Une vérification de configuration confirmant l'arrivée des premiers rapports navigateur

Le header Reporting-Endpoints expliqué