2017 © Pedro Peláez
 

library csp-builder

Easily add and update Content-Security-Policy headers for your project

image

paragonie/csp-builder

Easily add and update Content-Security-Policy headers for your project

  • Monday, June 18, 2018
  • by paragonie-scott
  • Repository
  • 22 Watchers
  • 410 Stars
  • 66,725 Installations
  • PHP
  • 9 Dependents
  • 2 Suggesters
  • 26 Forks
  • 6 Open issues
  • 18 Versions
  • 13 % Grown

The README.md

Content Security Policy Builder

Build Status Psalm Status Latest Stable Version Latest Unstable Version License Downloads, (*1)

Easily integrate Content-Security-Policy headers into your web application, either from a JSON configuration file, or programatically., (*2)

CSP Builder was created by Paragon Initiative Enterprises as part of our effort to encourage better application security practices., (*3)

Check out our other open source projects too., (*4)

There's also a CSP middleware available that uses this library., (*5)

Installing

First, get Composer, then run:, (*6)

composer require paragonie/csp-builder

Build a Content Security Policy header from a JSON configuration file

<?php

use ParagonIE\CSPBuilder\CSPBuilder;

$csp = CSPBuilder::fromFile('/path/to/source.json');
$csp->sendCSPHeader();

You can also load the configuration from a JSON string, like so:, (*7)

<?php

use ParagonIE\CSPBuilder\CSPBuilder;

$configuration = file_get_contents('/path/to/source.json');
if (!is_string($configuration)) {
    throw new Error('Could not read configuration file!');
}
$csp = CSPBuilder::fromData($configuration);
$csp->sendCSPHeader();

Finally, you can just pass an array to the first argument of the constructor:, (*8)

<?php

use ParagonIE\CSPBuilder\CSPBuilder;

$configuration = file_get_contents('/path/to/source.json');
if (!is_string($configuration)) {
    throw new Error('Could not read configuration file!');
}
$decoded = json_decode($configuration, true);
if (!is_array($decoded)) {
  throw new Error('Could not parse configuration!');
}
$csp = new CSPBuilder($decoded);
$csp->sendCSPHeader();

Example

{
    "report-only": false,
    "report-to": "PolicyName",
    "report-uri": "/csp_violation_reporting_endpoint",
    "base-uri": [],
    "default-src": [],    
    "child-src": {
        "allow": [
            "https://www.youtube.com",
            "https://www.youtube-nocookie.com"
        ],
        "self": false
    },
    "connect-src": [],
    "font-src": {
        "self": true
    },
    "form-action": {
        "allow": [
            "https://example.com"
        ],
        "self": true
    },
    "frame-ancestors": [],
    "img-src": {
        "blob": true,
        "self": true,
        "data": true
    },
    "media-src": [],
    "object-src": [],
    "plugin-types": [],
    "script-src": {
        "allow": [
            "https://www.google-analytics.com"
        ],
        "self": true,
        "unsafe-inline": false,
        "unsafe-eval": false
    },
    "style-src": {
        "self": true
    },
    "upgrade-insecure-requests": true
}

Build a Content Security Policy, programmatically

<?php

use ParagonIE\CSPBuilder\CSPBuilder;

$csp = CSPBuilder::fromFile('/path/to/source.json');

// Let's add a nonce for inline JS
$nonce = $csp->nonce('script-src');
$body .= "";

// Let's add a hash to the CSP header for $someScript
$hash = $csp->hash('script-src', $someScript, 'sha256');

// Add a new source domain to the whitelist
$csp->addSource('image', 'https://ytimg.com');

// Set the Report URI
$csp->setReportUri('https://example.com/csp_report.php');

// Let's turn on HTTPS enforcement
$csp->addDirective('upgrade-insecure-requests', true);

$csp->sendCSPHeader();

Note that many of these methods can be chained together:, (*9)

$csp = CSPBuilder::fromFile('/path/to/source.json');
$csp->addSource('image', 'https://ytimg.com')
    ->addSource('frame', 'https://youtube.com')
    ->addDirective('upgrade-insecure-requests', true)
    ->sendCSPHeader();
  • addSource()
  • addDirective()
  • disableOldBrowserSupport()
  • enableOldBrowserSupport()
  • hash()
  • preHash()
  • setDirective()
  • setBlobAllowed()
  • setDataAllowed()
  • setFileSystemAllowed()
  • setMediaStreamAllowed()
  • setReportUri()
  • setSelfAllowed()
  • setAllowUnsafeEval()
  • setAllowUnsafeInline()

Inject a CSP header into a PSR-7 message

Instead of invoking sendCSPHeader(), you can instead inject the headers into your PSR-7 message object by calling it like so:, (*10)

/**
 * $yourMessageHere is an instance of an object that implements 
 * \Psr\Http\Message\MessageInterface
 *
 * Typically, this will be a Response object that implements 
 * \Psr\Http\Message\ResponseInterface
 *
 * @ref https://github.com/guzzle/psr7/blob/master/src/Response.php
 */
$csp->injectCSPHeader($yourMessageHere);

Save a CSP header for configuring Apache/nginx

Instead of calling sendCSPHeader() on every request, you can build the CSP once and save it to a snippet for including in your server configuration:, (*11)

$policy = CSPBuilder::fromFile('/path/to/source.json');
$policy->saveSnippet(
    '/etc/nginx/snippets/my-csp.conf',
    CSPBuilder::FORMAT_NGINX
);

Make sure you reload your webserver afterwards., (*12)

Processing output before save to disk through hook

$policy = CSPBuilder::fromFile('/path/to/source.json');
$policy->saveSnippet(
    '/etc/nginx/snippets/my-csp.conf',
    CSPBuilder::FORMAT_NGINX
    fn ($output) =>  \str_replace('bar','foo',$output)
);

The output will change before save to file, (*13)

Support Contracts

If your company uses this library in their products or services, you may be interested in purchasing a support contract from Paragon Initiative Enterprises., (*14)

The Versions

18/06 2018

dev-master

9999999-dev

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

18/06 2018

v1.x-dev

1.9999999.9999999.9999999-dev

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

20/11 2017

v2.3.0

2.3.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

09/11 2017

v1.4.0

1.4.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

08/11 2017

v2.2.0

2.2.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

24/07 2017

v2.1.0

2.1.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

01/11 2016

v2.0.1

2.0.1.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

security http xss headers csp content-security-policy

01/11 2016

v1.3.3

1.3.3.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

10/04 2016

v2.0.0

2.0.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

17/02 2016

v1.3.1

1.3.1.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

01/02 2016

v1.3.0

1.3.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

30/01 2016

v1.2.4

1.2.4.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

29/01 2016

v1.2.3

1.2.3.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

20/01 2016

v1.2.2

1.2.2.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

13/01 2016

v1.2.1

1.2.1.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

03/01 2016

v1.2.0

1.2.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Requires

 

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

03/01 2016

v1.1.0

1.1.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

The Development Requires

by Paragon Initiative Enterprises

xss csp content-security-policy

17/06 2015

1.0.0

1.0.0.0

Easily add and update Content-Security-Policy headers for your project

  Sources   Download

MIT

by Paragon Initiative Enterprises

xss csp content-security-policy