flask-cookie-decode
###################
.. list-table::
* - .. image:: https://github.com/wgwz/flask-cookie-decode/actions/workflows/action.yml/badge.svg
:target: https://github.com/wgwz/flask-cookie-decode/actions
:alt: Github Build Status
* - .. image:: https://readthedocs.org/projects/flask-cookie-decode/badge/?version=latest
:target: https://flask-cookie-decode.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. 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
.. _`Flask Session Cookie Decoder`: https://www.kirsle.net/wizards/flask-session.cgi
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:
-----------------------
This extension will ship two CLI interfaces for dealing with decoding cookies. One requires a Flask application instance for the application you are wanting to debug. This method has the added benefit that the signature of the cookie can be verified, as your application instance has the ``SECRET_KEY`` used to sign the cookie. This method returns decoded cookie objects which can be seen in the examples below. This method can return a few different types of cookie objects depending on the state of the cookie. Please keep in mind that this extension provides only a thin-wrapper around the logic Flask uses to deal with cookies.
The second CLI interface is a tool for decoding cookies without the app secret. It cannot validate the signatures on the cookies or check the expirations and does not require the application instance like the other CLI. Intended for debugging purposes only.
CLI attached to application instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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')
CLI that ships with package which only decodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
$ fcd decode eyJhIjoiYXNkYXNkamtqYXNkIn0
{
"a": "asdasdjkjasd"
}
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.4.1 (2024-03-17)
======================================
Chores
------
- Added a github action that runs a test suite with variety of Python and Flask versions.
The github action also builds and deploys the package to Pypi. (actions)
Flask_Cookie_Decode 0.4.0 (2023-06-23)
======================================
Bugfixes
--------
- remove dependency on flask.helpers.total_seconds (#13)
Flask_Cookie_Decode 0.3.2 (2019-11-29)
======================================
Bugfixes
--------
- The `fcd` client now handles compressed cookies. (#10)
Flask_Cookie_Decode 0.3.1 (2019-11-29)
======================================
Features
--------
- Add the `fcd` CLI for reading cookies without a flask app. (#8)
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/wgwz/flask-cookie-decode",
"name": "flask-cookie-decode",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "flask_cookie_decode",
"author": "Kyle Lawlor",
"author_email": "klawlor419@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a4/8b/36e5754b8029cb0e324e9faad07cc32302c77f875d39031bcdf28ab07aa7/flask_cookie_decode-0.4.1.tar.gz",
"platform": null,
"description": "flask-cookie-decode\n###################\n\n.. list-table::\n\n * - .. image:: https://github.com/wgwz/flask-cookie-decode/actions/workflows/action.yml/badge.svg\n :target: https://github.com/wgwz/flask-cookie-decode/actions\n :alt: Github Build Status\n \n * - .. image:: https://readthedocs.org/projects/flask-cookie-decode/badge/?version=latest\n :target: https://flask-cookie-decode.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. contents::\n\n.. section-numbering::\n\nPurpose\n=======\n\nAdds a ``cookie`` command to the built-in Flask CLI which will provide various\ntools for debugging the secure session cookie that Flask uses by default.\n\nCurrent available commands\n--------------------------\n\n1. `flask cookie decode`: decodes and verifies the signature of the session cookie\n\nBackground\n==========\n\nBy default the Flask session uses a signed cookie to store its data. The Flask\napplication signs the cookie using its ``SECRET_KEY``. This provides the Flask\napplication a way to detect any tampering to the session data. If the application\nis indeed using a secret key and secure hashing algorithm, the session signature\nwill be unique to application.\n\nFor more on the topic of the Flask session see these references:\n\n* `How Secure Is The Flask User Session?`_\n* `Quickstart for Flask Sessions`_\n* `API Docs for Flask Sessions`_\n\n.. _`How Secure Is The Flask User Session?`: https://blog.miguelgrinberg.com/post/how-secure-is-the-flask-user-session\n.. _`Quickstart for Flask Sessions`: http://flask.pocoo.org/docs/1.0/quickstart/#sessions\n.. _`API Docs for Flask Sessions`: http://flask.pocoo.org/docs/1.0/api/#sessions\n.. _`Flask Session Cookie Decoder`: https://www.kirsle.net/wizards/flask-session.cgi\n\nDisclaimer: Keep your SECRET_KEY, secret!\n-----------------------------------------\n\nIf you expose this key your application becomes vulnerable to session replay\nattacks. `Here is an example`_ where an application exposed the ``SECRET_KEY``\nduring 404 errors. The example also illustrates how session replay works.\n\nBy default Flask does not expose the ``SECRET_KEY`` anywhere. It is up to you\nthe developer to keep it that way!\n\n.. _`Here is an example`: https://terryvogelsang.tech/MITRECTF2018-my-flask-app/\n\nUsage\n=====\n\nInstallation\n------------\n\n.. code-block:: bash\n\n $ pip install flask-cookie-decode\n\nExtracting the cookie using browser tools\n-----------------------------------------\n\n.. image:: https://raw.githubusercontent.com/wgwz/flask-cookie-decode/master/docs/cookie.png\n :alt: Finding the cookie in browser tools\n :width: 100%\n :align: center\n\nExample Flask app\n-----------------\n\nSee `examples/app.py <https://github.com/wgwz/flask-cookie-decode/blob/master/examples/app.py>`_:\n\n.. code-block:: python\n\n from flask import Flask, jsonify, session, request\n from flask_cookie_decode import CookieDecode\n\n app = Flask(__name__)\n app.config.update({'SECRET_KEY': 'jlghasdghasdhgahsdg'})\n cookie = CookieDecode()\n cookie.init_app(app)\n\n @app.route('/')\n def index():\n a = request.args.get('a')\n session['a'] = a\n return jsonify(dict(session))\n\nExamples using the CLI:\n-----------------------\n\nThis extension will ship two CLI interfaces for dealing with decoding cookies. One requires a Flask application instance for the application you are wanting to debug. This method has the added benefit that the signature of the cookie can be verified, as your application instance has the ``SECRET_KEY`` used to sign the cookie. This method returns decoded cookie objects which can be seen in the examples below. This method can return a few different types of cookie objects depending on the state of the cookie. Please keep in mind that this extension provides only a thin-wrapper around the logic Flask uses to deal with cookies.\n\nThe second CLI interface is a tool for decoding cookies without the app secret. It cannot validate the signatures on the cookies or check the expirations and does not require the application instance like the other CLI. Intended for debugging purposes only.\n\nCLI attached to application instance\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n1. A cookie with a valid signature:\n\n.. code-block:: bash\n\n $ export FLASK_APP=app.py\n $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA\n TrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')\n\n2. A cookie with an invalid signature:\n\n.. code-block:: bash\n\n $ export FLASK_APP=app.py\n $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA\n UntrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')\n\n3. An expired cookie:\n\n.. code-block:: bash\n\n $ export FLASK_APP=app.py\n $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA\n ExpiredCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')\n\nCLI that ships with package which only decodes\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: bash\n\n $ fcd decode eyJhIjoiYXNkYXNkamtqYXNkIn0\n {\n \"a\": \"asdasdjkjasd\"\n }\n\nDocumentation\n=============\n\n`Docs <https://flask-cookie-decode.readthedocs.io/en/latest/>`_\n\nLicense\n=======\n\n`MIT <https://github.com/wgwz/flask-cookie-decode/blob/master/LICENSE>`_.\n\n\nHistory\n#######\n\n.. towncrier release notes start\n\nFlask_Cookie_Decode 0.4.1 (2024-03-17)\n======================================\n\nChores\n------\n\n- Added a github action that runs a test suite with variety of Python and Flask versions.\n The github action also builds and deploys the package to Pypi. (actions)\n\n\nFlask_Cookie_Decode 0.4.0 (2023-06-23)\n======================================\n\nBugfixes\n--------\n\n- remove dependency on flask.helpers.total_seconds (#13)\n\n\nFlask_Cookie_Decode 0.3.2 (2019-11-29)\n======================================\n\nBugfixes\n--------\n\n- The `fcd` client now handles compressed cookies. (#10)\n\n\nFlask_Cookie_Decode 0.3.1 (2019-11-29)\n======================================\n\nFeatures\n--------\n\n- Add the `fcd` CLI for reading cookies without a flask app. (#8)\n\n\nFlask_Cookie_Decode 0.3.0 (2019-01-05)\n======================================\n\nBugfixes\n--------\n\n- In all previous releases the CLI with the ``--timestamp`` CLI flag was actually\n returning the timestamp when the cookie was signed. *Not* the timestamp when the\n cookie expires, as it should have been doing.\n\n In all previous releases there was no error handling for expired cookies. This\n release now returns a ``ExpiredCookie`` when it is detected. (#1)\n\n\nImproved Documentation\n----------------------\n\n- Updates the documentation to include some more details about the way the\n Flask session works, and things you should be looking out for from a security\n perspective. The documentation also reflects the latest in terms of the way\n the CLI works. (#1)\n\n\n0.1.0 (2018-12-29)\n==================\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Tools for debugging and working with the built-in Flask session cookie",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/wgwz/flask-cookie-decode"
},
"split_keywords": [
"flask_cookie_decode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73ae5ef16bc2092880eefae2843aa9d3f946dd7a034b6292042e2748ad3b328c",
"md5": "23e8086b52697b18995021063dd7590e",
"sha256": "e40c9d4709564bb4cdfc913f6eb263537d0027ad2076ad66e2953bd270672a56"
},
"downloads": -1,
"filename": "flask_cookie_decode-0.4.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "23e8086b52697b18995021063dd7590e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 7964,
"upload_time": "2024-03-17T16:07:18",
"upload_time_iso_8601": "2024-03-17T16:07:18.432427Z",
"url": "https://files.pythonhosted.org/packages/73/ae/5ef16bc2092880eefae2843aa9d3f946dd7a034b6292042e2748ad3b328c/flask_cookie_decode-0.4.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a48b36e5754b8029cb0e324e9faad07cc32302c77f875d39031bcdf28ab07aa7",
"md5": "25bfc7e27e876713c81ac97432c184d4",
"sha256": "d12e8c41458e86c06c1c8789f81c94e4470fd04cb27c75e9221348c1336499cd"
},
"downloads": -1,
"filename": "flask_cookie_decode-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "25bfc7e27e876713c81ac97432c184d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 113737,
"upload_time": "2024-03-17T16:07:20",
"upload_time_iso_8601": "2024-03-17T16:07:20.221356Z",
"url": "https://files.pythonhosted.org/packages/a4/8b/36e5754b8029cb0e324e9faad07cc32302c77f875d39031bcdf28ab07aa7/flask_cookie_decode-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-17 16:07:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wgwz",
"github_project": "flask-cookie-decode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "flask-cookie-decode"
}
JSON
