Download the PHP package hryvinskyi/magento2-csp without Composer

Advanced Content Security Policy (CSP) module for Magento 2

Overview

The Hryvinskyi_Csp module is a Magento 2 extension that provides additional Content Security Policy (CSP) configurations. This module allows administrators to manage CSP whitelists from the Magento admin panel

Features

1. CSP Whitelist Management: Administrators can manage CSP whitelists directly from the Magento admin panel.
2. Store-Specific Configuration: Module provides store view specific CSP configuration.
3. Violation Reports: The module collects and displays CSP violation reports, helping administrators identify and address security issues.
4. One-Click Conversion: Possibility to convert violation reports to whitelist rule with one click.
5. Mass Convert Reports: Bulk conversion of multiple CSP report groups to whitelist entries with automatic cleanup.
6. Automatic URL Collection: Automatically collects and adds all storefront URLs to the CSP whitelist.
7. CSP Header Splitting: Automatically splits large CSP headers into multiple smaller ones to prevent issues with header size limits.
8. CSP Value Optimization: Removes duplicate entries and redundant wildcard-covered values from CSP headers to reduce header size.
9. Flexible Configuration: The module provides various configuration options to enable or disable specific CSP features.
   10. Admin Panel Integration: The module integrates with the Magento admin panel, providing a user-friendly interface for managing CSP settings.
   11. Import/Export: Support for importing and exporting whitelist rules.
   12. Automatic Script Hash Generation: Command-line tool to scan CMS pages/blocks and configs for inline scripts and generate CSP hashes
   13. Visual Hash Validation: See at a glance if your script hashes are valid
   14. Template Nonce Provider: ViewModel class for easy CSP nonce generation in templates
   15. Enhanced Caching: Improved CSP policy caching with better serialization and cache management
   16. Report Grouping: Organized CSP violation reports into logical groups for better management
   17. Redundancy Detection: Visual indicators showing duplicate and redundant whitelist entries
   18. Advanced Grid Filtering: Filter whitelist entries by hash validation status and redundancy status
   19. Advanced Grid Sorting: Sort whitelist entries by computed columns (hash validation, redundancy)
   20. Automatic Report Cleanup: Scheduled cleanup of old violation reports by date or record count, with CLI command for manual execution
   21. Default-Src Consolidation: Automatically moves values shared across all directives into default-src, reducing header size by 40-70%
   22. Subdomain-to-Wildcard Consolidation: Automatically replaces groups of subdomains with wildcard entries (e.g., 3+ *.google.com subdomains become *.google.com)
   23. Scheme and Path Stripping: Removes redundant https:// prefixes and /path suffixes from CSP host values

Requirements

• Magento 2.4.4 or higher
• PHP 8.1 or higher

Installation

Composer (recommended)

Manual Installation

1. Download the module and upload it to app/code/Hryvinskyi/Csp
2. Enable the module and update the database:

Usage

Admin Panel Navigation

The module adds a new menu item in the admin panel:

1. Content Security Policy: Main menu item providing access to CSP features
   • Whitelist: Manage CSP whitelist rules
   • Violation Report: View and manage CSP violation reports
   • Configuration: Configure CSP settings

Managing Whitelist Rules

1. Navigate to System > Content Security Policy > Whitelist
2. Click Add to create a whitelist entry manually
3. Fill in required fields:
   • Identifier: Unique name for the rule
   • Policy: CSP directive (e.g., script-src, style-src)
   • Value Type: Type of value (URL, Domain, etc.)
   • Value: The actual value to whitelist
   • Store Views: Select applicable store views
   • Status: Enable or disable the rule

Using CSP Nonces in Templates

The module provides a CspNonceProvider ViewModel for easy nonce generation in templates:

In your template (template.phtml)

Generating Script Hashes

To make inline scripts work with CSP, you must generate cryptographic SHA hashes and add them to your whitelist. The module provides a console tool that lets you review each script and approve the addition of its hash to your CSP configuration. Use the built-in CLI tool:

Options:

• --type: Specify which entity types to scan (page, block, config)
• --store: Specify store ID (default is all stores)

Screenshots

Configuration

Navigate to System > Content Security Policy > Configuration or Stores > Configuration > Security > Content Security Policy to access module settings.

CSP Header Splitting

CSP headers can grow large, especially when many domains are whitelisted. Some servers and proxies have limits on header sizes, which can cause issues with security policy enforcement.

This module includes CSP header splitting functionality that automatically splits large CSP headers into multiple smaller headers to ensure proper delivery.

To configure header splitting:

1. Go to Stores > Configuration > Security > Content Security Policy
2. In the General section, you'll find:
   • Enable CSP header splitting: Toggle to enable/disable the feature
   • Max CSP header size (bytes): Specify the maximum size for a single header before splitting occurs (default: 4096 bytes)

