flask-talisman
HTTP security headers for Flask.
Rank: #2608Downloads: 2,258,737 (30 days)Stars: 84Forks: 10
Description
Talisman: HTTP security headers for Flask
=========================================
|PyPI Version|
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 <https://developer.mozilla.org/en-US/docs/Web/Security/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 Flask's session cookie to ``Lax``, preventing the cookie to be leaked
in CSRF-prone request methods.
- Sets
`X-Frame-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/X-Frame-Options>`_
to ``SAMEORIGIN`` to avoid
`clickjacking <https://en.wikipedia.org/wiki/Clickjacking>`_.
- Sets `X-Content-Type-Options
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options>`_
to prevent content type sniffing.
- Sets a strict `Content Security
Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`__
of ``default-src: 'self', 'object-src': 'none'``. 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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy>`_
of ``strict-origin-when-cross-origin`` that governs which referrer information should be included with
requests made.
- Disables ``browsing-topics`` by default in the `Permissions-Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy>`_
like `Drupal <https://www.drupal.org/project/drupal/issues/3209628>`_ to enhance privacy protection.
In addition to Talisman, you **should always use a cross-site request
forgery (CSRF) library**. It's highly recommended to use
`Flask-SeaSurf <https://flask-seasurf.readthedocs.org/en/latest/>`_,
which is based on Django's excellent library.
Installation & Basic Usage
--------------------------
Install via `pip <https://pypi.python.org/pypi/pip>`_:
::
pip install flask-talisman
After installing, wrap your Flask app with a ``Talisman``:
.. code:: python
from flask import Flask
from flask_talisman import Talisman
app = Flask(__name__)
Talisman(app)
There is also a full `Example App <https://github.com/wntrblm/flask-talisman/blob/master/example_app>`_.
Options
-------
- ``force_https``, default ``True``, forces all non-debug connects to
``https`` (`about HTTPS <https://developer.mozilla.org/en-US/docs/Glossary/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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_).
- ``strict_transport_security_preload``, default ``False``, enables HSTS
preloading. If you register your application with
`Google's HSTS preload list <https://hstspreload.appspot.com/>`_,
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'`, 'object-src': 'none'``, see the
`Content Security Policy`_ section (`about Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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
<https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy>`_).
- ``feature_policy``, default ``{}``, see the `Feature Policy`_ section (`about Feature Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy>`_).
- ``permissions_policy``, default ``{'browsing-topics': '()'}``, see the `Permissions Policy`_ section (`about Permissions Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy>`_).
- ``document_policy``, default ``{}``, see the `Document Policy`_ section (`about Document Policy <https://wicg.github.io/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 <https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/compatibility/jj542450(v=vs.85)?redirectedfrom=MSDN>`_
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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options>`_).
- ``x_xss_protection``, default ``False``, Protects against cross-site scripting (XSS) attacks (`about XSS Protection <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection>`_). This option is disabled by default because no modern browser (`supports this header <https://caniuse.com/mdn-http_headers_x-xss-protection>`_) anymore.
For a full list of (security) headers, check out: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers.
Per-view options
~~~~~~~~~~~~~~~~
Sometimes you want to change the policy for a specific view. The
``force_https``, ``frame_options``, ``frame_options_allow_from``,
`content_security_policy``, ``feature_policy``, ``permissions_policy``
and ``document_policy`` options can be changed on a per-view basis.
.. code:: python
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.
If you're not ready to deploy Content Security Policy, you can set
`content_security_policy` to `False` to disable sending this header
entirely.
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 <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy>`_:
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) and disallow
legacy HTML elements.
.. code:: python
csp = {
'default-src': '\'self\'',
'object-src': '\'none\'',
}
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.)
.. code:: python
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