Security

Helmet Security Headers

Set Content-Security-Policy, HSTS, X-Frame-Options, Referrer-Policy and more on every response with helmet() from @axiljs/security. All defaults and options.

4 min readUpdated DocumentationEdit this page
On this page10

helmet() sets a group of HTTP response headers that tell browsers to turn on their built-in protections against cross-site scripting, clickjacking, MIME sniffing, protocol downgrade and referrer leaks. It has no dependencies and every header can be changed or turned off.

❯npm install @axiljs/security
❯pnpm add @axiljs/security
❯yarn add @axiljs/security
❯bun add @axiljs/security
TypeScript
TS
1import { Application } from '@axiljs/core'
2import { helmet } from '@axiljs/security'
3
4const app = new Application()
5app.use(helmet())

Register it as global middleware, before your routes, so every response gets the headers.

Default headers

With no options, helmet() sets:

HeaderDefault valueProtects against
Content-Security-PolicySee "Default Content-Security-Policy" belowXSS and injected resources
X-Frame-OptionsDENYClickjacking (framing your pages)
Strict-Transport-Securitymax-age=15552000; includeSubDomainsHTTPS downgrade (180 days)
X-Content-Type-OptionsnosniffMIME-type sniffing
X-XSS-Protection1; mode=blockReflected XSS in legacy browsers
Referrer-Policyno-referrerLeaking URLs to other sites
Permissions-Policycamera=(), microphone=(), geolocation=(), payment=()Pages or embeds using those browser APIs

It also removes any X-Powered-By header already on the response, so the server stack is not advertised.

Default Content-Security-Policy

Output
TXT
default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self';
frame-ancestors 'self'; img-src 'self' data: https:; object-src 'none'; script-src 'self';
script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; upgrade-insecure-requests

(Sent as a single line.) Scripts load only from your own origin, inline event handlers are blocked, plugins are disabled, and http: sub-resources are upgraded to https:.

Options

OptionTypeDefaultDescription
contentSecurityPolicyboolean | stringtruetrue sends the default policy, a string replaces it, false omits the header
frameOptions'DENY' | 'SAMEORIGIN' | false'DENY'X-Frame-Options value, or false to omit it
hstsboolean | { maxAge?: number; includeSubDomains?: boolean }truefalse omits it. The object form defaults to maxAge: 15552000 and includeSubDomains: true
noSniffbooleantrueSend X-Content-Type-Options: nosniff
xssFilterbooleantrueSend X-XSS-Protection: 1; mode=block
referrerPolicystring | false'no-referrer'Referrer-Policy value, or false to omit it
permissionsPolicybooleantrueSend the fixed Permissions-Policy value above. Its value cannot be customised
hidePoweredBybooleantrueRemove X-Powered-By

Common configurations

A JSON API

An API that only returns JSON can use the strictest policy:

TypeScript
TS
1app.use(helmet({
2  contentSecurityPolicy: "default-src 'none'; frame-ancestors 'none'",
3  referrerPolicy: 'no-referrer'
4}))

Pages that load third-party scripts

Pass the full policy as a string. It replaces the default entirely, so restate every directive you need:

TypeScript
TS
1app.use(helmet({
2  contentSecurityPolicy: [
3    "default-src 'self'",
4    "script-src 'self' https://cdn.jsdelivr.net",
5    "img-src 'self' data: https:",
6    "style-src 'self' 'unsafe-inline'",
7    "connect-src 'self' https://api.example.com",
8    "frame-ancestors 'none'"
9  ].join('; ')
10}))

Allow framing by your own site

TypeScript
TS
app.use(helmet({ frameOptions: 'SAMEORIGIN' }))

The default CSP already contains frame-ancestors 'self', which modern browsers use instead of X-Frame-Options when both are present.

Longer HSTS for preload

TypeScript
TS
app.use(helmet({ hsts: { maxAge: 63072000, includeSubDomains: true } }))   // 2 years

There is no preload option. Browsers ignore Strict-Transport-Security on plain http: responses, so it does no harm in local development.

Turning headers off

TypeScript
TS
1app.use(helmet({
2  contentSecurityPolicy: false,   // set by your CDN or reverse proxy instead
3  xssFilter: false,
4  permissionsPolicy: false
5}))

Note

helmet() sets headers before your handler runs. A handler that sets the same header afterwards with res.header() overrides it for that response, which is the way to loosen a policy on a single route. hidePoweredBy only removes an X-Powered-By header that exists when the middleware runs.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY