# Documentation Django 6.0.7

# Politique de sécurité de contenu (CSP)

New in Django 6.0.

La politique de sécurité de contenu (CSP) est un standard de sécurité web aidant à prévenir les attaques par injection de contenu en limitant les sources à partir desquelles le contenu peut être chargé. Elle joue un rôle important dans le cadre d’une stratégie de sécurité complète.

Pour des instructions de configuration dans un projet Django, consultez la documentation Utilisation de CSP. Pour un guide HTTP au sujet de CSP, consultez le guide MDN sur CSP.

## Aperçu

La spécification Content-Security-Policy définit deux en-têtes complémentaires :

- `Content-Security-Policy`: applique la politique CSP, en bloquant le contenu qui viole les directives définies.

- `Content-Security-Policy-Report-Only`: signale les violations CSP sans bloquer le contenu, permettant de tester sans dommage.

Chaque politique est composée d’une ou de plusieurs directives avec leurs valeurs, qui indiquent ensemble au navigateur la façon de gérer des types spécifiques de contenus.

Lorsque `ContentSecurityPolicyMiddleware` est activé, Django construit et lie automatiquement les en-têtes appropriés à chaque réponse en fonction des réglages configurés, sauf s’ils ont déjà été définis par une autre couche.

## Réglages

`ContentSecurityPolicyMiddleware` est configuré en utilisant les réglages suivants:

- `SECURE_CSP`: définit la politique de sécurité de contenu comme appliquée.

- `SECURE_CSP_REPORT_ONLY`: définit la politique de sécurité de contenu en mode signalement uniquement.

Ces réglages peuvent être définis indépendamment ou conjointement.

- Utilisez `SECURE_CSP` seul pour appliquer une politique qui a déjà été testée et vérifiée.

- Utilisez `SECURE_CSP_REPORT_ONLY` seul pour évaluer une nouvelle politique sans casser le comportement du site. Ce mode ne bloque pas les violations, il ne fait que les journaliser. C’est utile pour tester et surveiller, mais ne fournit aucune protection contre les menaces actives.

- Use both to maintain an enforced baseline while experimenting with changes. Even for well-established policies, continuing to collect reports can help detect regressions, unexpected changes in behavior, or potential tampering in production environments.

## Rapports de violation de politique

Lorsqu’une violation CSP se produit, les navigateurs journalisent typiquement les détails dans la console de développement, fournissant un retour immédiat durant le développement. Pour recevoir aussi ces rapports de façon programmatique, la politique doit inclure une directive de signalement telle que `report-uri` qui indique où les données de violation doivent être envoyées.

Django prend en charge la configuration de ces directives via le réglage `SECURE_CSP_REPORT_ONLY`, mais les signalements ne vont être déclenchés par le navigateur que si la politique inclut explicitement une directive de signalement valable.

Django ne fournit pas de fonctionnalité intégrée pour recevoir, stocker ou traiter les rapports de violation. Pour les collecter et les analyser, vous devez implémenter vos propres points d’accès de signalement, ou intégrer un service de surveillance de tierce partie.

## Constantes CSP

Django fournit des constantes prédéfinies représentant des mots-clés d’expressions sources CSP courants, tels que `'self'`, `'none'` et `'unsafe-inline'`. Ces constantes sont prévues pour être utilisées dans les valeurs de directives définies dans les réglages.

Elles sont disponibles par l’énumération `CSP`, et il est recommandé de les utiliser plutôt que les chaînes brutes. Cela aide à éviter les erreurs courantes telles que des fautes d’orthographe, des mises sous guillemets incorrectes ou de la mise en forme incohérente, et permet de garantir le respect de la spécification CSP.

class CSP

  Énumération fournissant des constantes standardisées pour les expressions sources CSP courantes.

  NONE

    Représente `'none'`. Bloque le chargement de ressources pour la directive donnée.

  REPORT_SAMPLE

    Représente `'report-sample'`. Indique au navigateur d’inclure un extrait du code en faute dans les rapports. Sachez que cela pourrait exposer des données sensibles.

  SELF

    Représente `'self'`. Autorise à charger des ressources à partir de la même origine (même protocole, hôte et port).

  STRICT_DYNAMIC

    Représente `'strict-dynamic'`. Autorise l’exécution de scripts chargés par un script de confiance (par ex. un script possédant un nonce ou une empreinte valide), sans avoir besoin de `'unsafe-inline'`.

  UNSAFE_EVAL

    Représente `'unsafe-eval'`. Autorise l’utilisation d”`eval()` et des fonctions JavaScript similaires. Fortement découragé.

  UNSAFE_HASHES

    Représente `'unsafe-hashes'`. Autorise les gestionnaires d’événements et certains URI `javascript:` lorsque l’empreinte de leur contenu correspond à une règle de la politique. Nécessite le niveau 3+ de CSP.

  UNSAFE_INLINE

    Représente `'unsafe-inline'`. Autorise l’exécution de scripts, styles et URL `javascript:` intégrés dans les pages. Généralement déconseillé, particulièrement pour les scripts.

  WASM_UNSAFE_EVAL

    Représente `'wasm-unsafe-eval'`. Permet la compilation et l’exécution de code WebAssembly sans activer `'unsafe-eval'` pour les scripts.

  NONCE

    La valeur de substitution spécifique à Django (`"<CSP_NONCE_SENTINEL>"`) utilisée dans les directives `script-src` ou `style-src` pour activer le CSP basé sur les nonces. Au moment de son exécution, l’intergiciel `ContentSecurityPolicyMiddleware` remplace cette chaîne par un nonce sécurisé et aléatoire généré pour chaque requête. Voir les explications détaillées dans Nonce usage.

