Documentation
¶
Overview ¶
Package scriptsrc provides auto-generation of script-src policy directives of Content Security Policies (CSP) by parsing **trusted** HTML files.
For example, suppose you have the following HTML files inside of /web/root:
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<script>
// Some content to hash.
</script>
</head>
<body>
<button onclick="alert('Hello')">Hello</button>
<script>
// Some more content to hash.
</script>
</body>
</html>
<!-- just-self.html -->
<!DOCTYPE html>
<html>
<head>
<script src="foo.js"></script>
</head>
<body>
I just need scripts from 'self'
</body>
</html>
The script-src required to successfully run these, is:
'self' 'sha512-nbfZ9uoH92o+408nb2dlJhQJZLFdbJjY4ntbG7YAE23fMsuuEg261l9jm2HCns29WgvqGsjhO6F5bLDlIdSSMw==' 'sha512-Vj66Rmbqm1b9qQrkUNDR0OzPiTjQZ9Ayf25jSMRKvOgNlqnzNa8cn35DOErR7+AyOIxMT/ZYNJic15+Rj6lbkg==' 'sha512-X+aeR+9dEmqY9SqucXOUgHMKCI8yYCIBSgAOUxQ41fJBfPlM2nLA24g8XIxq1XJNuU+7YcvnrSkKoL5u4QVj3w==' https://challenges.cloudflare.com
This can be generated in a couple of ways.
CLI Usage ¶
go install github.com/JOT85/script-src-generator@latest script-src-generator /web/root/**.html > 'self' 'sha512-...' ... https://challenges.cloudflare.com
You can also specify a custom template (--csp-template-file can also be used to parse a template file):
script-src-generator --quiet --csp-template-string "Content-Security-Policy: script-src {{ .ScriptSrc }};" /web/root/**.html
> Content-Security-Policy: script-src 'self' 'sha512-...' ... https://challenges.cloudflare.com;
See script-src-generator --help for more details, including templating support.
If go/bin isn't in your path, the command will instead be ~/go/bin/script-src-generator.
Library Usage ¶
import "github.com/JOT85/script-src-generator/scriptsrc"
func generateScriptSrc() (string, error) {
scriptSrc, err := scriptsrc.ScriptSrcFromHTMLFileGlob("/web/root/**.html", true)
if err != nil {
return "", err
}
return scriptSrc.String()
}
Think about security ¶
This library must only be used to process trusted HTML. The point of the CSP script-src directive is to ensure that any JavaScript that gets injected cannot be run. Therefore, if you run this *after* code could be injected, you're negating the point of adding the security headers! The input to this must be trusted HTML code, i.e. your own static HTML files, and certainly not the output of a template that could accept user input!
Index ¶
- type HashAlgorithm
- type ScriptSrc
- func (scriptSrc *ScriptSrc) AddFromHTML(n *html.Node, includeEventHandlers bool) error
- func (scriptSrc *ScriptSrc) AddFromHTMLFile(path string, includeEventHandlers bool) error
- func (scriptSrc *ScriptSrc) AddInline(content string)
- func (scriptSrc *ScriptSrc) AddSrc(srcString string) error
- func (scriptSrc *ScriptSrc) String() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HashAlgorithm ¶ added in v0.2.0
type HashAlgorithm uint8
const ( Sha512 HashAlgorithm = 0 Sha256 HashAlgorithm = 1 )
type ScriptSrc ¶
type ScriptSrc struct {
// Self indicates if 'self' should be included.
Self bool
// Hashes are sha256, sha384 or sha512 hashes of scripts that are allowed to be inline (inside script tags or event handlers).
//
// The entries in this array should be of the form <hash-algorithm>-<base64-hash>.
//
// Surrounding quotes will be added when formatted.
Hashes []string
// DefaultHashAlgorithm specified which hashing algorithm is used for generating hashes of inline scripts.
//
// The zero value for this is [Sha512].
DefaultHashAlgorithm HashAlgorithm
// Hosts are the host sources, such as https://example.com
Hosts []string
// Others are strings, to be added exactly as they appear (without quotes, but surrounding spaces will be added).
Others []string
}
ScriptSrc represents a script-src from a Content Security Policy (CSP)
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
func ScriptSrcFromHTMLFile ¶
ScriptSrcFromHTMLFile generates the script-src required to load a requested HTML file.
The input files must be truested HTML files! See the package documentation if you're unsure.
func ScriptSrcFromHTMLFileGlob ¶
ScriptSrcFromHTMLFiles generates the script-src required to load any of the HTML files matching the glob pattern.
The input files must be truested HTML files! See the package documentation if you're unsure.
func ScriptSrcFromHTMLFiles ¶
ScriptSrcFromHTMLFiles generates the script-src required to load any of the requested HTML files.
The input files must be truested HTML files! See the package documentation if you're unsure.
func (*ScriptSrc) AddFromHTML ¶
AddFromHTML adds the required script sources for loading all scripts, recursively, within the node.
This adds entries from script src attributes, and content within script tags without src attributes.
If includeEventHandlers, the content within any attribute starting with "on" is also allowed.
func (*ScriptSrc) AddFromHTMLFile ¶
AddFromHTMLFile parses the file from path, as HTML, and then calls scriptSrc.AddFromHTML with the result.
func (*ScriptSrc) AddInline ¶
AddInline adds the hash of some inline JavaScript to this scriptSrc.Hashes
The hash type is specified by scriptSrc.DefaultHashAlgorithm
func (*ScriptSrc) AddSrc ¶
AddSrc adds either 'self' or the required host entry to scriptSrc to allow the provided script source to be loaded.
This function returns an error if the script src is http, not https.
func (*ScriptSrc) String ¶
String formats this scriptSrc as it should appear in the Content-Security-Policy header value.
For example: "'self' https://challenges.cloudflare.com"
In the header value, it should appear after "script-src", for example:
Content-Security-Policy: script-src 'self' https://challenges.cloudflare.com;
Source Files