Преглед изворни кода

Fixes #23502: Document CSP requirements for plugin templates

Adds a Content Security Policy section to the plugin template docs covering script nonces, inline event handlers, runtime eval in htmx attributes, and inline styles, linking to the administration page.
Jason Novinger пре 1 дан
родитељ
комит
3f781d5a28
1 измењених фајлова са 17 додато и 0 уклоњено
  1. 17 0
      docs/plugins/development/templates.md

+ 17 - 0
docs/plugins/development/templates.md

@@ -203,6 +203,23 @@ This template is used by the `BulkDeleteView` generic view to delete multiple ob
 | `table`      | Yes      | The table class used for rendering the list of objects          |
 | `return_url` | Yes      | The URL to which the user is redirect after submitting the form |
 
+## Content Security Policy
+
+Administrators can send a [Content Security Policy](../../administration/content-security-policy.md) (CSP) that only allows scripts carrying a per-request nonce. NetBox is planning to turn a CSP on by default in v5.0 ([#23503](https://github.com/netbox-community/netbox/issues/23503)), so plugin templates should work under one now.
+
+* **Nonce every script.** Add `nonce="{{ csp_nonce }}"` to every `<script>` element, inline or with a `src`. The `csp_nonce` template variable is public plugin API from NetBox v4.8.
+* **No inline event handler attributes.** Attributes such as `onclick=` or `onerror=` are blocked and the handler silently does not run. Attach a listener from a script file under your plugin's static directory instead.
+* **No runtime evaluation of strings as code.** This includes htmx's `hx-on` attributes, `hx-trigger` filter expressions such as `keyup[event.target.value.length > 2]`, and `js:` values in `hx-vals` or `hx-headers`. Without `'unsafe-eval'`, `hx-on` handlers and `js:` values throw an error, which shows in the browser console as a CSP violation, and they do not work. A trigger filter fails open instead: htmx drops the filter, so the request fires on every event. Use a listener that dispatches a custom event or sets a request parameter in `htmx:configRequest`.
+* **Inline styles are fine.** The [example policy](../../administration/content-security-policy.md#example-policy) allows inline `style=` attributes and `<style>` elements, and `style-src` takes no nonce. See [Styles](../../administration/content-security-policy.md#styles).
+
+```jinja2
+{% load static %}
+<script nonce="{{ csp_nonce }}">
+  window.myPluginConfig = { endpoint: "{% url 'plugins:my_plugin:endpoint' %}" };
+</script>
+<script nonce="{{ csp_nonce }}" src="{% static 'my_plugin/widget.js' %}"></script>
+```
+
 ## Tags
 
 The following custom template tags are available in NetBox.