H2SpaceX is a Python library for crafting raw HTTP/2 frames with Scapy, enabling authorized study of race conditions via the Single Packet Attack and timing analysis.
| Tool | nxenon/h2spacex — Scapy-based low-level HTTP/2 library for Last Frame Synchronization / Single Packet Attack research |
| Category | Protocol-level web security research library (Python, Scapy, HTTP/2) |
| Primary Use | Reproducing and studying HTTP/2 race conditions (TOCTOU) and web timing attacks against lab targets during authorized engagements |
| Safe Use | Educational and documentary analysis for authorized penetration testers and researchers working against systems they own or have written permission to test, e.g. PortSwigger-style lab environments |
| Telemetry Note | Generates distinctive HTTP/2 traffic patterns: many request HEADERS frames consolidated into a single TCP packet and PING frame probing; defenders can detect anomalous high-stream-count bursts in HTTP/2 logs |
H2SpaceX is a low-level HTTP/2 manipulation library written in Python on top of Scapy, built around one very specific research problem: Last Frame Synchronization, better known in the offensive security community as the Single Packet Attack. The technique, pioneered by James Kettle and presented at DEF CON 31, defeats classic per-request rate limiting and jitter by collapsing multiple HTTP/2 requests into a single network packet so that a vulnerable backend processes them near-simultaneously. Rather than being a point-and-shoot exploitation tool, H2SpaceX exposes the protocol plumbing — frames, connections, response parsing — that a researcher needs to study this class of race conditions in a controlled, authorized setting.
The provenance of the project is unusually credible for a GitHub security tool. The README states the library was part of academic research titled "QUIC-er Races: HTTP/3 won't save you from TOCTOU vulnerabilities," and the author credits direct input from Kettle himself, along with ideas borrowed from the earlier h2tinker library. That lineage matters: the tool is positioned as a research instrument for understanding time-of-check-to-time-of-use flaws in modern web protocols, not as a mass-scanning weapon. At roughly 229 stars and released under GPL-3.0, it is a compact, focused codebase rather than a framework trying to do everything.
Architecturally, the core abstraction is H2OnTlsConnection, which wraps a TLS connection to an HTTP/2 endpoint. Constructing it takes a hostname, a port_number, and — a nice touch for traffic analysis — an optional ssl_log_file_path that writes SSLKEYLOGFILE-style key material so the entire HTTP/2 session can be decrypted and inspected in Wireshark. This single parameter tells you a lot about the intended audience: people who want to watch exactly what their frames do on the wire, which is the correct mindset for protocol research and for defenders learning to recognize the traffic shape.
Installation is straightforward and non-weaponized: pip install h2spacex. The README notes the library prefers Python 3.8.x or newer and that Scapy dependency issues are resolved with pip install --upgrade scapy. Current version is 1.2.2 on PyPI, and the changelog shows healthy maintenance activity: the 1.2.2 release consolidated build configuration into pyproject.toml, removed a legacy setup.py, added a tests/ directory with unit tests for header utilities, and introduced CONTRIBUTING.md. The 1.2.1 release merged community pull requests including non-TLS H2Connection setup and a parser-based header normalization replacing fragile regex handling.
Feature coverage is documented through a refreshingly honest TODO list that is almost entirely checked off. Single Packet Attack variants for both POST and GET requests are implemented; the GET variants use techniques the README explicitly attributes to Kettle, namely the Content-Length: 1 method and a POST request carrying an x-override-method: GET header. Response parsing is fully built, including a threaded parser, body decompression for gzip, br, and deflate encodings, and — critically for timing research — response timestamps recorded in nanoseconds. SOCKS5 proxy support is also implemented for routing the crafted traffic.
The timing attack capability deserves its own attention. The README highlights the enhanced Single Packet Attack method Kettle presented at Black Hat 2024, described in the PortSwigger research "Listen to the whispers: web timing attacks that actually work." H2SpaceX exposes this through the send_ping_frame() method, and ships an example in examples/improved-spa-method.py. The combination of PING-frame pacing and nanosecond-resolution response times turns the library into a serious instrument for measuring side-channel delays in web applications — the kind of work that requires many careful repetitions against a target you are authorized to test, which is exactly the framing the documentation assumes.
The "More Research" section is a candid roadmap of untested ideas, and it reads like a curriculum in HTTP/2 internals. Suggested avenues for squeezing more requests into a single packet include increasing MSS, out-of-order TCP packets, and IP fragmentation — the first two explicitly credited to Kettle. On the GET request side, the author lists HPACK header indexing to shrink requests, HEADERS frames without the END_HEADER flag, and frames omitting some pseudo-headers. None of these are claimed to work; they are flagged as ideas, which is a level of scientific restraint that lends the project credibility.
In an authorized workflow, the natural home for H2SpaceX is the web exploitation lab. The examples/ directory explicitly contains race condition scenarios modeled on PortSwigger Web Security Academy material, which provides a legal, sandboxed target environment. A penetration tester who has written authorization to assess a client's HTTP/2 endpoint could use the library to demonstrate whether multi-endpoint TOCTOU conditions exist — but the tool itself is deliberately a library, not a scanner, so each use case requires the operator to understand the frames they are assembling. That friction is a feature: it filters out casual misuse.
From a defensive perspective, there is real value in studying the artifacts this library produces. A Single Packet Attack has a characteristic signature: a burst of concurrent HTTP/2 streams whose HEADERS frames arrive in one TCP segment, followed by interleaved response processing with negligible inter-request delay. Security teams monitoring HTTP/2 terminators and load balancers can use the traffic patterns generated in their own labs — decryptable via the ssl_log_file_path output — to build and validate detection logic for anomalous stream-count spikes, unusual PING cadences, and timing-attack probing.
Caveats worth noting for prospective users: the README pins preferred Python at 3.8.8, which is aging, so verify compatibility with newer interpreters before relying on it in a modern toolchain. The project's scope is also deliberately narrow — it is not a general HTTP/2 client like h2 or httpx, and it does not attempt HTTP/3 despite the academic paper's title touching on QUIC races. What it does is give a researcher raw, Scapy-level control over one of the most interesting attack primitives in contemporary web security, with documentation that carefully credits its sources and marks the boundary between implemented capability and speculation. For authorized professionals studying race conditions and web timing side channels, that focus is precisely the appeal.
nxenon/h2spacex.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.