# Django 6.0.7 documentation

# Django 的安全性

此文档是对 Django 安全特性的概述。包含保障那些用 Django 建立的网站的安全性建议。

Real-world security

Django's web security implementations have been designed with security for real-world applications in mind. Django is a general-purpose web application framework, and its defaults reflect this - they will not be the best solution for every particular case. Special cases deserve special attention to their needs.

Web security requires a multi-layered approach. Securing only a single vector does not make a site secure overall, nor does a single apparent weakness necessarily compromise the entire site. This should be borne in mind particularly when assessing individual points in security audits.

## Always sanitize user input

The golden rule of web application security is to never trust user-controlled data. Hence, all user input should be sanitized before being used in your application. See the forms documentation for details on validating user inputs in Django.

## Cross-site scripting (XSS) protection

In a cross-site scripting attack, malicious code in the form of a client-side script is injected into another user's web browser, where it will be executed.

This is typically done by:

- storing the malicious script in the database where it will be retrieved and presented to other users in their browsers, or

- getting users to click a link which will cause the attacker's JavaScript to be executed by the user's browser.

Cross-site scripting attacks can originate from any untrusted source of data, including cookies or web services, if the data are not adequately sanitized before being published in a page.

Django templates provide protection against the majority of cross-site scripting attacks by automatically escaping characters that represent a risk (that is, HTML characters that could be interpreted by the browser to malicious effect are instead safely displayed).

However, the extent of this protection and its limitations should be understood.

Ambiguity between the developer's intention and how the browser interprets HTML can expose the client to unintended code execution. Suppose that a developer creates:

    <style class={{ var }}>...</style>

where `var` is expected to contain something like `'class1'`. If `var` were set to `'class1 onmouseover=javascript:func()'` though, this could result in unauthorized JavaScript execution due to differences in how browsers will interpret this imperfect HTML.

Explicit template design, in which the quotes are not left to the variable to provide:

    <style class="{{ var }}">...</style>

would eliminate this possibility.

It is also important to be particularly careful when using the `is_safe` attribute with custom template tags, the `safe` template tag, `mark_safe`, and when autoescape is turned off.

Django's built-in escaping is intended to protect HTML output. If you are using the template system to output something other than HTML, the characters and strings that require escaping might be entirely different.

Additionally, be very careful when storing HTML in the database, especially when that HTML is retrieved and displayed. Unless the HTML is guaranteed to come from a trusted source - user input is not a trusted source - stored HTML should be checked and sanitized, preferably on input as well as output.

## Cross-site request forgery (CSRF) protection

发起 CSRF 攻击的人可以使用其他用户的证书执行操作，且是在其不知情或不同意的情况下。

Django 内置了保护措施来防御大多数 CSRF 攻击，您需要在合适的地方 授权并使用它 。但和多数缓解性技术一样，它是有局限性的。比如可以全局禁用 CSRF 模块或者特定的视图。请三思而后行。如果您的网页还有脱离您控制的子域，还将会有其他 限制 。

CSRF protection works by checking for a secret in each POST request. This ensures that a malicious user cannot "replay" a form POST to your website and have another logged-in user unwittingly submit that form. The malicious user would have to know the secret, which is user specific (using a cookie).

在部署 HTTPS 时，`CsrfViewMiddleware` 会检查 HTTP 报文的 referer 首部是否设置为同源的 URL（包括子域和端口）。因为 HTTPS 提供了额外的安全性，所有通过转发不安全连接请求并在支持的浏览器中使用 HSTS 来确保连接在可用的地方使用了 HTTPS ，这一点是很重要的。

除非绝对需要，否则对视图进行标记 `csrf_exempt` 装饰器时要极其慎重。

## 防御 SQL 注入

SQL 注入能让恶意用户能在数据库中执行任意 SQL 代码。这将导致记录被删除或泄露。

Django 的 querysets 在被参数化查询构建出来时就被保护而免于 SQL 注入。查询的 SQL 代码与查询的参数是分开定义的。参数可能来自用户从而不安全，因此它们由底层数据库引擎进行转义。

Django 也为开发者提供了书写 原始查询 或执行 自定义 sql 的权力。应当尽可能少地使用这些方法，并且您应该小心并准确地转义一切用户可控的参数。另外，在使用 `extra()` 和 `RawSQL` 时应当小心谨慎。

## 防御访问劫持

访问劫持能让恶意网页覆盖另一个网页。可能会有毫不知情的用户被骗入目标网页并执行意料之外的操作。

Django 包含 访问劫持保护 ，以 `X-Frame-Options middleware` 的形式在支持它的浏览器中阻止一个网页被渲染在 frame 的内部。可在每个视图的基础上禁用保护，也可配置发送的确切头部值。

对于任何不会被第三方网站嵌入 frame 的网页，或者只允许使用一小部分的网页来说，强烈建议使用中间件。

