Skip to content

Commit

Permalink
Fixes and rewording
Browse files Browse the repository at this point in the history
  • Loading branch information
@sbreker
sbreker committed Oct 25, 2023
1 parent 6965bef commit a926839
Showing 1 changed file with 82 additions and 71 deletions.
153 changes: 82 additions & 71 deletions admin-manual/security/csp-headers.rst
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,32 @@
===============================
Content security policy headers
Content Security Policy Headers
===============================

.. _CSP: https://en.wikipedia.org/wiki/Content_Security_Policy

Content Security Policy or `CSP`_ is "a computer security standard introduced
to prevent cross-site scripting (XSS), clickjacking, and other code injection
attacks resulting from execution of malicious content in the trusted web page
context" (Wikipedia). CSPs are implemented as HTTP response headers that modern
browsers use to enhance the security of web pages.

AtoM now implements CSP headers when Bootstrap 5 based themes are in use.

Brand new installations of AtoM 2.8 will have a default CSP header implementation
activated by default.

This default configuration is a baseline that works with the upgraded Bootstrap 5
based Dominion theme.

High level implementation example
---------------------------------
Content Security Policy (CSP) headers are a critical component of web security,
serving as a robust defense against a wide range of online threats. These
headers, which are implemented on web servers and embedded within web pages,
define a set of directives that instruct a browser on how to handle and restrict
the execution of various web resources, such as scripts, stylesheets, and
images.

The primary function of CSP headers is to mitigate the risks associated with
cross-site scripting (XSS) attacks, data injection attacks, and other malicious
activities that exploit the trust model of web applications. By specifying which
sources of content are permitted, CSP headers help prevent unauthorized code
execution and reduce the attack surface, enhancing the overall security posture
of web applications.

Starting in AtoM 2.8, AtoM has built in support for CSP headers when Bootstrap 5
based themes are in use. When installing AtoM 2.8 from scratch, there's
a pre-configured CSP directive setting in place and CSP headers will be in use by
default. These default settings serve as a foundation compatible with the upgraded
Bootstrap 5 based Dominion theme and can be used as a base for custom themes based
on Dominion.

Content Security Policy headers
-------------------------------

In a high-level example of web security using Content Security Policy (CSP),
let's consider a scenario. When a user's web browser sends a request to a server
Expand All @@ -39,56 +46,65 @@ is allowed to run on the webpage. In doing so, CSP effectively protects against
XSS attacks and other security threats, making the user's browsing experience
safer and more secure.

```mermaid
sequenceDiagram
participant Browser
participant Server
.. mermaid::

Browser ->> Server: HTTP Request
note over Server: Generate unique nonce and<br/>store in session variable
note over Server: Build CSP header directive including nonce to use in reponse
sequenceDiagram
participant Browser
participant Server

note over Server: Tag each inline script with nonce
Server ->> Browser: HTTP Response
note over Browser: Verify reponse sources<br/>against values in CSP directive<br />rejecting any that do not match
```
Browser ->> Server: HTTP Request
note over Server: Generate unique nonce and<br/>store in session variable
note over Server: Build CSP header directive including nonce to use in reponse

note over Server: Tag each inline script with nonce
Server ->> Browser: HTTP Response
note over Browser: Verify reponse sources<br/>against values in CSP directive<br />rejecting any that do not match

Default implementation for the Bootstrap 5 Dominion theme
Default Implementation for the Bootstrap 5 Dominion Theme
---------------------------------------------------------

The ``Content-Security-Policy`` header value is made up of one or more
directives, where multiple directives are separated with a semicolon (``;``).
The ``Content-Security-Policy`` header encompasses one or more
directives. Multiple directives get delineated with a semicolon (``;``).

The ``default-src`` directive does not automatically cover iframes, so we
can also use the ``frame-ancestors`` directive to specify that the use of
elements such as ``<frame>``, ``<iframe>``, ``<object>``, ``<embed>``, etc.
will only be allowed when originating from the same origin as well:
The ``default-src`` directive doesn't inherently account for iframes. Hence,
the ``frame-ancestors`` directive can specify that the use of
elements such as ``<frame>``, ``<iframe>``, ``<object>``, ``<embed>``, and the likes
will only be permitted when sourced from the same origin:

