flask-unsign

Unsign Flask session cookies

TLDR

Decode a Flask session cookie

$ flask-unsign [[-d|--decode]] [[-c|--cookie]] [cookie]

Decode a session cookie fetched from a URL which returns a Set-Cookie header

$ flask-unsign [[-d|--decode]] --server [URL]

Brute-force a secret key using the default flask-unsign-wordlist (requires flask-unsign-wordlist)

$ flask-unsign [[-u|--unsign]] [[-c|--cookie]] [cookie]

Brute-force a secret key with a custom wordlist (use --no-literal-eval for unquoted entries)

$ flask-unsign [[-u|--unsign]] [[-c|--cookie]] [cookie] [[-w|--wordlist]] [path/to/wordlist.txt]

Sign a new session cookie with a secret key

$ flask-unsign [[-s|--sign]] [[-c|--cookie]] "[{'logged_in': False]}" [[-S|--secret]] [secret]

Sign a session cookie using legacy timestamp (useful for old versions)

$ flask-unsign [[-s|--sign]] [[-c|--cookie]] "[{'logged_in': False]}" [[-S|--secret]] [secret] [[-l|--legacy]]

Brute-force a session cookie with custom threads and no literal evaluation

-h, --help
    Show help message and exit.

-d, --dump
    Dump parsed contents of the signed cookie.

-s, --sign
    Sign provided data as a new cookie.

-u, --unsign
    Unsign/decode the provided cookie.

-S SECRET, --secret SECRET
    Specify the secret key for signing/unsigning.

--with-creds
    Crack secret using known app credentials.

-c CREDS, --creds CREDS
    Path to credentials file for cracking.

-w WORDLIST, --wordlist WORDLIST
    Wordlist file for brute-force secret cracking.

--no-bruteforce
    Disable automatic brute-force attempts.

-a, --all
    Try cracking against all known popular Flask secrets.

-D, --decode
    Base64-decode the cookie payload.

DESCRIPTION

flask-unsign is a Python-based command-line utility designed to manipulate signed data structures used by the Flask web framework, particularly cookies and sessions. Flask signs these with a secret key using its own algorithm (a variant of itsdangerous), preventing tampering. This tool enables users to unsign (decrypt/parse) cookies if the secret is known, sign new data to forge valid cookies, or crack the secret key via brute-force attacks using wordlists or known credentials.

It supports dumping cookie contents for inspection, base64 decoding, and cracking against popular Flask secrets. Primarily used by security researchers and penetration testers to assess session security in Flask applications, identify weak secrets, or forge sessions for vulnerability testing (e.g., privilege escalation).

Installation is via pip install flask-unsign. It leverages Python's cryptography libraries and does not require root privileges. While powerful for ethical hacking, misuse for unauthorized access violates laws like the CFAA.

CAVEATS

Tool requires Python 3 and pip install flask-unsign; not a native binary. Brute-forcing can be CPU-intensive and time-consuming for strong secrets. Intended for authorized security testing only—unauthorized use is illegal. May trigger antivirus false positives.

INSTALLATION

pip install flask-unsign or clone repo and pip install -r requirements.txt.

EXAMPLE

Unsign: flask-unsign --unsign --secret 'dev' 'eyJ...'
Crack: flask-unsign --with-creds --creds creds.txt 'eyJ...'

HISTORY

Developed by GitHub user tikubonn in 2018 as an open-source tool (https://github.com/tikubonn/flask-unsign). Gained popularity in bug bounty and pentest communities for Flask app assessments. Initial versions focused on basic unsigning; later added brute-force and creds-based cracking. Actively maintained with Python 3 support.