MiniNIDS — Network Intrusion Detection System

BCA Final Year Project | SOC L1 Portfolio Project

---

📁 Project Files

File	Purpose
nids_engine.py	Main NIDS — sniffs real packets, detects threats, auto-blocks HIGH severity sources (Windows)
nids_engine_kali.py	Kali Linux version — same detection logic, iptables-ready, tested against Metasploitable2
simulate_alerts.py	Generates fake alerts for testing the dashboard without live traffic
sync_alerts.py	Keeps alerts.json in sync with alerts.db — run alongside nids_engine or simulate_alerts
database.py	SQLite layer — handles all alert storage and retrieval
generate_report.py	Exports a formatted incident report as .txt
dashboard.html	Browser-based SOC alert dashboard (live polling)
alerts.db	Real attack data captured from Kali + Metasploitable2 lab session
traffic.log	Auto-created — raw packet log from nids_engine.py
blocked_ips.txt	Auto-created — log of IPs auto-blocked via Windows Firewall

---

⚙️ Setup (Windows)

Step 1 — Install Python packages

Open Command Prompt (as Administrator) and run:

pip install scapy

Step 2 — Install Npcap (needed by Scapy on Windows)

Download from: https://npcap.com/#download Install with default settings (check "WinPcap API-compatible mode")

---

⚙️ Setup (Kali Linux)

sudo apt install python3-scapy -y

No additional dependencies needed — SQLite is built into Python.

---

▶️ How to Run

⚠️ Important: dashboard.html must be opened through a local server, not by double-clicking the file. Opening it directly (file:///...) blocks it from loading alerts.json due to browser CORS restrictions — the dashboard will stay stuck on "Waiting..." with 0 alerts and the console will fill with net::ERR_FAILED errors.

Step 0 — Start a local server (do this first, every time)

In the project folder, run:

python -m http.server 8000

Leave this terminal running, then open:

http://localhost:8000/dashboard.html

Step 1 — Start the sync process (keeps dashboard updated)

In a second terminal:

python sync_alerts.py

Option A — Test dashboard with fake alerts (no Admin needed)

In a third terminal:

python simulate_alerts.py

Refresh the dashboard — alerts should start appearing within a few seconds.

Option B — Real packet sniffing on Windows (requires Admin)

Right-click Command Prompt → Run as Administrator

python nids_engine.py

Then check the dashboard (server and sync_alerts from Steps 0–1 must still be running).

Option C — Real packet sniffing on Kali Linux (recommended for lab testing)

sudo python3 nids_engine_kali.py

Attack from a second terminal using Nmap or Hydra against a target VM (e.g. Metasploitable2).

Generate Report

After running either option above:

python generate_report.py

A .txt incident report is saved in the same folder.

---

🔍 What This Project Detects

Threat	How
Port Scan	One IP hits 15+ different ports in 5 seconds
Brute Force	5+ connections to SSH/RDP/FTP/Telnet in 10 seconds
ICMP Flood	50+ pings from one IP in 2 seconds
NULL Scan	TCP packet with zero flags
XMAS Scan	TCP FIN+URG+PSH flags
Suspicious Ports	Single packet to Metasploit, RAT, IRC C2, or Telnet ports

---

🚨 Automated Response (read before running Option B)

nids_engine.py does more than alert — on any HIGH severity detection it will:

• Automatically add a Windows Firewall block rule for the source IP via netsh advfirewall
• Send a Telegram notification (if TELEGRAM_TOKEN / TELEGRAM_CHAT_ID are configured)

⚠️ Note: SSH (22) and RDP (3389) are intentionally excluded from SUSPICIOUS_PORTS. Single-packet detection on these ports would auto-block legitimate admin connections. Brute-force detection for SSH/RDP is still active — it triggers only after 5+ connection attempts in 10 seconds, which is the correct threshold for that signal.

Firewall rules created by this tool (MiniNIDS_Block_*) are not automatically removed — clean them up manually via Windows Defender Firewall if testing repeatedly.

On Kali (nids_engine_kali.py): Auto-blocking is logged only — no firewall rules are added by default. Uncomment the iptables line in block_ip() to enable active blocking.

---

🔐 Telegram Alerts (optional)

To enable Telegram notifications for HIGH severity alerts, set TELEGRAM_TOKEN and TELEGRAM_CHAT_ID in nids_engine.py and simulate_alerts.py. Leave as the default placeholder values to disable.

---

🧪 Lab Testing Evidence

Real attack captures from a Kali Linux + Metasploitable2 home lab are in the /evidence folder:

Attack	Tool Used	Result
Port Scan	nmap -sS	HIGH alert fired
XMAS Scan	nmap -sX	MEDIUM alert fired
NULL Scan	nmap -sN	MEDIUM alert fired
Brute Force	hydra (FTP)	HIGH alert fired
ICMP Flood	ping -f	MEDIUM alert fired

---

🧰 Tech Stack

• Python + Scapy — packet sniffing and detection
• SQLite — persistent alert storage via database.py
• HTML / CSS / JS + Chart.js — real-time SOC dashboard

---

💡 How to Explain This in Interviews

"I built a Python-based NIDS using Scapy that monitors network packets in real time. It detects port scans, brute force attempts, ICMP floods, and XMAS/NULL scans using custom detection rules. Alerts are stored in SQLite, displayed on a live SOC-style dashboard, and can be exported as incident reports — similar to what a Level 1 SOC analyst would review in a SIEM. Validated against real attacks in a Kali Linux + Metasploitable2 lab environment."

---

🚀 How to Make It Even Better (optional upgrades)

• Store alerts in SQLite instead of JSON ✅
• Validated with real adversarial testing (Kali + Metasploitable2) ✅
• Add GeoIP lookup to show where IPs are from
• Add email alerts using smtplib
• Integrate with Elasticsearch for real SIEM feel
• Add Snort/Suricata rules on top