proxyscope 0.1.1

Interactive HTTP/HTTPS debugging proxy with runtime policies and terminal UI.

proxyscope

proxyscope is an interactive HTTP/HTTPS proxy for request inspection, response editing, static-response policies, and live runtime control in a terminal UI.

Highlights

• Forward HTTP requests through an upstream connection.
• Handle HTTPS via CONNECT and optional TLS interception (MITM).
• Group request/response logs by request id.
• Inspect request/response details in a TUI.
• Edit matching responses in an external editor.
• Persist runtime configuration and policy rules.
• Replay captured requests.

Requirements

• Python 3.13+
• Poetry 2.x

Installation

poetry install

Run

poetry run proxyscope --host 127.0.0.1 --port 8080

With persisted runtime configuration:

poetry run proxyscope --config ./runtime-config.json

Without TUI:

poetry run proxyscope --no-ui

Runtime Commands (TUI)

• help
• clear
• sites
• loglevel <DEBUG|INFO|WARNING|ERROR>
• whitelist [show|add|remove|clear] ...
• cache [show|on|off|toggle]
• config [show|save [path]|reload]
• policy [show|add-editor|add-static|edit|remove|enable|disable] ...
• quit

Keyboard Shortcuts (TUI)

• Left / Right: Focus zwischen Panels wechseln.
• Up / Down: Auswahl bewegen oder vertikal scrollen (abhängig vom aktiven Panel).
• PageUp / PageDown: Schnelles vertikales Scrollen.
• Enter: Request-Detail für den ausgewählten Request öffnen (oder Kommando ausführen, wenn Eingabezeile befüllt ist).
• Backspace: Zeichen in der Kommandozeile löschen.
• Tab / Shift+Tab: Im Request-Detail zwischen Request und Response Tab wechseln.
• Shift+B: Request-Detail schließen, zurück zur Request-Liste.
• Shift+P: Rechtes Panel auf Policies fokussieren.
• Shift+S: Rechtes Panel auf Sites fokussieren.
• Shift+V: Rechtes Panel ein-/ausblenden.
• Shift+M: Ausgewählten Request als Editor-Policy (METHOD + URL) hinzufügen.
• Shift+R: Ausgewählten Request editieren und erneut senden.
• Shift+T: Im Request-Detail zwischen Request und Response Tab wechseln.
• Shift+A: Ausgewählte Site zur Log-Whitelist hinzufügen (Sites-Tab).
• Shift+D: Ausgewählte Site aus der Log-Whitelist entfernen (Sites-Tab).
• Shift+E: Ausgewählte Policy aktivieren (Policies-Tab).
• Shift+D: Ausgewählte Policy deaktivieren (Policies-Tab).
• Shift+I: Ausgewählte Policy bearbeiten (Policies-Tab).
• Shift+X: Ausgewählte Policy entfernen (Policies-Tab).

TLS Interception (MITM)

On startup, proxyscope now auto-creates local CA materials under certs/ca if they are missing.

Import certs/ca/mitm-ca.crt into your browser trust store for local testing.

To regenerate CA files, delete the existing cert material and restart proxyscope:

rm -f certs/ca/mitm-ca.key.pem certs/ca/mitm-ca.cert.pem certs/ca/mitm-ca.crt certs/ca/mitm-ca.cnf certs/hosts/*.pem certs/hosts/*.srl

Tests

poetry run python -m unittest discover -s tests -p "test_*.py" -v

Release / Publish

1. Bump Version

poetry version patch
# or: poetry version minor / poetry version major

2. Validate + Build

poetry check
poetry build

3. Configure PyPI Token

Either use an environment variable:

export POETRY_PYPI_TOKEN_PYPI="pypi-..."

or persistent Poetry config:

poetry config pypi-token.pypi "pypi-..."

4. Publish to PyPI

poetry publish --no-interaction

Alternative:

./scripts/publish_pypi.sh

5. Install from PyPI (verification)

pip install proxyscope

License

MIT. See LICENSE.