PyFu

Insecure Flask Debug Mode and PIN Bypass

Python-based Web Application Attacks

Flask’s debug mode provides developers with an interactive debugger that activates when an unhandled exception occurs. While invaluable during development, enabling debug mode in production exposes a critical security vulnerability that can lead to remote code execution.

When debug=True is set, Flask enables the Werkzeug debugger which provides an interactive Python console directly in the browser. This console is protected by a PIN code that is generated at application startup and displayed in the server console.

The Debug Mode Vulnerability

The vulnerability exists in how Flask applications are initialized. Consider the following code:

from flask import Flask, request

app = Flask(__name__)

# Simulated sensitive data
SECRET_API_KEY = "sk-prod-api-key-abc123xyz"
DATABASE_PASSWORD = "SuperSecretDBPass!"

@app.route('/')
def index():
    return "Welcome to the application"

@app.route('/user/<username>')
def get_user(username):
    # Vulnerable: no input validation leads to potential error
    user_id = int(username)  # Will crash if username is not numeric
    return f"User ID: {user_id}"

if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=5000)

The critical line is:

app.run(debug=True, host='0.0.0.0', port=5000)

When debug=True is passed to app.run(), Flask enables the Werkzeug interactive debugger. Any unhandled exception in the application will render a detailed traceback page with an interactive console.

How the Debugger Gets Enabled

Flask’s run() method accepts a debug parameter that controls the debugger behavior:

def run(self, host=None, port=None, debug=None, ...):

When debug=True:

  1. The Werkzeug debugger middleware wraps the application
  2. Detailed tracebacks are displayed on errors
  3. An interactive Python console becomes available at each stack frame
  4. A PIN is generated and printed to the console for “protection”

The PIN generation happens in Werkzeug and is displayed when the server starts:

 * Debugger is active!
 * Debugger PIN: 123-456-789

Exploiting the Debug Console

When an error occurs in the vulnerable application, such as visiting /user/notanumber, the debugger page appears. Each frame in the traceback has a small console icon that opens an interactive Python shell.

Once the PIN is entered, the attacker has full Python code execution in the context of the running application:

# Access application secrets
import os
os.environ.get('SECRET_KEY')

# Read sensitive files
open('/etc/passwd').read()

# Execute system commands
import subprocess
subprocess.check_output(['whoami'])

# Access application variables
app.config

PIN Bypass Through Code Analysis

The Werkzeug PIN is generated using predictable values that can be obtained if an attacker has file read access or information disclosure vulnerabilities. The PIN calculation uses:

# Values used in PIN generation (Werkzeug source)
probably_public_bits = [
    username,           # Username running the server
    modname,            # Usually 'flask.app'
    getattr(app, '__name__', app.__class__.__name__),  # Usually 'Flask'
    getattr(mod, '__file__', None),  # Path to flask/app.py
]

private_bits = [
    str(uuid.getnode()),  # MAC address as integer
    get_machine_id(),     # Machine ID from /etc/machine-id or similar
]

If an attacker can read /etc/machine-id and determine the MAC address (from /sys/class/net/eth0/address), they can calculate the PIN without needing console access.

Common Insecure Patterns

Debug mode often gets enabled through environment variables or configuration mistakes:

# Pattern 1: Hardcoded debug=True
app.run(debug=True)

# Pattern 2: Environment variable without default safety
app.run(debug=os.environ.get('DEBUG'))  # Any truthy value enables it

# Pattern 3: Configuration file with debug enabled
app.config['DEBUG'] = True
app.run()

# Pattern 4: Using Flask's environment variable
# FLASK_DEBUG=1 in environment enables debug mode

Why Flask debug mode matters from an offensive security perspective

A reachable Werkzeug debugger is one of the highest-value findings I can get on a Flask target, because it is a browser-based Python console running inside the application process. Once I am in, I do not pivot through a constrained web context. I have os, subprocess, the app config, the secret key, environment variables, and every connection the worker holds. The console is gated by a PIN, but the PIN is derived from host data (username, machine-id, a MAC address, and module file paths), so any file-read or information-disclosure primitive on the same host lets me reconstruct it offline. The traceback page is also a recon gift on its own, because it leaks source, local variable values, and the full environment before I have any code execution at all.

This finding shows up far more than it should, usually from a config slip rather than a deliberate choice. I watch for these tells:

  • A detailed traceback page with the Werkzeug branding instead of a generic 500, which tells me the debugger is live.
  • A small console icon on each stack frame and a ?__debugger__=yes request that returns 200, confirming the interactive console is reachable.
  • debug=True, app.config['DEBUG'] = True, or FLASK_DEBUG=1 in source, deploy scripts, or container env, often hidden behind a truthy environment variable with no production default.
  • The dev server (app.run()) answering directly rather than a WSGI server like Gunicorn or uWSGI behind it.

The defender takeaway: an error page that renders a traceback in production is a code execution surface, so force debug=False and serve behind a real WSGI server. Once a debugger console or PIN is in reach this becomes full code execution, the same outcome as Insecure Dynamic Code Evaluation and Execution in Python.

Proof of exploitation

Run the lab app (PyFuLabs/flask-fu/flask-debug-pin), which starts Flask with debug=True. Any unhandled exception (the / route divides by zero) serves Werkzeug’s interactive debugger instead of a generic 500:

curl -s http://pyfu.local/flask-fu/flask-debug-pin/ \
  | grep -o "Werkzeug Debugger\|The debugger caught an exception\|console is locked"

The debugger caught an exception
Werkzeug Debugger
console is locked

The traceback page carries an interactive Python console (?__debugger__=yes&cmd=resource&f=debugger.js returns 200). That console is gated by a PIN derived from predictable host data (the username, machine-id, a network MAC, and module paths), so an attacker who can read those values, often through a file-read primitive on the same host, reconstructs the PIN offline and gains code execution in the running process.

Mitigation

Never enable debug mode in production:

# Safe: explicitly disable debug
app.run(debug=False, host='0.0.0.0', port=5000)

# Safe: use environment check
import os
app.run(debug=os.environ.get('FLASK_ENV') == 'development', host='0.0.0.0', port=5000)

# Safe: use production WSGI server instead of Flask's built-in server
# gunicorn -w 4 app:app

For production deployments, use a proper WSGI server like Gunicorn or uWSGI instead of Flask’s built-in development server.