When enabled, the module will monitor CSP header sizes and automatically split them if they exceed the configured maximum size.

CSP Value Optimization

Over time, CSP headers can accumulate duplicate entries and redundant values that are already covered by wildcard patterns. This increases header size unnecessarily.

The module includes CSP value optimization that can:

• Remove exact duplicates: Eliminates entries like data: appearing multiple times in the same directive
• Remove wildcard-covered entries: Removes specific domains when a wildcard already covers them (e.g., removes www.example.com when *.example.com exists)
• Detect redundant wildcards: Removes wildcards covered by broader wildcards (e.g., *.sub.example.com when *.example.com exists)
• Warn about unrestricted wildcards: Logs a warning when * is used, which makes all other entries redundant

To configure value optimization:

1. Go to Stores > Configuration > Security > Content Security Policy
2. In the General section, you'll find:
   • Enable CSP value optimization: Toggle to enable/disable duplicate removal
   • Enable redundant wildcard removal: Toggle to enable/disable wildcard coverage analysis (requires optimization to be enabled)

Example optimization:

Before:

After (with both options enabled):

The optimization removes:

• Duplicate data: entry
• www.example.com and api.example.com (covered by *.example.com)

When debug mode is enabled, the module logs details about removed entries and bytes saved.

Default-Src Consolidation

When multiple CSP directives share common values, the header repeats those values in every directive. The default-src consolidation feature identifies values present in all fallback-eligible directives and moves them into default-src, removing them from individual directives.

Example:

Before:

After (with consolidation enabled):

This can reduce header size by 40-70% depending on how many values are shared.

To enable:

1. Go to Stores > Configuration > Security > Content Security Policy
2. Set Enable CSP value optimization to Yes
3. Set Enable default-src consolidation to Yes

Note: frame-ancestors, base-uri, and form-action are excluded from consolidation since they do not inherit from default-src per the CSP specification. Consolidation is also skipped when default-src already contains 'none'.

Subdomain-to-Wildcard Consolidation

When multiple subdomains of the same parent domain are whitelisted, the module can automatically consolidate them into a single wildcard entry.

Example (threshold: 3):

Before:

After:

To configure:

1. Go to Stores > Configuration > Security > Content Security Policy
2. Set Enable CSP value optimization to Yes
3. Set Enable subdomain-to-wildcard consolidation to Yes
4. Set Subdomain wildcard threshold (default: 3) — the minimum number of subdomains required to trigger consolidation

Note: Port-bearing hosts (e.g., api.example.com:8080) are excluded from consolidation since wildcards do not cover port-specific origins.

Scheme and Path Stripping

CSP host-source example.com already matches both http:// and https:// origins. The scheme and path stripping feature removes redundant scheme prefixes and path suffixes from host values, reducing header size and improving deduplication.

Example:

Before:

After (with stripping enabled):

To enable:

1. Go to Stores > Configuration > Security > Content Security Policy
2. Set Enable CSP value optimization to Yes
3. Set Enable scheme and path stripping to Yes

Keywords ('self', data:, https:, etc.), hashes, and nonces are never stripped. Ports are preserved.

Redundancy Detection

The whitelist grid includes visual indicators to help identify duplicate and redundant entries:

Status Indicators:

• Unique (green): The entry is unique within its policy directive
• Duplicate (yellow): An exact duplicate of another entry exists
• Redundant (orange): The entry is covered by a wildcard pattern (e.g., www.example.com when *.example.com exists)
• N/A (gray): Not applicable for non-host value types (hash, nonce, keyword)

Filtering and Sorting:

Both the Hash Validation and Redundancy Status columns support:

• Filtering: Use the dropdown filter to show only entries with a specific status
• Sorting: Click the column header to sort entries by their status

This helps you quickly identify and clean up redundant whitelist entries to keep your CSP configuration optimized.

Example Use Cases:

1. Filter by "Duplicate" to find and remove duplicate entries
2. Filter by "Redundant" to find entries that can be safely removed because they're covered by wildcards
3. Sort by "Hash Validation" to group invalid hashes together for review

Report Cleanup

The hryvinskyi_csp_violation_report table can grow very large over time. The module provides automatic and manual cleanup options. Aggregated counts in the report group table are preserved.

Automatic cleanup (cron):

1. Go to Stores > Configuration > Security > Content Security Policy > Report Cleanup
2. Set Enable automatic cleanup to Yes
3. Choose a mode:
   • By Date: Delete reports older than N days (default: 30)
   • By Record Count: Keep only the N most recent reports
4. Set the threshold value

The cron job runs daily at 2:00 AM.

Manual cleanup (CLI):

Support

If you encounter any issues or have questions, please contact the author or open an issue on GitHub.

License

This module is licensed under the MIT License - see the LICENSE file for details.

Author

Volodymyr Hryvinskyi
Email: [email protected]
GitHub: https://github.com/hryvinskyi