csp

README

csp

csp is a tiny Go library that makes it easy to craft Content-Security-Policy HTTP headers.

Features

• Tiny - less than 300 LOC and no external dependencies
• Simple - easy to use API

Installation

go get github.com/novrin/csp

Usage

package main

import (
	"net/http"

	"github.com/novrin/csp"
)

func SecureHeader(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Use HeaderKey and Policy + Directives.
		w.Header().Set(csp.HeaderKey, csp.Policy(csp.Directives{
			DefaultSrc:    []string{"self", "example.com"},
			ImgSrc:        []string{"https:"},
			ScriptSrcElem: []string{"self", "https://example.com/static/app.js"},
			// Optionally use keyword source constants.
			StyleSrc: []string{csp.SourceSelf, csp.SourceUnsafeInline},
		}))
		...
		next.ServeHTTP(w, r)
	})
}

Optionally use convenience defaults. For example, Basic is a simple, non-strict CSP policy where sources is restricted to 'self' for the default-src,form-action, and frame-ancestors directives.

func SecureHeader(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Set a basic non-strict CSP.
		w.Header().Set(csp.HeaderKey, csp.Basic())
		...
		next.ServeHTTP(w, r)
	})
}

License

Copyright (c) 2023-present novrin

Licensed under MIT License

Documentation

Index

• Constants
• Variables
• func Basic() string
• func BasicTight() string
• func IsKeywordSource(s string) bool
• func Policy(ds Directives) string
• type Directives

Constants

const (
	WebRTCAllow = "'allow'"
	WebRTCBlock = "'block'"
)

Acceptable webrtc values.

const (
	SourceNone                 = "'none'"
	SourceSelf                 = "'self'"
	SourceUnsafeInline         = "'unsafe-inline'"
	SourceUnsafeEval           = "'unsafe-eval'"
	SourceStrictDynamic        = "'strict-dynamic'"
	SourceUnsafeHashes         = "'unsafe-hashes'"
	SourceReportSample         = "'report-sample'"
	SourceUnsafeAllowRedirects = "'unsafe-allow-redirects'"
	SourceWasmUnsafeEval       = "'wasm-unsafe-eval'"
)

Acceptable keyword-sources used in directive values.

const HeaderKey = "Content-Security-Policy"

HeaderKey is the canonical form of the Content Security Policy header key.

Variables

var CName = map[string]string{
	"BaseURI":        "base-uri",
	"ChildSrc":       "child-src",
	"ConnectSrc":     "connect-src",
	"DefaultSrc":     "default-src",
	"FontSrc":        "font-src",
	"FormAction":     "form-action",
	"FrameAncestors": "frame-ancestors",
	"FrameSrc":       "frame-src",
	"ImgSrc":         "img-src",
	"ManifestSrc":    "manifest-src",
	"MediaSrc":       "media-src",
	"ObjectSrc":      "object-src",
	"ReportTo":       "report-to",
	"Sandbox":        "sandbox",
	"ScriptSrc":      "script-src",
	"ScriptSrcAttr":  "script-src-attr",
	"ScriptSrcElem":  "script-src-elem",
	"StyleSrc":       "style-src",
	"StyleSrcAttr":   "style-src-attr",
	"StyleSrcElem":   "style-src-elem",
	"WebRTC":         "webrtc",
	"WorkerSrc":      "worker-src",
}

CName is a mapping of the csp package's variable names to directive names as outlined in Content Security Policy Level 3.

Functions

func Basic

func Basic() string

Basic returns a simple, non-strict CSP policy where sources is restricted to 'self' for the following directives:

• default-src
• form-action
• frame-ancestors

func BasicTight

func BasicTight() string

BasicTight returns a tightened form of the simple, non-strict CSP policy where sources is restricted to 'none' as a fallback and restricted to 'self' for following directives:

• connect-src
• form-action
• frame-ancestors
• img-src
• script-src
• style-src

func IsKeywordSource

func IsKeywordSource(s string) bool