## SSL/HTTPS

通过 HTTPS 部署您的网页是保障安全的最佳办法。没有它，恶意用户就可以在客户端和服务器之间嗅探验证资格或其他信息，在某些情况下 -- 比如 主动 网络攻击者 -- 会修改发送中的数据。

如果您想得到 HTTPS 的保护，且已经在您的服务器上启用了，下面还有一些额外的步骤需要执行：

- 如有必要，设置 `SECURE_PROXY_SSL_HEADER`，确保您已经彻底的了解了它的警告提示。如果不这么做，将会导致 CSRF 漏洞，如果操作不正确，也是非常危险的。

- 设置 `SECURE_SSL_REDIRECT` 为 `True`，这样 HTTP 的请求就会被重定向到 HTTPS。

  请注意 `SECURE_PROXY_SSL_HEADER` 下的注意事项。对于反向代理的情况，配置主 Web 服务器来做重定向到 HTTPS 可能更容易或更安全。

- 使用 'secure' cookies。

  如果浏览器使用默认的 HTTP 来实现初始连接，可能会导致已有的 cookies 泄露。因此，您应当将 `CSRF_COOKIE_SECURE` 和 `CSRF_COOKIE_SECURE` 设置为 `True`。这样浏览器就会仅用 HTTPS 连接来发送 cookies。注意，这会使得 sessions 不能再通过 HTTP 工作，且 CSRF 防御机制将会阻止任何通过 HTTP 接收到的 POST 数据（当然把所有 HTTP 都弄成 HTTPS 是最好的）。

- 使用 HTTP 严格传输安全 （HSTS）

  HSTS 是一个 HTTP 标头，它通知浏览器，所有未来连接到一个特定的网站应该始终使用 HTTPS。结合重定向 HTTP 请求到 HTTPS，这将确保连接总是享受 SSL 的额外安全，只要有一个成功的连接发生。HSTS 可以通过 `SECURE_HSTS_SECONDS`、 `SECURE_HSTS_INCLUDE_SUBDOMAINS` 和 `SECURE_HSTS_PRELOAD` 来配置，或者在网络服务器上配置。

## Host 头部验证

Django uses the `Host` header provided by the client to construct URLs in certain cases. While these values are sanitized to prevent cross-site scripting attacks, a fake `Host` value can be used for cross-site request forgery, cache poisoning attacks, and poisoning links in emails.

Because even seemingly-secure web server configurations are susceptible to fake `Host` headers, Django validates `Host` headers against the `ALLOWED_HOSTS` setting in the `django.http.HttpRequest.get_host()` method.

This validation only applies via `get_host()`; if your code accesses the `Host` header directly from `request.META` you are bypassing this security protection.

更多细节请参照完整的 `ALLOWED_HOSTS` 文档。

Warning

本文档的较早版本建议配置你的网络服务器，以确保它验证传入的 HTTP `Host` 头。虽然我们现在还是这样建议，但在许多常见 Web 服务器中，看似验证了 `Host` 头的配置，实际上却没有验证。例如，即使 Apache 的配置是让你的 Django 网站从一个非默认的虚拟主机上运行，并设置了 "ServerName"，HTTP 请求仍然有可能匹配这个虚拟主机，并提供一个假的 "Host " 头。因此，Django 现在要求你显式地设置 `ALLOWED_HOSTS`，而不是依赖 Web 服务器的配置。

另外，如果您的配置需要，Django 要求您明确启用对 `X-Forwarded-Host` 标头的支持（通过 `USE_X_FORWARDED_HOST` 配置）。

## Referrer 策略

浏览器使用 `Referer` 头部来把关于用户是如何到达那里的信息发送到网站。通过设置 Referrer 策略，限制在哪些情况下设置 `Referer` 头部，可以保护您用户的隐私。请看 安全中间件参考中的 referrer 策略部分 了解更多细节。

## 跨源弹出式窗口策略

跨源弹出式窗口策略（COOP）头允许浏览器将一个顶级窗口与其他文档隔离，把它们放在不同的上下文组中，使它们不能直接与顶级窗口交互。如果一个受 COOP 保护的文档打开了一个跨源弹出窗口，该弹出窗口的 `window.opener` 属性将为 `null`。COOP 可以防止跨源攻击。详情请看 安全中间件参考资料中的跨源弹出式窗口策略部分。

## 会话安全

类似于 CSRF 限制 要求一个被部署的网页应让不受信任的用户不能访问任何子域，`django.contrib.sessions` 也有限制。参照 会话主题指南中关于安全的部分 获取更多细节。

## 用户上传内容

Note

考虑 从云服务或 CDN 提供静态文件服务 来避免此类问题。

