csp

README

go-csp-engine

Content Security Policy engine for Go/Golang. Unit test your CSP rules!

This allows you to check HTML and CSS for preflight CSP violations.

Features:

• Checks script, img, audio, video, track, iframe, object, embed, applet, style, base tags.
• Checks link tags for stylesheet, prefetch, prerender, icon, and manifest types.
• Checks unsafe inline style and script tags for nonce & hash.
• Check stylesheet @import and @font-face external URLs.

Known limitations:

• Doesn't fetch imported/referenced URLs to check for post flight violations. Thus, it doesn't check that the imported external resources have valid hashes.
• Doesn't check stylesheet declarations that access resources like background-image.
• Doesn't check any network requests made by javascript.

Example

package main

import (
	"net/url"
	"strings"
  "log"

	csp "github.com/d4l3k/go-csp-engine"
)

func main() {
  policy, err := csp.ParsePolicy("default-src: 'self'; script-src: 'nonce-foo'; img-src https://cdn")
  if err != nil {
    log.Fatal(err)
  }
  page, err := url.Parse('http://example.com/bar/')
  if err != nil {
    log.Fatal(err)
  }
  valid, reports, err := csp.ValidatePage(policy, *page, strings.NewReader(`
    <link rel="stylesheet" href="./foo.css">
    <script nonce="foo">alert('boo yeah!')</script>
    <img src="https://cdn/blah">
  `))
  if err != nil {
    log.Fatal(err)
  }
  log.Println(valid, reports)
}

License

go-csp-engine is licensed under the MIT license. See LICENSE file for more information.

Documentation

Index

• func GetCSPFromWeb(webaddress string) (string, string)
• type AllowDirective
  • func (AllowDirective) Check(Policy, SourceContext) (bool, error)
• type Directive
• type HashSource
  • func (s HashSource) Check(ctx SourceContext) (bool, error)
• type Policy
  • func ParsePolicy(policy string) (Policy, error)
  • func (p Policy) Directive(name string) Directive
• type Report
  • func ValidatePage(p Policy, page url.URL, html io.Reader) (bool, []Report, error)
  • func ValidateStylesheet(p Policy, page url.URL, css string) (bool, []Report, error)
• type SourceContext
  • func (s SourceContext) Report(name string, directive Directive) Report
• type SourceDirective
  • func ParseSourceDirective(sources []string) (SourceDirective, error)
  • func (s SourceDirective) Check(p Policy, ctx SourceContext) (bool, error)
  • func (s *SourceDirective) ParseSource(source string) error
  • func (s *SourceDirective) Validate() error

Functions

func GetCSPFromWeb

func GetCSPFromWeb(webaddress string) (string, string)

retrieves the current CSP setting from a web page

Types

type AllowDirective

type AllowDirective struct{}

AllowDirective always allows access to the context.

func (AllowDirective) Check

func (AllowDirective) Check(Policy, SourceContext) (bool, error)

Check implements Directive.

type Directive

type Directive interface {
	// Check the context and return whether or not it's allowed.
	Check(Policy, SourceContext) (bool, error)
}

Directive is a rule for a CSP directive.

type HashSource

type HashSource struct {
	Algorithm func() hash.Hash
	Value     string
}

HashSource is a SourceDirective rule that matches the hash of content.

func (HashSource) Check

func (s HashSource) Check(ctx SourceContext) (bool, error)

Check if the ctx hash matches this hash.

type Policy

type Policy struct {
	Directives              map[string]Directive
	UpgradeInsecureRequests bool
	BlockAllMixedContent    bool
}

Policy represents the entire CSP policy and its directives.

func ParsePolicy

func ParsePolicy(policy string) (Policy, error)

ParsePolicy parses all the directives in a CSP policy.

func (Policy) Directive

func (p Policy) Directive(name string) Directive

Directive returns the first directive that exists in the order: directive with the provided name, default-src, and finally 'none' directive.

type Report

type Report struct {
	Document      string
	Blocked       string
	DirectiveName string
	Directive     Directive
	Context       SourceContext
}

Report contains information about a CSP violation.

func ValidatePage

func ValidatePage(p Policy, page url.URL, html io.Reader) (bool, []Report, error)

ValidatePage checks that an HTML page passes the specified CSP policy.

func ValidateStylesheet

func ValidateStylesheet(p Policy, page url.URL, css string) (bool, []Report, error)

ValidateStylesheet validates a stylesheet for CSP violations from imports and font-face sources.

type SourceContext

type SourceContext struct {
	URL          url.URL
	Page         url.URL
	UnsafeInline bool
	UnsafeEval   bool
	Nonce        string
	Body         []byte
}

SourceContext is the context required by a CSP policy.

func (SourceContext) Report

func (s SourceContext) Report(name string, directive Directive) Report

Report returns a report with the specified parameters.

type SourceDirective

type SourceDirective struct {
	None         bool
	Nonces       map[string]bool
	Hashes       []HashSource
	UnsafeEval   bool
	UnsafeInline bool
	Self         bool
	Schemes      map[string]bool
	Hosts        []glob.Glob
	SrcHosts     []string
	// contains filtered or unexported fields
}

SourceDirective is used to enforce a CSP source policy on a URL.

func ParseSourceDirective

func ParseSourceDirective(sources []string) (SourceDirective, error)

ParseSourceDirective parses a source directive arguments.

func (SourceDirective) Check

func (s SourceDirective) Check(p Policy, ctx SourceContext) (bool, error)

Check that the SourceContext is allowed for this SourceDirective.

func (*SourceDirective) ParseSource

func (s *SourceDirective) ParseSource(source string) error

ParseSource parses a source and adds it to the SourceDirective.

func (*SourceDirective) Validate

func (s *SourceDirective) Validate() error

Validate checks the source policy to make sure it's valid.