PyPI · httpcore2
HTTPX2: Secure WebSocket traffic sent without TLS through SOCKS proxies
httpcore2 does not start TLS for wss:// connections routed through a SOCKS5 proxy. The WebSocket opening handshake and all subsequent frames are sent in plaintext through the proxy path, despite the caller selecting the secure wss scheme.
The transport flaw affects httpcore2 releases before 2.10.0. HTTPX2 exposed this behavior through its public Client.websocket() and AsyncClient.websocket() APIs from 2.6.0 through 2.9.1.
The synchronous and asynchronous SOCKS5 connection implementations upgrade the established proxy tunnel to TLS only when the remote origin scheme is https. The equivalent check does not include wss. After the SOCKS5 handshake succeeds, the raw stream is therefore passed directly to the HTTP/1.1 connection, which writes the WebSocket upgrade request without first performing a TLS handshake or verifying the destination certificate.
For example, an application using HTTPX2 2.6.0 through 2.9.1 may open an authenticated WebSocket through a SOCKS proxy:
import httpx2
with httpx2.Client(proxy="socks5://proxy.example:1080") as client:
with client.websocket(
"wss://service.example/private?token=query-secret",
headers={"Authorization": "Bearer header-secret"},
cookies={"session": "cookie-secret"},
) as websocket:
websocket.send_text("private message")
On affected versions, the stream passing through the SOCKS proxy begins with a plaintext request such as:
GET /private?token=query-secret HTTP/1.1
Host: service.example
Authorization: Bearer header-secret
Cookie: session=cookie-secret
Before HTTPX2 2.6.0, the same underlying httpcore2 behavior could be reached by integrations constructing a WebSocket upgrade request through the low-level transport API, but HTTPX2 did not yet provide its native WebSocket client API.
A normal secure WebSocket server will usually reject these plaintext bytes because it expects a TLS ClientHello. However, a malicious or compromised SOCKS proxy can accept the SOCKS connection, observe the plaintext handshake, return a forged 101 Switching Protocols response, and then read or modify WebSocket frames in both directions. An observer between the proxy and destination may also read the plaintext traffic.
RFC 6455 requires a client using a secure WebSocket connection to perform the TLS handshake before sending the WebSocket opening handshake. A wss URI promises confidentiality, integrity, and endpoint authentication through TLS.
An attacker able to control or observe the SOCKS proxy path can obtain URL query parameters, authorization headers, cookies, and application messages that the caller expected TLS to protect. Because no TLS handshake occurs, certificate verification also does not occur, allowing an attacker controlling the proxy to impersonate the WebSocket server and inject or alter messages.
Only wss:// connections routed through a SOCKS5 proxy are affected. Direct wss:// connections and ordinary https:// requests through SOCKS already start TLS correctly.
Upgrade HTTPX2 and httpcore2 to 2.10.0 or later. Patched versions start TLS for both https and wss origins in the synchronous and asynchronous SOCKS5 connection paths.
If upgrading is not immediately possible, do not route wss:// connections through a SOCKS proxy. Use a direct secure WebSocket connection or another transport that performs and verifies TLS to the WebSocket origin.
Is your project exposed to this? Stateward checks every dependency on every pull request and flags it only if your code actually reaches it.
Check my repoSources: CISA KEV (public domain), OSV.dev & GitHub Advisory Database (CC-BY-4.0), FIRST EPSS, NVD/CWE (public domain). Served live from the Stateward advisory database.