Add CSP header page #243
Add CSP header page #243
Conversation
sbreker
force-pushed
the
dev/csp-header-documentation
branch
from
0467e87
to
4209c7d
Compare
sbreker
force-pushed
the
dev/csp-header-documentation
branch
from
4209c7d
to
f1a6101
Compare
There was a problem hiding this comment.
Hi @sbreker , this looks great!
You forgot to add a link to it to the general index.rst landing page for all the docs, and I've requested some subheader anchors be added, but overall this content looks awesome. Thanks!
| Once the response is sent to the user's browser, the browser acts as a security | ||
| enforcer. It checks each requested resource and script against the CSP | ||
| directive. If any resource or script does not match the trusted sources | ||
| specified in the CSP header or lack the correct nonce, the browser rejects those |
There was a problem hiding this comment.
nitpick: should it be "lacks" rather than lack here? hard to keep track of...
There was a problem hiding this comment.
Yes - that sounds better - fixed.
| elements, preventing them from loading or executing. This strict validation | ||
| process ensures that only content from trusted sources, as defined by the CSP, | ||
| 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 |
There was a problem hiding this comment.
might be good to spell this out the first time, i.e. "protects against cross-site scripting (XSS) attacks and..."
| XSS attacks and other security threats, making the user's browsing experience | ||
| safer and more secure. | ||
|
|
||
| .. mermaid:: |
There was a problem hiding this comment.
I've not see this used before, did you generate the preview files when writing these and ensure that it renders correctly? If yes, great!
I've always done it by first specifying it's a code block, followed by the specific language / format used - if Sphinx knows it, then it will properly color the syntax, etc - like this:
.. code-block:: mermaid
That said, if this short-hand works in the local renders, then nevermind!
There was a problem hiding this comment.
I have tested this locally and it seems to work. I've added the appropriate references for this to work in a second commit.
There was a problem hiding this comment.
yep, looks good! thanks for double-checking too :D
| Specifying ``self`` ensures that only trusted resources from the *same origin* are loaded | ||
| and executed. | ||
|
|
||
| Updating these settings will require restarting **php-fpm**. |
There was a problem hiding this comment.
I would suggest linking to the instructions for restarting PHP-FPM, since it changes with each PHP version. i.e.
Updating these settings will require restarting :ref:`PHP-FPM <troubleshooting-restart-php-fpm>`.
| of the CSP policy by changing the header from | ||
| ``Content-Security-Policy-Report-Only`` to ``Content-Security-Policy``. | ||
|
|
||
| .. _allow-inline-sources: |
There was a problem hiding this comment.
i'd suggest prefacing this anchor with csp- so we can tell what the anchor relates to at a glance, and all CSP anchors are similarly named? (and generally all subheadings on this page, minus the page header one, which gets the security- prefix to match other pages in the section).... e.g.
.. _csp-allow-inline-sources:
| * https://developers.google.com/web/fundamentals/security/csp/ | ||
| * https://content-security-policy.com/examples/google-maps/ | ||
|
|
||
| .. SEEALSO:: |
There was a problem hiding this comment.
I think this was from your security doc! 👍
requirements.txt
Outdated
| @@ -1,2 +1,3 @@ | |||
| sphinx | |||
| sphinx_rtd_theme | |||
| sphinxcontrib-mermaid | |||
There was a problem hiding this comment.
oh cool, i guess that this add support for the mermaid block you added above! great, if it's tested then you can ignore my comments there
| XSS attacks and other security threats, making the user's browsing experience | ||
| safer and more secure. | ||
|
|
||
| .. mermaid:: |
There was a problem hiding this comment.
yep, looks good! thanks for double-checking too :D
|
|
||
| .. IMPORTANT:: | ||
|
|
||
| CSP headers will only be applied toa response if a Bootstrap 5 based theme is in use. See: |
There was a problem hiding this comment.
nitpick: just saw this tiiiiiiny typo here (toa instead of "to a")
sbreker
force-pushed
the
dev/csp-header-documentation
branch
2 times, most recently
from
ab6a85a
to
9cc0467
Compare
|
@sbreker did this never get merged? or is this an older version and the work got merged elsewhere? just wondering if some cleanup is needed here... |
Add security section page detailing CSP header functionality.
Added note about updating the default header type. Updated directive to include the Google integration changes. Additional detail added to CSP implementation section.
sbreker
force-pushed
the
dev/csp-header-documentation
branch
from
0449676
to
6209ff0
Compare
Add security section page detailing CSP header functionality.