fi-aegis

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({
  csrf: true,
  csp: {
    angular: true
  },
  xframe: 'SAMEORIGIN',
  p3p: 'ABCDEF', /*[DEPRECATED]*/
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  },
  xssProtection: true,
  nosniff: 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:

Param	Type	Required	Default	Description
key	String	No	_csrf	The name of the CSRF token added to the model.
secret	String	No	_csrfSecret	The key to place on the session object which maps to the server side token.
impl	Function	No	See lib/token.js.	Custom implementation to generate a token.
angular	Boolean	No	false	Shorthand setting to set Fi Aegis up to use the default settings for CSRF validation according to the AngularJS docs.
cookie	String or Object	Yes (if angular is false)	None	If set, a cookie with the name you provide will be set with the CSRF token.
cookie.name	String	Yes (if angular is false and cookie is Object)	None	The name you provide will be set as the cookie with the CSRF token.
cookie.options	Object	No	None	A valid Express cookie options object. See Express response cookies for more information.
header	String	Yes (if angular is false)	None	If set, the header name you provide will be set with the CSRF token.

---

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:

Param	Type	Required	Default	Description
policy	String, Object or Array	Yes	Empty	Object definition of policy. Valid policies examples include.
reportOnly	Boolean	No	false	Enable report only mode.
reportUri	String	No	Empty	URI where to send the report data

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:

Param	Type	Required	Default	Description
value	String	Yes	None	The value for the header, e.g. DENY, SAMEORIGIN or ALLOW-FROM uri.

---

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:

Param	Type	Required	Default	Description
maxAge	Number	Yes	None	Number of seconds HSTS is in effect.
includeSubDomains	Boolean	No	None	Applies HSTS to all subdomains of the host.
preload	Boolean	No	None	Adds preload flag. This is not part of the specification. See this for more details about why.

---

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:

Param	Type	Required	Default	Description
enabled	Boolean	No	1	If the header is enabled or not.
mode	String	No	block	Mode to set on the header.

---

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:

Param	Type	Required	Default	Description
value	String	Yes	None	The compact privacy policy.

Changelog

v1.0.1

• Updated documentation, license and package information (d8c031eb37edcb3cbffd0cd1be2267affddd9391).