Security

Almost every built-in protection is a middleware, so the order of MIDDLEWARE is part of the security configuration (see Middleware for the onion model and The Request/Response Cycle for the full path). The diagram follows a request into the Bookshelf and back out, with the stack shown in The middleware list, with the third-party CORS layer placed before CommonMiddleware (config/settings.py).

Two consequences follow from that layout. First, a response produced by a layer above another (a CORS preflight, an HTTPS redirect) never reaches the layers below it, so those layers' protections do not apply to it, and the layers above can only add headers to what comes back. Second, protections that live in the front-end web server (HTTPS redirect, size limits, Host validation, security headers) also cover the requests Django never sees, such as static files and media, which is why the documentation recommends doing them there when you can and treating Django’s versions as the fallback.

The examples share one small project. The key is read from the environment and never committed; DJANGO_SECRET_KEY can be generated once with python -c "from django.core.management.utils import get_random_secret_key as g; print(g())".

Source: Deployment checklist: SECRET_KEY, Built-in middleware reference

The models that the examples use are a Review with a staff-only featured flag and a Cover image with upload validators.

Source: ImageField, FileExtensionValidator

The golden rule of the security overview is that user-controlled data is never trusted. Django’s tool for that is the forms framework: declare the shape of valid data once, call is_valid(), and use only cleaned_data. Anything that arrives in request.GET, request.POST, request.body, request.FILES, cookies, headers, the URL and even data from web services or the database that a user once supplied is input. The sections below are the specific places where unvalidated input becomes an attack; for forms and validators see Forms and Form Validation and Validators.

The security team applies the same rule when it triages reports: a report that depends on unsanitised input reaching send_mail() or extra() is not a framework vulnerability, because validating input is the developer’s job.

Source: Security in Django: sanitize user input, Security policies: user input must be sanitized

In an XSS attack, script written by an attacker runs in another user’s browser with that user’s privileges: it can read the page, send requests as the user and read anything not marked HttpOnly. The script reaches the victim either stored (a review body saved in the database and shown to every reader) or reflected (a crafted link whose query string is echoed by the page). In Django the primary defence is automatic escaping in the template engine, and the common ways to lose it are mark_safe(), the safe filter, autoescape off, HTML stored in the database and unquoted attributes.

A CSRF attack makes a logged-in user’s browser send a request the user did not intend, for example a hidden form on an attacker’s page that posts to /reviews/new/; the browser attaches the session cookie automatically, so the site cannot tell the request from a real one. Django’s defence has three parts: safe methods must be side-effect free, unsafe methods must carry a secret that the attacker’s page cannot read, and the Origin (or, on HTTPS, Referer) header must come from a trusted origin.

SQL injection happens when user input becomes part of the SQL text instead of a value, letting the attacker change the query. Querysets are protected because the query is built with parameterisation: the SQL text and the parameters travel separately and the driver escapes the parameters. The risk returns with the raw-SQL features and with a few places where the client chooses a field name rather than a value.

The test test_string_formatting_is_injectable shows why formatting is wrong: the same payload that returns nothing through the ORM or params returns every row when the text is spliced into the SQL. The last test sends a hostile sort and a hostile lookup key and gets the normal listing because only allow-listed names are used. For raw(), cursors and transactions see Transactions, Raw SQL and Multiple Databases and for lookups Making Queries.

Source: Security in Django: SQL injection protection, Passing parameters into raw()

In a clickjacking attack a malicious page loads your site in a transparent iframe and lines up a button of yours under a button of its own, so the user’s click performs an action on your site. Browsers honour the X-Frame-Options response header: DENY forbids framing, SAMEORIGIN allows only your own pages to frame it. XFrameOptionsMiddleware adds it to every response that does not already carry one, and it is in the startproject template. The default value comes from X_FRAME_OPTIONS, which defaults to 'DENY'.

Three decorators change the header per view and override the middleware: xframe_options_deny, xframe_options_sameorigin and xframe_options_exempt (which tells the middleware not to add the header, for widgets that other sites must frame). If a form inside a frame must post, or a session cookie must be sent from inside it, you may also need to loosen CSRF_COOKIE_SAMESITE or SESSION_COOKIE_SAMESITE. The decorators wrap async views since 5.0. The header only protects in modern browsers; the Content Security Policy frame-ancestors directive is its modern complement.

