proxyscope 0.1.0__tar.gz

proxyscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Seyschab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proxyscope-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: proxyscope
+Version: 0.1.0
+Summary: Interactive HTTP/HTTPS debugging proxy with runtime policies and terminal UI.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: proxy,http,https,mitm,tui,debugging
+Author: Tim Seyschab
+Author-email: tim@shellnuts.de
+Requires-Python: >=3.13,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Environment :: Console :: Curses
+Requires-Dist: requests (>=2.32.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+poetry install
+```
+
+## Run
+
+```bash
+poetry run proxyscope --host 127.0.0.1 --port 8080
+```
+
+With persisted runtime configuration:
+
+```bash
+poetry run proxyscope --config ./runtime-config.json
+```
+
+Without TUI:
+
+```bash
+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)
+
+Generate local CA materials:
+
+```bash
+./scripts/generate_mitm_ca.sh
+```
+
+Import `certs/ca/mitm-ca.crt` into your browser trust store for local testing.
+
+## Tests
+
+```bash
+poetry run python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+## Release / Publish
+
+### 1. Bump Version
+
+```bash
+poetry version patch
+# or: poetry version minor / poetry version major
+```
+
+### 2. Validate + Build
+
+```bash
+poetry check
+poetry build
+```
+
+### 3. Configure PyPI Token
+
+Either use an environment variable:
+
+```bash
+export POETRY_PYPI_TOKEN_PYPI="pypi-..."
+```
+
+or persistent Poetry config:
+
+```bash
+poetry config pypi-token.pypi "pypi-..."
+```
+
+### 4. Publish to PyPI
+
+```bash
+poetry publish --no-interaction
+```
+
+Alternative:
+
+```bash
+./scripts/publish_pypi.sh
+```
+
+### 5. Install from PyPI (verification)
+
+```bash
+pip install proxyscope
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+

proxyscope-0.1.0/README.md