- If your site accepts file uploads, it is strongly advised that you limit these uploads in your web server configuration to a reasonable size in order to prevent denial of service (DOS) attacks. In Apache, this can be easily set using the LimitRequestBody directive. You should not rely solely on `DATA_UPLOAD_MAX_MEMORY_SIZE` nor `FILE_UPLOAD_MAX_MEMORY_SIZE`.

- 如果您为自己的静态文件提供服务，确保像 Apache 的 `mod_php` 这种能把静态文件当作代码来执行的处理程序已经关闭。您绝不会希望用户能够通过上传并请求特制文件来执行任意的代码。

- 如果媒体文件没有遵循安全性最佳惯例，Django 的媒体上传处理会产生一些漏洞。特别的，如果一个 HTML 文件包含合法的 PNG 格式头部并附加一些恶意的 HTML，它是可以作为一个图片文件上传的。该文件将会通过 Django 用于 `ImageField` 图片处理（Pillow）库的验证。当此文件随后被展示给用户时，它可以被显示为 HTML，这取决于您的服务器类型于配置。

  在框架级别上没有防护技术方案可以安全地验证所有用户上传的文件内容，但是您可以采取其他步骤来减轻这些攻击：

  1. 通过一直为来自不同顶级域名或二级域名的用户提供上传内容可以防御一类的攻击。这可以防止被 same-origin policy 保护机制阻止的任何攻击，比如跨站脚本攻击。例如您的网站是 `example.com`，您应当通过形如 `usercontent-example.com` 的方式来提供上传内容服务（配置 `MEDIA_URL`）。仅仅从像 `usercontent.example.com` 这样的子域提供内容是*不够*的。

  2. 除此之外，应用可以选择定义一个列表来限制允许用户上传的文件的扩展名，并将 Web 服务器配置为仅为此类文件服务。

## Form Submissions

- Form submissions containing files are not limited by `DATA_UPLOAD_MAX_MEMORY_SIZE`. Under ASGI, the entire request may be spooled to disk before any file size validation is performed. It is strongly advised that you limit the maximum request body size in your web server configuration to prevent denial of service (DOS) attacks.

## Content Security Policy

New in Django 6.0.

Content Security Policy (CSP) is a browser security mechanism that helps protect web applications against attacks such as cross-site scripting (XSS) and other content injection attacks.

CSP allows web applications to define which sources of content are trusted, instructing the browser to load, execute, or render resources only from those sources. This effectively creates an allowlist of content origins, reducing the risk of malicious code execution.

Key benefits of enabling CSP include:

1. Mitigating XSS attacks by blocking inline scripts and restricting external script loading.

2. Controlling which external resources (e.g., images, fonts, stylesheets) can be loaded.

3. Preventing unwanted framing of your site to protect against clickjacking.

4. Reporting violations to a specified endpoint, enabling monitoring and debugging.

For configuration instructions, see the Using CSP documentation, and refer to the CSP overview for details on directives and settings.

### Limitations and considerations

While CSP is a powerful security mechanism, it's important to understand its limitations and implications, particularly when used in Django:

- Policy exclusion risks: Avoid excluding specific paths or responses from CSP protection. Due to the browser’s same-origin policy, a vulnerability on an unprotected page (e.g., one allowing arbitrary script injection) may be leveraged to attack protected pages. Excluding any route can significantly weaken the site's overall CSP protection.

- Performance overhead: Although typically negligible, CSP adds some processing overhead. Nonce generation involves secure randomness for each applicable request. For high-traffic applications or resource-constrained environments, measure the performance impact accordingly.

- Browser support: While CSP Levels 1 and 2 are widely supported, newer directives (CSP Level 3+) or complex policy behaviors may vary across browsers. Test your policy across the environments you intend to support.

Despite these limitations, CSP remains an important and recommended security layer for web applications. Understanding its constraints will help you design a more effective and reliable deployment.

## 其他安全性相关主题

虽然 Django 开箱即提供了良好的安全保护，但正确部署你的应用程序并利用网络服务器、操作系统和其他组件的安全保护仍然很重要。

- 确保你的 Python 代码是在网络服务器的根目录之外。这将确保你的 Python 代码不会被意外地作为纯文本提供（或意外地执行）。

- 小心一切 用户上传的文件。

- Django 不会对认证用户的请求进行节流。为了防止针对认证系统的暴力攻击，你可以考虑部署一个 Django 插件或网络服务器模块来节制这些请求。

- 保持您的 `SECRET_KEY`，以及如果正在使用的话，`SECRET_KEY_FALLBACKS` 保持保密。

- 用防火墙限制缓存系统和数据库的可访问性是个好主意。

- 看一下开源 Web 应用安全计划（OWASP） Top 10 list ，它指定了网络应用程序中一些常见的漏洞。尽管 Django 拥有解决某些问题的工具，但在项目设计中必须考虑其他问题。

- Mozilla 讨论了很多与 web security 相关的主题。他们的网页还包括适用于任何系统的安全原则。