Comment configurer le Reporting API du navigateur

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 sert à le faire sortir : quelques lignes de configuration suffisent pour que le navigateur empaquette ces événements en JSON et les envoie à un serveur que vous contrôlez. Ce guide vous emmène de zéro à un endpoint qui reçoit de vrais rapports, à la manière moderne : Reporting-Endpoints d'abord, et le Report-To déprécié seulement 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 puis livre des rapports JSON à votre URL, hors bande. Le reste de ce guide détaille ces trois étapes et explique comment lire ce qui arrive.

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 comment cela circule.

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 envoie le lot en POST à votre endpoint, à son propre rythme et indépendamment de la page. C'est tout l'intérêt de ce découplage : un rapport peut encore arriver après que la page a navigué ailleurs ou même planté, car la livraison ne dépend pas de sa survie.

Une réserve, pour fixer les attentes : la spec parle d'une livraison au mieux, pas d'un canal garanti. Des rapports peuvent être abandonnés, dédupliqués ou retardés. Traitez donc le flux comme un signal de grande valeur, pas comme un journal d'audit dont vous pourriez prouver l'exhaustivité. Pour le modèle complet, voir comment fonctionne le Reporting API.

É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 associant un nom à une URL HTTPS.

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

Deux règles comptent ici. L'URL doit être en HTTPS : le navigateur ignore silencieusement un endpoint non sécurisé, et une faute de frappe ou une URL http:// fait donc disparaître les rapports sans la moindre erreur. Et le header ne vaut que pour la réponse sur laquelle il est servi : envoyez-le sur chaque page qui doit pouvoir rapporter, pas seulement sur la page d'accueil.

Rien ne vous empêche de déclarer plusieurs endpoints et d'acheminer chaque politique vers une URL différente. Vous pouvez aussi déclarer un endpoint spécial nommé default, qui récupère les types de rapports sans destination désignée (deprecations et interventions, crashs).

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

Un producteur reste en dehors de tout cela. Network Error Logging ne sait pas lire Reporting-Endpoints : le header NEL désigne un groupe déclaré dans le header historique Report-To, et Chromium ne livre les erreurs réseau qu'à ces groupes. Si vous les voulez, envoyez Report-To en plus de Reporting-Endpoints.

La syntaxe complète est sur la référence Reporting-Endpoints.

Étape 2, pointer une politique vers l'endpoint

Déclarer un endpoint ne suffit pas : 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 se contente de remonter un rapport au lieu de bloquer, sans casser la page pendant que vous l'ajustez.

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

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) partent vers l'endpoint default sans aucun câblage.

Étape 3, lire ce qui arrive

Au moment de la livraison, le navigateur envoie un POST HTTP avec Content-Type: application/reports+json et un tableau JSON. Toutes les entrées partagent la même enveloppe, les champs type, url, user_agent, age et body ; seul le body change d'un type de rapport à l'autre.

[
  {
    "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 : le reporting n'a rien d'instantané. L'enveloppe, et ce qui la distingue du format hérité à objet unique application/csp-report qu'utilise report-uri, est détaillée dans le format de livraison des rapports. Si vous préférez vérifier qu'un site en production est bien câblé avant de construire un récepteur, le vérificateur de configuration du 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

Le panorama complet est dans où vont les rapports du navigateur et comment les recevoir ; voici les compromis. Vous pouvez monter votre propre collecteur, et pour une seule politique sur un site à faible trafic, cela suffit très bien. La vraie limite apparaît à l'échelle : le trafic réel produit énormément de rapports, dont beaucoup de doublons sans intérêt, et la valeur n'est pas de les stocker mais de les grouper, de les dédupliquer et d'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, les groupe, rattache les violations CSP et les hashs de scripts à de vraies causes, et transforme le flux en alertes et en preuves exportables. Vous faites l'économie du collecteur et démarrez directement sur la partie utile.

Étapes suivantes

Passez en revue tous les types de rapports et ce que chacun vous apprend.
Câblez des politiques précises : CSP, COOP, NEL.
Comprenez les deux générations de headers avec 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.