search

GoogleCloudPlatform / flask-talisman

HTTP security headers for Flask
Apache License 2.0
920 stars 85 forks source link

readme

Talisman: HTTP security headers for Flask

|Build Status| |Coverage Status| |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:

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/GoogleCloudPlatform/flask-talisman/blob/master/example_app>_.

Options

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.

.. 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.

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.)

.. code:: python

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.)

.. 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:

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

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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy#Browser_compatibility>. Please note this has been renamed Permissions Policy <https://github.com/w3c/webappsec-feature-policy/issues/359> 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.

.. code:: python

    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`_

.. _LICENSE: https://github.com/GoogleCloudPlatform/flask-talisman/blob/master/LICENSE
.. _CONTRIBUTING.md: https://github.com/GoogleCloudPlatform/flask-talisman/blob/master/CONTRIBUTING.md
.. |Build Status| image:: https://travis-ci.org/GoogleCloudPlatform/flask-talisman.svg
   :target: https://travis-ci.org/GoogleCloudPlatform/flask-talisman
.. |Coverage Status| image:: https://coveralls.io/repos/GoogleCloudPlatform/flask-talisman/badge.svg
   :target: https://coveralls.io/r/GoogleCloudPlatform/flask-talisman
.. |PyPI Version| image:: https://img.shields.io/pypi/v/flask-talisman.svg
   :target: https://pypi.python.org/pypi/flask-talisman