frankieshakes / csp-generator

Manage and create Content Security Policies more easily.

Content Security Policies Generator

Managing and creating Content Security Policies can be a challenge. The Content Security Policy header format does not lend itself to managing lots of domains across multiple directives. Especially if you need to allow Google Analytics.

This Rust library allows you to generate a CSP header string from well organised JSON strings. The JSON structure this library accepts allows you to more easily manage many domains and many directives for your website CSP policies.

If you need to learn more about Content Security Policies we suggest you read the following resources:

• Content Security Policies Website
• MDN Content Security Policies Documentation
• RFC 7762

Installation

To install csp_generator in your Rust project simply add it as a dependency within your Cargo manifest.

Example Cargo.toml

[dependencies]
csp_generator = "0.2.0-beta.3"

Usage

This library exposes three methods:

• csp_generator::enforce()
• csp_generator::report_only()
• csp_generator::csp_only()

The enforce() and report_only() methods will return a struct which contains a header string and a csp string. This will make sure you have the correct CSP header and CSP directive string dependent on whether you wish to use enforcement or report only modes.

If you only wish to return the CSP directive string call the csp_only() method.

Each of the methods accepts two arguments a list of CSP directives you wish to use, plus the JSON config. You can use the built in CSP directives list configuration if you wish as it contains all the standard CSP directives, see csp_generator::config. However, as this functionality complies with an interface, it can be overridden.

Example Code

use csp_generator::{directives, Csp};

fn main() {
    let json = r#"
    [
        {"domain": "example.com", "directives": ["connect-src"]},
        {"domain": "test.com", "directives": ["connect-src", "script-src"]}
    ]
    "#;

    let csp: Csp = csp_generator::enforce(directives::directives(), json);

    println!("This is the CSP Header: {}", csp.header);
    // This is the CSP Header: Content-Security-Policy
    println!("This is the CSP Directives String: {}", csp.csp);
    // This is the CSP Directives String: script-src test.com; connect-src example.com test.com;
}

JSON Configuration

This library relies on a specific JSON format. This is an array of objects which contain two properties. The domain which is a string and the directive which is an array of directive strings.

Format

[
    {"domain": string, "directive": array<string>}
]

Example Config In this example we associate example.com with the connect-src directive and the test.com domain with the connect-src and script-src directives.

[
    {"domain": "example.com", "directive": ["connect-src"]},
    {"domain": "test.com", "directive": ["connect-src", "script-src"]}
]

CSP Directives List

Along with supplying a list of domains and directives in JSON format, we also need to supply the csp_generator with a list of directives which we want to use in our CSP.

You can use the built CSP directives list config, as it contains a list of all the standard CSP directives. But if you wish to override this you can.

You just need to comply with the csp_generator::directives::GetDirectives trait (interface).

Example Override This override will generate a CSP directive string which only makes use of the script-src and connect-src.

use csp_generator::directives::GetDirectives;
use csp_generator::Csp;

pub struct MyDirectives {
    list: Vec<String>,
}

impl GetDirectives for MyDirectives {
    fn get_directives(&self) -> Vec<String> {
        self.list.clone()
    }
}

// Construct MyDirectives Struct with the directives you wish to use.
fn my_directives() -> MyDirectives {
    MyDirectives {
        list: vec![
            String::from("script-src"),
            String::from("connect-src"),
        ],
    }
}

pub fn main() {
    let json = r#"
    [
        {"domain": "example.com", "directives": ["connect-src"]},
        {"domain": "test.com", "directives": ["connect-src", "img-src"]}
    ]
    "#;

    let csp: Csp = csp_generator::report_only(my_directives(), json);

    println!("This is the CSP Header: {}", csp.header);
    // This is the CSP Header: Content-Security-Policy-Report-Only
    println!("This is the CSP Directives String: {}", csp.csp);
    // This is the CSP Directives String: connect-src example.com test.com;
}

License

MIT

Author

@RobDWaller