README

Magento 2 Content Security Policy (CSP) Whitelist Manager

A Magento 2 module that lets store administrators manage Content Security Policy whitelists, SHA-256 inline script hashes, and per-directive domain allowlists directly from the Magento admin panel without touching code or XML files.

The Problem

Magento 2.4+ enforces strict Content Security Policy (CSP) headers by default. Any third-party script, image, font, or API call that isn't explicitly whitelisted produces browser console errors like:

Refused to load the script 'https://www.googletagmanager.com/...' because it violates the following Content Security Policy directive: "script-src ..."

The native solution requires developers to create or edit csp_whitelist.xml files and redeploy static content every time a new domain needs to be allowed. This is slow and requires developer access.

The Solution

Hotchand_CspManager exposes a full CSP management UI under:

Stores → Configuration → Hotchand → CSP Whitelist Manager

Add or remove domains for any CSP directive, paste inline script SHA-256 hashes from your browser console, and set your store's own domain for image whitelisting — all without touching a single file or running a deployment.

Features

✅ Admin UI for all major CSP directives (script-src, img-src, connect-src, style-src, font-src, frame-src, media-src)
✅ SHA-256 inline script hash management — paste hashes directly from browser console errors
✅ Explicit self-domain field for img-src to fix same-domain image blocking (common with Magebig and other themes)
✅ Comment support — lines starting with # are ignored, so you can annotate your whitelist
✅ Wildcard support — *.example.com syntax works natively
✅ Pre-populated defaults covering 50+ common third-party services out of the box
✅ Per-store-view configuration — different whitelists per store view or website
✅ Enable/disable toggle — disable the module without uninstalling
✅ Zero performance impact — policies are injected at request time via Magento's native PolicyCollectorInterface
✅ Compatible with Magento's existing CSP stack — merges with, not replaces, native policies

Pre-configured Third-Party Services

The module ships with defaults covering the most common services that trigger CSP violations:

Category	Services
Analytics	Google Analytics, Google Tag Manager, Adobe Analytics
Advertising	Google Ads, DoubleClick, Facebook Pixel, Bing Ads, TikTok Pixel
Payments	PayPal, Stripe, Klarna, Amazon Pay, Cardinal Commerce (3DS)
Support	Tawk.to, Disqus
Fonts & CDN	Google Fonts, Typekit, Cloudflare, jsDelivr
Video	YouTube, Vimeo
Reviews	Trustpilot, Trusted Shops
New Relic	Browser agent, data ingest
CMP	Usercentrics
Stape	Server-side GTM proxy

Requirements

Dependency	Version
PHP	8.1 or higher
Magento Open Source / Adobe Commerce	2.4.4 – 2.4.8
`Magento_Csp` module	Included in Magento 2.4+

Installation

Composer (Recommended)

composer require hotchand/module-csp-manager
php bin/magento module:enable Hotchand_CspManager
php bin/magento setup:upgrade
php bin/magento cache:flush

Manual Installation

Create the directory app/code/Hotchand/CspManager/
Copy all module files into that directory
Run the following commands from your Magento root:

php bin/magento module:enable Hotchand_CspManager
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Configuration

Navigate to Stores → Configuration → Hotchand → CSP Whitelist Manager.

General

Field	Description
Enable CSP Whitelist Manager	Master on/off switch

Inline Script Hashes

Fixes Executing inline script violates the following Content Security Policy directive errors.

How to find the hash:

Open your browser's developer console
Look for a CSP error message ending in: ...a hash ('sha256-XXXXXXX='), or a nonce is required
Copy the full sha256-XXXXXXX= string
Paste it into the SHA-256 Inline Script Hashes field — one per line

# Checkout page inline scripts
sha256-6caeB6wTLT806tdBj/ysbbY0p5wQzo9q0nefuMyzoQo=
sha256-hqVdB6q2lpSfxobG08BVO5jo6Mq1svAIueYt1F9XnFU=

Directives

Each directive has its own textarea. Format rules:

# Lines starting with # are comments — ignored by the module

# Wildcards are supported
*.example.com

# Full URLs are supported
https://cdn.example.com

# Data URIs
data:

# Blob URIs
blob:

Directive	Controls
`script-src`	JavaScript files and inline scripts
`img-src`	Images, favicons, tracking pixels
`connect-src`	XHR, fetch(), WebSocket, EventSource
`style-src`	External CSS stylesheets
`font-src`	Web fonts
`frame-src`	`<iframe>` embeds
`media-src`	`<audio>` and `<video>` elements

Image Sources — Store Domain Field

If your store's own images (wysiwyg, media) are being blocked despite 'self' being in the policy, enter your domain here:

connectresale.com

This explicitly adds your domain as a host source in img-src, which resolves a known edge case in Magento 2.4.x where dynamically loaded images are not covered by 'self'.

Architecture

The module implements Magento\Csp\Api\PolicyCollectorInterface and registers itself into Magento's CompositePolicyCollector via di.xml.

Admin Config (core_config_data)
        │
        ▼
CspPolicyCollector::collect()
        │
        ├── Reads domain lists per directive
        ├── Parses SHA-256 hashes
        ├── Merges with existing policies (preserves native + other module policies)
        │
        ▼
Magento CSP Header (Content-Security-Policy)

Key class: Hotchand\CspManager\Model\CspPolicyCollector

Runs on every frontend/adminhtml request
Reads config from core_config_data (respects store scope)
Merges custom domains into existing FetchPolicy objects rather than replacing them
Safely parses sha256-XXXX= hash strings into the format FetchPolicy expects

Module Structure

app/code/Hotchand/CspManager/
├── registration.php
├── etc/
│   ├── module.xml              # Module declaration, loads after Magento_Csp
│   ├── di.xml                  # Registers CspPolicyCollector into pipeline
│   ├── config.xml              # Default domain values (50+ pre-populated)
│   ├── acl.xml                 # Admin access permissions
│   └── adminhtml/
│       └── system.xml          # Full admin configuration form
└── Model/
    └── CspPolicyCollector.php  # Core: reads config, injects into CSP headers

Troubleshooting

Changes not taking effect

Flush the Magento cache after saving configuration:

php bin/magento cache:flush

If you are using Varnish or full-page cache, also purge that.

A domain I added is still being blocked

Make sure you added it to the correct directive. A script blocked under script-src won't be fixed by adding it to img-src.
Check that the domain format is correct — include the subdomain if the error URL has one.
If the error is about an inline script (not an external URL), it needs a SHA-256 hash, not a domain.

Inline script hash still blocked after adding it

Make sure you copied the full string including the sha256- prefix and the trailing =:

# ✅ Correct
sha256-6caeB6wTLT806tdBj/ysbbY0p5wQzo9q0nefuMyzoQo=

# ❌ Wrong — missing prefix
6caeB6wTLT806tdBj/ysbbY0p5wQzo9q0nefuMyzoQo=

Same-domain images blocked (Magebig, wysiwyg)

Enter your store's domain (without https://) in the Image Sources → Store Domain field and flush cache.

Frequently Asked Questions

Does this replace Magento's native CSP system? No. It merges with it. Domains from csp_whitelist.xml files across all modules are preserved. This module adds on top.

Will this work on Magento Cloud / Adobe Commerce Cloud? Yes. The module uses Magento's standard config and DI systems with no file system writes at runtime.

Is there a performance impact? Minimal. The module reads from the Magento config cache on each request. No external HTTP calls are made.

Can I use this per store view? Yes. All fields support Default / Website / Store View scope.

What happens if I disable the module? Only the domains configured in this module's admin panel are removed from CSP headers. Native csp_whitelist.xml policies from Magento core and other modules continue to apply normally.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m 'Add my feature'
Push to the branch: git push origin feature/my-feature
Open a Pull Request

License

MIT License

Author

Hotchand Sajnani Senior PHP / Magento Engineer ConnectResale LLC

Changelog

1.0.0 — 2026-01-01

Initial release
Admin UI for 7 CSP directives
SHA-256 inline script hash management
Explicit self-domain field for img-src
50+ pre-populated third-party domain defaults
Per-store-view configuration support

hotchand / module-csp-manager

Maintainers

Package info

Statistics

Security