# Comment configurer le Reporting API du navigateur (/fr/blog/how-to-set-up-the-reporting-api) Le navigateur sait déjà quand vos politiques de sécurité se déclenchent, quand des requêtes réseau échouent, et quand une page utilise une API sur le point d'être supprimée. La plupart du temps, ce savoir reste dans le navigateur de l'utilisateur et vous ne le voyez jamais. Le Reporting API est la façon de le faire sortir : un peu de configuration indique au navigateur d'empaqueter ces événements en JSON et de les envoyer à un serveur que vous contrôlez. Ce guide vous mène de rien à un endpoint fonctionnel qui reçoit de vrais rapports, de façon moderne, avec `Reporting-Endpoints` d'abord et le `Report-To` déprécié uniquement là où vous en avez encore besoin. En bref : déclarez un endpoint avec un header, nommez-le depuis une politique, et le navigateur regroupe et livre des rapports JSON à votre URL hors bande. Le reste de ce guide est le détail derrière ces trois étapes, et comment lire ce qui arrive. ## Ce que fait réellement le Reporting API [#ce-que-fait-réellement-le-reporting-api] Il est utile de séparer deux choses. Une politique ou une fonctionnalité de plateforme est le *producteur* : politique de sécurité du contenu (CSP), Cross-Origin-Opener-Policy (COOP), Network Error Logging, un avertissement de deprecation, un crash. Le Reporting API est le *transport* : une file partagée dans le navigateur qui collecte ces rapports et les livre. Le producteur décide de ce qui mérite d'être rapporté ; l'API décide de la façon dont cela voyage. Quand un producteur signale un événement, le navigateur ne l'envoie pas immédiatement. Il collecte le rapport, le regroupe avec d'autres, et POST le lot à votre endpoint selon son propre calendrier, indépendamment de la page. Ce découplage est le but : un rapport peut encore arriver après que la page a navigué ailleurs ou même a planté, parce que la livraison ne dépend pas du fait que la page soit vivante. Une réserve pour poser les attentes : la spec qualifie la livraison de fournie au mieux, pas de canal garanti. Des rapports peuvent être abandonnés, dédupliqués ou retardés, donc traitez le flux comme un signal de grande valeur, pas comme un journal d'audit dont vous pouvez prouver l'exhaustivité. Pour le modèle complet, voir [comment fonctionne le Reporting API](/fr/docs/web-security/reporting-api/concepts/how-the-reporting-api-works). ## Étape 1, déclarer un endpoint de reporting [#étape-1-déclarer-un-endpoint-de-reporting] Tout commence par un header de réponse. `Reporting-Endpoints` est une liste d'endpoints nommés, chacun un nom associé à une URL HTTPS. ```http Reporting-Endpoints: main-endpoint="https://.report.centralcsp.com" ``` Deux règles comptent ici. L'URL doit être en HTTPS, parce que le navigateur ignore silencieusement un endpoint non sécurisé, donc une faute de frappe ou une URL `http://` signifie que les rapports disparaissent sans erreur. Et le header n'affecte que la réponse sur laquelle il est servi, vous devez donc l'envoyer sur chaque page qui doit pouvoir rapporter, pas seulement la page d'accueil. Vous pouvez déclarer plus d'un endpoint et acheminer différentes politiques vers différentes URL, et vous pouvez déclarer un endpoint spécial nommé `default` qui attrape les types de rapports qui n'ont nulle part où aller ([deprecations et interventions](/fr/blog/deprecation-intervention-reports), [crashs](/fr/blog/browser-crash-reports)). ```http Reporting-Endpoints: default="https://.report.centralcsp.com", csp-endpoint="https://.report.centralcsp.com" ``` La syntaxe complète est sur la [référence Reporting-Endpoints](/fr/docs/web-security/reporting-api/headers/reporting-endpoints). ## Étape 2, pointer une politique vers l'endpoint [#étape-2-pointer-une-politique-vers-lendpoint] Déclarer un endpoint ne fait rien en soi. Une politique doit le référencer par son nom. Pour CSP, c'est la directive `report-to`. Démarrez en Report-Only pour qu'une erreur dans la politique rapporte au lieu de bloquer, et ne puisse pas casser la page pendant que vous l'ajustez. ```http Reporting-Endpoints: main-endpoint="https://.report.centralcsp.com" ``` ```http Content-Security-Policy-Report-Only: default-src 'self'; report-to main-endpoint ``` Les autres politiques se rattachent à un endpoint de la même façon, avec de petites différences de syntaxe : COOP et COEP utilisent un paramètre `report-to="..."` sur leur header, Integrity-Policy utilise une directive `endpoints=(...)`, et les types de rapports implicites (deprecation, intervention, crash) vont à l'endpoint nommé `default` sans aucun câblage. ## Étape 3, lire ce qui arrive [#étape-3-lire-ce-qui-arrive] Quand le navigateur livre, il envoie un POST HTTP avec `Content-Type: application/reports+json` et un tableau JSON. Chaque entrée partage la même enveloppe, les champs `type`, `url`, `user_agent`, `age` et `body`, et seul le `body` change d'un type de rapport à l'autre. ```json [ { "type": "csp-violation", "age": 53, "url": "https://example.com/", "user_agent": "Mozilla/5.0 ...", "body": { "documentURL": "https://example.com/", "blockedURL": "https://evil.example/script.js", "effectiveDirective": "script-src-elem", "disposition": "report", "statusCode": 200 } } ] ``` Ne soyez pas surpris si le premier rapport met une minute à apparaître. Chromium regroupe les livraisons et les retarde pour économiser la batterie et la bande passante, donc le reporting n'est pas instantané. L'enveloppe, et en quoi elle diffère du format hérité à objet unique `application/csp-report` qu'utilise `report-uri`, est couverte dans [le format de livraison des rapports](/fr/docs/web-security/reporting-api/concepts/report-delivery-format). Si vous préférez confirmer qu'un site en production est correctement câblé avant de construire un récepteur, le [vérificateur de configuration du Reporting API](/tools/reporting-api) le fait pour vous. Un bloc d'en-têtes généré qui déclare le point de collecte et y dirige chaque politique ## Où les rapports devraient aller [#où-les-rapports-devraient-aller] Pour le panorama complet de [où vont les rapports du navigateur et comment les recevoir](/fr/blog/where-to-send-csp-reports), les compromis sont ci-dessous. Vous pouvez monter votre propre collecteur, et pour une seule politique sur un site à faible trafic, c'est très bien. Le compromis honnête apparaît à l'échelle : le trafic réel produit beaucoup de rapports, dont une grande partie de bruit en double, et la valeur n'est pas de les stocker mais de grouper, dédupliquer et alerter sur ceux qui comptent. C'est un backend à construire et à maintenir. CentralCSP est ce backend en tant que service. Pointez l'URL `Reporting-Endpoints` vers lui et il [collecte tous les types de rapports](/fr/docs/platform/monitoring), les groupe, met en correspondance les violations CSP et les hashs de scripts avec de vraies causes, et transforme le flux en alertes et en preuves exportables. Vous sautez le collecteur et commencez par la partie réellement utile. ## Étapes suivantes [#étapes-suivantes] * Parcourez [tous les types de rapports](/fr/docs/web-security/reporting-api/reports) et ce que chacun vous dit. * Câblez des politiques précises : [CSP](/fr/docs/web-security/policies/content-security-policy), [COOP](/fr/docs/web-security/policies/cross-origin-opener-policy), [NEL](/fr/docs/web-security/policies/network-error-logging). * Comprenez les deux générations de headers dans [Report-To vs Reporting-Endpoints](/fr/docs/web-security/reporting-api/concepts/report-to-vs-reporting-endpoints). Prêt à collecter depuis le trafic réel plutôt que depuis un endpoint jetable ? [Démarrez un essai gratuit](/register). ## Sources [#sources] * [W3C, Reporting API](https://www.w3.org/TR/reporting-1/) * [W3C, Network Error Logging](https://www.w3.org/TR/network-error-logging/) * [MDN, Reporting-Endpoints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints) * [MDN, Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API)