Source: Clickjacking protection, X_FRAME_OPTIONS

Without HTTPS an attacker on the network can read credentials and session cookies and alter responses. Any site that lets users log in should enforce HTTPS site-wide (the same session cookie travels over HTTP and HTTPS, so protecting only the login or admin pages is not enough). django.middleware.security.SecurityMiddleware does the Django-side part and should be the first entry of MIDDLEWARE; it is both a request and a response layer (see Where each protection runs in the request cycle). Each feature is enabled by its own setting.

Related settings that make the picture complete: SESSION_COOKIE_SECURE and CSRF_COOKIE_SECURE (both default False; set them so the cookies are never sent over HTTP; sessions and POSTs then fail over plain HTTP, which is fine behind a redirect), SESSION_COOKIE_HTTPONLY (default True) and SESSION_COOKIE_SAMESITE (default 'Lax'; 'Strict' suits pages that must never be reached from a link on another site, 'None' sends the cookie cross-site). Session security is covered on Sessions, Cookies, Messages and Signing.

Django builds absolute URLs (password-reset links, redirects, request.build_absolute_uri()) from the Host header. The header is client-controlled, so a forged value can poison links in emails, caches and CSRF checks. Even a web server that looks like it validates the header often does not (a request can match a default virtual host and still carry a fake Host), so Django validates it itself in HttpRequest.get_host() against ALLOWED_HOSTS, and a mismatch is a SuspiciousOperation that Django turns into a 400 and logs to django.security.DisallowedHost.

A trailing dot in the header (some browsers send it) is stripped before matching. The setting is also checked when running tests, which is why the test client uses testserver (added automatically by the test runner, and the reason the @override_settings(ALLOWED_HOSTS=[…​]) test below sends its own Host). Code that reads request.META["HTTP_HOST"] directly bypasses the validation: always call request.get_host().

Against the development server with ALLOWED_HOSTS set to localhost,127.0.0.1 the same attack is rejected:

Also configure the web server in front of Django to answer unknown hosts itself (for example nginx’s default server returning 444), so bad requests do not fill the Django logs, and never rely on the server alone.

Source: Security in Django: Host header validation, ALLOWED_HOSTS

Uploads are the largest attack surface of many sites: denial of service by size, code execution if the web server interprets the file, stored XSS if the browser renders it as HTML, path traversal through the file name. Django’s upload machinery (see File Uploads and Storage) helps, but the security overview is candid that no framework-level check can prove arbitrary content is safe.

Mass assignment happens when a form or serializer binds every field a client sends to a model, so a reader can set featured=on, is_staff=on or author=1 simply by adding a parameter. In Django the cause is almost always a ModelForm whose Meta uses fields = "all" or exclude, and a Django REST framework serializer with fields = "all". The fix is an explicit allow-list of fields, and server-side assignment of everything the user must not choose.

The review_create view above saves with commit=False and sets review.author = request.user itself.

exclude is a deny-list, so a field added to the model next year is silently exposed; fields is an allow-list, so it is not. Django (since 1.8) refuses a ModelForm that sets neither, which is why fields = "all" has to be spelled out and is easy to find in a review. For APIs the same rule applies: list the serializer fields, mark server-owned fields read-only, and use different serializers for create and for staff; a viewset that returns every customer’s orders because nothing scopes its queryset is the same class of bug at the row level (see Permissions and Authorization and Model Forms and Formsets). Do not expose sequential primary keys for resources that need to stay private; authorise every object access, or use a non-guessable identifier in addition.

Source: ModelForm: selecting the fields to use

A login or logout view that redirects to a next parameter without checking it lets an attacker send users to a look-alike site from a link on your domain. django.utils.http.url_has_allowed_host_and_scheme(url, allowed_hosts, require_https=False) returns True only for relative URLs and absolute ones whose host is in allowed_hosts; it also rejects javascript: and protocol-relative //host URLs. Django’s own LoginView and LogoutView use it; use it in every view that redirects to client-supplied data. Pass require_https=request.is_secure() so a secure page cannot be redirected to plain HTTP. The function is named in the 3.0 release notes (where it replaced the private is_safe_url()) but is not listed in the utilities reference, so the signature and behaviour described here were checked against the 6.1.1 source and the test below rather than a reference page; treat it as a stable helper that the framework itself relies on.

