decodelabs/sanctum

Define and deploy Content Security Policies in your PHP application

v0.1.5 2024-04-26 17:58 UTC

This package is auto-updated.

Last update: 2024-07-15 13:50:29 UTC


README

PHP from Packagist Latest Version Total Downloads GitHub Workflow Status PHPStan License

Content Security Policies for your PHP application.

Sanctum allows you to create and deploy Content Security Policies with ease. Take the guesswork out of this important security feature.

Get news and updates on the DecodeLabs blog.

Installation

composer require decodelabs/sanctum

Usage

Create your definition:

use DecodeLabs\Sanctum\Definition;

class MyCsp extends Definition {

    // These items can be reused in other directives
    const SHARED_SRC = [
        '@self', // Resolves to 'self'
        '*.myotherdomain.com'
    ];

    // These items create the default-src directive
    const DEFAULT_SRC = [
        '@shared-src', // Import items from SHARED_SRC
    ];

    // These define script sources
    const SCRIPT_SRC = [
        '@nonce', // Creates a unique nonce to be used in markup
        '@unsafe-inline', // Resolves to 'unsafe-inline'

        '@strict-dynamic',
        '@https',
        '@http'
    ];

    // These define image sources
    const IMG_SRC = [
        '@shared', // Import items from SHARED_SRC
        '@data', // Resolves to data: for data URLs
        '*.myimagecdn.net',
        '!*.myotherdomain.com' // Exclude importing from SHARED_SRC
    ];


    // Report endpoint
    const REPORT_URI = 'https://mydomain.com/report';
}

Please see https://content-security-policy.com/ for a full list of directives.

Then in your HTTP handler:

$csp = new MyCsp();

foreach($csp->exportHeaders() as $header => $value) {
    $response->setHeader($header, $value);
}

/*
Reporting-Endpoints => sanctum-csp-report="https://mydomain.com/report"
Content-Security-Policy =>
    default-src 'self' *.myotherdomain.com;
    script-src nonce-98b88fa48f23911d6fc1f5092efb2e36d76423ce4f5d7ef42765a2c2501d57c9' 'unsafe-inline' 'strict-dynamic' https: http:;
    img-src 'self' data: *.myimagecdn.net;
    report-uri https://mydomain.com/report;
    report-to sanctum-csp-report
*/

Hashes

Make use of the hash feature for scripts - see https://content-security-policy.com/hash/ for explanation

/*
HTML:
<script>doSomething();</script>
*/
$script = 'doSomething();'; // Your JS


// Adds sha256-xxx hash to CSP directive
$hash = $csp->hashContent($script, 'script-src');

Archetype loader

Sanctum also provides an optional Archetype loader:

namespace DecodeLabs\Sanctum\Definition;

use DecodeLabs\Sanctum\Definition;

class MyCsp extends Definition {}

$csp = Definition::load('MyCsp');
$csp->exportHeaders();

Archetype will look for implementations in the root namespace (DecodeLabs\Sanctum\Definition) by default. If you want to host your implementations in a different namespace, you should create and register a new Archetype resolver to find them.

Licensing

Sanctum is licensed under the MIT License. See LICENSE for the full license text.