The default config found in AtoM's app.yml file:
```
# Content Security Policy (CSP) header configuration. CSP settings are used
# only when a B5 theme is in use, otherwise these settings will be ignored.
csp:
# Configure CSP response header to be either
# 'Content-Security-Policy-Report-Only' or 'Content-Security-Policy'
response_header: Content-Security-Policy
# Configure CSP response directives.
directives: "default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/ blob:; script-src 'self' 'nonce'; style-src 'self' 'nonce'; worker-src 'self' blob:; frame-ancestors 'self';"
```
Updating AtoM's CSP configuration
---------------------------------

Here's the default configuration you'll find in AtoM's `app.yml` file:

.. code-block:: yaml
# Content Security Policy (CSP) header configuration. CSP settings apply
# only when a B5 theme is active, else these settings are bypassed.
csp:
response_header: Content-Security-Policy
directives: "default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/ blob:; script-src 'self' 'nonce'; style-src 'self' 'nonce'; worker-src 'self' blob:; frame-ancestors 'self';"
Strategy for working with your custom theme
##TODO: This can exist in a few places depending on how you start AtoM. If you run it from Docker

Strategy for Working with Your Custom Theme
-------------------------------------------

1. Start with a basic CSP Header Directive.
1. Begin with a Basic CSP Header Directive.

If your custom theme is derived from AtoM's Dominion Bootstrap 5 theme, begin
with the baseline CSP directive from AtoM 2.8's `app.yml``:

.. code-block:: plaintext
Assuming you are updating a web application similar to AtoM, update your
application to return a baseline `content-security-policy` header.
Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self' https://www.gravatar.com/avatar/ blob:; script-src 'self' 'nonce'; style-src 'self' 'nonce'; worker-src 'self' blob:; frame-ancestors 'self';
```
Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self'; script-src 'self'; style-src 'self'; frame-ancestors 'self';
For those who have crafted a custom theme, but haven't used AtoM's default Bootstrap 5
Dominion theme as a foundation, it's recommended to start with a more restrictive
`content-security-policy` header:

```
.. code-block:: plaintext
Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self'; script-src 'self'; style-src 'self'; frame-ancestors 'self';
This example references the `Content-Security-Policy-Report-Only` header -
this header will log violations in Chrome's Developer Tools but will not
Expand All @@ -98,16 +114,18 @@ Strategy for working with your custom theme
ready to go live this CSP header type can be changed to
`Content-Security-Policy` to activate enforcement.

- default-src: if resources are not defined in the other sections, use this
policy
- font-src: defines what fonts may be loaded
- img-src: defines what images may be loaded
- script-src: defines what scripts may be loaded
- style-src: defines what styles/css may be loaded
- default-src: if resources aren't mentioned in other sections, this policy is applied.
- font-src: stipulates which fonts can be loaded.
- img-src: stipulates which images can be loaded.
- script-src: stipulates which scripts can be loaded.
- style-src: stipulates which styles or CSS can be loaded.
- frame-ancestors 'self': determines which domains can embed the page as a frame.

2. Monitor in the browser watching for CSP violations.

The line number can be grabbed from the error as shown in Chrome’s dev tools:
The line number can be obtained from the error as shown in Chrome's dev tools console.

TODO: Add pic here!

![Example: CSP warnings in the console in red when editing and authority record](../atom-b5-auth-csp-errors.png)

Expand All @@ -120,7 +138,7 @@ Strategy for working with your custom theme
`Content-Security-Policy-Report-Only` to `Content-Security-Policy`.


Allowing inline sources
Allowing Inline Sources
-----------------------

If your application has inline scripts there are 4 choices:
Expand Down Expand Up @@ -157,10 +175,7 @@ If your application has inline scripts there are 4 choices:
script and style bundle. If it's an inline style can it be replaced with a
Bootstrap 5 equivalent?




Allowing external sources
Allowing External Sources
-------------------------

This is fairly straightforward - if for example the application loaded
Expand All @@ -186,12 +201,8 @@ for this:
.. SEEALSO::

* https://content-security-policy.com/examples/google-maps/

AtoM documentation links related to Google service integrations:
Additional AtoM documentation links related to Google service integrations:

* :ref:`maintenance-web-analytics`
* :ref:`maps-api-key`

## X-Frame headers

It is no longer recommended to use X-Frame headers.

0 comments on commit a926839

Please sign in to comment.