HK2 CSP Whitelisting

Overview

HK2 CSP is a Magento 2 extension that enables administrators to manage Content Security Policy (CSP) whitelists dynamically. In addition to a robust set of pre-configured whitelist hosts for third-party scripts, styles, fonts, images, frames, and connections, it provides an admin interface to add custom domains without touching configuration files.

🎯 Use Cases

• Third-Party Integrations: Safe whitelisting for Google Analytics, Stripe, Facebook, and other standard services.
• Admin Management: Direct, safe administrative management of CSP hosts dynamically.

🚀 Features

• 🛡 Declares standard CSP policy parameters in etc/csp.xml.
• 📦 Out-of-the-box whitelists for popular services (Google, Facebook, Stripe, Hotjar, Sentry, etc.).
• ⚙️ Dynamic admin configurations for directive hosts (script-src, style-src, img-src, connect-src, font-src, frame-src).
• 🔌 Backend validation plugin preventing invalid hosts or header injections.
• 🔄 One-click dynamic "Reset CSP to Defaults" button via Ajax backend redirect.

🏗 Architecture

• Plugin: HK2\Csp\Plugin\PolicyListPlugin intercepts Magento\Csp\Model\Policy\PolicyList::getAllPolicies to dynamically merge administrative hosts.
• Controller: HK2\Csp\Controller\Adminhtml\Reset\ResetConfig handles configuration wipe operations.

🧩 Magento Components

Blocks

• HK2\Csp\Block\Adminhtml\System\Config\ResetButton

Plugins

• HK2\Csp\Plugin\PolicyListPlugin on Magento\Csp\Model\Policy\PolicyList

Controllers

• HK2\Csp\Controller\Adminhtml\Reset\ResetConfig

📦 Requirements

• Magento version: 2.4.4 - 2.4.9
• PHP requirements: 8.1 || 8.2 || 8.3 || 8.4
• Required Extension: HK2_Core

⚙️ Installation

1. composer require hk2/csp
2. bin/magento module:enable HK2_Csp
3. bin/magento setup:upgrade
4. bin/magento setup:di:compile
5. bin/magento cache:flush

🔧 Configuration

Configure settings under Stores > Configuration > HK2 > CSP Whitelisting:

Usage

Navigate to Stores > Configuration > HK2 > CSP Whitelisting, populate domains matching your external integrations, and save. Run bin/magento cache:flush to apply.

🗄 Database Changes

Not Applicable

📂 Module Structure

Block/
└── Adminhtml/
    └── System/
        └── Config/
            └── ResetButton.php
Controller/
└── Adminhtml/
    └── Reset/
        └── ResetConfig.php
Plugin/
└── PolicyListPlugin.php
etc/
├── adminhtml/
│   ├── menu.xml
│   ├── routes.xml
│   └── system.xml
├── acl.xml
├── config.xml
├── csp.xml
├── csp_whitelist.xml
├── di.xml
└── module.xml
view/
└── adminhtml/
    └── templates/
        └── system/
            └── config/
                └── reset_button.phtml

📈 Performance Considerations

The policies list is cached inside Magento's standard configuration cache, preventing database queries or regex calculations on standard page loads.

🔐 Security Considerations

• Input Validation: isValidCspHost prevents semicolons, commas, and white spaces in custom values, protecting the headers against header splitting or policy injection attacks.

Compatibility

Reference: docs/compatibility.md

🛠 Troubleshooting

Dynamic values not appearing in CSP header

Verify you have flushed the configuration cache after making changes: bin/magento cache:flush.

🤝 Contributing

Contributions are welcome! If you'd like to improve the installer:

• ⭐ Star this repository (Helps others find it!)
• 🍴 Fork the project
• 🐛 Report bugs
• 💡 Suggest new features
• 🤝 Contribute improvements

Every ⭐ helps increase the visibility of the project and motivates further development.

⚖️ Disclaimer

The author provides this installation script "as is" without any warranties. Users are responsible for ensuring that running this script complies with their internal security and software requirements.

🤝 Support

For bug reports, feature requests, and general support:

• Author: Basant Mandal
• Email: [email protected]
• Website: https://www.basantmandal.in

License

This project is licensed under the OSL 3.0 License. See the LICENSE.txt file for details.

2.1.0 (2026-07-16)

✨ Features

• update placeholder version in bug report template (a7c10b9)

1.0.0 (2026-07-16)

⚠ BREAKING CHANGES

• Implement CSP Whitelisting Module

✨ Features

• add contributing guide, bug report template, and pull request template for improved collaboration (85d915d)
• add localization files for English, Hindi, and Russian languages (3f71f73)
• add semantic release configuration for automated versioning and changelog generation (a90c684)
• addition of Installation Guide (060225b)
• Implement CSP Whitelisting Module (b23e35f)

📝 Documentation

• update README.md to enhance clarity and structure, including use cases and features (ca79814)

1.0.0 (2026-07-16)

⚠ BREAKING CHANGES

• Implement CSP Whitelisting Module

✨ Features

• add contributing guide, bug report template, and pull request template for improved collaboration (85d915d)
• add localization files for English, Hindi, and Russian languages (3f71f73)
• add semantic release configuration for automated versioning and changelog generation (a90c684)
• Implement CSP Whitelisting Module (b23e35f)

📝 Documentation

• update README.md to enhance clarity and structure, including use cases and features (ca79814)