Metadata-Version: 2.4
Name: pqc-traffic-analyzer
Version: 1.1.0
Summary: A Scapy-based tool to detect and fingerprint post-quantum and hybrid TLS 1.3 handshakes on the wire
Author: makb1831
License: MIT License
        
        Copyright (c) 2026 makb1831
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/makb1831/pqc-traffic-analyzer
Project-URL: Issues, https://github.com/makb1831/pqc-traffic-analyzer/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scapy>=2.5.0
Requires-Dist: rich>=13.0.0
Requires-Dist: cryptography>=42.0.0
Dynamic: license-file
Dynamic: requires-python

# 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](docs/pqc_handshake_explanation.md).

---

## 🚀 Features

- **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.

---

## 📦 Installation

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/makb1831/pqc-traffic-analyzer.git
   cd pqc-traffic-analyzer
   ```

2. **Set Up Virtual Environment**:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install -e .
   ```

---

## 🛠️ Usage Guide

### CLI Command Reference
```text
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
```

---

## 🖥️ Live Dashboard Monitoring

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:
   ```bash
   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.

---

## 🧪 Step-by-Step Live Capture Test

### 1. Configure local OpenSSL/Curl (WSL/Linux)
System `curl` can be configured using `liboqs` and `oqs-provider` (documented in [Developer Guide](docs/development.md)), or via the official Open Quantum Safe Docker container:

```bash
sudo usermod -aG docker $USER && newgrp docker
```

### 2. Sniff Traffic & Connect
1. In one terminal, start the live sniffer outputting to a dashboard file:
   ```bash
   sudo .venv/bin/pqc-analyze -i eth0 -o pqc_dashboard.html
   ```
2. In a second terminal, execute a post-quantum request:
   ```bash
   # 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)`

---

## 📖 Documentation

For detailed guides, see the `docs` folder:
- [Post-Quantum TLS 1.3 Key Exchange Mechanics](docs/pqc_handshake_explanation.md) - Theoretical background on PQC/hybrid curves and FIPS standards.
- [Architecture & Design](docs/architecture.md) - Internal design, state machine tracking, QUIC dissection, and multi-protocol parsing.
- [Developer & Contribution Guide](docs/development.md) - Local setup, building liboqs/oqs-provider, and test configurations.
- [Advanced Usage & Sniffing Guides](docs/advanced_usage.md) - Sniffing without root (`setcap`), custom BPF filters (`tcp or udp`), and JSON/Markdown export integration.

---

## 🛡️ License

MIT License.
