fix: disable debug=True / Werkzeug debugger exposure (closes #9)

[timon0305]

Problem

app.py was hard-coding debug=True in its app.run(...) call. The Werkzeug debugger that ships with Flask debug mode is a documented remote-code-execution primitive — anyone reaching the listening port (and guessing the PIN, which is generated from machine-stable inputs) can execute arbitrary Python in the server process. The default 127.0.0.1 bind is the only thing standing between the operator and RCE; a misconfigured --host, an SSH tunnel, or a careless reverse proxy is enough to expose it.

There was also no way to opt out — the literal was unconditional.

Change

Three files:

• app.py — removed debug=True. Default debug now off. Opt-in via either --debug CLI flag or FLASK_DEBUG=1 env var. When debug is enabled, prints a stderr WARNING naming the RCE risk + reminding the operator to bind only to loopback. Auto-reloader gated on the same flag.
• utils/debug_flag.py — new tiny module with resolve_debug_flag(env_value, cli_flag). Lives outside app.py so it can be unit-tested without importing Flask (matching the existing _build_app_parser mirror convention in the test suite). Truthy env values: "1", "true", "yes" — case-insensitive, whitespace-tolerant. CLI flag wins.
• tests/test_cli_args.py — new TestDebugFlagGating class: 8 cases covering env-truthy / env-falsey / env-unset / CLI-override + argparse --debug default & explicit + a source-level guard that fails if debug=True is ever re-introduced as a literal in app.py.

Test plan

Unit: python3 -m unittest tests.test_cli_args → 42/42 OK (was 34, +8 new).

Live smoke (all four matrix cells, on a real flask>=3.0 install):

Trial	Setting	Debug mode	WARNING	Debugger is active!
A	(default — no env, no flag)	off	—	—
B	--debug	on	✅	✅
C	FLASK_DEBUG=1	on	✅	✅
D	FLASK_DEBUG=0	off	—	—

Bogus paths in trials A/D return a plain Flask 404 — not the orange Werkzeug debugger console. The WARNING prints once per process (parent + reloader child = 2× when the reloader is on, which is correct).

Severity

Critical — Werkzeug debugger exposure is a documented RCE pathway. Listed as a Critical / 1pt item in the eval week-1 plan for cppa-cursor-browser.

Closes #9.

Summary by CodeRabbit

• New Features

  • Debug mode is now off by default; can be enabled explicitly via a new --debug CLI option or FLASK_DEBUG.
  • When enabled, a clear security warning about the remote debugger is shown.

• Tests

  • Expanded test coverage for debug flag behavior and added a regression guard preventing always-on debug.

• Documentation

  • README updated to document debugger behavior and how to enable it.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 32947aaf-0f53-4002-9e11-fe96e75ee81c

📥 Commits

Reviewing files that changed from the base of the PR and between c2b4a21 and 6dc182f.

📒 Files selected for processing (3)

• README.md
• app.py
• tests/test_cli_args.py

✅ Files skipped from review due to trivial changes (1)

• README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• app.py

---

📝 Walkthrough

Walkthrough

Replaces unconditional debug=True with an opt-in resolver and CLI flag; integrates resolve_debug_flag() into app startup, prints a security warning when enabled, updates app.run() behavior, adds unit tests and AST regression checks, and documents the new opt-in behavior.

Changes

Debug Mode Security: Opt-In Flag & Werkzeug Debugger Exposure Remediation

Layer / File(s)	Summary
Debug Flag Resolution Contract utils/debug_flag.py	Introduces resolve_debug_flag(env_value, cli_flag) implementing opt-in debug logic: CLI flag overrides; unset environment defaults to False; environment enables debug only for normalized truthy values ("1", "true", "yes").
CLI & Runtime Integration app.py	Adds --debug CLI option, imports resolve_debug_flag, computes debug_enabled, prints security warning to stderr when enabled, and updates app.run() to set debug accordingly and conditionally enable reloader (excluding Windows).
Test Coverage & Regression Prevention tests/test_cli_args.py	Extends argument parser with --debug boolean flag; adds TestDebugFlagGating test class validating env/CLI resolution paths; adds AST-based regression check ensuring debug=True literal never reappears in app.py.
Documentation Note README.md	Clarifies Werkzeug debugger is disabled by default and must be enabled via --debug or FLASK_DEBUG=1; FLASK_ENV is not consulted.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant Parser
  participant Resolver
  participant App
  User->>CLI: run command (maybe --debug)
  CLI->>Parser: parse args (includes --debug)
  Parser->>Resolver: provide cli_flag and env FLASK_DEBUG
  Resolver->>App: return debug_enabled
  App->>App: print stderr warning if debug_enabled
  App->>App: call app.run(debug=debug_enabled, use_reloader=...)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A little hop, a cautious flag held tight,

I whisper to ops: "Only enable in light."
Tests sniff the AST, no naughty True in sight,
A warning on stderr to guard the night.
Hooray — opt-in debug, safe and polite.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.09% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: disabling the hardcoded debug=True and preventing Werkzeug debugger exposure, directly matching the main objective in the changeset.
Linked Issues check	✅ Passed	The PR successfully addresses all coding requirements from issue #9: removes unconditional debug=True, implements opt-in debug via --debug flag and FLASK_DEBUG env var, adds stderr WARNING when enabled, gates auto-reloader, and includes regression and unit tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #9: app.py debug handling, utils/debug_flag.py resolution helper, test coverage, and README documentation. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/disable-debug-werkzeug-9

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[bradjin8]

READ.md - mention for the debug is off by default.

PR/issue are security-sensitive; a short note that debug is off by default and enabled only with --debug or FLASK_DEBUG would match operator expectations. Optional; you asked not to expand scope unless useful.