---
license: apache-2.0
tags:
- encrypted-traffic-classification
- network-traffic
- state-space-model
- mamba
- kolmogorov-arnold-network
- supervised-contrastive-learning
- quic
- tls
datasets:
- cesnet-quic22
- cesnet-tls-year22
library_name: pytorch
pipeline_tag: feature-extraction
---

# MJKAN-Net — Payload-Free, Protocol-Invariant Encrypted-Traffic Classification

MJKAN-Net classifies **encrypted** network flows into **9 behavioural classes** using only
behavioural features — packet sizes, directions, and inter-arrival timing — **without inspecting any
packet payload**. It learns a single shared embedding space across **QUIC and TLS**, runs in
linear time (~6.7 ms/flow), and meets its accuracy, embedding-quality, and latency targets on a
strict time-based (temporal) split.

Developed by **Team Shigan — Shivam Patel & Kavan Gandhi (IIIT Hyderabad)** for the
Samsung EnnovateX AX Hackathon (Problem Statement 2).

---

## Behavioural classes

`audio_streaming` · `cdn_web_assets` · `ecommerce` · `file_transfer` · `gaming` ·
`messaging` · `search_info_news` · `social_media` · `video_streaming`

## Architecture

```
seq [30 × 5]  →  SSM encoder (pure-PyTorch, Mamba-style)  →  h
                          │
        flow context (6) → Gated FiLM conditioning
                          ↓
                Tiny FasterKAN reasoning head  (r = h + KAN(h))
                          ↓
                Projection head → z ∈ ℝ¹²⁸  (L2-normalised, SupCon-trained)
```

- **Deployed embedding is `z`** (the projection output), classified by k-NN against class centroids.
- The SSM is implemented in **pure PyTorch** (no CUDA `mamba-ssm` dependency) — runs on any GPU/CPU.
- ~0.55 M parameters.

## Input features

- **Sequence** `[30, 5]`: signed packet size, direction (±1), inter-arrival time, RFC-3550 jitter, direction-change flag. (30-packet cap is set by the CESNET PPI field.)
- **Context** `[6]`: flow_duration, packet_rate, roundtrip_density, upload/download ratio, truncation_ratio, burstiness. Normalised with the checkpoint's stored `sm/ss/cm/cs` (do **not** feed raw features — the on-disk data is raw and must be normalised first).

---

## Verified results (strict temporal split, leakage-checked)

Train = QUIC W44–W45 + TLS months 1–9. Test = QUIC W46–W47 + TLS months 10–12.

| KPI | Value | Target |
|-----|-------|--------|
| QUIC accuracy | **91.1%** | ≥ 90% ✅ |
| TLS accuracy | **90.6%** | ≥ 90% ✅ |
| Intra-class cosine | **0.941** | > 0.7 ✅ |
| Inter-class cosine | **−0.090** | < 0.3 ✅ |
| Latency | **~6.7 ms/flow** | < 100 ms ✅ |

A trivial baseline on the same temporal split scores only 0.27–0.31, confirming the accuracy is real signal, not leakage.

### Protocol invariance
QUIC-only training transfers to TLS at ≈0.20 (chance); **joint QUIC+TLS contrastive training lifts TLS to 0.72**, and the flagship reaches 90.6% — QUIC and TLS land within half a point of each other.

### Generalization to unseen apps (characterised, not a single threshold)
Evaluated on a published benchmark of 19 genuinely-unseen apps (`generalization/unknown_apps_combined.npz`):
- **Generalises** for behaviourally-distinctive classes — search/messaging/audio unseen apps classify at **90–99%**.
- **Fails predictably** where behaviour overlaps (gaming→cdn, storage→web) — mechanistically explained, not random.
- **Novelty detection** for traffic matching no class: threshold-free **AUROC 0.832** (known vs unseen).

---

## How to use

The repository ships a flagship checkpoint and the temporal test data. Minimal inference:

