La Reporting API du navigateur expliquée

La Reporting API est le mécanisme du navigateur qui collecte les événements survenus sur une page, violations de politiques, erreurs réseau, dépréciations, interventions et crashs, et les livre à un endpoint que vous contrôlez. Vous déclarez un endpoint avec un seul header HTTP, vous y pointez une politique, et le navigateur envoie des reports JSON structurés hors bande. Cette documentation est une référence des standards en langage clair pour l'ensemble du sujet : ce qu'est l'API, comment configurer chaque header de reporting, et la signification de chaque politique et de chaque type de report.

CentralCSP est construit sur cette API. Elle collecte et agrège tous les types de report sur un endpoint unique, puis transforme le flux en supervision de la sécurité côté client et en preuves PCI DSS v4, avec la politique de sécurité du contenu (CSP) comme cas d'usage le plus approfondi.

Ce qu'est la Reporting API

Il est utile de distinguer deux rôles. Une politique ou une fonctionnalité de la plateforme est le producteur d'un report : Content Security Policy, Cross-Origin-Opener-Policy, Network Error Logging, un avertissement de dépréciation, un crash. La Reporting API est le transport partagé sous-jacent : une file d'attente dans le navigateur qui collecte ces reports et les livre. Le producteur décide de ce qui mérite d'être signalé ; l'API décide de la manière dont cela circule.

Trois termes reviennent tout au long de cette référence. Un report est un objet JSON unique décrivant un événement (une violation CSP, un échec réseau). Un endpoint est une URL que vous contrôlez et qui reçoit les reports, nommée dans un header. Une politique est un ensemble de règles que le navigateur applique, configuré par un header de réponse, et qui peut nommer un endpoint où reporter. L'API elle-même ne définit aucun comportement de politique ; elle se contente de structurer, de mettre en file d'attente et de livrer ce que les politiques produisent.

Une chose à comprendre dès le départ : la livraison est au mieux possible, ce n'est pas un canal garanti. La spécification le dit explicitement. Les reports peuvent être regroupés, retardés, dédupliqués ou abandonnés, alors traitez le flux comme un signal de grande valeur, pas comme un journal d'audit complet.

Comment ça fonctionne

Une politique signale un événement. Le navigateur ne l'envoie pas immédiatement ; il collecte le report, le regroupe avec d'autres, et POST le lot vers l'endpoint nommé en tant que application/reports+json, selon son propre calendrier. La livraison s'exécute indépendamment de la page, ce qui explique qu'un report puisse encore arriver après que la page a quitté ou même planté.

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

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

Ce que vous pouvez en faire

• Détecter les violations CSP avant que les utilisateurs ne signalent une page cassée ou attaquée, avec le report csp-violation.
• Inventorier les scripts qui s'exécutent dans le navigateur via le hash reporting CSP, le report csp-hash, base d'un inventaire de scripts et d'un SBOM.
• Surveiller les échecs réseau que votre serveur ne voit jamais (DNS, TLS, connexion) avec Network Error Logging et le report network-error.
• Voir les dépréciations et les interventions avant qu'elles ne cassent le site, avec les reports deprecation et intervention.
• Obtenir des signaux de crash d'utilisateurs réels avec le report crash.
• Déployer les politiques cross-origin en toute sécurité (COOP, COEP, Permissions-Policy) en mode report-only et observer ce qui casserait.

CentralCSP collecte tout cela sur un endpoint et le transforme en alertes et en preuves.

Dans cette référence

Pour commencer

Le chemin le plus court consiste à déclarer un endpoint et à confirmer l'arrivée d'un premier report. Voir Pour commencer. Pour vérifier qu'un site en production est correctement câblé, utilisez le vérificateur de configuration de la Reporting API.

Sources

• W3C, Reporting API
• MDN, Reporting API
• Chrome, the Reporting API