PQC Traffic Fingerprinting Tool (pqc-traffic-analyzer)

A Scapy-based network analysis tool that parses, dissects, and fingerprints TLS 1.3, QUIC/HTTP3, SSH, and custom Post-Quantum Cryptography (PQC) and hybrid key exchanges on the wire.

For a detailed technical background on hybrid key agreements and the codepoint registry, see Post-Quantum TLS 1.3 Key Exchange Mechanics.

• Multi-Protocol Agnosticism: Detects standard TLS (0x16), QUIC/HTTP3 (UDP), SSH PQC banners (sntrup761, mlkem), custom PQCF magic-byte headers (0x50514346), and JSON REST/gRPC PQC stream payloads.
• Payload Size Heuristics: Fingerprints obfuscated or encapsulated TCP/UDP proxy streams based on key share payload size windows (800B–2,500B+).
• Expanded Codepoint Catalog: Fully maps NIST FIPS 203 (ML-KEM-512/768/1024), FIPS 204 (ML-DSA-44/65/87), FIPS 205 (SLH-DSA), Composite/Dual Signatures, FrodoKEM, HQC, and Classic McEliece.
• In-Depth Metadata & Wire Overhead: Extracts negotiated TLS versions, selected cipher suites, ALPN values, handshake latency ($\Delta t$), and calculates total wire overhead impact (bytes vs classical 32B baseline).
• Interactive Visual Dashboard: Generates HTML dashboards featuring distribution breakdown charts, latency metrics, and real-time auto-refreshing session logs.

1. Clone the Repository:

   git clone https://github.com/makb1831/pqc-traffic-analyzer.git
   cd pqc-traffic-analyzer

2. Set Up Virtual Environment:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install -e .

usage: pqc-analyze [-h] (-f FILE | -i INTERFACE) [-o OUTPUT] [-t {json,markdown,md,html}] [--filter FILTER] [--no-heuristics]

PQC Traffic Fingerprinting Tool - Detect TLS 1.3 Post-Quantum and Hybrid key exchanges on the wire.

options:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  Path to offline PCAP file to analyze
  -i INTERFACE, --interface INTERFACE
                        Network interface to sniff live traffic from
  -o OUTPUT, --output OUTPUT
                        Path to write the report file
  -t {json,markdown,md,html}, --type {json,markdown,md,html}
                        Output report type
  --filter FILTER       BPF filter to apply (default: 'tcp or udp')
  --no-heuristics       Disable payload size heuristic fingerprinting

To stream live packet captures straight to a browser dashboard:

1. Launch the Sniffer with Output Redirection: Run pqc-analyze on your active interface (e.g. eth0) and point the output to an HTML file:

   sudo .venv/bin/pqc-analyze -i eth0 -o pqc_dashboard.html

2. Open the Dashboard: Open the generated pqc_dashboard.html file in your web browser.
3. Enable Auto-Refresh: Check the Auto-refresh (5s) box in the top-right header of the web page. The dashboard reloads itself every 5 seconds to load new handshakes captured by the CLI in the background.

System curl can be configured using liboqs and oqs-provider (documented in Developer Guide), or via the official Open Quantum Safe Docker container:

sudo usermod -aG docker $USER && newgrp docker

1. In one terminal, start the live sniffer outputting to a dashboard file:

   sudo .venv/bin/pqc-analyze -i eth0 -o pqc_dashboard.html

2. In a second terminal, execute a post-quantum request:

   # Via Docker container (X25519MLKEM768 hybrid handshake)
   docker run -it --rm openquantumsafe/curl curl -k https://test.openquantumsafe.org:6671
   
   # Via native Curl (if configured)
   curl -k --curves X25519MLKEM768 https://test.openquantumsafe.org

3. Observe the terminal output and the pqc_dashboard.html page refreshing showing: Group: X25519MLKEM768 (1120B) [TLS 1.3 / 68ms] (PQ Hybrid Key Exchange)

For detailed guides, see the docs folder:

• Post-Quantum TLS 1.3 Key Exchange Mechanics - Theoretical background on PQC/hybrid curves and FIPS standards.
• Architecture & Design - Internal design, state machine tracking, QUIC dissection, and multi-protocol parsing.
• Developer & Contribution Guide - Local setup, building liboqs/oqs-provider, and test configurations.
• Advanced Usage & Sniffing Guides - Sniffing without root (setcap), custom BPF filters (tcp or udp), and JSON/Markdown export integration.

MIT License.