Metadata-Version: 2.4
Name: pqc-traffic-analyzer
Version: 1.0.0
Summary: A Wireshark/Scapy-based tool to detect and fingerprint post-quantum TLS 1.3 handshakes on the wire
Author: PQC Network Security Team
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: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PQC Traffic Fingerprinting Tool (`pqc-traffic-analyzer`)

A Scapy-based network analysis tool that parses, dissects, and fingerprints TLS 1.3 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

- **Offline PCAP Auditing**: Parse network captures to map key agreement groups.
- **Live Handshake Sniffing**: Intercept and parse TLS Client/Server Hello handshakes in real-time.
- **Protocol Agnostic**: Intercepts raw TCP traffic and checks for TLS handshake records (`0x16`), capturing traffic from databases (Postgres/MySQL TLS), APIs (gRPC/WebSockets), email clients (STARTTLS), and apps (Spotify, Discord).
- **In-Depth Metadata**: Extracts negotiated TLS versions, selected cipher suites, ALPN values, and handshake latency (ms).
- **Live HTML Dashboard**: Stream results to an HTML dashboard that dynamically updates during sniffing.

---

## 📦 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

### Command Line Options
```bash
# Analyze an offline PCAP file
pqc-analyze -f capture.pcap

# Save results to a report file (type is auto-detected from extension)
pqc-analyze -f capture.pcap -o report.html
```

---

## 🖥️ 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 will automatically reload 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)
By default, system-installed `curl` does not support PQC curves. You can build `liboqs` and `oqs-provider` to enable system-wide PQC support (documented in [Developer & Contribution Guide](docs/development.md)), or use the official Open Quantum Safe Docker container:

```bash
# Ensure docker is installed and running
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 to the OQS test server:
    ```bash
    # Via Docker container (X25519MLKEM768 hybrid handshake)
    docker run -it --rm openquantumsafe/curl curl -k https://test.openquantumsafe.org:6671

    # Via natively compiled Curl (if configured)
    curl -k --curves X25519MLKEM768 https://test.openquantumsafe.org
    ```
3.  Observe the terminal output and the `pqc_dashboard.html` page refreshing. You will see the captured session 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.
- [Architecture & Design](docs/architecture.md) - Internal design, state machine tracking, and TCP packet dissection.
- [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 filters, and JSON reporting integration.

---

## 🛡️ License

MIT License.
