Flask-SeaSurf

SeaSurf is a Flask extension for preventing cross-site request forgery (CSRF).

CSRF vulnerabilities have been found in large and popular sites such as YouTube. These attacks are problematic because the mechanism they use is relatively easy to exploit. This extension attempts to aid you in securing your application from such attacks.

This extension is based on the excellent Django middleware.

Installation

Install the extension with one of the following commands:

$ easy_install flask-seasurf

or alternatively if you have pip installed:

$ pip install flask-seasurf

Usage

Using SeaSurf is fairly straightforward. Begin by importing the extension and then passing your application object back to the extension, like this:

import Flask
from flask.ext.seasurf import SeaSurf

app = Flask(__name__)
csrf = SeaSurf(app)

This extension is configurable via a set of configuration variables which can we added to the Flask app’s config file. The cookie name, cookie timeout, and CSRF disable parameters may be set via CSRF_COOKIE_NAME, CSRF_COOKIE_TIMEOUT, and CSRF_DISABLE, respectively.

Corrosponding code will need to be added to the templates where POST, PUT, and DELETE HTTP methods are anticipated. In the case of POST requests a hidden field should be added, something like this:

<form method="POST">
    ...
    <input type="hidden" name="_csrf_token" value="{{ csrf_token() }}">
</form>

The extension adds a global function to the Jinja template engine called csrf_token. This is a function that retrieves the current token and will be matched against the request token.

By default all requests that are not GET, HEAD, OPTIONS, or TRACE are validated against the CSRF token sent by the client and as rendered on the page. However a view may be completely exempted from validation using the exempt decorator. For instance it’s possible to decorate a view as shown below:

@csrf.exempt
@app.route('/exempt_view', methods=['POST'])
def exempt_view():
    '''This view is exempted from CSRF validation.'''
    return 'foobar'

AJAX Usage

AJAX is not exempted from CSRF validation as it is a plausible vector for cross-site request forgery. As such, POSTing with AJAX can make use of the aforementioned method, but other HTTP methods, such as PUT and DELETE might be better suited to using the X-CSRFToken header instead.

Essentially this header is passed back to the backend by way of extrating the token from the cookie using JavaScript. For a better explanation of how this might be done please refer to the Django CSRF documentation.

Flask-WTForms Usage

If you would like to use Flask-Seasurf with a form generator, such as WTForms, it is possible to do so. Below is a simple example.

First we will define a custom SeaSurfForm object in a seasurf_form module like so:

from flask.ext.wtf import Form, HiddenField
from flask import g

# import your app here
from your_project import app


class SeaSurfForm(Form):
    @staticmethod
    @app.before_request
    def add_csrf():
        csrf_name = app.config.get('CSRF_COOKIE_NAME', '_csrf_token')
        setattr(SeaSurfForm,
                csrf_name,
                HiddenField(default=getattr(g, csrf_name)))

Now assume we define a module forms as such:

from flask.ext.wtf import DataRequired, TextField, PasswordField, Email
from seasurf_form import SeaSurfForm


class LoginForm(SeaSurfForm):
    email = TextField('email', validators=[DataRequired(), Email()])
    password = PasswordField('password', validators=[DataRequired()])

This is the basis of our login form which we will serve up in a view to the user. Finally we can use this in our template login.html:

<form method="POST" action="{{ url_for('login') }}">
    {{ form.hidden_tag() }}

    <p>
        {{form.email.label }} {{ form.email(size=50) }}
    </p>
    <p>
        {{form.password.label }} {{ form.password(size=50) }}
    </p>
    <p>
        <input type="submit" value="Login">
    </p>
</form>

API

class flask_seasurf.SeaSurf(app=None)

Primary class container for CSRF validation logic. The main function of this extension is to generate and validate CSRF tokens. The design and implementation of this extension is influenced by Django’s CSRF middleware.

Tokens are generated using a salted SHA1 hash. The salt is based off a a random range. The OS’s SystemRandom is used if available, otherwise the core random.randrange is used.

You might intialize SeaSurf something like this:

csrf = SeaSurf(app)

Validation will now be active for all requests whose methods are not GET, HEAD, OPTIONS, or TRACE.

When using other request methods, such as POST for instance, you will need to provide the CSRF token as a parameter. This can be achieved by making use of the Jinja global. In your template:

<form method="POST">
...
<input type="hidden" name="_csrf_token" value="{{ csrf_token() }}">
</form>

This will assign a token to both the session cookie and the rendered HTML which will then be validated on the backend. POST requests missing this field will fail unless the header X-CSRFToken is specified.

Excluding Views From Validation

For views that use methods which may be validated but for which you wish to not run validation on you may make use of the exempt decorator to indicate that they should not be checked.

Parameters:app – The Flask application object, defaults to None.
exempt(view)

A decorator that can be used to exclude a view from CSRF validation.

Example usage of exempt might look something like this:

csrf = SeaSurf(app)

@csrf.exempt
@app.route('/some_view')
def some_view():
    """This view is exempt from CSRF validation."""
    return render_template('some_view.html')
Parameters:view – The view to be wrapped by the decorator.
include(view)

A decorator that can be used to include a view from CSRF validation.

Example usage of include might look something like this:

csrf = SeaSurf(app)

@csrf.include
@app.route('/some_view')
def some_view():
    """This view is include from CSRF validation."""
    return render_template('some_view.html')
Parameters:view – The view to be wrapped by the decorator.
init_app(app)

Initializes a Flask object app, binds CSRF validation to app.before_request, and assigns csrf_token as a Jinja global.

Parameters:app – The Flask application object.
Fork me on GitHub