mdghufran/iot-fingerprinting

IoT Device Fingerprinting & Anomaly Detection Framework

      ![Accuracy]() 

M.Tech Cyber Forensics — Final Semester Thesis NIELIT Srinagar  |  Md Ghufran Alam  |  Roll No. NDU202400038

Live Deployment

Deployed on HuggingFace Spaces (Docker) — fully live, no local setup required.

A production-grade machine learning system that fingerprints IoT devices by their network traffic signature and detects Mirai / BASHLITE botnet attacks in real time — without installing anything on the devices themselves.

Trained on the real N-BaIoT dataset (UCI ML Repository #442) featuring 9 physical IoT devices and live attack traffic. Delivers results through a FastAPI REST interface and a live Plotly Dash dashboard, with full SHAP explainability on every prediction.

Table of Contents

• —Overview
• —Screenshots
• —Key Results
• —Architecture
• —Features
• —Quick Start
• —Dataset
• —Project Structure
• —API Reference
• —Plots
• —Tech Stack
• —Citation

Overview

Smart home devices — cameras, thermostats, smart bulbs — cannot run antivirus software. Yet they are the most common entry point for botnets. The Mirai botnet (2016) compromised over 600,000 IoT devices and took down Twitter, Netflix, and Reddit with a single DDoS attack. BASHLITE followed the same playbook.

Traditional network security tools cannot defend against this because they do not know what device they are looking at or what normal behaviour looks like for that device.

This framework solves both problems directly from network traffic — no agent software, no device modification required:

All three answers arrive in a single POST /analyze call, in under 40 ms.

Screenshots

Live Dashboard

[image] Main dashboard — anomaly score timeline, detected device types, and real-time stats

[image] Alerts by severity (HIGH / CRITICAL) + anomaly score gauge + recent alert feed

SHAP Explainability

[image] Live SHAP panel — top features that drove the model's last prediction (green = toward device, red = away)

FastAPI REST Interface

[image] Dark-themed Swagger UI at `http://localhost:8000/docs` — all 8 endpoints

[image] `GET /health` response — models loaded, SHAP ready, 36 ms latency

Key Results

Device Fingerprinting (8 IoT device types)

Anomaly Detection (Real Mirai / BASHLITE attacks)

Note: Lower F1 on anomaly detection is expected and realistic — Mirai/BASHLITE are engineered to blend with normal traffic. AUC-ROC is the threshold-independent metric used here.

Architecture

Network Flow (37 features)
         │
         ▼
  RobustScaler (normalization)
         │
    ┌────┴────────────────────┐
    │                         │
    ▼                         ▼
Device Fingerprinting    Anomaly Detection
(Random Forest)          (IF + OC-SVM ensemble)
    │                         │
    ▼                         ▼
Device Label             Anomaly Score
+ Confidence             + Severity
    │                         │
    └──────────┬──────────────┘
               ▼
         Alert Manager
               │
    ┌──────────┴──────────┐
    ▼                     ▼
FastAPI REST API     Plotly Dash
(port 8000)          (port 8050)

Features

Quick Start

1. Clone the repository

git clone https://github.com/Ghufran2002/iot-fingerprinting-framework.git
cd iot-fingerprinting-framework

2. Create a virtual environment (recommended)

python -m venv venv

# Windows
venv\Scripts\activate

# Linux / macOS
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Download real dataset & train models

python train.py --download

This will:

• —Download the N-BaIoT dataset (~1.7 GB, one-time) from UCI ML Repository
• —Train all fingerprinting + anomaly models
• —Generate 10 evaluation plots in plots/

Slow internet? Manually download from Kaggle N-BaIoT and extract to data/nbaiot/

5. Start the system

python run.py

Training Modes

python train.py --download   # Download N-BaIoT + train hybrid (recommended)
python train.py --hybrid     # Real N-BaIoT + synthetic fill-in
python train.py --real       # Real N-BaIoT only
python train.py              # Synthetic data only (no download needed)

Dataset

N-BaIoT — Detection of IoT Botnet Attacks Source: UCI ML Repository #442

Attack types included: Mirai (ack, scan, syn, udp, udpplain) + BASHLITE/Gafgyt (combo, junk, scan, tcp, udp)

37 Network Flow Features

Project Structure

iot-fingerprinting-framework/
│
├── src/
│   ├── data/
│   │   ├── generator.py        # Synthetic dataset generator
│   │   ├── preprocessor.py     # RobustScaler + SMOTE + train/val/test split
│   │   ├── real_loader.py      # N-BaIoT loader + 115→37 feature mapping
│   │   └── download_real.py    # One-click N-BaIoT downloader
│   │
│   ├── features/
│   │   └── extractor.py        # 37 feature names + 8 device type definitions
│   │
│   ├── models/
│   │   ├── fingerprinter.py    # RF / GB / SVM / VotingEnsemble classifier
│   │   ├── anomaly_detector.py # Per-device IsolationForest + OneClassSVM
│   │   └── trainer.py          # End-to-end training pipeline + plots
│   │
│   ├── api/
│   │   └── main.py             # FastAPI app with 8 endpoints + SHAP
│   │
│   ├── dashboard/
│   │   └── app.py              # Plotly Dash live dashboard
│   │
│   └── utils/
│       ├── alert_manager.py    # Alert severity + deduplication
│       └── logger.py           # loguru logger setup
│
├── data/
│   └── iot_flows.csv           # Synthetic dataset (fallback, 1600 rows)
│
├── plots/                      # Auto-generated evaluation charts
│   ├── cm_random_forest.png
│   ├── roc_curves.png
│   ├── feature_importance.png
│   ├── anomaly_scores.png
│   └── ...
│
├── models/                     # Saved .pkl files (git-ignored, regenerate via train.py)
│
├── tests/
│   └── test_pipeline.py
│
├── train.py                    # Training entry point
├── run.py                      # Start API + Dashboard
├── requirements.txt
└── README.md

API Reference

Example — Analyze a flow

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "features": {
      "flow_duration": 90,
      "mean_iat": 0.003,
      "packet_count": 28000,
      "byte_count": 42000000,
      "tcp_ratio": 0.95,
      "is_https": 1.0,
      "mean_dest_port": 443
    }
  }'

Response:

{
  "fingerprint": {
    "device_type": "smart_camera",
    "confidence": 0.9876,
    "is_known": true
  },
  "anomaly": {
    "anomaly_score": 0.21,
    "is_anomalous": false,
    "severity": null,
    "threshold": 0.75
  }
}

Plots

All plots are auto-saved to plots/ after running train.py:

Tech Stack

Citation

If you use this framework or the N-BaIoT dataset, please cite:

@dataset{nbaiot2018,
  author    = {Meidan, Yair and Bohadana, Michael and Mathov, Yael and
               Mirsky, Yisroel and Shabtai, Asaf and Breitenbacher, Dominik and Elovici, Yuval},
  title     = {N-BaIoT: Network-based Detection of IoT Botnet Attacks Using Deep Autoencoders},
  year      = {2018},
  publisher = {UCI Machine Learning Repository},
  url       = {https://archive.ics.uci.edu/dataset/442}
}

License

This project is released under the MIT License. You are free to use, modify, and distribute it with attribution.

<div align="center">

_{Designed and developed as part of M.Tech Cyber Forensics thesis work}

Md Ghufran Alam Roll No. NDU202400038 &nbsp;|&nbsp; M.Tech Cyber Forensics &nbsp;|&nbsp; NIELIT Srinagar &nbsp;|&nbsp; 2026

_{If this project helped you, consider giving it a ⭐ on GitHub}

</div>