Document-Policy
Document-Policy définit des points de configuration par document, comme js-profiling, avec un reporting de violations optionnel.
Dernière mise à jour:
Document-Policy configure le comportement et les contraintes de fonctionnalités d'un
document donné via des points de configuration nommés, par exemple l'activation de
l'API JS Self-Profiling avec js-profiling. Contrairement à
Permissions-Policy, elle n'est pas déléguée aux
sous-frames de la même façon : c'est un ensemble de garde-fous par document.
Expérimental
Document-Policy est un brouillon du Community Group WICG, pas un standard W3C, et n'est implémentée que dans Chromium, où la plupart des points de configuration sont derrière des flags ; seul js-profiling est activé par défaut. L'ensemble des points de configuration est défini par l'implémentation et peut changer, ne comptez donc pas sur une liste de directives figée.
La configuration utilisable aujourd'hui active l'API JS Self-Profiling :
Document-Policy: js-profilingComment fonctionne Document-Policy
Le header est un dictionnaire structured-field de points de configuration. Chaque
point a une valeur typée, un booléen (?0 désactivé, ?1 activé), un entier, un
flottant ou une énumération, et chaque point gouverne un comportement du document. La
liste des points existants est définie par le navigateur, pas par un registre
standard figé.
Comment configurer Document-Policy
| Point de configuration | Statut | Effet |
|---|---|---|
js-profiling | 🧪 Expérimental | Active l'API JS Self-Profiling. Le seul point de configuration activé par défaut dans Chromium. |
include-js-call-stacks-in-crash-reports | 🧪 Expérimental | Conditionne l'inclusion des piles d'appels JavaScript dans les rapports de crash. |
Document-Policy est un brouillon WICG, implémenté uniquement dans Chromium, et la plupart de ses points de configuration sont derrière des flags. Les deux points ci-dessus sont ceux qui valent la peine d'être connus aujourd'hui ; traitez toute liste plus longue comme instable, et vérifiez qu'un point fonctionne dans vos navigateurs cibles avant de vous y fier.
Mode Report-Only
Reporting-Endpoints: doc-endpoint="https://<Endpoint-ID>.report.centralcsp.com"Document-Policy-Report-Only: js-profiling;report-to=doc-endpointChaque point peut porter un paramètre report-to ; *;report-to=endpoint définit un
endpoint par défaut pour tous les points, et report-to=none désactive le reporting
pour un point. Le brouillon définit Document-Policy-Report-Only, mais la livraison
des rapports de bout en bout dans Chromium n'est pas confirmée, vérifiez donc que les
rapports arrivent réellement avant de construire dessus.
Ce contre quoi il protège
Aujourd'hui, moins que le nom ne le suggère. Les deux points de configuration
utilisables encadrent des diagnostics plutôt que de bloquer des attaques :
js-profiling contrôle si un document peut profiler son propre JavaScript, et
include-js-call-stacks-in-crash-reports contrôle si les rapports de crash portent
des piles d'appels. La valeur du header est d'activer ces capacités délibérément, par
document.
Configurations non sûres à éviter
Laisser sans contrainte un point de configuration connu comme risqué va à l'encontre
du but, et, comme pour toute fonctionnalité de reporting, pointer report-to vers un
hôte que vous ne contrôlez pas fait fuiter des données de rapport. Contraignez
explicitement les points qui vous importent plutôt que de supposer un défaut sûr.
Contournements et limites connus
Il n'existe pas de registre normatif des points de configuration, le support est limité à Chromium, et la politique n'est pas déléguée aux sous-frames comme l'est Permissions-Policy : elle gouverne le document sur lequel elle est définie plutôt qu'un arbre de frames entier.
Risques
Parce que l'ensemble de fonctionnalités est instable, un point dont vous dépendez peut changer ou disparaître entre deux versions du navigateur. Gardez les contraintes en Report-Only quand vous le pouvez, et surveillez les rapports avant d'appliquer.
Recommandation
Document-Policy: js-profilingTraitez Document-Policy comme expérimentale. N'adoptez que les deux points de
configuration qui fonctionnent dans Chromium aujourd'hui, js-profiling et
include-js-call-stacks-in-crash-reports, et seulement après des tests dans vos
navigateurs cibles. Préférez Document-Policy-Report-Only là où il est disponible ;
le brouillon le définit, mais la livraison de bout en bout dans Chromium n'est pas
confirmée, vérifiez donc que les rapports arrivent avant de vous y fier.
Reporting
Un paramètre report-to par point route les violations de ce point vers un endpoint
nommé, et le navigateur émet le
rapport document-policy-violation.
Un point voisin, include-js-call-stacks-in-crash-reports, enrichit le
rapport crash avec une pile JS, comme le
couvre rapports de crash et de non-réponse du navigateur.
CentralCSP collecte le flux.
Prise en charge par les navigateurs
Navigateurs basés sur Chromium uniquement ; expérimental, sans registre normatif des points de configuration.
Voir aussi
- rapport document-policy-violation
- Document-Policy expliqué (guide)
- rapport crash
- Header Reporting-Endpoints
- Surveillance Document-Policy dans CentralCSP
Sources
Permissions-Policy
Permissions-Policy autorise ou refuse des fonctionnalités du navigateur comme la caméra, le microphone et la géolocalisation, par document et par frame.
Integrity-Policy
Integrity-Policy exige que les scripts chargés portent une Subresource Integrity valide, pour bloquer ou signaler une ressource altérée ou remplacée.