@@ -0,0 +1,144 @@
+# 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
+
+```bash
+poetry install
+```
+
+## Run
+
+```bash
+poetry run proxyscope --host 127.0.0.1 --port 8080
+```
+
+With persisted runtime configuration:
+
+```bash
+poetry run proxyscope --config ./runtime-config.json
+```
+
+Without TUI:
+
+```bash
+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)
+
+Generate local CA materials:
+
+```bash
+./scripts/generate_mitm_ca.sh
+```
+
+Import `certs/ca/mitm-ca.crt` into your browser trust store for local testing.
+
+## Tests
+
+```bash
+poetry run python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+## Release / Publish
+
+### 1. Bump Version
+
+```bash
+poetry version patch
+# or: poetry version minor / poetry version major
+```
+
+### 2. Validate + Build
+
+```bash
+poetry check
+poetry build
+```
+
+### 3. Configure PyPI Token
+
+Either use an environment variable:
+
+```bash
+export POETRY_PYPI_TOKEN_PYPI="pypi-..."
+```
+
+or persistent Poetry config:
+
+```bash
+poetry config pypi-token.pypi "pypi-..."
+```
+
+### 4. Publish to PyPI
+
+```bash
+poetry publish --no-interaction
+```
+
+Alternative:
+
+```bash
+./scripts/publish_pypi.sh
+```
+
+### 5. Install from PyPI (verification)
+
+```bash
+pip install proxyscope
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

proxyscope-0.1.0/proxyscope/__init__.py

@@ -0,0 +1,2 @@
+"""tproxy package."""
+

proxyscope-0.1.0/proxyscope/app/config/matching.py

@@ -0,0 +1,154 @@
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from proxyscope.app.config.models import PolicyRule
+
+
+def normalize_whitelist_entry(value: str) -> str:
+    raw_value = value.strip()
+    if not raw_value:
+        raise ValueError("Whitelist entry must not be empty.")
+
+    if "://" in raw_value:
+        parsed = urlsplit(raw_value)
+        host = parsed.hostname
+    elif "/" in raw_value:
+        parsed = urlsplit(f"http://{raw_value}")
+        host = parsed.hostname
+    else:
+        parsed = urlsplit(f"http://{raw_value}")
+        host = parsed.hostname
+
+    if not host:
+        raise ValueError(f"Invalid whitelist entry: {value}")
+    return host.lower()
+
+
+def normalize_modification_url(value: str) -> str:
+    raw_value = value.strip()
+    if not raw_value:
+        raise ValueError("Modification URL must not be empty.")
+
+    if "://" not in raw_value:
+        raw_value = f"http://{raw_value}"
+
+    parsed = urlsplit(raw_value)
+    if not parsed.hostname:
+        raise ValueError(f"Invalid modification URL: {value}")
+
+    scheme = parsed.scheme.lower() or "http"
+    host = parsed.hostname.lower()
+    port = parsed.port
+    path = parsed.path or "/"
+    normalized_path = path if path.startswith("/") else f"/{path}"
+    netloc = f"{host}:{port}" if port is not None else host
+    return f"{scheme}://{netloc}{normalized_path}"
+
+
+def normalize_http_method(method: str | None) -> str:
+    if method is None:
+        raise ValueError("HTTP method must not be empty.")
+    normalized = method.strip().upper()
+    if not normalized:
+        raise ValueError("HTTP method must not be empty.")
+    return normalized
+
+
+def request_url_candidates(url: str) -> tuple[str, ...]:
+    normalized = normalize_modification_url(url)
+    alternate = _alternate_scheme_url(normalized)
+    if alternate is None:
+        return (normalized,)
+    return (normalized, alternate)
+
+
+def policy_rule_matches_request(*, rule: PolicyRule, method: str, url_candidates: tuple[str, ...]) -> bool:
+    methods = rule.match.methods
+    if methods is not None and method not in methods:
+        return False
+
+    url_exact = rule.match.url_exact
+    url_prefix = rule.match.url_prefix
+    if url_exact is None and url_prefix is None:
+        return True
+
+    for candidate in url_candidates:
+        if url_exact is not None and candidate == url_exact:
+            return True
+        if url_prefix is not None and candidate.startswith(url_prefix):
+            return True
+        # Host-wide fallback when configured with "/"
+        candidate_parsed = _parse_normalized_modification_url(candidate)
+        if url_exact is not None:
+            entry = _parse_normalized_modification_url(url_exact)
+            if entry.host == candidate_parsed.host and entry.port == candidate_parsed.port:
+                if entry.path == "/" or candidate_parsed.path.startswith(entry.path):
+                    return True
+        if url_prefix is not None:
+            entry = _parse_normalized_modification_url(url_prefix)
+            if entry.host == candidate_parsed.host and entry.port == candidate_parsed.port:
+                if entry.path == "/" or candidate_parsed.path.startswith(entry.path):
+                    return True
+    return False
+
+
+def rule_matches_url(rule: PolicyRule, normalized_url: str) -> bool:
+    target = rule.match.url_exact or rule.match.url_prefix
+    if target is None:
+        return False
+    return target == normalized_url
+
+
+def first_rule_method(rule: PolicyRule) -> str | None:
+    methods = rule.match.methods
+    if not methods:
+        return None
+    return methods[0]
+
+
+def rule_method_display(rule: PolicyRule) -> str:
+    method = first_rule_method(rule)
+    return method or "*"
+
+
+def rule_url_display(rule: PolicyRule) -> str:
+    return rule.match.url_exact or rule.match.url_prefix or "*"
+
+
+def policy_description(rule: PolicyRule) -> str:
+    state = "on" if rule.enabled else "off"
+    method = rule_method_display(rule)
+    target = rule_url_display(rule)
+    if rule.action == "open_editor":
+        return f"{rule.name} [{state}] open_editor {method} {target}"
+    if rule.action == "static_response" and rule.static_response is not None:
+        return (
+            f"{rule.name} [{state}] static_response {method} {target} "
+            f"-> {rule.static_response.status_code} {rule.static_response.reason}"
+        )
+    return f"{rule.name} [{state}] {rule.action} {method} {target}"
+
+
+def _alternate_scheme_url(normalized_url: str) -> str | None:
+    parsed = urlsplit(normalized_url)
+    scheme = parsed.scheme.lower()
+    if scheme not in {"http", "https"}:
+        return None
+    alternate_scheme = "https" if scheme == "http" else "http"
+    return f"{alternate_scheme}://{parsed.netloc}{parsed.path or '/'}"
+
+
+@dataclass(frozen=True)
+class _NormalizedModUrl:
+    host: str
+    port: int | None
+    path: str
+
+
+def _parse_normalized_modification_url(value: str) -> _NormalizedModUrl:
+    parsed = urlsplit(value)
+    return _NormalizedModUrl(
+        host=(parsed.hostname or "").lower(),
+        port=parsed.port,
+        path=parsed.path or "/",
+    )

proxyscope-0.1.0/proxyscope/app/config/models.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RequestMatchRule:
+    methods: tuple[str, ...] | None = None
+    url_exact: str | None = None
+    url_prefix: str | None = None
+
+
+@dataclass(frozen=True)
+class StaticResponseTemplate:
+    status_code: int
+    reason: str
+    headers: dict[str, str]
+    body: bytes
+
+
+@dataclass(frozen=True)
+class PolicyRule:
+    name: str
+    enabled: bool
+    action: str  # "open_editor" | "static_response"
+    match: RequestMatchRule
+    static_response: StaticResponseTemplate | None = None