🛡️ NetScan

Advanced Metadata-Only Network Intrusion Detection System

Explore Docs • View Dashboard • Report Bug

---

NetScan is a near real-time, high-performance NIDS designed for modern corporate and campus environments. By focusing exclusively on network metadata, it provides deep visibility and proactive threat detection without compromising user privacy.

✨ Key Features

🔍 Hybrid Detection Engine Combines lightning-fast Rule-based matching with unsupervised IsolationForest ML for 99% accuracy.	🧠 AI-Powered Reasoning Escalates complex or ambiguous threats to Google Gemini 2.0 for semantic context and deep analysis.
⚡ Real-Time Response Automated IP and Domain blocking via nftables/iptables and hosts-file redirection.	📊 Interactive Dashboard A modern, responsive web interface built with FastAPI and Chart.js for live monitoring.

---

🏗️ Architecture

graph TD
    subgraph "Capture Layer"
        P[Packet Sniffing] -->|Scapy/libpcap| F[Flow Aggregation]
    end

    subgraph "Processing Pipeline"
        F -->|Sliding Window| FE[Feature Extraction]
        FE -->|Vector| HE[Hybrid Detection Engine]
    end

    subgraph "Intelligence"
        HE -->|Score| RE[Rule Engine]
        HE -->|Anomaly| ML[IsolationForest ML]
        RE & ML -->|Hybrid Score| DM[Decision Maker]
        DM -->|Escalate| AI[Gemini AI Reasoner]
    end

    subgraph "Actions"
        DM -->|Alert| AM[Alert Manager]
        DM -->|Block| BM[Firewall/Host Blocker]
        AM -->|Notify| NT[Email/Telegram]
    end

    BM & AM & AI -->|Log| DB[(SQLite/Postgres)]
    DB -->|Serve| API[Admin Dashboard]

Loading

---

📸 Dashboard Preview

Note: This is a representative mockup of the NetScan telemetry interface.

---

🚀 Quick Start

1. Prerequisites (Linux)

sudo apt update
sudo apt install -y python3 python3-pip python3-venv libpcap-dev nftables iproute2

2. One-Shot Installation

git clone https://github.com/Desapphire/netscan.git
cd netscan
bash install_linux.sh

3. Launching

Command	Mode	Description
python cli.py api	API Only	Start dashboard at localhost:8000
sudo python cli.py live	Full Mode	Auto-capture + Dashboard (Root required)
sudo python cli.py train	Train	Re-train ML model on baseline data

---

⚙️ Configuration

Tunable parameters are located in config/app_config.yaml.

View Detection Parameters

Key	Default	Description
detection.rule_weight	0.70	Rule engine importance
detection.ml_weight	0.30	ML model importance
detection.block_threshold	0.75	Risk level required to auto-block
detection.ai_review	0.40 - 0.74	Escalate to Gemini in this range

View Gemini Setup

1. Set gemini.enabled: true in config/app_config.yaml.
2. Export your API key:

export GEMINI_API_KEY=<your-key>

---

🛠️ Tech Stack

• Core: Python 3.10+, Scapy, Pandas, Scikit-learn
• API: FastAPI, Uvicorn, Jinja2
• Database: SQLAlchemy, SQLite (Dev), Postgres (Prod)
• Security: nftables, iptables
• AI: Google Gemini Pro (Vertex AI / AI Studio)

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ by the Desapphire Team