flask-talisman 0.8.1

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

• force_https, default True, forces all non-debug connects to https (about HTTPS).

• force_https_permanent, default False, uses 301 instead of 302 for https redirects.

• frame_options, default SAMEORIGIN, can be SAMEORIGIN, DENY, or ALLOWFROM (about Frame Options).

• frame_options_allow_from, default None, a string indicating the domains that are allowed to embed the site via iframe.

• strict_transport_security, default True, whether to send HSTS headers (about HSTS).

• strict_transport_security_preload, default False, 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, default ONE_YEAR_IN_SECS, length of time the browser will respect the HSTS header.

• strict_transport_security_include_subdomains, default True, whether subdomains should also use HSTS.

• content_security_policy, default default-src: 'self', see the Content Security Policy section (about Content Security Policy).

• 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, default False, 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 the content_security_policy_report_uri parameter

• content_security_policy_report_uri, default None, a string indicating the report URI used for CSP violation reports

• referrer_policy, default strict-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) (about Referrer Policy).

• feature_policy, default {}, see the Feature Policy section (about Feature Policy).

• permissions_policy, default {'interest-cohort': '()'}, see the Permissions Policy section (about Permissions Policy).

• document_policy, default {}, see the Document Policy section (about Document Policy).

• session_cookie_secure, default True, set the session cookie to secure, preventing it from being sent over plain http (about cookies (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)_).

• session_cookie_http_only, default True, set the session cookie to httponly, preventing it from being read by JavaScript.

• session_cookie_samesite, default Lax, set this to Strict to prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.

• force_file_save, default False, whether to set the X-Download-Options header to noopen to prevent IE >= 8 to from opening file downloads directly and only save them instead.

• x_content_type_options, default True, Protects against MIME sniffing vulnerabilities (about Content Type Options).

• x_xss_protection, default True, Protects against cross-site scripting (XSS) attacks (about XSS Protection).

For a full list of (security) headers, check out: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers.

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:

csp = {
    'default-src': '\'self\''
}
talisman = Talisman(app, content_security_policy=csp)

csp = {
    'default-src': [
        '\'self\'',
        '*.trusted.com'
    ]
}

csp = {
    'default-src': '\'self\'',
    'img-src': '*',
    'media-src': [
        'media1.com',
        'media2.com',
    ],
    'script-src': 'userscripts.example.com'
}

csp = {
    'default-src': 'https://onlinebanking.jumbobank.com'
}

csp = {
    'default-src': [
        '\'self\'',
        '*.mailsite.com',
    ],
    'img-src': '*'
}

csp = {
    'default-src': '\'self\'',
    'script-src': '\'self\'',
}
talisman = Talisman(
    app,
    content_security_policy=csp,
    content_security_policy_nonce_in=['script-src']
)

<script nonce="{{ csp_nonce() }}">
    //...
</script>

export CSP_DIRECTIVES="default-src 'self'; image-src *"
python app.py

import os
from flask_talisman import Talisman, DEFAULT_CSP_POLICY

talisman = Talisman(
    app,
    content_security_policy=os.environ.get("CSP_DIRECTIVES", DEFAULT_CSP_POLICY),
)

Feature Policy

Note: Feature Policy has largely been renamed Permissions Policy in the latest draft and some features are likely to move to Document Policy. At this writing, most browsers support the Feature-Policy HTTP Header name. See the Permissions Policy and Document Policy sections below should you wish to set these.

Also note that the Feature Policy specification did not progress beyond the draft https://wicg.github.io/feature-policy/ stage before being renamed, but is supported in some form in most browsers.

The default feature policy is empty, as this is the default expected behaviour.

feature_policy = {
    'geolocation': '\'none\''
}
talisman = Talisman(app, feature_policy=feature_policy)

Permissions Policy

Feature Policy has been split into Permissions Policy and Document Policy but at this writing browser support of Permissions Policy is very limited, and it is recommended to still set the Feature-Policy HTTP Header. Permission Policy support is included in Talisman for when this becomes more widely supported.

Note that the Permission Policy is still an Working Draft.

When the same feature or permission is set in both Feature Policy and Permission Policy, the Permission Policy setting will take precedence in browsers that support both.

It should be noted that the syntax differs between Feature Policy and Permission Policy as can be seen from the geolocation examples provided.

The default Permissions Policy is interest-cohort=(), which opts sites out of Federated Learning of Cohorts an interest-based advertising initiative.

Permission Policy can be set either using a dictionary, or using a string.

permission_policy = {
    'geolocation': '()',
    'microphone': '()'
}
talisman = Talisman(app, permission_policy=permission_policy)

permission_policy = 'geolocation=(), microphone=()'
talisman = Talisman(app, permission_policy=permission_policy)

Document Policy

Feature Policy has been split into Permissions Policy and Document Policy but at this writing browser support of Document Policy is very limited, and it is recommended to still set the Feature-Policy HTTP Header. Document Policy support is included in Talisman for when this becomes more widely supported.

Note that the Document Policy is still an Unofficial Draft.

The default Document Policy is empty, as this is the default expected behaviour.

Document Policy can be set either using a dictionary, or using a string.

document_policy = {
    'oversized-images': '?0'
}
talisman = Talisman(app, document_policy=document_policy)

document_policy = 'oversized-images=?0'
talisman = Talisman(app, document_policy=document_policy)

Disclaimer

This code originated at Google, but is not an official Google product, experimental or otherwise. It was forked on June 6th, 2021 from the unmaintained GoogleCloudPlatform/flask-talisman.

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