README

HK2 CSP Whitelisting — Magento 2 Module

Manage Content Security Policy (CSP) whitelists in Magento 2 with zero overhead. Ships with a pre-built whitelist of 80+ trusted hosts and a flexible admin interface for adding custom origins.

Overview

Magento 2.4.x ships with a strict CSP mode that blocks inline scripts, external resources, and cross-origin requests by default. Extensions integrating third-party services (analytics, payment gateways, CDNs, social widgets) routinely violate these policies, causing broken checkout flows, missing assets, and console errors.

HK2 CSP Whitelisting solves this by providing a maintainable, audit-friendly CSP management layer — no core hacks, no compilation steps, no deployment pipelines required.

Problem Statement

• Magento CSP violations break payment iframes, analytics scripts, and CDN assets silently.
• Default CSP configuration requires manual XML editing or compilation.
• Hardcoding hosts into etc/csp_whitelist.xml makes per-store or per-environment customisation impossible.
• Merchant-specific host additions are lost on module updates.

Solution Approach

Three-layer CSP architecture:

1. Safe-report-only defaults — broad but safe directive coverage (CSP.xml), violations logged, nothing blocked.
2. Pre-built whitelist (csp_whitelist.xml) — 80+ verified hosts across 7 directives, updated per release.
3. Admin custom whitelist — 6 textarea fields per store view, persisted in DB, survives updates.

A plugin intercepts Magento\Csp\Model\Policy\PolicyList::getAllPolicies and merges all three layers into a single policy object. No template overrides, no layout handles, no public assets — purely server-side policy assembly.

Alternatives Considered

Who is this for?

• Magento 2 merchants using third-party integrations (analytics, payments, CDNs, social media).
• Agencies managing multi-store deployments with different CSP requirements per store.
• Developers needing a predictable, code-reviewed allowlist that doesn't break on module updates.
• Store owners preparing for PCI DSS 4.0 compliance (CSP requirements).

Use Cases

• Payment gateways — whitelist Stripe, PayPal, or Braintree script & frame sources.
• Analytics & tracking — Google Analytics, Tag Manager, Facebook Pixel, Hotjar, Klaviyo.
• CDN assets — jsDelivr, cdnjs, Cloudflare, Fontsource, Tailwind CSS.
• Third-party widgets — YouTube/Vimeo embeds, Trustpilot reviews, TikTok pixels.
• Monitoring — Sentry error tracking, Contentsquare session replay.
• Social media — Facebook, Instagram, Twitter/X, Pinterest, LinkedIn pixels & SDKs.

Key Features

• 80+ trusted hosts pre-loaded across 7 CSP directives
• Admin custom fields — script-src, style-src, img-src, connect-src, font-src, frame-src
• Per-store-view configuration — different whitelists per website/store
• One-click reset — clears all custom entries from DB
• Zero frontend impact — no layout XML, no block rewrites, no JS
• No compilation step — policies assembled at runtime via plugin
• Report-only by default — violations logged, nothing blocked out of the box
• Marketplace-friendly — no ObjectManager, no preferences, no core rewrites

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                  HTTP Response                        │
│         Content-Security-Policy-Report-Only           │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│  PolicyList::getAllPolicies (Magento\Csp)            │
│  ┌────────────────────────────────────────────────┐  │
│  │  Plugin: afterGetAllPolicies                    │  │
│  │  ┌──────────────────┐ ┌──────────────┐ ┌─────┐ │  │
│  │  │ etc/csp.xml      │ │ csp_whitelist │ │ DB  │ │  │
│  │  │ (9 directives,   │ │ .xml          │ │custom│ │  │
│  │  │ report-only)     │ │ (80+ hosts,   │ │(6   │ │  │
│  │  │                  │ │  7 directives)│ │fields│ │  │
│  │  └──────────────────┘ └──────────────┘ └─────┘ │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

Layer 1 — Base CSP (etc/csp.xml)

Safe-report-only defaults for 9 directives. No hosts blocked — only logged. Provides immediate visibility into all policy violations without breaking storefront functionality.

Directives covered: script-src, style-src, img-src, connect-src, font-src, media-src, object-src, base-uri, child-src.

Layer 2 — Pre-built Whitelist (etc/csp_whitelist.xml)

Curated set of 80+ hosts across the most commonly needed directives. Sources verified for correctness — no wildcard entries, no redundant allowances.

Layer 3 — Admin Custom Whitelist

Six multi-line textarea fields under Stores → Configuration → CSP Whitelisting:

System Requirements

Installation

composer require hk2/csp
php bin/magento module:enable HK2_Csp
php bin/magento setup:upgrade
php bin/magento cache:clean config

See docs/installation.md for full instructions including verification steps.

Configuration

1. Navigate to Stores → Configuration → CSP Whitelisting.
2. Select the store view (website/store level).
3. Enter one host per line in the desired directive field(s).
4. Save config.
5. Flush the Magento cache (php bin/magento cache:flush config).

Reset Custom Whitelist

Click Reset Custom CSP Whitelist to clear all six custom fields from the database for the current scope. This does not affect the pre-built csp_whitelist.xml or the base csp.xml.

CSP in Magento 2

By default Magento ships with Content-Security-Policy headers in Report-Only mode. This module follows the same approach — violations are logged but never blocked.

• Production: switch to enforcement mode by editing etc/csp.xml (change report-only to enforce).
• Development: monitor violations in browser console and at the configured report-uri endpoint.
• Testing: use Chrome DevTools or Firefox CSP Inspector to validate directive coverage.

Privacy & GDPR

This module does not:

• Collect, transmit, or store personal data.
• Set cookies or access browser storage.
• Load external resources on its own (whitelist is security metadata, not executable code).

The CSP whitelist only allows — it does not fetch. Any data collection is performed solely by the third-party services whose hosts you whitelist, and is subject to their respective privacy policies.

Documentation

Known Limitations

• No CSP reporting endpoint — Magento expects you to configure your own report-uri (e.g. report-uri.com, a self-hosted collector, or Sentry). This module respects whatever reporting configuration you set in etc/csp.xml.
• No report-to header support — Magento's CSP framework uses the older report-uri directive.
• Wildcard sources — not included in the pre-built whitelist by design; use admin custom fields if you need them.
• strict-dynamic — not enabled; Magento's CSP framework does not natively support the strict-dynamic token.

Contributing

Contributions are welcome. Please open an issue or pull request on the GitHub repository.

Guidelines

• Follow PSR-12 and Magento 2 coding standards.
• Add or update tests for any new whitelist entries.
• Verify hosts serve content over HTTPS.
• Avoid wildcard (*) entries in the pre-built whitelist.
• Keep csp_whitelist.xml entries alphabetically sorted by host.

License

OSL-3.0 — Open Software License 3.0

This license requires that any derivative work distributed as a whole must be made available under the same license terms. See LICENSE for full text.

AFL-3.0 — Academic Free License 3.0 (alternate license for certain jurisdictions).

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. The authors and Super Market Depot shall not be held liable for any damages arising from the use of this software. The pre-built CSP whitelist is provided as a convenience and may not cover all third-party hosts used by your store. Always audit CSP policies in a staging environment before deploying to production.