Security models¶
Security views¶
-
security.views.
csp_report
(*args, **kwargs)¶ Collect Content Security Policy reports from browsers. This view has two optional keyword arguments:
csp_save
if True, reports will be saved asCspReport
objects- in database; this table is registered with Django Admin, so they can be later viewed in admin console.
csp_log
if True, reports will be logged through Django logging- facility under
security
class
By default only logging is enabled. To collect reports, this view needs to be added to project’s urls.py. Examples:
Default mode, only logger enable, no database logging:
url(r'^csp-report/$', security.views.csp_report),
Logger and database enabled:
url(r'^csp-report/$', security.views.csp_report, kwargs={'csp_save':True,'csp_log':True}),
-
security.views.
require_ajax
(view)¶ A view decorator which ensures that the request being proccessed by view is an AJAX request. We return a 403 error if the request is not an AJAX request.
Security middleware¶
-
class
security.middleware.
BaseMiddleware
(get_response=None)¶ Abstract class containing some functionality common to all middleware that require configuration.
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
-
class
security.middleware.
ClearSiteDataMiddleware
(get_response=None)¶ Sends Clear-Site-Data HTTP response header on requests that match CLEAR_SITE_DATA_URL_WHITELIST.
Clears browsing data (cookies, storage, cache) associated with the requesting website. Allows web developers to have more control over the data stored locally by a browser for their origins.
Reference:
- Clear-Site-Data: “cache”, “cookies”, “storage”, “executionContexts”, “*” <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data>`_
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_response
(request, response)¶ Add
Clear-Site-Data
response header if request in CLEAR_SITE_DATA_URLS.
-
class
security.middleware.
ContentNoSniff
(get_response=None)¶ Sends X-Content-Options HTTP header to disable autodetection of MIME type of files returned by the server in Microsoft Internet Explorer. Specifically if this flag is enabled, MSIE will not load external CSS and JavaScript files unless server correctly declares their MIME type. This mitigates attacks where web page would for example load a script that was disguised as an user- supplied image.
Note: As of 1.8, Django’s SECURE_CONTENT_TYPE_NOSNIFF controls the X-Content-Type-Options header.
Reference:
-
process_response
(request, response)¶ Add
X-Content-Options: nosniff
to the response header.
-
-
class
security.middleware.
ContentSecurityPolicyMiddleware
(get_response=None)¶ Adds Content Security Policy (CSP) header to HTTP response. CSP provides fine grained instructions to the browser on location of allowed resources loaded by the page, thus mitigating attacks based on loading of untrusted JavaScript code such as Cross-Site Scripting.
The policy can be set in two modes, controlled by
CSP_MODE
options:CSP_MODE='enforce'
browser will enforce policy settings and- log violations (default)
CSP_MODE='report-only'
browser will not enforce policy, only- report violations
The policy itself is a dictionary of content type keys and values containing list of allowed locations. For example,
img-src
specifies locations of images allowed to be loaded by this page:'img-src' : [ 'img.example.com' ]
Content types and special location types (such as
none
orself
) are defined in CSP draft (see References).Example of policy dictionary (suitable for long, complex policies), with all supported content types (but not listing all supported locations):
CSP_DICT = { # arrays of allowed locations "default-src" : ["self", "https:" ], "script-src" : ["self", "http://js.example.com" ], "style-src" : ["self", "http://css.example.com" ], "img-src" : ["self", "https://img.example.com" ], "connect-src" : ["self" ], "font-src" : ["https://*.example.com" ], "object-src" : ["none" ], "media-src" : ["http://media.example.com" ], "frame-src" : ["self" ], # array of allowed sandbox features "sandbox" : [ "" ], # array of allowed MIME types "plugin-types" : [ "application/pdf" ], # these are **not** arrays "reflected-xss" : 'filter', "report-uri" : "http://example.com/csp-report", }
You can also supply a raw policy string, which is more suitable for short policies:
CSP_STRING="default-src 'self'; script-src *.google.com"
If both
CSP_DICT
andCSP_STRING
are set the middleware will throw an exception.Notes:
- The special locations (‘self’, ‘none’, ‘unsafe-eval’, ‘unsafe-inline’) come without the additional single quotes in CSP_DICT and they will be automatically quoted by the middleware in the HTTP header.
- The
CSP_STRING
on the other hand should be a verbatim copy of the HTTP header contents. It’s not going the be processed in any way. - This middleware only sets the standard HTTP header variants
(
Content-Security-Policy
). The experimental ones (X-WebKit-CSP
andContent-Security-Policy
) are now obsolete. - Enabling CSP has significant impact on browser behaviour - for example inline JavaScript is disabled. Read Default Policy Restrictions to see how pages need to be adapted to work under CSP.
- Browsers will log CSP violations in JavaScript console and to a remote
server configured by
report-uri
option. This package provides a view (csp_report) to collect these alerts in your application. They can be then viewed using Django admin interface. For more advanced analytics try CspBuilder. - The middleware partially supports CSP 1.1 draft syntax.
References:
-
process_response
(request, response)¶ Add Content Security Policy policy to the response header. Use either enforcement or report-only headers in all currently used variants.
-
class
security.middleware.
CustomLogoutMixin
¶ If the CUSTOM_LOGOUT_MODULE is set in Django config, import and use that when performing a logout.
-
class
security.middleware.
DoNotTrackMiddleware
(get_response=None)¶ When this middleware is installed Django views can access a new
request.dnt
parameter to check client’s preference on user tracking as expressed by their browser configuration settings.The parameter can take True, False or None values based on the presence of the
Do Not Track
HTTP header in client’s request, which in turn depends on browser’s configuration. The header indicates client’s general preference to opt-out from behavioral profiling and third-party tracking.The parameter does not change behaviour of Django in any way as its sole purpose is to pass the user’s preference to application. It’s then up to the owner to implement a particular policy based on this information. Compliant website should adapt its behaviour depending on one of user’s preferences:
- Explicit opt-out (
request.dnt
isTrue
): Disable third party tracking for this request and delete all previously stored tracking data. - Explicit opt-in (
request.dnt
isFalse
): Website may track user. - Header not present (
request.dnt
isNone
): Website may track user, but should not draw any definite conclusions on user’s preferences as the user has not expressed it.
For example, if
request.dnt
is `` True`` the website might respond by disabling template parts responsible for personalized statistics, targeted advertisements or switching to DNT aware ones.Examples:
- Do Not Track (DNT) tutorial for Django
- Do Not Track - Web Application Templates
- Opt-out of tailoring Twitter
References:
-
process_request
(request)¶ Read DNT header from browser request and create request attribute
-
process_response
(request, response)¶ Echo DNT header in response per section 8.4 of draft-mayer-do-not- track-00
- Explicit opt-out (
-
class
security.middleware.
LoginRequiredMiddleware
(get_response=None)¶ Middleware that requires a user to be authenticated to view any page on the site that hasn’t been white listed. (The middleware also ensures the user is ‘active’. Disabled users will be logged out and redirected to the login page.
Exemptions to this requirement can optionally be specified in settings via a list of regular expressions in LOGIN_EXEMPT_URLS (which you can copy from your urls.py).
Requires authentication middleware and template context processors to be loaded. You’ll get an error if they aren’t.
By default this middleware will call the builtin Django logout function to perform the logout. You can customize which logout function will be called by specifying it in your django settings using the CUSTOM_LOGOUT_MODULE variable. The value should be the module path to the function, e.g. ‘django.contrib.auth.logout’.
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
-
class
security.middleware.
MandatoryPasswordChangeMiddleware
(get_response=None)¶ Redirects any request from an authenticated user to the password change form if that user’s password has expired. Must be placed after
AuthenticationMiddleware
in the middleware list.Configured by dictionary
MANDATORY_PASSWORD_CHANGE
with the following keys:URL_NAME
name of of the password change viewEXEMPT_URL_NAMES
list of URLs that do not trigger password change requestINCLUDE_SUPERUSERS
also check superusers for password change, default False-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
-
class
security.middleware.
NoConfidentialCachingMiddleware
(get_response=None)¶ Adds No-Cache and No-Store headers to confidential pages. You can either whitelist non-confidential pages and treat all others as non-confidential, or specifically blacklist pages as confidential. The behaviour is configured in
NO_CONFIDENTIAL_CACHING
dictionary in settings file with the following keys:WHITELIST_ON
all pages are confifendialt, except for pages- explicitly whitelisted in
WHITELIST_REGEXES
WHITELIST_REGEXES
list of regular expressions defining pages- exempt from the no caching policy
BLACKLIST_ON
only pages defined inBLACKLIST_REGEXES
- will have caching disabled
BLACKLIST_REGEXES
list of regular expressions defining- confidential pages for which caching should be prohibited
Note: Django’s cache_control decorator allows more granular control of caching on individual view level.
Reference:
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_response
(request, response)¶ Add the Cache control no-store to anything confidential. You can either whitelist non-confidential pages and treat all others as non- confidential, or specifically blacklist pages as confidential
-
class
security.middleware.
P3PPolicyMiddleware
(get_response=None)¶ Adds the HTTP header attribute specifying compact P3P policy defined in P3P_COMPACT_POLICY setting and location of full policy defined in P3P_POLICY_URL. If the latter is not defined, a default value is used (/w3c/p3p.xml). The policy file needs to be created by website owner.
Note: P3P work stopped in 2002 and the only popular browser with limited P3P support is MSIE.
Reference:
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_response
(request, response)¶ Add P3P policy to the response header.
-
-
class
security.middleware.
SessionExpiryPolicyMiddleware
(get_response=None)¶ The session expiry middleware will let you expire sessions on browser close, and on expiry times stored in the cookie itself. (Expiring a cookie on browser close means you don’t set the expiry value of the cookie.) The middleware will read SESSION_COOKIE_AGE and SESSION_INACTIVITY_TIMEOUT from the settings.py file to determine how long to keep a session alive.
We will purge a session that has expired. This middleware should be run before the LoginRequired middleware if you want to redirect the expired session to the login page (if required).
Exemptions to this requirement can optionally be specified in settings via a list of regular expressions in SESSION_EXPIRY_EXEMPT_URLS (which you can copy from your urls.py).
By default this middleware will call the builtin Django logout function to perform the logout. You can customize which logout function will be called by specifying it in your django settings using the CUSTOM_LOGOUT_MODULE variable. The value should be the module path to the function, e.g. ‘django.contrib.auth.logout’.
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_request
(request)¶ Verify that the session should be considered active. We check the start time and the last activity time to determine if this is the case. We set the last activity time to now() if the session is still active.
-
-
class
security.middleware.
StrictTransportSecurityMiddleware
(get_response=None)¶ Adds Strict-Transport-Security header to HTTP response that enforces SSL connections on compliant browsers. Two parameters can be set in settings file, otherwise reasonable defaults will be used:
STS_MAX_AGE
time in seconds to preserve host’s STS policy (default: 1 year)STS_INCLUDE_SUBDOMAINS
True if subdomains should be covered by the policy as well (default: True)STS_PRELOAD
addpreload
flag to the STS header so that your website can be added to preloaded websites list
Note: As of 1.8, Django’s SECURE_HSTS_SECONDS controls the HTTP Strict Transport Security header.
Reference:
- `HTTP Strict Transport Security (HSTS)
-
process_response
(request, response)¶ Add Strict-Transport-Security header.
-
security.middleware.
XFrameOptionsDenyMiddleware
¶
-
class
security.middleware.
XFrameOptionsMiddleware
(get_response=None)¶ Emits
X-Frame-Options headers
in HTTP response. These headers will instruct the browser to limit ability of this web page to be framed, or displayed within a FRAME or IFRAME tag. This mitigates password stealing attacks like Clickjacking and similar.Use
X_FRAME_OPTIONS
in settings file with the following values:deny
prohibit any framing of this pagesameorigin
allow frames from the same domain (default)allow-from URL
allow frames from specified URL
Note: Frames and inline frames are frequently used by ads, social media plugins and similar widgets so test these features after setting this flag.
You can exclude certain URLs from this header by setting
X_FRAME_OPTIONS_EXCLUDE_URLS
to a list of URL regexes like so:X_FRAME_OPTIONS_EXCLUDE_URLS = ( r'^/some/url/here$', # Note the initial slash r'^/another/to/exclude$', )
The header will be sent unless
request.path
matches any of the above list. For more granular control, use ContentSecurityPolicyMiddleware.References:
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_response
(request, response)¶ Add X-Frame-Options and Frame-Options to the response header.
-
class
security.middleware.
XssProtectMiddleware
(get_response=None)¶ Sends X-XSS-Protection HTTP header that controls Cross-Site Scripting filter on MSIE. Use XSS_PROTECT option in settings file with the following values:
sanitize
enable XSS filter that tries to sanitize requests instead of blocking (default)on
enable full XSS filter blocking XSS requests (may leak document.referrer)off
completely disable XSS filterNote: As of 1.8, Django’s SECURE_BROWSER_XSS_FILTER controls the X-XSS-Protection header.
Reference:
-
load_setting
(setting, value)¶ Called initially for each of the keys in REQUIRED_SETTINGS and OPTIONAL_SETTINGS, and again whenever any of these settings change (from the setting_changed signal). Passed the setting key and the new value, which may be None for the keys in OPTIONAL_SETTINGS. If no setting keys are defined then this method is never called.
-
process_response
(request, response)¶ Add X-XSS-Protection to the reponse header.
-