headers.js

ABOUT

The headers.js module configures and sets often overlooked or misused security headers such as the content security policy headers (csp)

REQUIREMENTS & ASSUMPTIONS

require('../security.json')
const helmet = require('helmet')
const uuidv4 = require('uuid/v4')
  • _spartan uses the helmet npm module to configure most security header settings
  • _spartan assumes a strict header settings policy meaning, given no other input, the default headers will reflect a same-origin browser policy. If you want to explictly disable all headers, you have to change this by setting securityHeaders.enabled: false and run _spartan --force. This means no headers will be set (because headers.js won’t be written) and you’ll have to set them individually on your own.
    • Alternatively, if there are individual headers you want to disable, you can provide {[headername]: disable} to the security header configuration in your code (see examples below)

      _spartan assumes that any/all listings added to the content security policy (other than self) are also trusted to be on the CORS origin whitelist. An empty csp === an empty CORS whitelist unless you change this directly in the policy and run _spartan --force afterward

THE CONTENT SECURITY POLICY

The Content Security Policy (CSP) Header allows you to provide a list of acceptable content sources through the use of directives. This allows your application to proactively prevent malicious injection of JavaScript, CSS, plugins, and more. This header is woefully under-adopted, mostly because it requires its users to know and list their sources of content which can be a tedious process, especially if multiple teams working on the same platform require different content sources. To make this process a little easier, _spartan provides a mechanism to build your CSP from the very beginning, during the interview process:

# in your terminal
Q6. Content Acquisition : Is all of the data/content generated and processed within your application?
 * Tip : if you plan to use external APIs at any point, choose the second answer. You'll have the opportunity to specify these sources later 
 A.6 Some of the data and content comes from sources that I don't own or control
? Q6.1. Content Sources: Sweet! What are those sources? (JSON)

If you choose the second answer, you should be presented with an editor that looks something like this: csp specification

Take note of the format here ^^^ it should look something like: "directive1" : ["'https://www.source1.com'", "'*.example.org'", "'https://mysite.io:443'"]. See MDN or report-uri.com for more information on all of the available directives and settings

AVAILABLE METHODS

Module Instantiation

method name description params returns
N/A returns a function with headers configured based upon the policy N/A Error if policy module is disabled

USAGE

const headers = security.headers

...

Using Headers

method name description params returns
headers.setHeaders() actually builds the headers {csp: boolean, cdp: boolean, sts: {usePolicy: boolean, hidePower {setTo: String }} optional helmet()* function or helmet(options)** or Error
  • * uses all default headers as defined in helmet
  • ** overloads helmet settings with the settings defined in the options object

The default policy assumes that your CSP will be running in “Report Only” mode. Once you’re satisfied that you have all of your sources and hashes correctly added & configured, change this entry in your policy: securityHeaders.config.csp.reportOnly : false to begin enforcing the policy

USAGE

You can use Headers by route or for every route

// can add headers to all routes like this
app.use(headers.setHeaders({ csp: true, cdp: true, sts: { usePolicy: true }, hidePower: { setTo: 'Daft Punk is Playing At My House' }))
// or use default settings on an individual route like this
app.get('/route', headers(), (request, response, next) => {
  ... // do something
})

ERRORS

  • (‘headers/disabled-in-policy’) => thrown if the security headers policy object is not enabled. To change this, change securityHeaders.enabled : true in security.json then run the _spartan --force command
  • (‘headers/runtime-error’) => this error won’t be thrown until the application actually runs. The most likely cause of this issue is that source included in the CSP is in the wrong format. Make sure that all sources are in the same format as listed above