When Fossil’s web interface generates an HTML page, it
normally includes a Content Security Policy (CSP)
in the <head>.
The CSP tells the browser what types of content (HTML, image, CSS,
JavaScript...) the document may reference and from where the
content may be sourced.
CSP is a security measure designed to prevent cross-site scripting (XSS) and other similar code injection attacks. The CSP defines a “white list” of content types and origins that are considered safe. Any references to resources that are not on the white list are ignored.
If Fossil were perfect and bug-free and never allowed any kind of code injection on the pages it generates, then the CSP would not be useful. The Fossil developers are not aware of any defects in Fossil that allow code injection, and will promptly fix any defects that are brought to their attention. Lots of eyeballs are looking at Fossil to find problems in the code, and the Fossil build process uses custom static analysis techniques to help identify code injection problems at compile-time. Nevertheless, problems do sometimes (rarely) slip through. The CSP serves as a final line of defense, preventing code injection defects in Fossil from turning into actual vulnerabilities.
Fossil site administrators can modify the default CSP, perhaps to add trusted external sources for auxiliary content. But for maximum safety, site developers are encouraged to work within the restrictions imposed by the default CSP and avoid the temptation to relax the CSP unless they fully understand the security implications of what they are doing.
The Default Restrictions
The Fossil default CSP declares the following content restrictions:
default-src 'self' data:
This policy means mixed-origin content isn’t allowed, so you can’t refer to resources (images, style-sheets, and scripts) on other web domains. Hence the following Markdown for an inline image hosted on another site will cause a CSP error:
The default policy does allows inline data: URIs, which means you could
data-encode your image content and put it inline within the
document:
That method is best used for fairly small resources. Large data: URIs
are hard to read and edit. Keep in mind that if you put such a thing
into a Fossil forum post, anyone subscribed to email alerts will get a
copy of the raw URI text, which is really ugly.
For larger images in embedded documentation you store the image as a separate file in the Fossil repository and reference it via a relative URI.
Any content from the same domain as the Fossil repository will work fine. So if the Fossil repository is but one path in a larger website, it will be able reference other static resources within that same website. It can also reference unversioned content. However, as unversioned content and content outside of the Fossil repository itself will not be transferred by sync, the references probably will not work in clones of your repository.
style-src 'self' 'unsafe-inline'
This policy allows CSS information to come from separate files in the same domain of the Fossil server, or for CSS to be embedded inline within the document text.
The 'unsafe-inline' element means that an injection vulnerability in
Fossil would allow an attacker to modify the CSS for a Fossil-generated
page. This is not ideal, but nor is it as dangerous as allowing
injected javascript to run, and Fossil uses of in-line CSS
for things like setting background colors in timelines and defining
line widths in bar graphs on the Activity Reports page,
so it seems like in-line CSS is a necessary compromise at this time.
script-src 'self' 'nonce-%s'
This policy disables in-line javascript and only allows <script>
elements if the <script> includes a nonce= attribute the
matches the %s section of the CSP. Fossil provides a different
random nonce for every page it generates, and since an attacker has
no way of predicting what that nonce will be, the attacker is unable
to inject working javascript.
For documents generated by the CGI extensions, the value of the nonce is accessible in the FOSSIL_NONCE environment variable. TH1 scripts that run while generating the header or footer can access the nonce in the $nonce variable. The JavaScript section of a custom skin automatically includes the appropriate nonce.
Cross-Site Scripting via Ordinary User Capabilities
We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
<script> tags as for <style> tags, anyone with check-in
rights on your repository could add a JavaScript file to your repository
and then refer to it from other content added to the site. Since
JavaScript code can access any data from any URI served under its same
Internet domain, and many Fossil users host multiple Fossil repositories
under a single Internet domain, such a CSP would only be safe if all of
those repositories are trusted equally.
Consider the Chisel hosting service, which
offers free Fossil repository hosting to anyone on the Internet, all
served under the same http://chiselapp.com/user/$NAME/$REPO URL
scheme. Any one of those hundreds of repositories could trick you into
visiting their repository home page, set to an HTML-formatted embedded
doc page via Admin → Configuration → Index Page, with this
content:
<script src="/doc/trunk/bad.js"></script>
That script can then do anything allowed in JavaScript to any other Chisel repository your browser can access.The possibilities for mischief are vast. For just one example, if you have login cookies on four different Chisel repositories, your attacker could harvest the login cookies for all of them through this path if we allowed Fossil to serve JavaScript files under the same CSP policy as we do for CSS files.
This is why the default configuration of Fossil has no way for embedded docs, wiki articles, tickets, forum posts, or tech notes to automatically insert a nonce into the page content. This is all user-provided content, which could link to user-provided JavaScript via check-in rights, effectively giving all such users a capability that is usually reserved to the repository’s administrator.
The default-disabled TH1 documents feature is the only known
path around this restriction. If you are serving a Fossil repository
that has any user you do not implicitly trust to a level that you would
willingly run any JavaScript code they’ve provided, blind, you must
not give the --with-th1-docs option when configuring Fossil, because
that allows substitution of the pre-defined $nonce TH1
variable into HTML-formatted embedded docs:
<script src="/doc/trunk/bad.js" nonce="$nonce"></script>
Even with this feature enabled, you cannot put <script> tags into
Fossil Wiki or Markdown-formatted content, because our HTML generators
for those formats purposely strip or disable such tags in the output.
Therefore, if you trust those users with check-in rights to provide
JavaScript but not those allowed to file tickets, append to wiki
articles, etc., you might justify enabling TH1 docs on your repository,
since the only way to create or modify HTML-formatted embedded docs is
through check-ins.
Replacing the Default CSP
If you wish to relax the default CSP’s restrictions or to tighten them further, there are two ways to accomplish that:
TH1 Setup Hook
The stock CSP text is hard-coded in the Fossil C source code, but it’s
only used to set the default value of one of the TH1 skinning
variables, $default_csp. That means you can
override the default CSP by giving this variable a value before Fossil
sees that it’s undefined and uses this default.
The best place to do that is from the th1-setup
script, which runs before TH1 processing happens during
skin processing:
$ fossil set th1-setup "set default_csp {default-src: 'self'}"
This is the cleanest method, allowing you to set a custom CSP without
recompiling Fossil or providing a hand-written <head> section in the
Header section of a custom skin.
You can’t remove the CSP entirely with this method, but you can get the same effect by telling the browser there are no content restrictions:
$ fossil set th1-setup 'set default_csp {default-src: *}'
Custom Skin Header
Fossil only inserts a CSP into the HTML pages it generates when the
skin’s Header section doesn’t contain a
<head> tag. None of the stock skins include a <head> tag,² so if you
haven’t created a custom skin, you should be getting Fossil’s
default CSP.
We say “should” because long-time Fossil users may be hanging onto a
legacy behavior from before Fossil 2.5, when Fossil added this automatic
<head> insertion feature. Repositories created before that release
where the admin either defined a custom skin or chose one of the stock
skins (!) will effectively override this automatic HTML <head>
insertion feature because the skins from before that time did include
these elements. Unless the admin for such a repository updated the skin
to track this switch to automatic <head> insertion, the default CSP
added to the generated header text in Fossil 2.7 is probably being
overridden by the skin.
If you want the protection of the default CSP in your custom skin, the
simplest method is to leave the <html><head>... elements out of the
skin’s Header section, starting it with the <div class="head"> element
instead as described in the custom skinning guide. Alternately, you can
make use of $default_csp.
This then tells you one way to override Fossil’s default CSP: provide your own HTML header in a custom skin.
A useful combination is to entirely override the default CSP in the skin but then provide a new CSP in the front-end proxy layer using any of the many reverse proxy servers that can define custom HTTP headers.
Asides and Digressions:
There is actually a third context that can correctly insert this nonce attribute: a CGI server extension, by use of the
FOSSIL_NONCEvariable sent to the CGI by Fossil.The stock Bootstrap skin does actually include a
<head>tag, but from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP text that Fossil’s C code inserts into the HTML header for all other stock skins. With Fossil 2.10, the stock Bootstrap skin uses$default_cspinstead, so you can override it as above.