## Décorateurs

Django fournit des décorateurs pour contrôler les en-têtes CSP pour chaque vue. Cela permet de surcharger ou désactiver la politique d’application ou de signalement seul pour des vues particulières, fournissant un contrôle fin lorsque les réglages globaux ne suffisent pas. L’application de ces surcharges remplace complètement le CSP de base : il n’y a pas de fusion avec les règles existantes. Elles peuvent être utilisées conjointement avec les constantes définies dans `CSP`.

Avertissement

L’affaiblissement ou la désactivation d’une politique CSP sur une page peut compromettre la sécurité de tout le site. En raison de la politique de « même origine », un attaquant pourrait exploiter une vulnérabilité sur une page pour accéder à d’autres pages du site.

csp_override(config)(view)

  Surcharge l’en-tête `Content-Security-Policy` pour la vue décorée en utilisant des directives au même format que le réglage `SECURE_CSP`.

  L’argument `config` doit être une correspondance entre les directives CSP souhaitées. Si `config` est vide (`{}`), aucun en-tête CSP ne sera appliqué à la réponse renvoyée par cette vue, ce qui désactivera en pratique CSP pour cette vue.

  Exemples :

      from django.http import HttpResponse
      from django.utils.csp import CSP
      from django.views.decorators.csp import csp_override

      @csp_override(
          {
              "default-src": [CSP.SELF],
              "img-src": [CSP.SELF, "data:"],
          }
      )
      def my_view(request):
          return HttpResponse("Custom Content-Security-Policy header applied")

      @csp_override({})
      def my_other_view(request):
          return HttpResponse("No Content-Security-Policy header added")

csp_report_only_override(config)(view)

  Overrides the `Content-Security-Policy-Report-Only` header for the decorated view using directives in the same format as the `SECURE_CSP_REPORT_ONLY` setting.

  Like `csp_override()`, the `config` argument must be a mapping with the desired CSP directives. If `config` is an empty mapping (`{}`), no CSP report-only header will be added to the response returned by that view, effectively disabling report-only CSP for that view.

  Exemples :

      from django.http import HttpResponse
      from django.utils.csp import CSP
      from django.views.decorators.csp import csp_report_only_override

      @csp_report_only_override(
          {
              "default-src": [CSP.SELF],
              "img-src": [CSP.SELF, "data:"],
              "report-uri": "https://mysite.com/csp-report/",
          }
      )
      def my_view(request):
          return HttpResponse("Custom Content-Security-Policy-Report-Only header applied")

      @csp_report_only_override({})
      def my_other_view(request):
          return HttpResponse("No Content-Security-Policy-Report-Only header added")

The examples above assume function-based views. For class-based views, see the guide for decorating class-based views.

## Nonce usage

A CSP nonce (« number used once ») is a unique, random value generated per HTTP response. Django supports nonces as a secure way to allow specific inline `<script>` or `<style>` elements to execute without relying on `'unsafe-inline'`.

Nonces are enabled by including the special placeholder `NONCE` in the relevant directive(s) of your CSP settings, such as `script-src` or `style-src`. When present, the `ContentSecurityPolicyMiddleware` will generate a nonce and insert the corresponding `nonce-<value>` source expression into the CSP header.

To use this nonce in templates, the `csp()` context processor needs to be enabled. It adds a `csp_nonce` variable to the template context.

Changed in Django 6.1:

The `csp_nonce_attr` template tag was added, including support for rendering `Media` objects.

For inline `<script>` and `<style>` elements, include the nonce directly using the context variable:

    <script nonce="{{ csp_nonce }}">
      // This inline JavaScript will be allowed.
    </script>

For external `<script src="...">` and `<link rel="stylesheet">` elements, use the `csp_nonce_attr` template tag:

    <script src="/path/to/script.js" {% csp_nonce_attr %}></script>
    <link rel="stylesheet" href="/path/to/style.css" {% csp_nonce_attr %}>

To render a `Media` object’s assets with the nonce applied, pass the object to the `csp_nonce_attr` template tag:

    {% csp_nonce_attr form.media %}

The browser will only execute inline elements that include a `nonce=<value>` attribute matching the one specified in the `Content-Security-Policy` (or `Content-Security-Policy-Report-Only`) header. This mechanism provides fine-grained control over which inline code is allowed to run.

If a template includes the CSP nonce but the policy does not include `NONCE`, the HTML will include a nonce attribute, but the header will lack the required source expression. In this case, the browser will block the inline script or style (or report it for report-only configurations).

### Nonce generation and caching

Django’s nonce generation is lazy: the middleware only generates a nonce if `{{ csp_nonce }}` is accessed during template rendering. This avoids unnecessary work for pages that do not use nonces.

However, because nonces must be unique per request, extra care is needed when using full-page caching (e.g., Django’s cache middleware, CDN caching). Serving cached responses with previously generated nonces may result in reuse across users and requests. Although such responses may still appear to work (since the nonce in the CSP header and HTML content match), reuse defeats the purpose of the nonce and weakens security.

To ensure nonce-based policies remain effective:

- Avoid caching full responses that include `{{ csp_nonce }}` or `csp_nonce_attr`.

- If caching is necessary, use a strategy that injects a fresh nonce on each request, or consider refactoring your application to avoid inline scripts and styles altogether.