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 content, but to restrict
audio or video media to trusted providers, and all scripts only to a
specific server that hosts trusted code.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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).
.. code:: python
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:
.. code:: html
<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.:
.. code:: bash
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:
.. code:: python
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
--------------
**Note:** Feature Policy has largely been `renamed Permissions Policy <https://github.com/w3c/webappsec-feature-policy/issues/359>`_
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
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy#Browser_compatibility>`_.
The default feature policy is empty, as this is the default expected behaviour.
Geolocation Example
~~~~~~~~~~~~~~~~~~~
Disable access to Geolocation interface.
.. code:: python
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 <https://caniuse.com/permissions-policy>`_,
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 <https://www.w3.org/TR/permissions-policy/>`_.
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 ``browsing-topics=()``, which opts sites out of
`Federated Learning of Cohorts <https://wicg.github.io/floc/>`_ an interest-based advertising initiative
called Topics API.
Permission Policy can be set either using a dictionary, or using a string.
Geolocation and Microphone Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Disable access to Geolocation interface and Microphone using dictionary syntax
.. code:: python
permissions_policy = {
'geolocation': '()',
'microphone': '()'
}
talisman = Talisman(app, permissions_policy=permissions_policy)
Disable access to Geolocation interface and Microphone using string syntax
.. code:: python
permissions_policy = 'geolocation=(), microphone=()'
talisman = Talisman(app, permissions_policy=permissions_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 <https://caniuse.com/document-policy>`_,
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 <https://wicg.github.io/document-policy/>`_.
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.
Oversized-Images Example
~~~~~~~~~~~~~~~~~~~~~~~~
Forbid oversized-images using dictionary syntax:
.. code:: python
document_policy = {
'oversized-images': '?0'
}
talisman = Talisman(app, document_policy=document_policy)
Forbid oversized-images using string syntax:
.. code:: python
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`_
.. _LICENSE: https://github.com/wntrblm/flask-talisman/blob/master/LICENSE
.. _CONTRIBUTING.md: https://github.com/wntrblm/flask-talisman/blob/master/CONTRIBUTING.md
.. |PyPI Version| image:: https://img.shields.io/pypi/v/flask-talisman.svg
:target: https://pypi.python.org/pypi/flask-talisman
Raw data
{
"_id": null,
"home_page": "https://github.com/wntrblm/flask-talisman",
"name": "flask-talisman",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "flask security https xss",
"author": "Alethea Katherine Flowers",
"author_email": "me@thea.codes",
"download_url": "https://files.pythonhosted.org/packages/38/5c/157d51e32eaffdb34ee316261239937d66400a57cd8146176fd8ce50c43a/flask-talisman-1.1.0.tar.gz",
"platform": null,
"description": "Talisman: HTTP security headers for Flask\n=========================================\n\n|PyPI Version|\n\nTalisman is a small Flask extension that handles setting HTTP headers\nthat can help protect against a few common web application security\nissues.\n\nThe default configuration:\n\n- Forces all connects to ``https``, unless running with debug enabled.\n- Enables `HTTP Strict Transport\n Security <https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security>`_.\n- Sets Flask's session cookie to ``secure``, so it will never be set if\n your application is somehow accessed via a non-secure connection.\n- Sets Flask's session cookie to ``httponly``, preventing JavaScript\n from being able to access its content. CSRF via Ajax uses a separate\n cookie and should be unaffected.\n- Sets Flask's session cookie to ``Lax``, preventing the cookie to be leaked\n in CSRF-prone request methods.\n- Sets\n `X-Frame-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/X-Frame-Options>`_\n to ``SAMEORIGIN`` to avoid\n `clickjacking <https://en.wikipedia.org/wiki/Clickjacking>`_.\n- Sets `X-Content-Type-Options\n <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options>`_\n to prevent content type sniffing.\n- Sets a strict `Content Security\n Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy>`__\n of ``default-src: 'self', 'object-src': 'none'``. This is intended to almost completely\n prevent Cross Site Scripting (XSS) attacks. This is probably the only\n setting that you should reasonably change. See the\n `Content Security Policy`_ section.\n- Sets a strict `Referrer-Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy>`_\n of ``strict-origin-when-cross-origin`` that governs which referrer information should be included with\n requests made.\n- Disables ``browsing-topics`` by default in the `Permissions-Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy>`_\n like `Drupal <https://www.drupal.org/project/drupal/issues/3209628>`_ to enhance privacy protection.\n\n\nIn addition to Talisman, you **should always use a cross-site request\nforgery (CSRF) library**. It's highly recommended to use\n`Flask-SeaSurf <https://flask-seasurf.readthedocs.org/en/latest/>`_,\nwhich is based on Django's excellent library.\n\nInstallation & Basic Usage\n--------------------------\n\nInstall via `pip <https://pypi.python.org/pypi/pip>`_:\n\n::\n\n pip install flask-talisman\n\nAfter installing, wrap your Flask app with a ``Talisman``:\n\n.. code:: python\n\n from flask import Flask\n from flask_talisman import Talisman\n\n app = Flask(__name__)\n Talisman(app)\n\n\nThere is also a full `Example App <https://github.com/wntrblm/flask-talisman/blob/master/example_app>`_.\n\nOptions\n-------\n\n- ``force_https``, default ``True``, forces all non-debug connects to\n ``https`` (`about HTTPS <https://developer.mozilla.org/en-US/docs/Glossary/https>`_).\n- ``force_https_permanent``, default ``False``, uses ``301`` instead of\n ``302`` for ``https`` redirects.\n\n- ``frame_options``, default ``SAMEORIGIN``, can be ``SAMEORIGIN``,\n ``DENY``, or ``ALLOWFROM`` (`about Frame Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options>`_).\n- ``frame_options_allow_from``, default ``None``, a string indicating\n the domains that are allowed to embed the site via iframe.\n\n- ``strict_transport_security``, default ``True``, whether to send HSTS\n headers (`about HSTS <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_).\n- ``strict_transport_security_preload``, default ``False``, enables HSTS\n preloading. If you register your application with\n `Google's HSTS preload list <https://hstspreload.appspot.com/>`_,\n Firefox and Chrome will never load your site over a non-secure\n connection.\n- ``strict_transport_security_max_age``, default ``ONE_YEAR_IN_SECS``,\n length of time the browser will respect the HSTS header.\n- ``strict_transport_security_include_subdomains``, default ``True``,\n whether subdomains should also use HSTS.\n\n- ``content_security_policy``, default ``default-src: 'self'`, 'object-src': 'none'``, see the\n `Content Security Policy`_ section (`about Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy>`_).\n- ``content_security_policy_nonce_in``, default ``[]``. Adds a per-request nonce\n value to the flask request object and also to the specified CSP header section.\n I.e. ``['script-src', 'style-src']``\n- ``content_security_policy_report_only``, default ``False``, whether to set\n the CSP header as \"report-only\" (as `Content-Security-Policy-Report-Only`)\n to ease deployment by disabling the policy enforcement by the browser,\n requires passing a value with the ``content_security_policy_report_uri``\n parameter\n- ``content_security_policy_report_uri``, default ``None``, a string\n indicating the report URI used for `CSP violation reports\n <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_CSP_violation_reports>`_\n\n- ``referrer_policy``, default ``strict-origin-when-cross-origin``, a string\n that sets the Referrer Policy header to send a full URL when performing a same-origin\n request, only send the origin of the document to an equally secure destination\n (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>`_).\n\n- ``feature_policy``, default ``{}``, see the `Feature Policy`_ section (`about Feature Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy>`_).\n\n- ``permissions_policy``, default ``{'browsing-topics': '()'}``, see the `Permissions Policy`_ section (`about Permissions Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy>`_).\n- ``document_policy``, default ``{}``, see the `Document Policy`_ section (`about Document Policy <https://wicg.github.io/document-policy/>`_).\n\n- ``session_cookie_secure``, default ``True``, set the session cookie\n to ``secure``, preventing it from being sent over plain ``http`` (`about cookies (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)_`).\n- ``session_cookie_http_only``, default ``True``, set the session\n cookie to ``httponly``, preventing it from being read by JavaScript.\n- ``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.\n\n\n- ``force_file_save``, default ``False``, whether to set the\n `X-Download-Options <https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/compatibility/jj542450(v=vs.85)?redirectedfrom=MSDN>`_\n header to ``noopen`` to prevent IE >= 8 to from opening file downloads\n directly and only save them instead.\n\n- ``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>`_).\n- ``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.\n\nFor a full list of (security) headers, check out: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers.\n\nPer-view options\n~~~~~~~~~~~~~~~~\n\nSometimes you want to change the policy for a specific view. The\n``force_https``, ``frame_options``, ``frame_options_allow_from``,\n`content_security_policy``, ``feature_policy``, ``permissions_policy``\nand ``document_policy`` options can be changed on a per-view basis.\n\n.. code:: python\n\n from flask import Flask\n from flask_talisman import Talisman, ALLOW_FROM\n\n app = Flask(__name__)\n talisman = Talisman(app)\n\n @app.route('/normal')\n def normal():\n return 'Normal'\n\n @app.route('/embeddable')\n @talisman(frame_options=ALLOW_FROM, frame_options_allow_from='*')\n def embeddable():\n return 'Embeddable'\n\nContent Security Policy\n-----------------------\n\nThe default content security policy is extremely strict and will\nprevent loading any resources that are not in the same domain as the\napplication. Most web applications will need to change this policy.\nIf you're not ready to deploy Content Security Policy, you can set\n`content_security_policy` to `False` to disable sending this header\nentirely.\n\nA slightly more permissive policy is available at\n``flask_talisman.GOOGLE_CSP_POLICY``, which allows loading Google-hosted JS\nlibraries, fonts, and embeding media from YouTube and Maps.\n\nYou can and should create your own policy to suit your site's needs.\nHere's a few examples adapted from\n`MDN <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy>`_:\n\nExample 1\n~~~~~~~~~\n\nThis is the default policy. A web site administrator wants all content\nto come from the site's own origin (this excludes subdomains) and disallow\nlegacy HTML elements.\n\n.. code:: python\n\n csp = {\n 'default-src': '\\'self\\'',\n 'object-src': '\\'none\\'',\n }\n talisman = Talisman(app, content_security_policy=csp)\n\nExample 2\n~~~~~~~~~\n\nA web site administrator wants to allow content from a trusted domain\nand all its subdomains (it doesn't have to be the same domain that the\nCSP is set on.)\n\n.. code:: python\n\n csp = {\n 'default-src': [\n '\\'self\\'',\n '*.trusted.com'\n ]\n }\n\nExample 3\n~~~~~~~~~\n\nA web site administrator wants to allow users of a web application to\ninclude images from any origin in their own content, but to restrict\naudio or video media to trusted providers, and all scripts only to a\nspecific server that hosts trusted code.\n\n.. code:: python\n\n csp = {\n 'default-src': '\\'self\\'',\n 'img-src': '*',\n 'media-src': [\n 'media1.com',\n 'media2.com',\n ],\n 'script-src': 'userscripts.example.com'\n }\n\nIn this example content is only permitted from the document's origin\nwith the following exceptions:\n\n- Images may loaded from anywhere (note the ``*`` wildcard).\n- Media is only allowed from media1.com and media2.com (and not from\n subdomains of those sites).\n- Executable script is only allowed from userscripts.example.com.\n\nExample 4\n~~~~~~~~~\n\nA web site administrator for an online banking site wants to ensure that\nall its content is loaded using SSL, in order to prevent attackers from\neavesdropping on requests.\n\n.. code:: python\n\n csp = {\n 'default-src': 'https://onlinebanking.jumbobank.com'\n }\n\nThe server only permits access to documents being loaded specifically\nover HTTPS through the single origin onlinebanking.jumbobank.com.\n\nExample 5\n~~~~~~~~~\n\nA web site administrator of a web mail site wants to allow HTML in\nemail, as well as images loaded from anywhere, but not JavaScript or\nother potentially dangerous content.\n\n.. code:: python\n\n csp = {\n 'default-src': [\n '\\'self\\'',\n '*.mailsite.com',\n ],\n 'img-src': '*'\n }\n\nNote that this example doesn't specify a ``script-src``; with the\nexample CSP, this site uses the setting specified by the ``default-src``\ndirective, which means that scripts can be loaded only from the\noriginating server.\n\nExample 6\n~~~~~~~~~\n\nA web site administrator wants to allow embedded scripts (which might\nbe generated dynamicially).\n\n.. code:: python\n\n csp = {\n 'default-src': '\\'self\\'',\n 'script-src': '\\'self\\'',\n }\n talisman = Talisman(\n app,\n content_security_policy=csp,\n content_security_policy_nonce_in=['script-src']\n )\n\nThe nonce needs to be added to the script tag in the template:\n\n.. code:: html\n\n <script nonce=\"{{ csp_nonce() }}\">\n //...\n </script>\n\nNote that the CSP directive (`script-src` in the example) to which the `nonce-...`\nsource should be added needs to be defined explicitly.\n\nExample 7\n~~~~~~~~~\n\nA web site adminstrator wants to override the CSP directives via an\nenvironment variable which doesn't support specifying the policy as\na Python dictionary, e.g.:\n\n.. code:: bash\n\n export CSP_DIRECTIVES=\"default-src 'self'; image-src *\"\n python app.py\n\nThen in the app code you can read the CSP directives from the environment:\n\n.. code:: python\n\n import os\n from flask_talisman import Talisman, DEFAULT_CSP_POLICY\n\n talisman = Talisman(\n app,\n content_security_policy=os.environ.get(\"CSP_DIRECTIVES\", DEFAULT_CSP_POLICY),\n )\n\nAs you can see above the policy can be defined simply just like the official\nspecification requires the HTTP header to be set: As a semicolon separated\nlist of individual CSP directives.\n\nFeature Policy\n--------------\n\n**Note:** Feature Policy has largely been `renamed Permissions Policy <https://github.com/w3c/webappsec-feature-policy/issues/359>`_\nin the latest draft and some features are likely to move to Document Policy.\nAt this writing, most browsers support the ``Feature-Policy`` HTTP Header name.\nSee the `Permissions Policy`_ and `Document Policy`_ sections below should you wish\nto set these.\n\nAlso note that the Feature Policy specification did not progress beyond the `draft https://wicg.github.io/feature-policy/`\nstage before being renamed, but is `supported in some form in most browsers\n<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy#Browser_compatibility>`_.\n\nThe default feature policy is empty, as this is the default expected behaviour.\n\nGeolocation Example\n~~~~~~~~~~~~~~~~~~~\n\nDisable access to Geolocation interface.\n\n.. code:: python\n\n feature_policy = {\n 'geolocation': '\\'none\\''\n }\n talisman = Talisman(app, feature_policy=feature_policy)\n\nPermissions Policy\n------------------\n\nFeature Policy has been split into Permissions Policy and Document Policy but\nat this writing `browser support of Permissions Policy is very limited <https://caniuse.com/permissions-policy>`_,\nand it is recommended to still set the ``Feature-Policy`` HTTP Header.\nPermission Policy support is included in Talisman for when this becomes more\nwidely supported.\n\nNote that the `Permission Policy is still an Working Draft <https://www.w3.org/TR/permissions-policy/>`_.\n\nWhen the same feature or permission is set in both Feature Policy and Permission Policy,\nthe Permission Policy setting will take precedence in browsers that support both.\n\nIt should be noted that the syntax differs between Feature Policy and Permission Policy\nas can be seen from the ``geolocation`` examples provided.\n\nThe default Permissions Policy is ``browsing-topics=()``, which opts sites out of\n`Federated Learning of Cohorts <https://wicg.github.io/floc/>`_ an interest-based advertising initiative\ncalled Topics API.\n\nPermission Policy can be set either using a dictionary, or using a string.\n\nGeolocation and Microphone Example\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDisable access to Geolocation interface and Microphone using dictionary syntax\n\n.. code:: python\n\n permissions_policy = {\n 'geolocation': '()',\n 'microphone': '()'\n }\n talisman = Talisman(app, permissions_policy=permissions_policy)\n\nDisable access to Geolocation interface and Microphone using string syntax\n\n.. code:: python\n\n permissions_policy = 'geolocation=(), microphone=()'\n talisman = Talisman(app, permissions_policy=permissions_policy)\n\nDocument Policy\n---------------\n\nFeature Policy has been split into Permissions Policy and Document Policy but\nat this writing `browser support of Document Policy is very limited <https://caniuse.com/document-policy>`_,\nand it is recommended to still set the ``Feature-Policy`` HTTP Header.\nDocument Policy support is included in Talisman for when this becomes more\nwidely supported.\n\nNote that the `Document Policy is still an Unofficial Draft <https://wicg.github.io/document-policy/>`_.\n\nThe default Document Policy is empty, as this is the default expected behaviour.\n\nDocument Policy can be set either using a dictionary, or using a string.\n\nOversized-Images Example\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nForbid oversized-images using dictionary syntax:\n\n.. code:: python\n\n document_policy = {\n 'oversized-images': '?0'\n }\n talisman = Talisman(app, document_policy=document_policy)\n\nForbid oversized-images using string syntax:\n\n.. code:: python\n\n document_policy = 'oversized-images=?0'\n talisman = Talisman(app, document_policy=document_policy)\n\nDisclaimer\n----------\n\nThis code originated at Google, but is not an official Google product,\nexperimental or otherwise. It was forked on June 6th, 2021 from the\nunmaintained GoogleCloudPlatform/flask-talisman.\n\nThere is no silver bullet for web application security. Talisman can\nhelp, but security is more than just setting a few headers. Any\npublic-facing web application should have a comprehensive approach to\nsecurity.\n\n\nContributing changes\n--------------------\n\n- See `CONTRIBUTING.md`_\n\nLicensing\n---------\n\n- Apache 2.0 - See `LICENSE`_\n\n.. _LICENSE: https://github.com/wntrblm/flask-talisman/blob/master/LICENSE\n.. _CONTRIBUTING.md: https://github.com/wntrblm/flask-talisman/blob/master/CONTRIBUTING.md\n.. |PyPI Version| image:: https://img.shields.io/pypi/v/flask-talisman.svg\n :target: https://pypi.python.org/pypi/flask-talisman\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "HTTP security headers for Flask.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/wntrblm/flask-talisman"
},
"split_keywords": [
"flask",
"security",
"https",
"xss"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "771ca15ac936dc3ae4491c5ff089dccdccd72cd3608b15fcf4e2de961f9ee8f3",
"md5": "0e3b0af81149d9d0118e86b91bddc706",
"sha256": "3c42b610ebe49b0e35ca150e179bf51aa1da01e4635b49a674868ea681046208"
},
"downloads": -1,
"filename": "flask_talisman-1.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e3b0af81149d9d0118e86b91bddc706",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 18967,
"upload_time": "2023-08-03T12:00:26",
"upload_time_iso_8601": "2023-08-03T12:00:26.041909Z",
"url": "https://files.pythonhosted.org/packages/77/1c/a15ac936dc3ae4491c5ff089dccdccd72cd3608b15fcf4e2de961f9ee8f3/flask_talisman-1.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "385c157d51e32eaffdb34ee316261239937d66400a57cd8146176fd8ce50c43a",
"md5": "cb2d73108c81bc6e9687843055f97905",
"sha256": "c5f486f5f54420729f84b3c3850cd63f96e8b033a9629bee66c524ea363797ff"
},
"downloads": -1,
"filename": "flask-talisman-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cb2d73108c81bc6e9687843055f97905",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22656,
"upload_time": "2023-08-03T12:00:28",
"upload_time_iso_8601": "2023-08-03T12:00:28.090693Z",
"url": "https://files.pythonhosted.org/packages/38/5c/157d51e32eaffdb34ee316261239937d66400a57cd8146176fd8ce50c43a/flask-talisman-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-03 12:00:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wntrblm",
"github_project": "flask-talisman",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flask-talisman"
}
JSON