```python
import numpy as np, torch
from huggingface_hub import hf_hub_download
# (define the MJKAN model class — see src/ in the project repo)

ck = torch.load(hf_hub_download("donbosoc/shigan-mjkan-baseline",
                "combined_temporal/combined_temporal_best.pt"),
                map_location="cpu", weights_only=False)
sm, ss, cm, cs = (np.array(ck["norm"][k], np.float32) for k in ("sm","ss","cm","cs"))

model = MJKAN(nf=5, nc=len(cm)); model.load_state_dict(ck["model"], strict=True); model.eval()

def embed(seq_raw, ctx_raw):                 # seq:[N,30,5], ctx:[N,6] RAW
    mk = (np.abs(seq_raw).sum(-1, keepdims=True) > 0)
    Sn = ((seq_raw - sm) / ss * mk).astype(np.float32)
    Cn = ((ctx_raw - cm) / cs).astype(np.float32)
    with torch.no_grad():
        return model(torch.tensor(Sn), torch.tensor(Cn))[1].numpy()   # z, L2-normalised
```

Classify by cosine-nearest class centroid, or k-NN against a labelled reference bank.
**Note:** `torch.load` needs `weights_only=False` (PyTorch 2.6+ default change).

---

## Repository contents

- `combined_temporal/` — flagship MJKAN Temporal checkpoint + temporal test data (RAW features)
- `protocol_invariance/`, `condition_invariance/` — V-ladder ablation checkpoints (V1, V2, V3, V5z, V7, V-COND)
- `realtime_joint_temporal/` — window-only real-time variant (mid-flow classification)
- `generalization/unknown_apps_combined.npz` — published unseen-app benchmark (19 apps, QUIC+TLS, RAW features)

---

## Intended use & limitations

**Intended use.** Research and prototyping of behavioural (payload-free) encrypted-traffic
classification, QoS analytics, and novelty/drift detection on QUIC/TLS flows.

**Out-of-scope / limitations (stated honestly):**
- **Pipeline-coupled features.** Two context features (`roundtrip_density`, `truncation_ratio`) are CESNET-exporter-specific and cannot be reconstructed from raw packet captures. Deploying on a *different* capture pipeline requires replicating that exporter or retraining on the target pipeline's features. (Confirmed empirically: a cross-distribution test on an external [5G traffic dataset](https://www.kaggle.com/datasets/kimdaegyeom/5g-traffic-datasets) failed for exactly this reason — its context features did not match our pipeline, surfacing the coupling rather than a model deficiency.)
- **Protocol scope.** Invariance is learned from joint QUIC+TLS training. It is **not** guaranteed for unseen protocols (e.g. plain HTTP). Tested on the **CESNET HTTPS** dataset ([Kaggle](https://www.kaggle.com/datasets/inhngcn/https-traffic-classification); 145,671 flows; classes D/L/M/P/U/W; CC BY 4.0): *behavioural-family* membership transferred (~95%) but exact-class accuracy did not (≈28%, partly due to feature-distribution shift).
- **Unseen-app classification** is bounded by behavioural overlap (see Generalization above) — distinctive classes transfer, overlapping ones do not (detected via novelty signal).
- Trained on CESNET backbone traffic (2022); behaviour from very different networks/eras may differ.

---

## License

**Apache-2.0** applies to the model weights and the code authored by Team Shigan.

**Training data — CESNET-QUIC22 and CESNET-TLS-Year22 — are released under CC BY 4.0**, which
permits training and releasing derived models under any license (including Apache-2.0) with
**attribution only** (no commercial or share-alike restriction). Required dataset citations:

> Luxemburk, J., Hynek, K., Čejka, T., Lukačovič, A., & Šiška, P. (2023). *CESNET-QUIC22: A large one-month QUIC network traffic dataset from backbone lines.* Data in Brief, 46, 108888.

> Luxemburk, J., et al. (2024). *CESNET-TLS-Year22: A year-spanning TLS network traffic dataset.* Scientific Data, 11.

This model does not relicense or redistribute the source datasets. See `attribution.md` in the project repository for full attribution.

---

## Citation

```
@misc{mjkan-net-2026,
  title  = {MJKAN-Net: Payload-Free, Protocol-Invariant Encrypted-Traffic Classification},
  author = {Shivam Patel and Kavan Gandhi},
  year   = {2026},
  note   = {Samsung EnnovateX AX Hackathon, Team Shigan, IIIT Hyderabad},
  url    = {https://huggingface.co/donbosoc/shigan-mjkan-baseline}
}
```