or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

content-security-policy.mdcross-origin-policies.mdindex.mdlegacy-security-headers.mdmain-helmet-function.mdtransport-security.md
tile.json

content-security-policy.mddocs/

Content Security Policy

Comprehensive Content Security Policy header management with extensive directive configuration and built-in security defaults.

Capabilities

Content Security Policy Function

Sets the Content-Security-Policy or Content-Security-Policy-Report-Only header to prevent XSS attacks and other code injection vulnerabilities.

/**
 * Sets Content-Security-Policy header with configurable directives
 * @param options - CSP configuration options
 * @returns Express middleware function
 */
function contentSecurityPolicy(
  options?: ContentSecurityPolicyOptions
): MiddlewareFunction;

interface ContentSecurityPolicyOptions {
  /** Whether to use Helmet's default directives (default: true) */
  useDefaults?: boolean;
  /** CSP directives configuration */
  directives?: Record<string, CSPDirectiveValue>;
  /** Use Content-Security-Policy-Report-Only instead of enforcing (default: false) */
  reportOnly?: boolean;
}

type CSPDirectiveValue = 
  | null 
  | Iterable<string> 
  | typeof dangerouslyDisableDefaultSrc;

Usage Examples:

import { contentSecurityPolicy } from "helmet";
// OR
import helmet from "helmet";

// Use default CSP
app.use(contentSecurityPolicy());
// OR  
app.use(helmet.contentSecurityPolicy());

// Custom directives
app.use(contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    styleSrc: ["'self'", "'unsafe-inline'"],
    scriptSrc: ["'self'", "https://cdn.example.com"],
    imgSrc: ["'self'", "data:", "https:"],
    fontSrc: ["'self'", "https://fonts.gstatic.com"]
  }
}));

// Report-only mode for testing
app.use(contentSecurityPolicy({
  reportOnly: true,
  directives: {
    defaultSrc: ["'self'"],
    reportUri: ["/csp-report"]
  }
}));

// Disable defaults and set custom policy
app.use(contentSecurityPolicy({
  useDefaults: false,
  directives: {
    defaultSrc: ["'none'"],
    scriptSrc: ["'self'"],
    styleSrc: ["'self'"]
  }
}));

Get Default Directives

Returns Helmet's default CSP directives for inspection or modification.

/**
 * Returns the default CSP directives used by Helmet
 * @returns Object containing default CSP directives
 */
function getDefaultDirectives(): CSPDirectives;

interface CSPDirectives {
  "default-src": string[];
  "base-uri": string[];
  "font-src": string[];
  "form-action": string[];
  "frame-ancestors": string[];
  "img-src": string[];
  "object-src": string[];
  "script-src": string[];
  "script-src-attr": string[];
  "style-src": string[];
  "upgrade-insecure-requests": string[];
}

Usage Example:

import helmet from "helmet";

// Get and modify default directives
const defaults = helmet.contentSecurityPolicy.getDefaultDirectives();
const customDirectives = {
  ...defaults,
  "script-src": [...defaults["script-src"], "https://cdn.example.com"],
  "style-src": [...defaults["style-src"], "'unsafe-inline'"]
};

app.use(helmet.contentSecurityPolicy({
  directives: customDirectives
}));

Dangerous Default-Src Disabling

Special symbol for completely disabling the default-src directive (use with extreme caution).

/**
 * Symbol used to dangerously disable the default-src directive
 * WARNING: This can make your site vulnerable to XSS attacks
 */
const dangerouslyDisableDefaultSrc: unique symbol;

Usage Example:

import helmet from "helmet";

// Access via the contentSecurityPolicy function property
const { dangerouslyDisableDefaultSrc } = helmet.contentSecurityPolicy;

// Completely disable default-src (dangerous!)
app.use(helmet.contentSecurityPolicy({
  directives: {
    "default-src": dangerouslyDisableDefaultSrc,
    "script-src": ["'self'"],
    "style-src": ["'self'"]
  }
}));

Common CSP Directives

Source Directives

  • default-src: Fallback for other directives
  • script-src: JavaScript sources
  • style-src: CSS sources
  • img-src: Image sources
  • font-src: Font sources
  • connect-src: XMLHttpRequest, WebSocket, EventSource sources
  • media-src: Audio and video sources
  • object-src: <object>, <embed>, <applet> sources
  • child-src: Worker and frame sources (deprecated, use frame-src and worker-src)
  • frame-src: Frame sources
  • worker-src: Worker sources

Document Directives

  • base-uri: Restricts URLs in <base> element
  • sandbox: Enables sandbox restrictions
  • form-action: Restricts form submission URLs

Navigation Directives

  • frame-ancestors: Restricts embedding in frames (similar to X-Frame-Options)
  • navigate-to: Restricts document navigation URLs

Reporting Directives

  • report-uri: URL to send violation reports (deprecated, use report-to)
  • report-to: Named group for violation reports

Other Directives

  • upgrade-insecure-requests: Upgrade HTTP to HTTPS
  • block-all-mixed-content: Block mixed content
  • require-sri-for: Require Subresource Integrity

Common Source Values

  • 'self': Same origin
  • 'unsafe-inline': Inline scripts/styles (avoid if possible)
  • 'unsafe-eval': eval() and similar (avoid if possible)
  • 'none': No sources allowed
  • 'strict-dynamic': Allow scripts loaded by trusted scripts
  • 'nonce-<value>': Scripts with matching nonce attribute
  • 'sha256-<value>': Scripts matching hash
  • data:: Data URLs
  • https:: Any HTTPS URL
  • blob:: Blob URLs
  • filesystem:: Filesystem URLs

Default CSP Policy

Helmet's default CSP includes these directives:

default-src 'self';
base-uri 'self';
font-src 'self' https: data:;
form-action 'self';
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;

This provides a secure baseline that works with most applications while preventing common XSS attacks.