🕵️ NetGuard – Full-Stack NIDS & Security Observability Engine

מערכת Network Intrusion Detection System (NIDS) מקצה לקצה בזמן אמת.
משלבת מנוע לכידה וניתוח ב-Python (Scapy) בארכיטקטורת Multi-threaded, יחד עם DPI, זיהוי אנומליות ב-Sliding Window, מנגנוני סיכול אקטיביים (Active Defense), וסטאק ניטור מנוהל קוד (Dashboard as Code) ב-Docker (Grafana + Loki + Promtail).

---

🔎 Overview & Architecture

NetGuard מספקת מענה שלם לניטור, ניתוח ותגובה לאירועי אבטחה ברשת בשכבות 3, 4 ו-7 של מודל ה-OSI.
הארכיטקטורה מבוססת צינור נתונים רציף (Pipeline) המפריד בין לכידת החבילות, עיבודן בזמן אמת, והזנתן למערכת הוויזואליזציה:

📡 Network Traffic  ➔  🐍 Python Engine (Sniffer + Worker + GC)  ➔  📄 JSON Logs File

📊 Auto-Provisioned Grafana  ⬅️  🗄️ Loki DB  ⬅️  🔄 Promtail Shipper

---

📂 Project Structure

python_sniffer/
├── grafana/
│   └── dashboards/                 # Standard JSON Dashboards (Git Version-Controlled)
│       ├── dashboard-Live Security Log Stream.json
│       ├── dashboard-Security Events Distribution.json
│       ├── dashboard-Threat Timeline & Severity Levels.json
│       ├── dashboard-Top Suspicious Source IPs.json
│       └── dashboard-Total Security Alerts.json
├── provisioning/                   # Grafana Automated Provisioning Configs
│   ├── dashboards/
│   │   └── dashboards.yml
│   └── datasources/
│       └── datasources.yml
├── logs/                           # Runtime Log Directory (Ignored by Git)
├── .env.example
├── .gitignore
├── docker-compose.yml
├── main.py                         # NIDS Core Engine (Thread-Safe & GC Refactored)
├── promtail-config.yml
├── requirements.txt
└── test_attack.py                  # Traffic Simulator

---

🚀 Core Features

Domain	Feature	Status	Description
📡 Network	Real-time L2-L7 Sniffing	✅	לכידה וניתוח של תעבורת IP, TCP, UDP ו-DNS בזמן אמת תוך מניעת הצפת זיכרון (store=0).
🛡️ Cyber Security	Sliding-Window Detection	✅	זיהוי DoS (SYN Flood) וסריקת פורטים מבוסס חלון זמן נייד מדויק.
⚡ Active Defense	Dynamic IP Isolation	✅	מנגנון סיכול אקטיבי המבודד כתובות תוקפות לזמן קצוב (Blacklist עם תפוגה אוטומטית).
🔍 DPI Engine	Deep Packet Inspection	✅	סריקת Raw Payload ברמת ה-Bytes לזיהוי מחרוזות חשודות (SQLi, Credentials, Path Traversal).
⚙️ Architecture	Producer-Consumer & Thread-Safety	✅	שימוש ב-Queue מוגבל, מנעולי threading.Lock ו-Thread רקע ייעודי (Garbage Collector) למניעת זליגות זיכרון.
📊 Observability & IaC	Dashboard as Code (Grafana + Loki)	✅	חמישה דשבורדים מוגדרים מראש בפורמט JSON סטנדרטי הנטענים אוטומטית בעליית ה-Container דרך קבצי ה-Provisioning.
📝 Logging	Structured JSON Dual-Stream	✅	פלט קונסולה צבעוני במקביל לכתיבת לוגים במבנה JSON מובנה המותאם לאיסוף ע"י Promtail.
🧪 Testing	Traffic Attack Simulator	✅	סקריפט סימולציה (test_attack.py) ליצירת תעבורת תקיפה סינתטית לאימות מנגנוני הזיהוי.

---

🛠️ טכנולוגיות ודגשים ארכיטקטוניים

Python & Scapy: לכידת חבילות נתונים ברמת ה-Raw Sockets, פיענוח פרוטוקולי תקשורת, וסריקת עומק ברמת ה-Payload (DPI).

Producer-Consumer Architecture: הפרדה מלאה בין לכידת החבילות לבין ניתוחן באמצעות queue.Queue(maxsize=10000) המונעת Packet Loss באירועי עומס.

Thread-Safety & Active Defense: ניהול מצבי Whitelist/Blacklist וזיהוי אנומליות תחת מנעולים (threading.Lock) למניעת Data Race, לצד חסימה דינמית וזמנית של כתובות IP תוקפות.

Background Garbage Collector: תהליך רקע ייעודי (Garbage Collector Thread) המנקה מבני נתונים ישנים (Sliding Window History & Blacklist) מהזיכרון מדי 30 שניות בצורה סנכרונית ובטוחה (Thread-Safe), ומבטיח אפס זליגות זיכרון עקב כתובות IP רדומות.

Promtail & Grafana Loki: שינוע הלוגים המובנים (JSON Structured Logs) מתיקיית ה-Logs המקומית ואינדוקסם ב-Loki.

Dashboards as Code (IaC): ניהול גרסאות מלא של 5 לוחות הבקרה ב-Git תחת grafana/dashboards/ וטעינתם האוטומטית ל-Grafana בעליית ה-Container.

Docker Compose Stack: פריסה בלחיצת כפתור אחת של כל תשתיות ה-Observability.

---

📝 מבנה לוג JSON (Structured Logging)

{
  "timestamp": "2026-08-06T10:30:15.123456",
  "level": "WARNING",
  "message": "[PORT SCAN DETECTED] Host 10.0.0.4 scanned 18 unique ports",
  "logger": "NetworkGuardian",
  "src_ip": "10.0.0.4",
  "event_type": "PORT_SCAN",
  "details": "18 ports scanned"
}

---

⚙️ התקנה והרצה (Quick Start)

## 1. Clone the repository
git clone https://github.com/Raz-Eini/python_sniffer.git
cd python_sniffer
2. Environment Setup

cp .env.example .env # Set your Grafana password in .env
3. Start Observability Stack (Grafana, Loki, Promtail)

Grafana will automatically provision all dashboards from grafana/dashboards/

docker compose up -d
4. Setup Python Environment

python -m venv .venv
..venv\Scripts\activate     # On Windows
source .venv/bin/activate    # On Linux/Mac
pip install -r requirements.txt
5. Run NIDS Engine (Requires Administrator / Root)

On Linux / Mac:

sudo .venv/bin/python main.py
On Windows (Run PowerShell / CMD as Administrator):

python main.py
6. (Optional) Run Attack Simulator in a separate terminal

python test_attack.py

📊 גישה ל-Grafana: היכנס בדפדפן ל-http://localhost:3000 (שם משתמש: admin, סיסמה מוגדרת ב-.env). כל הדשבורדים כבר יופיעו טעונים ומוכנים לשימוש!

---

📄 רישיון

הפרויקט מופץ תחת רישיון MIT – חופשי לשימוש ושינוי למטרות לימודיות ומחקריות.

---

👨‍💻 Raz Eini (2026)