Overview
The Blue Triangle Portal currently supports CSP Version 1. This guide documents the upgrade path to CSP Level 3 (Draft), including new directives, deprecated features, and best practices. Portal administrators can use this guide to understand what has changed, configure policies correctly, and enable or disable directives as needed.
|
✅ Best Practice: The Blue Triangle Portal defaults to CSP Level 3 best practices. Customers may disable specific directives as needed — see the Configuration section for details. |
CSP Level 3 Updates
New Directives for Granular Control
CSP Level 3 introduces several new directives that allow administrators and developers to set more specific, precise policies. The table below outlines each new directive, its purpose, and its fallback hierarchy if not explicitly set.
|
Directive |
Purpose in CSP Level 3 |
Fallback Hierarchy |
|
script-src-elem |
Controls sources for <script> elements. |
script-src → default-src |
|
script-src-attr |
Controls inline event handlers (e.g., onclick, onerror). |
script-src → default-src |
|
style-src-elem |
Controls sources for <style> elements and <link rel="stylesheet">. |
style-src → default-src |
|
style-src-attr |
Controls inline style attributes. |
style-src → default-src |
|
worker-src |
Controls sources for Worker, SharedWorker, and ServiceWorker scripts. |
child-src → script-src → default-src |
|
manifest-src |
Restricts sources for the web app manifest file (manifest.json). |
default-src |
|
frame-src |
Reinstated to restrict sources for nested browsing contexts (e.g., <iframe>). Was deprecated in Level 2. |
child-src → default-src |
|
require-trusted-types-for |
Enforces Trusted Types for DOM manipulation, mitigating DOM-based XSS by ensuring only type-safe objects can be used in dangerous DOM sinks like innerHTML. |
N/A |
|
⚠️ Important: frame-src was deprecated in CSP Level 2 but has been reinstated in Level 3 for clarity. If you were relying on child-src to control frames, update your configuration to use frame-src explicitly. |
Enhanced Script and Style Source Expressions
CSP Level 3 provides powerful new keywords that enable secure dynamic script loading — a major limitation of Level 1, which required the insecure 'unsafe-inline' keyword.
New Keywords
-
'strict-dynamic': Allows scripts dynamically loaded by another trusted script (verified via hash or nonce) to execute. This is essential for modern web frameworks and enables a robust Strict CSP that is less prone to bypasses than traditional URL whitelisting.
-
'unsafe-hashes': Allows hashes to match specific inline event handlers or javascript: navigations. This provides a way to permit targeted inline code without resorting to the broad 'unsafe-inline' keyword.
|
🚫 Deprecated / Not Recommended: 'unsafe-inline' is now considered a legacy approach. Wherever possible, migrate to nonces or hashes for inline scripts and styles. |
Policy Reporting Improvements
The mechanism for reporting CSP violations has been updated in Level 3 to use a more robust, standards-aligned approach.
report-to (Replaces report-uri)
The report-to directive replaces the deprecated report-uri directive. It uses the modern Reporting API, which offers:
-
Structured JSON violation reports
-
Support for cross-origin reporting
-
Better compatibility with modern browser security features
|
🚫 Deprecated / Not Recommended: report-uri is deprecated in CSP Level 3. If your current configuration uses report-uri, you should migrate to report-to. The portal will flag this as a legacy setting. |
Summary of Changes: CSP Level 1 vs. Level 3
The following table summarizes the key differences between CSP Level 1 and Level 3, highlighting the shift in approach for XSS mitigation, inline code handling, and resource isolation.
|
Feature |
CSP Level 1 Focus |
CSP Level 3 Focus (Draft) |
|
XSS Mitigation |
Whitelisting trusted URLs for scripts and styles. |
Cryptographic integrity (nonce and hash), 'strict-dynamic', and Trusted Types for a stricter, more maintainable policy. |
|
Inline Code |
Only allowed via the often-insecure 'unsafe-inline' keyword. |
Discouraged, but can be safely allowed using hashes or nonces on specific elements. |
|
Frames / Workers |
Used child-src for both nested frames and worker scripts. |
Introduces separate frame-src and worker-src for clearer separation of concerns. |
|
✅ Best Practice: CSP Level 3 provides the tools needed to build a 'Strict CSP' that is highly effective against modern XSS attacks and easier to maintain without breaking dynamic web applications. |
Configuring a CSP in the Blue Triangle Portal
The portal applies CSP Level 3 best practices by default. Administrators can customize which directives are enabled and adjust values to suit their deployment.
Enabling / Disabling Directives
Walkthrough coming soon
Applying a Strict CSP (Recommended)
A Strict CSP uses nonces or hashes instead of URL allowlists. The portal provides a 'Strict CSP' template that pre-configures the recommended directives.
Walkthrough coming soon
Handling Legacy Directives
Directives that are deprecated or not recommended in Level 3 are marked with a warning indicator in the portal UI. You can still enable them if required, but the portal will display guidance on safer alternatives.
|
⚠️ Important: If you enable a deprecated directive (e.g., report-uri, unsafe-inline), the portal will display a warning with a link to the recommended alternative. |
Frequently Asked Questions
-
Do I need to migrate immediately?
-
No immediate migration is required. The portal will continue to support CSP Level 1 configurations. However, upgrading to Level 3 is strongly recommended for improved security.
-
-
Where can I see CSP violation reports?
-
After configuring report-to, violation reports will be available in the Reporting dashboard. See Section 3 for configuration steps.
-
-
Can I revert to a previous CSP configuration?
-
Yes. The portal maintains a configuration history. Steps to restore a previous version:
-