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 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

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.

É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.

Reporting-Endpoints: main-endpoint="https://<Endpoint-ID>.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, crashs).

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

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 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.

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) vont à l'endpoint nommé default sans aucun câblage.

É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.

[
  {
    "type": "csp-violation",
    "age": 53,
    "url": "https://api-next.centralcsp.com/",
    "user_agent": "Mozilla/5.0 ...",
    "body": {
      "documentURL": "https://api-next.centralcsp.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. 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 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

Pour le panorama complet de où vont les rapports du navigateur et comment les recevoir, 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, 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

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