Helmet helps you secure your Express apps by setting various HTTP headers. It's not a silver bullet, but it can help!
First, run npm install helmet --save
for your app. Then, in an Express app:
const express = require("express");
const helmet = require("helmet");
const app = express();
app.use(helmet());
// ...
Helmet is Connect-style middleware, which is compatible with frameworks like Express. (If you need support for Koa, see koa-helmet
.)
The top-level helmet
function is a wrapper around 11 smaller middlewares.
In other words, these two things are equivalent:
// This...
app.use(helmet());
// ...is equivalent to this:
app.use(helmet.contentSecurityPolicy());
app.use(helmet.dnsPrefetchControl());
app.use(helmet.expectCt());
app.use(helmet.frameguard());
app.use(helmet.hidePoweredBy());
app.use(helmet.hsts());
app.use(helmet.ieNoOpen());
app.use(helmet.noSniff());
app.use(helmet.permittedCrossDomainPolicies());
app.use(helmet.referrerPolicy());
app.use(helmet.xssFilter());
To set custom options for one of the middleware, add options like this:
// This sets custom options for the `referrerPolicy` middleware.
app.use(
helmet({
referrerPolicy: { policy: "no-referrer" },
})
);
You can also disable a middleware:
// This disables the `contentSecurityPolicy` middleware but keeps the rest.
app.use(
helmet({
contentSecurityPolicy: false,
})
);
helmet(options)
Helmet is the top-level middleware for this module, including all 11 others.
All 11 middlewares are enabled by default.
// Includes all 11 middlewares
app.use(helmet());
If you want to disable one, pass options to helmet
. For example, to disable frameguard
:
// Includes 10 middlewares, skipping `helmet.frameguard`
app.use(
helmet({
frameguard: false,
})
);
Most of the middlewares have options, which are documented in more detail below. For example, to pass { action: "deny" }
to frameguard
:
// Includes all 11 middlewares, setting an option for `helmet.frameguard`
app.use(
helmet({
frameguard: {
action: "deny",
},
})
);
Each middleware's name is listed below.
helmet.contentSecurityPolicy(options)
helmet.contentSecurityPolicy
sets the Content-Security-Policy
header which helps mitigate cross-site scripting attacks, among other things. See MDN's introductory article on Content Security Policy.
This middleware performs very little validation. You should rely on CSP checkers like CSP Evaluator instead.
options.directives
is an object. Each key is a directive name in camel case (such as defaultSrc
) or kebab case (such as default-src
). Each value is an iterable (usually an array) of strings or functions for that directive. If a function appears in the iterable, it will be called with the request and response. The default-src
can be explicitly disabled by setting its value to helmet.contentSecurityPolicy.dangerouslyDisableDefaultSrc
.
options.reportOnly
is a boolean, defaulting to false
. If true
, the Content-Security-Policy-Report-Only
header will be set instead.
If no directives are supplied, the following policy is set (whitespace added for readability):
default-src 'self';
base-uri 'self';
block-all-mixed-content;
font-src 'self' https: data:;
frame-ancestors 'self';
img-src 'self' data:;
object-src 'none';
script-src 'self';
script-src-attr 'none';
style-src 'self' https: 'unsafe-inline';
upgrade-insecure-requests
You can fetch this default with helmet.contentSecurityPolicy.getDefaultDirectives()
.
Examples:
// Sets "Content-Security-Policy: default-src 'self';script-src 'self' example.com;object-src 'none';upgrade-insecure-requests"
app.use(
helmet.contentSecurityPolicy({
directives: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", "example.com"],
objectSrc: ["'none'"],
upgradeInsecureRequests: [],
},
})
);
// Sets "Content-Security-Policy: default-src 'self';script-src 'self' example.com;object-src 'none'"
app.use(
helmet.contentSecurityPolicy({
directives: {
"default-src": ["'self'"],
"script-src": ["'self'", "example.com"],
"object-src": ["'none'"],
},
})
);
// Sets all of the defaults, but overrides script-src
app.use(
helmet.contentSecurityPolicy({
directives: {
...helmet.contentSecurityPolicy.getDefaultDirectives(),
"script-src": ["'self'", "example.com"],
},
})
);
// Sets the "Content-Security-Policy-Report-Only" header instead
app.use(
helmet.contentSecurityPolicy({
directives: {
/* ... */
},
reportOnly: true,
})
);
// Sets "Content-Security-Policy: default-src 'self';script-src 'self' 'nonce-e33ccde670f149c1789b1e1e113b0916'"
app.use((req, res, next) => {
res.locals.cspNonce = crypto.randomBytes(16).toString("hex");
next();
});
app.use(
helmet.contentSecurityPolicy({
directives: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", (req, res) => `'nonce-${res.locals.cspNonce}'`],
},
})
);
// Sets "Content-Security-Policy: script-src 'self'"
app.use(
helmet.contentSecurityPolicy({
directives: {
"default-src": helmet.contentSecurityPolicy.dangerouslyDisableDefaultSrc,
"script-src": ["'self'"],
},
})
);
You can install this module separately as helmet-csp
.
helmet.expectCt(options)
helmet.expectCt
sets the Expect-CT
header which helps mitigate misissued SSL certificates. See MDN's article on Certificate Transparency and the Expect-CT
header for more.
options.maxAge
is the number of seconds to expect Certificate Transparency. It defaults to 0
.
options.enforce
is a boolean. If true
, the user agent (usually a browser) should refuse future connections that violate its Certificate Transparency policy. Defaults to false
.
options.reportUri
is a string. If set, complying user agents will report Certificate Transparency failures to this URL. Unset by default.
Examples:
// Sets "Expect-CT: max-age=86400"
app.use(
helmet.expectCt({
maxAge: 86400,
})
);
// Sets "Expect-CT: max-age=86400, enforce, report-uri="https://example.com/report"
app.use(
helmet.expectCt({
maxAge: 86400,
enforce: true,
reportUri: "https://example.com/report",
})
);
You can install this module separately as expect-ct
.
helmet.referrerPolicy(options)
helmet.referrerPolicy
sets the Referrer-Policy
header which controls what information is set in the Referer
header. See "Referer header: privacy and security concerns" and the header's documentation on MDN for more.
options.policy
is a string or array of strings representing the policy. If passed as an array, it will be joined with commas, which is useful when setting a fallback policy. It defaults to no-referrer
.
Examples:
// Sets "Referrer-Policy: no-referrer"
app.use(
helmet.referrerPolicy({
policy: "no-referrer",
})
);
// Sets "Referrer-Policy: origin,unsafe-url"
app.use(
helmet.referrerPolicy({
policy: ["origin", "unsafe-url"],
})
);
You can install this module separately as referrer-policy
.
helmet.hsts(options)
helmet.hsts
sets the Strict-Transport-Security
header which tells browsers to prefer HTTPS over insecure HTTP. See the documentation on MDN for more.
options.maxAge
is the number of seconds browsers should remember to prefer HTTPS. If passed a non-integer, the value is rounded down. It defaults to 15552000
, which is 180 days.
options.includeSubDomains
is a boolean which dictates whether to include the includeSubDomains
directive, which makes this policy extend to subdomains. It defaults to true
.
options.preload
is a boolean. If true, it adds the preload
directive, expressing intent to add your HSTS policy to browsers. See the "Preloading Strict Transport Security" section on MDN for more. It defaults to false
.
Examples:
// Sets "Strict-Transport-Security: max-age=123456; includeSubDomains"
app.use(
helmet.hsts({
maxAge: 123456,
})
);
// Sets "Strict-Transport-Security: max-age=123456"
app.use(
helmet.hsts({
maxAge: 123456,
includeSubDomains: false,
})
);
// Sets "Strict-Transport-Security: max-age=123456; includeSubDomains; preload"
app.use(
helmet.hsts({
maxAge: 63072000,
preload: true,
})
);
You can install this module separately as hsts
.
helmet.noSniff()
helmet.noSniff
sets the X-Content-Type-Options
header to nosniff
. This mitigates MIME type sniffing which can cause security vulnerabilities. See documentation for this header on MDN for more.
This middleware takes no options.
Example:
// Sets "X-Content-Type-Options: nosniff"
app.use(helmet.noSniff());
You can install this module separately as dont-sniff-mimetype
.
helmet.dnsPrefetchControl(options)
helmet.dnsPrefetchControl
sets the X-DNS-Prefetch-Control
header to help control DNS prefetching, which can improve user privacy at the expense of performance. See documentation on MDN for more.
options.allow
is a boolean dictating whether to enable DNS prefetching. It defaults to false
.
Examples:
// Sets "X-DNS-Prefetch-Control: off"
app.use(
helmet.dnsPrefetchControl({
allow: false,
})
);
// Sets "X-DNS-Prefetch-Control: on"
app.use(
helmet.dnsPrefetchControl({
allow: true,
})
);
You can install this module separately as dns-prefetch-control
.
helmet.ieNoOpen()
helmet.ieNoOpen
sets the X-Download-Options
header, which is specific to Internet Explorer 8. It forces potentially-unsafe downloads to be saved, mitigating execution of HTML in your site's context. For more, see this old post on MSDN.
This middleware takes no options.
Examples:
// Sets "X-Download-Options: noopen"
app.use(helmet.ieNoOpen());
You can install this module separately as ienoopen
.
helmet.frameguard(options)
helmet.frameguard
sets the X-Frame-Options
header to help you mitigate clickjacking attacks. This header is superseded by the frame-ancestors
Content Security Policy directive but is still useful on old browsers. For more, see the documentation on MDN.
options.action
is a string that specifies which directive to use—either DENY
or SAMEORIGIN
. (A legacy directive, ALLOW-FROM
, is not supported by this middleware. Read more here.) It defaults to SAMEORIGIN
.
Examples:
// Sets "X-Frame-Options: DENY"
app.use(
helmet.frameguard({
action: "deny",
})
);
// Sets "X-Frame-Options: SAMEORIGIN"
app.use(
helmet.frameguard({
action: "sameorigin",
})
);
You can install this module separately as frameguard
.
helmet.permittedCrossDomainPolicies(options)
helmet.permittedCrossDomainPolicies
sets the X-Permitted-Cross-Domain-Policies
header, which tells some clients (mostly Adobe products) your domain's policy for loading cross-domain content. See the description on OWASP for more.
options.permittedPolicies
is a string that must be "none"
, "master-only"
, "by-content-type"
, or "all"
. It defaults to "none"
.
Examples:
// Sets "X-Permitted-Cross-Domain-Policies: none"
app.use(
helmet.permittedCrossDomainPolicies({
permittedPolicies: "none",
})
);
// Sets "X-Permitted-Cross-Domain-Policies: by-content-type"
app.use(
helmet.permittedCrossDomainPolicies({
permittedPolicies: "by-content-type",
})
);
You can install this module separately as helmet-crossdomain
.
helmet.hidePoweredBy()
helmet.hidePoweredBy
removes the X-Powered-By
header, which is set by default in some frameworks (like Express). Removing the header offers very limited security benefits (see this discussion) and is mostly removed to save bandwidth.
This middleware takes no options.
If you're using Express, this middleware will work, but you should use app.disable("x-powered-by")
instead.
Examples:
// Removes the X-Powered-By header if it was set.
app.use(helmet.hidePoweredBy());
You can install this module separately as hide-powered-by
.
helmet.xssFilter()
helmet.xssFilter
disables browsers' buggy cross-site scripting filter by setting the X-XSS-Protection
header to 0
. See discussion about disabling the header here and documentation on MDN.
This middleware takes no options.
Examples:
// Sets "X-XSS-Protection: 0"
app.use(helmet.xssFilter());
You can install this module separately as x-xss-protection
.