IsKeywordSource returns true if s is a valid keyword-source as described in Content Security Policy Level 3; they are required to be enclosed in single-quotes.

func Policy

func Policy(ds Directives) string

Policy returns a white space joined string of all directives where each directive ends in a semi-colon.

Types

type Directives

type Directives struct {
	// (base-uri) BaseURI is a document directive that restricts the URLs which
	// can be used in a HTML <base> element.
	BaseURI []string

	// (child-src) ChildSrc is a fetch directive that restricts the sources for
	// child navigables such as <frame> and <iframe> and Worker execution
	// contexts.
	ChildSrc []string

	// (connect-src) ConnectSrc is a fetch directive that restricts the URLs
	// which can be loaded using script interfaces (e.g. fetch(), <a ping>, XHR,
	// EventSource, WebSockets). If not allowed, the browser emulates a 400 Bad
	// Request HTTP status code.
	ConnectSrc []string

	// (default-src) DefaultSrc is a fetch directive that serves as the fallback
	// for other fetch directives.
	DefaultSrc []string

	// (font-src) FontSrc is a fetch directive that restricts the URLs from
	// which font resources may be loaded.
	FontSrc []string

	// (form-action) FormAction is a navigation directive that restricts the
	// URLs which can be used as the target of a form submissions from a given
	// context.
	FormAction []string

	// (frame-ancestors) FrameAncestors is a navigation directive that restricts
	// the URLS which can embed the resource using <frame>, <iframe>, <object>,
	// or <embed>.
	FrameAncestors []string

	// (frame-src) FrameSrc is a fetch directive that restricts the URLs which
	// may be loaded into child navigables.
	FrameSrc []string

	// (img-src) ImgSrc is a fetch directive that restricts the URLs from which
	// image resources may be loaded.
	ImgSrc []string

	// (manifest-src) ManifestSrc is a fetch directive that restricts the URLs
	// from which application manifests may be loaded.
	ManifestSrc []string

	// (media-src) MediaSrc is a fetch directive that restricts the URLs from
	// which video, audio, and associated text track resources may be loaded.
	MediaSrc []string

	// (object-src) ObjectSrc is a fetch directive that restricts the URLs from
	// which plugin content may be loaded.
	ObjectSrc []string

	// (report-to) ReportTo is a reporting directive that defines an endpoint to
	// which violation reports should be sent.
	ReportTo string

	// (sandbox) Sandbox is a navigation directive that specifies an HTML
	// sandbox policy which the user agent will apply to a resource, as if it
	// had been included in an <iframe> with a sandbox property.
	Sandbox string

	// (script-src) ScriptSrc is a fetch directive that restricts the locations
	// from which scripts may be executed and serves as a default fallback for
	// all script-like destinations.
	ScriptSrc []string

	// (script-src-attr) ScriptSrcAttr is a fetch directive that applies to
	// event handlers and, if present, it will override the script-src directive
	// for relevant checks.
	ScriptSrcAttr []string

	// (script-src-elem) ScriptSrcElem is a fetch directive that applies to all
	// script requests and script blocks.
	ScriptSrcElem []string

	// (style-src) StyleSrc is a fetch directive that restricts the locations
	// from which style may be applied to a Document.
	StyleSrc []string

	// (style-src-attr) StyleSrcAttr is a fetch directive that governs the
	// behaviour of style attributes.
	StyleSrcAttr []string

	// (style-src-elem) StyleSrcElem is a fetch directive that governs the
	// behaviour of styles except for styles defined in inline attributes.
	StyleSrcElem []string

	// (webrtc) WebRTC is a directive that restricts whether connections may be
	// established via WebRTC - possible values are "'allow'" or "'block'".
	WebRTC string

	// (worker-src) WorkerSrc is a directive that restricts the URLs which may
	// be loaded as a Worker, SharedWorker, or ServiceWorker.
	WorkerSrc []string
}

Directives represent possible Content Security Policy rules that enable developers to manage particular features of their websites.