Guardian-IDS: Intrusion Detection System

Guardian-IDS is a sophisticated, modular Intrusion Detection System (IDS) designed specifically for IoT ecosystems (like Smart Home environments). It monitors network traffic in real-time, builds behavioral baselines for devices, and automatically mitigates threats such as DDoS attacks, port scanning, and lateral movement.

🏗️ Project Structure

guardian-ids/
├── main_guardian.py       # Entry point - The IDS Control Console
├── config/                # ✨ NEW: Configuration files (YAML/JSON)
│   └── settings.yaml      # Thresholds, Whitelists, and OS settings
├── analyzer/
│   ├── traffic_profiler.py   # Traffic profiling (Adaptive Baselines)
│   ├── anomaly_detector.py   # Detection algorithms (Threshold/Pattern)
│   └── threat_signatures.py  # Malicious signature library
├── core/
│   ├── packet_sniffer.py     # OS-Aware Scapy Sniffer
│   ├── alert_manager.py      # Alert levels & Notifications
│   └── logger.py             # Standard & JSON Logging
├── mitigation/
│   ├── firewall_mimic.py     # Firewall blocking simulation
│   └── device_quarantine.py  # Device isolation workflow
├── logs/                     # JSON/Text Security Audit Logs
├── docs/                  # ✨ NEW: Documentation & Screenshots
├── tests/
│   └── traffic_injector.py   # Malicious traffic simulator
└── requirements.txt

🌟 Feature List

A. Adaptive Traffic Profiling

• Behavioral Whitelisting: Automatically learns the "Normal" behavior of IoT devices. (e.g., A Smart Bulb should only consume ~10KB/min and communicate with specific Cloud IPs).
• Threshold Monitoring: Detects sudden traffic spikes. If a lightbulb starts transmitting at 200Kbps, the system flags it as a potential DDoS node.

B. Malicious Signature Detection

• Anti-Port Scanning: Detects if a compromised device is performing lateral movement scans against the Gateway or neighboring IoT devices.
• Protocol Anomaly Detection: Identifies traffic inconsistent with device types (e.g., A smart toaster initiating an SSH or Telnet request).

C. Active Auditing & Security Scanning

• Passive Triggered Scanning: Automatically initiates a deep port scan via a SecurityScanner when anomalous traffic is detected from a specific host.
• Dynamic Security Scoring: Combines traffic risk and vulnerability scan results to provide a real-time health score for every device.

D. Automated Remediation & Isolation

• Network Quarantine: Once a device is deemed "Compromised," it is visually flagged on the dashboard and "virtually severed" from the network to prevent further infection.
• SOC Integration: Generates industry-standard JSON security logs, ready to be exported to any Security Operations Center (SOC) or SIEM (like ELK stack).

🛠️ Installation & Setup

Prerequisites

• Python 3.8+
• Root/Admin Privileges: Required for capturing raw packets (BPF/Raw Sockets).

Install Dependencies

pip install scapy cryptography pyyaml requests psutil

Quick Start

1. Start the IDS Console:

sudo python main_guardian.py

2. Launch a Simulated Attack (in a separate terminal):

sudo python -m tests.traffic_injector

📝 Usage Notes for macOS Users

Due to macOS kernel restrictions (BPF architecture), when monitoring the loopback interface (lo0), the BPF filter might drop packets with spoofed source IPs. For testing purposes, it is recommended to monitor the physical interface (en0) or use filter_str=None in the PacketSniffer configuration.

Cross-Platform Usage Notes

• Linux (Ubuntu/Debian/CentOS):

  • Interface: Use eth0, wlan0, or any.
  • Loopback: lo.
  • Performance: Best performance with filter="ip". Linux handles BPF filters natively and efficiently.

• macOS (Darwin):

  • Interface: Use en0 (Wi-Fi) or en1.
  • Loopback: lo0.
  • Constraint: Due to BSD-style encapsulation, filter="ip" may drop local loopback packets. Use filter_str=None if testing on lo0.

• Windows:

  • Requirement: Requires Npcap (installed in WinPcap API-compatible mode).
  • Interface: Use conf.ifaces to find the GUID of your adapter.

📩 Contact & Contributions

Developed by Da-Wei Lin.