Fixes #23502: Document Copilot, remote media and static hosts in the example CSP

The example policy now allows the scripts and frame NetBox Copilot loads (unpkg.com, js.stripe.com) and a new section says which directives get remote media and static hosts. Checked in a browser against an enforcing policy.

docs/administration/content-security-policy.md

@@ -6,14 +6,18 @@ NetBox's own pages are written to work under a strict script policy. Every `<scr
 
 ## Example policy
 
-The policy below is an example, not a default. It has been checked against the pages that need no outside setup: the login page, object lists and detail pages, cable traces, Markdown images, GraphiQL, the Swagger and Redoc API documentation, and the REST API's browsable view.
+The policy below is an example, not a default. It has been checked against the login page, object lists and detail pages, cable traces, Markdown images, GraphiQL, the Swagger and Redoc API documentation, and the REST API's browsable view, with and without NetBox Copilot turned on, as described below. Remote media and static hosts and a redirect-based single sign-on login were checked separately.
 
 ```python
 from django.utils.csp import CSP
 
 SECURE_CSP = {
     'default-src': [CSP.SELF],
-    'script-src': [CSP.SELF, CSP.NONCE, 'https://static.copilot.netboxlabs.ai'],
+    'script-src': [
+        CSP.SELF,
+        CSP.NONCE,
+        'https://static.copilot.netboxlabs.ai',
+    ],
     'style-src': [CSP.SELF, CSP.UNSAFE_INLINE, 'https://fonts.googleapis.com'],
     'font-src': [CSP.SELF, 'data:', 'https://fonts.gstatic.com'],
     'img-src': [CSP.SELF, 'data:', 'https:'],
@@ -27,9 +31,29 @@ The policy has no `object-src` directive because cable traces embed their SVG in
 
 To try it without enforcing it, assign the same dictionary to `SECURE_CSP_REPORT_ONLY` instead. See [Testing a policy](#testing-a-policy) below.
 
+### NetBox Copilot
+
+The example allows only Copilot's own loader at `static.copilot.netboxlabs.ai`. If users turn on [NetBox Copilot](../configuration/miscellaneous.md#copilot_enabled) in their preferences, Copilot then loads React and Turbo from `unpkg.com`, and the browser blocks them under the example. Those scripts in turn load Stripe's script from `js.stripe.com`, which is never requested while they are blocked. To allow all of them, merge the entries below into the example policy. This is an excerpt, not a whole policy. `script-src` is the example's list with two entries appended, and `frame-src` is a new directive because the example does not define one.
+
+```python
+SECURE_CSP = {
+    # ...
+    'script-src': [
+        CSP.SELF,
+        CSP.NONCE,
+        'https://static.copilot.netboxlabs.ai',
+        'https://unpkg.com',
+        'https://js.stripe.com',
+    ],
+    'frame-src': [CSP.SELF, 'https://js.stripe.com'],
+}
+```
+
+Allowing `unpkg.com` lets scripts from any npm package run on your NetBox pages, which weakens the protection the nonce gives. The alternative is `'strict-dynamic'`, described in [Stronger script policies](#stronger-script-policies), which trusts the scripts that nonced scripts load instead of naming hosts. Requests Copilot makes after a user signs in to it were not checked, so a policy that stays quiet while Copilot loads may still report violations once it is in use.
+
 ## What each directive allows
 
-* `script-src` allows scripts served by NetBox, scripts carrying the request's nonce, and the loader script for NetBox Copilot. Copilot is only loaded when it is enabled. The loader may request further hosts of its own, which this page does not cover.
+* `script-src` allows scripts served by NetBox, scripts carrying the request's nonce, and NetBox Copilot's loader at `static.copilot.netboxlabs.ai`. Copilot is only loaded when it is enabled and a user has turned it on in their preferences. The further scripts it loads need the entries in [NetBox Copilot](#netbox-copilot).
 * `style-src` allows inline styles, plus Google Fonts stylesheets, which the Redoc page loads. See [Styles](#styles) below.
 * `font-src` allows NetBox's own fonts, the `data:` fonts embedded in the GraphiQL stylesheet, and `fonts.gstatic.com` for Redoc.
 * `img-src` allows `https:` so that Markdown images hosted elsewhere keep loading. NetBox keeps `http` and `https` image sources in rendered Markdown from any host. You can replace `https:` with a list of named hosts, but images from every other host will stop loading.
@@ -37,7 +61,20 @@ To try it without enforcing it, assign the same dictionary to `SECURE_CSP_REPORT
 * `worker-src` allows the web workers GraphiQL starts from NetBox's own files, and the `blob:` worker Redoc starts.
 * `base-uri` stops an injected `<base>` element from redirecting relative URLs.
 
-Other deployments need more. If media files are served from another host, add it to `img-src`, and to `media-src` or other directives if the files are not images. If `STATIC_URL` points at another host, add that host to `script-src`, `style-src`, `font-src`, and `img-src`.
+## Remote media and static files
+
+If uploaded media (image attachments, device type images) or static files are served from another host through the [`STORAGES`](../configuration/system.md#storages) parameter, add that host to the matching directives of the example policy above. Do not replace your policy with these lines: they show only the entries to append to the existing lists. Replace `media.example.com` and `static.example.com` with your hosts.
+
+```text
+script-src: add 'https://static.example.com'
+style-src:  add 'https://static.example.com'
+font-src:   add 'https://static.example.com'
+img-src:    add 'https://media.example.com' and 'https://static.example.com'
+```
+
+* A media host goes in `img-src`. Use `media-src` or other directives too if the files are not images.
+* A static host goes in `script-src`, `style-src`, `font-src`, and `img-src`. NetBox's logos and icons are static files loaded as images.
+* The example policy already allows any `https:` image source, so `img-src` needs no change unless you replace `https:` with a list of hosts. Without the host in a narrowed list, the browser blocks every media and static image, including the logo and the device type images.
 
 ## Styles