Talisman: HTTP security headers for Flask
Talisman is a small Flask extension that handles setting HTTP headers that can help protect against a few common web application security issues.
The default configuration:
- Forces all connects to
https, unless running with debug enabled. - Enables HTTP Strict Transport Security.
- Sets Flask's session cookie to
secure, so it will never be set if your application is somehow accessed via a non-secure connection. - Sets Flask's session cookie to
httponly, preventing JavaScript from being able to access its content. CSRF via Ajax uses a separate cookie and should be unaffected. - Sets X-Frame-Options to
SAMEORIGINto avoid clickjacking. - Sets X-XSS-Protection to enable a cross site scripting filter for IE and Safari (note Chrome has removed this and Firefox never supported it).
- Sets X-Content-Type-Options to prevent content type sniffing.
- Sets a strict Content Security Policy of
default-src: 'self'. This is intended to almost completely prevent Cross Site Scripting (XSS) attacks. This is probably the only setting that you should reasonably change. See the Content Security Policy section. - Sets a strict Referrer-Policy of
strict-origin-when-cross-originthat governs which referrer information should be included with requests made.
In addition to Talisman, you should always use a cross-site request forgery (CSRF) library. It's highly recommended to use Flask-SeaSurf, which is based on Django's excellent library.
Installation & Basic Usage
Install via pip:
pip install flask-talisman
After installing, wrap your Flask app with a Talisman:
from flask import Flask
from flask_talisman import Talisman
app = Flask(__name__)
Talisman(app)
There is also a full Example App.
Options
feature_policy, default{}, see the Feature Policy section.force_https, defaultTrue, forces all non-debug connects tohttps.force_https_permanent, defaultFalse, uses301instead of302forhttpsredirects.frame_options, defaultSAMEORIGIN, can beSAMEORIGIN,DENY, orALLOWFROM.frame_options_allow_from, defaultNone, a string indicating the domains that are allowed to embed the site via iframe.strict_transport_security, defaultTrue, whether to send HSTS headers.strict_transport_security_preload, defaultFalse, enables HSTS preloading If you register your application with Google's HSTS preload list, Firefox and Chrome will never load your site over a non-secure connection.strict_transport_security_max_age, defaultONE_YEAR_IN_SECS, length of time the browser will respect the HSTS header.strict_transport_security_include_subdomains, defaultTrue, whether subdomains should also use HSTS.content_security_policy, defaultdefault-src: 'self', see the Content Security Policy section.content_security_policy_nonce_in, default[]. Adds a per-request nonce value to the flask request object and also to the specified CSP header section. I.e.['script-src', 'style-src']content_security_policy_report_only, defaultFalse, whether to set the CSP header as "report-only" (as Content-Security-Policy-Report-Only) to ease deployment by disabling the policy enforcement by the browser, requires passing a value with thecontent_security_policy_report_uriparametercontent_security_policy_report_uri, defaultNone, a string indicating the report URI used for CSP violation reportsreferrer_policy, defaultstrict-origin-when-cross-origin, a string that sets the Referrer Policy header to send a full URL when performing a same-origin request, only send the origin of the document to an equally secure destination (HTTPS->HTTPS), and send no header to a less secure destination (HTTPS->HTTP).session_cookie_secure, defaultTrue, set the session cookie tosecure, preventing it from being sent over plainhttp.session_cookie_http_only, defaultTrue, set the session cookie tohttponly, preventing it from being read by JavaScript.force_file_save, defaultFalse, whether to set the X-Download-Options header tonoopento prevent IE >= 8 to from opening file downloads directly and only save them instead.
Per-view options
Sometimes you want to change the policy for a specific view. The force_https, frame_options, frame_options_allow_from, and content_security_policy options can be changed on a per-view basis.
from flask import Flask
from flask_talisman import Talisman, ALLOW_FROM
app = Flask(__name__)
talisman = Talisman(app)
@app.route('/normal')
def normal():
return 'Normal'
@app.route('/embeddable')
@talisman(frame_options=ALLOW_FROM, frame_options_allow_from='*')
def embeddable():
return 'Embeddable'
Content Security Policy
The default content security policy is extremely strict and will prevent loading any resources that are not in the same domain as the application. Most web applications will need to change this policy.
A slightly more permissive policy is available at flask_talisman.GOOGLE_CSP_POLICY, which allows loading Google-hosted JS libraries, fonts, and embeding media from YouTube and Maps.
You can and should create your own policy to suit your site's needs. Here's a few examples adapted from MDN:
Example 1
This is the default policy. A web site administrator wants all content to come from the site's own origin (this excludes subdomains.)
csp = {
'default-src': '\'self\''
}
talisman = Talisman(app, content_security_policy=csp)
Example 2
A web site administrator wants to allow content from a trusted domain and all its subdomains (it doesn't have to be the same domain that the CSP is set on.)
csp = {
'default-src': [
'\'self\'',
'*.trusted.com'
]
}
Example 3
A web site administrator wants to allow users of a web application to include images from any origin in their own content, but to restrict audio or video media to trusted providers, and all scripts only to a specific server that hosts trusted code.
csp = {
'default-src': '\'self\'',
'img-src': '*',
'media-src': [
'media1.com',
'media2.com',
],
'script-src': 'userscripts.example.com'
}
In this example content is only permitted from the document's origin with the following exceptions:
- Images may loaded from anywhere (note the
*wildcard). - Media is only allowed from media1.com and media2.com (and not from subdomains of those sites).
- Executable script is only allowed from userscripts.example.com.
Example 4
A web site administrator for an online banking site wants to ensure that all its content is loaded using SSL, in order to prevent attackers from eavesdropping on requests.
csp = {
'default-src': 'https://onlinebanking.jumbobank.com'
}
The server only permits access to documents being loaded specifically over HTTPS through the single origin onlinebanking.jumbobank.com.
Example 5
A web site administrator of a web mail site wants to allow HTML in email, as well as images loaded from anywhere, but not JavaScript or other potentially dangerous content.
csp = {
'default-src': [
'\'self\'',
'*.mailsite.com',
],
'img-src': '*'
}
Note that this example doesn't specify a script-src; with the example CSP, this site uses the setting specified by the default-src directive, which means that scripts can be loaded only from the originating server.
Example 6
A web site administrator wants to allow embedded scripts (which might be generated dynamicially).
csp = {
'default-src': '\'self\'',
'script-src': '\'self\'',
}
talisman = Talisman(
app,
content_security_policy=csp,
content_security_policy_nonce_in=['script-src']
)
The nonce needs to be added to the script tag in the template:
<script nonce="{{ csp_nonce() }}">
//...
</script>
Note that the CSP directive (script-src in the example) to which the nonce-... source should be added needs to be defined explicitly.
Example 7
A web site adminstrator wants to override the CSP directives via an environment variable which doesn't support specifying the policy as a Python dictionary, e.g.:
export CSP_DIRECTIVES="default-src 'self'; image-src *"
python app.py
Then in the app code you can read the CSP directives from the environment:
import os
from flask_talisman import Talisman, DEFAULT_CSP_POLICY
talisman = Talisman(
app,
content_security_policy=os.environ.get("CSP_DIRECTIVES", DEFAULT_CSP_POLICY),
)
As you can see above the policy can be defined simply just like the official specification requires the HTTP header to be set: As a semicolon separated list of individual CSP directives.
Feature Policy
The default feature policy is empty, as this is the default expected behaviour. Note that the Feature Policy is still a draft https://wicg.github.io/feature-policy/ but is supported in some form in most browsers. Please note this has been renamed Permissions Policy in the latest draft by at this writing, browsers and this extension only supports the Feature-Policy HTTP Header name.
Geolocation Example
Disable access to Geolocation interface.
feature_policy = {
'geolocation': '\'none\''
}
talisman = Talisman(app, feature_policy=feature_policy)
Disclaimer
This is not an official Google product, experimental or otherwise.
There is no silver bullet for web application security. Talisman can help, but security is more than just setting a few headers. Any public-facing web application should have a comprehensive approach to security.
Contributing changes
- See CONTRIBUTING.md
Licensing
- Apache 2.0 - See LICENSE
![[FR] option to remove 'Server' from resp header](https://avatars.githubusercontent.com/u/4163396?v=4)
1 Nov 10, 2021
118 Dec 24, 2022
2 Jan 22, 2022
2.1k Dec 25, 2022
462 Jan 02, 2023
14 Sep 30, 2022
635 Dec 20, 2022
12 Sep 01, 2022
3 Dec 13, 2021
10 Oct 06, 2022
1k Jan 04, 2023
133 Dec 24, 2022
![Trewis [work] Scotch](https://avatars.githubusercontent.com/u/92666826?v=4&s=60)
4 Sep 23, 2022
17 Nov 30, 2022
1 Dec 09, 2021
41 Dec 30, 2022
1 Jan 14, 2022
2.5k Jan 07, 2023
4 Jun 30, 2022
2 Dec 20, 2022