Tools for debugging and working with the built-in Flask session cookie
Project description
flask-cookie-decode
###################
.. image:: https://travis-ci.com/wgwz/flask-cookie-decode.svg?branch=master
:target: https://travis-ci.com/wgwz/flask-cookie-decode
.. contents::
.. section-numbering::
Purpose
=======
Adds a ``cookie`` command to the built-in Flask CLI which will provide various
tools for debugging the secure session cookie that Flask uses by default.
Current available commands
--------------------------
1. `flask cookie decode`: decodes and verifies the signature of the session cookie
Background
==========
By default the Flask session uses a signed cookie to store its data. The Flask
application signs the cookie using its ``SECRET_KEY``. This provides the Flask
application a way to detect any tampering to the session data. If the application
is indeed using a secret key and secure hashing algorithm, the session signature
will be unique to application.
For more on the topic of the Flask session see these references:
* `How Secure Is The Flask User Session?`_
* `Quickstart for Flask Sessions`_
* `API Docs for Flask Sessions`_
.. _`How Secure Is The Flask User Session?`: https://blog.miguelgrinberg.com/post/how-secure-is-the-flask-user-session
.. _`Quickstart for Flask Sessions`: http://flask.pocoo.org/docs/1.0/quickstart/#sessions
.. _`API Docs for Flask Sessions`: http://flask.pocoo.org/docs/1.0/api/#sessions
Disclaimer: Keep your SECRET_KEY, secret!
-----------------------------------------
If you expose this key your application becomes vulnerable to session replay
attacks. `Here is an example`_ where an application exposed the ``SECRET_KEY``
during 404 errors. The example also illustrates how session replay works.
By default Flask does not expose the ``SECRET_KEY`` anywhere. It is up to you
the developer to keep it that way!
.. _`Here is an example`: https://terryvogelsang.tech/MITRECTF2018-my-flask-app/
Usage
=====
Installation
------------
.. code-block:: bash
$ pip install flask-cookie-decode
Extracting the cookie using browser tools
-----------------------------------------
.. image:: https://raw.githubusercontent.com/wgwz/flask-cookie-decode/master/docs/cookie.png
:alt: Finding the cookie in browser tools
:width: 100%
:align: center
Example Flask app
-----------------
See `examples/app.py <https://github.com/wgwz/flask-cookie-decode/blob/master/examples/app.py>`_:
.. code-block:: python
from flask import Flask, jsonify, session, request
from flask_cookie_decode import CookieDecode
app = Flask(__name__)
app.config.update({'SECRET_KEY': 'jlghasdghasdhgahsdg'})
cookie = CookieDecode()
cookie.init_app(app)
@app.route('/')
def index():
a = request.args.get('a')
session['a'] = a
return jsonify(dict(session))
Examples using the CLI:
-----------------------
1. A cookie with a valid signature:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
TrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
2. A cookie with an invalid signature:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
UntrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
3. An expired cookie:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
ExpiredCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
Documentation
=============
`Docs <https://flask-cookie-decode.readthedocs.io/en/latest/>`_
License
=======
`MIT <https://github.com/wgwz/flask-cookie-decode/blob/master/LICENSE>`_.
=======
History
=======
.. towncrier release notes start
Flask_Cookie_Decode 0.3.0 (2019-01-05)
======================================
Bugfixes
--------
- In all previous releases the CLI with the ``--timestamp`` CLI flag was actually
returning the timestamp when the cookie was signed. *Not* the timestamp when the
cookie expires, as it should have been doing.
In all previous releases there was no error handling for expired cookies. This
release now returns a ``ExpiredCookie`` when it is detected. (#1)
Improved Documentation
----------------------
- Updates the documentation to include some more details about the way the
Flask session works, and things you should be looking out for from a security
perspective. The documentation also reflects the latest in terms of the way
the CLI works. (#1)
0.1.0 (2018-12-29)
==================
* First release on PyPI.
###################
.. image:: https://travis-ci.com/wgwz/flask-cookie-decode.svg?branch=master
:target: https://travis-ci.com/wgwz/flask-cookie-decode
.. contents::
.. section-numbering::
Purpose
=======
Adds a ``cookie`` command to the built-in Flask CLI which will provide various
tools for debugging the secure session cookie that Flask uses by default.
Current available commands
--------------------------
1. `flask cookie decode`: decodes and verifies the signature of the session cookie
Background
==========
By default the Flask session uses a signed cookie to store its data. The Flask
application signs the cookie using its ``SECRET_KEY``. This provides the Flask
application a way to detect any tampering to the session data. If the application
is indeed using a secret key and secure hashing algorithm, the session signature
will be unique to application.
For more on the topic of the Flask session see these references:
* `How Secure Is The Flask User Session?`_
* `Quickstart for Flask Sessions`_
* `API Docs for Flask Sessions`_
.. _`How Secure Is The Flask User Session?`: https://blog.miguelgrinberg.com/post/how-secure-is-the-flask-user-session
.. _`Quickstart for Flask Sessions`: http://flask.pocoo.org/docs/1.0/quickstart/#sessions
.. _`API Docs for Flask Sessions`: http://flask.pocoo.org/docs/1.0/api/#sessions
Disclaimer: Keep your SECRET_KEY, secret!
-----------------------------------------
If you expose this key your application becomes vulnerable to session replay
attacks. `Here is an example`_ where an application exposed the ``SECRET_KEY``
during 404 errors. The example also illustrates how session replay works.
By default Flask does not expose the ``SECRET_KEY`` anywhere. It is up to you
the developer to keep it that way!
.. _`Here is an example`: https://terryvogelsang.tech/MITRECTF2018-my-flask-app/
Usage
=====
Installation
------------
.. code-block:: bash
$ pip install flask-cookie-decode
Extracting the cookie using browser tools
-----------------------------------------
.. image:: https://raw.githubusercontent.com/wgwz/flask-cookie-decode/master/docs/cookie.png
:alt: Finding the cookie in browser tools
:width: 100%
:align: center
Example Flask app
-----------------
See `examples/app.py <https://github.com/wgwz/flask-cookie-decode/blob/master/examples/app.py>`_:
.. code-block:: python
from flask import Flask, jsonify, session, request
from flask_cookie_decode import CookieDecode
app = Flask(__name__)
app.config.update({'SECRET_KEY': 'jlghasdghasdhgahsdg'})
cookie = CookieDecode()
cookie.init_app(app)
@app.route('/')
def index():
a = request.args.get('a')
session['a'] = a
return jsonify(dict(session))
Examples using the CLI:
-----------------------
1. A cookie with a valid signature:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
TrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
2. A cookie with an invalid signature:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
UntrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
3. An expired cookie:
.. code-block:: bash
$ export FLASK_APP=app.py
$ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
ExpiredCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
Documentation
=============
`Docs <https://flask-cookie-decode.readthedocs.io/en/latest/>`_
License
=======
`MIT <https://github.com/wgwz/flask-cookie-decode/blob/master/LICENSE>`_.
=======
History
=======
.. towncrier release notes start
Flask_Cookie_Decode 0.3.0 (2019-01-05)
======================================
Bugfixes
--------
- In all previous releases the CLI with the ``--timestamp`` CLI flag was actually
returning the timestamp when the cookie was signed. *Not* the timestamp when the
cookie expires, as it should have been doing.
In all previous releases there was no error handling for expired cookies. This
release now returns a ``ExpiredCookie`` when it is detected. (#1)
Improved Documentation
----------------------
- Updates the documentation to include some more details about the way the
Flask session works, and things you should be looking out for from a security
perspective. The documentation also reflects the latest in terms of the way
the CLI works. (#1)
0.1.0 (2018-12-29)
==================
* First release on PyPI.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
flask_cookie_decode-0.3.0.tar.gz
(108.6 kB
view hashes)
Built Distribution
Close
Hashes for flask_cookie_decode-0.3.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 33247386c597e88403ed7d7d838650aa4f1094e85c4a2bed4629ef67af71e922 |
|
MD5 | e71e5f7a270addc3beb64b9ae131d031 |
|
BLAKE2b-256 | 790bbae9c5fce74ce633f5b625ccaab95c473b4766ea2d228777ed6468ebf390 |
Close
Hashes for flask_cookie_decode-0.3.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a90f5e9b5d706577fbe0157fa4b4c8b6873294555982e9ed3d21f2e3d02be85e |
|
MD5 | aa5d9647b410715281d83be626d09eb2 |
|
BLAKE2b-256 | 0518cd65cda43d17f04a71a7d4ec19082fba359a1859ff1df91d9df50024ca9e |