The same discipline covers server-side requests made with a client-supplied URL. A feature such as "import a cover from this URL" is server-side request forgery: restrict the scheme and host to an allow-list, resolve and check the address against private ranges, and set timeouts and a size cap. Django does not offer a helper for this.

Source: Django 3.0 release notes: url_has_allowed_host_and_scheme(), LoginView

Source: Deployment checklist, SECRET_KEY_FALLBACKS, Error reporting

The browser’s same-origin policy stops a page on one origin from reading responses from another. Cross-Origin Resource Sharing (CORS) is the opt-in: the API answers with Access-Control-Allow-Origin and related headers. Django has no built-in CORS support; the community package django-cors-headers (4.9.0, PyPI classifiers up to Django 6.0, installed and run here with 6.1.1) is the usual choice. The protocol, the preflight and the common mistakes are explained on CORS; this section covers only the Django configuration.

Add "corsheaders" to INSTALLED_APPS and corsheaders.middleware.CorsMiddleware to MIDDLEWARE as high as possible, and in particular before any middleware that can generate responses, such as CommonMiddleware (and WhiteNoise’s middleware, if you use it), otherwise redirects and error responses lack the headers. The middleware answers preflight (OPTIONS with Access-Control-Request-Method) requests itself, so they never reach the view or CSRF middleware, and adds Vary: Origin to enabled responses.

CORS and CSRF solve different problems. CORS only controls which origins' scripts may read responses; it does not stop a cross-site form post, which the browser sends anyway. A cross-origin AJAX client that authenticates with the session cookie therefore needs all of: the origin in CORS_ALLOWED_ORIGINS, CORS_ALLOW_CREDENTIALS = True, the same origin in CSRF_TRUSTED_ORIGINS (with its scheme), an appropriate SameSite cookie setting and the X-CSRFToken header; the test_trusted_origin_is_accepted test above exercises the CSRF half. The middleware is both sync and async capable.

Source: django-cors-headers, django-cors-headers on PyPI, Security in Django: CORS

Security failures are logged to dedicated loggers: django.security.csrf for CSRF rejections and one django.security.<ExceptionName> logger per SuspiciousOperation subtype (DisallowedHost, RequestDataTooBig, TooManyFields, SuspiciousFileOperation, and so on). A SuspiciousOperation that ends in a 400 is logged to the security logger only, not to django.request. By default these events reach the django logger, which mails ADMINS when DEBUG is False; route them to your log pipeline and alert on spikes instead, and silence a noisy one with a NullHandler and propagate: False for that single logger name.

The tests above use assertLogs("django.security.csrf"), assertLogs("django.security.DisallowedHost") and assertLogs("django.security.RequestDataTooBig") to assert that the events are emitted. Do not log secrets: request bodies, tokens and cookies must stay out of log records, and the include_html option of AdminEmailHandler sends full tracebacks with settings, so enable it only for trusted recipients.

Source: django.security loggers, Logging

manage.py check --deploy adds the deployment checks to the normal system checks and is the quickest automated review of the settings above. Run it against the production settings module, not the development one, in CI, with the production environment variables set. --fail-level WARNING makes warnings fail the command (the default fails only on errors), --tag security restricts it to one tag, --list-tags --deploy lists tags (including deployment-only ones such as security) and --database runs the database checks for the named aliases.

With the development settings and DJANGO_DEBUG=1 the command reports five security warnings:

With the production module the output is clean, and a weak key is caught:

A passing check is not a security audit: it cannot know that a proxy strips X-Forwarded-Proto, that your upload directory is not executable, or that a view forgets authorisation. Silence a warning only with a comment explaining who provides the protection instead (SILENCED_SYSTEM_CHECKS = ["security.W008"] when the load balancer redirects).

Source: django-admin check, System check framework: security, Deployment checklist

Django treats security as a first-class release type, and an application inherits that only if it upgrades.

Source: Django 6.1 release notes, 6.0, 5.1, 5.0, 4.1, 4.0, 3.1, 3.0 and 1.8

The books that informed this section were written for Django releases between 1.11 and 5.x; the security advice in them is mostly sound, but several specifics have moved on.