fi-aegis v2.0.1

Fi Aegis

Web Application Security Middleware

This fork is based on lusca v1.4.1 but has changed greatly since.

The most relevant changes are minor optimizations, code refactoring and improved documentation with the addition of some functionality.

Installation

Fi Aegis is available only as an NPM package.

Install using:

npm install fi-aegis

Remember to add the --save modifier if you're using an NPM version lower than 5.x.x.

Usage

const session = require('express-session');
const express = require('express');
const aegis = require('fi-aegis');

const app = express();

/* This or other session management will be required */
app.use(session({
  secret: 'abc',
  resave: true,
  saveUninitialized: true
}));

app.use(aegis({
  xframe: 'SAMEORIGIN',
  xssProtection: true,
  nosniff: true,
  csrf: {
    angular: true
  },
  csp: ,
  hsts: {
    includeSubDomains: true,
    maxAge: 31536000,
    preload: true
  }
}));

Setting any value to false will disable it. Alternately, you can opt into methods one by one:

app.use(aegis.csrf());
app.use(aegis.csp({ angular: true }));
app.use(aegis.xframe('SAMEORIGIN'));
app.use(aegis.p3p('ABCDEF')); /*[DEPRECATED]*/
app.use(aegis.hsts({ maxAge: 31536000 }));
app.use(aegis.xssProtection(true));
app.use(aegis.nosniff());

Please note that you must use express-session, cookie-session, their express 3.x alternatives, or other session object management in order to use Fi Aegis.

API

Cross-Site Request Forgery

Enables Cross Site Request Forgery (CSRF) headers.

If enabled, the CSRF token must be in the payload when modifying data or you will receive a 403 Forbidden. To send the token you'll need to echo back the _csrf value you received from the previous request.

Furthermore, parsers must be registered before Fi Aegis.

Usage:

aegis.csrf(options);

Options:

Content Security Policy

Enables Content Security Policy (CSP) headers.

See the MDN CSP usage page for more information on available policy options.

See the AngularJS ngCsp directive docs to learn the how to implement it when using CSP on your server.

Usage:

aegis.csp(options);

Options:

Example Options:

Everything but images can only come from own domain (excluding subdomains):

{
  policy: {
    'default-src': '\'self\'',
    'img-src': '*'
  }
}

Pre-existing site that uses too much inline code to fix but wants to ensure resources are loaded only over https and disable plugins:

{
  policy: 'default-src https: \'unsafe-inline\'; object-src \'none\''
}

Load images only through HTTPS and from self domain and upgrade all insecure requests:

{
  policy: [
    {
      'img-src': '\'self\' https:'
    },

    'upgrade-insecure-requests'
  ]
}

See MDN CSP Headers for more examples and directives.

X-Frame-Options

Enables X-FRAME-OPTIONS headers to help prevent Clickjacking.

See MDN X-Frame-Options docs to learn more about it.

Usage:

aegis.xframe(value);

Value:

HTTP Strict Transport Security

Enables HTTP Strict Transport Security for the host domain. The preload flag is required for HSTS domain submissions to Chrome's HSTS preload list.

See MDN Strict-Transport-Security for more information.

Usage:

aegis.hsts(options);

Options:

X-Content-Type-Options

Enables X-Content-Type-Options header to prevent MIME-sniffing a response away from the declared content-type.

Usage:

aegis.nosniff();

X-XSS-Protection

Enables X-XSS-Protection headers to help prevent cross site scripting (XSS) attacks in older IE browsers (IE8).

Usage:

aegis.xssProtection(options);

Options:

Platform for Privacy Preferences (P3P) Project

Enables Platform for Privacy Preferences (P3P) Project headers.

The development of P3P has been suspended. This is still available in order to maintain compatibility. See Platform for Privacy Preferences (P3P) Project on W3C for more information.

Usage:

aegis.p3p(value);

Value: