A lightweight, modular Network Intrusion Detection System built from scratch in Python. Designed for real-time traffic analysis and offline pcap inspection with signature-based and anomaly-based detection engines.
Modern networks face constant threats — from port scanning and SYN floods to SQL injection attempts hidden in packet payloads. Commercial IDS solutions are often heavyweight and opaque. This project implements a transparent, extensible detection pipeline that can be used for learning, research, and practical network security monitoring.
- Dual detection engines — signature matching (rule-based) and statistical anomaly detection working in parallel
- Live capture & offline analysis — sniff traffic from a network interface or analyze existing
.pcapfiles - Configurable YAML rules — define detection rules for port-based, payload-based, and rate-based attacks
- Threat classification — automatically categorizes detected threats (reconnaissance, exploitation, denial of service)
- Severity scoring — four-tier severity model (low / medium / high / critical) with configurable alert thresholds
- Rich terminal dashboard — real-time statistics and color-coded alert display
- Automated reporting — generates JSON and human-readable text reports after each analysis session
nids-project/
├── capturer/ Packet capture & parsing layer
│ ├── packer_capture.py Live traffic sniffing (scapy)
│ ├── packet_parser.py Raw packet → structured dict (TCP/UDP/ICMP/payload)
│ └── pcap_reader.py Offline .pcap file reading (eager, lazy, generator)
├── analyzer/ Detection & classification layer
│ ├── signature_engine.py Rule matching engine (port, payload regex, rate limiting)
│ ├── anomaly_detector.py Statistical anomaly detection (rate spikes, large packets, port scans)
│ ├── threat_classifier.py Threat categorization and severity scoring
│ └── rules_loader.py YAML rule parsing and validation
├── alerts/ Alert management layer
│ ├── alert_manager.py Central alert pipeline with severity filtering
│ ├── notifier.py Rich console notifications
│ └── severity_scorer.py Severity level utilities
├── dashboard/ Monitoring & reporting layer
│ ├── stats_aggregator.py Real-time traffic statistics
│ ├── live_monitor.py Terminal-based live dashboard (rich)
│ └── report_generator.py JSON and text report generation
├── config/
│ └── rules.yaml Detection rules
├── data/
│ └── sample.pcap Sample capture for testing
└── main.py CLI entry point
Rules are defined in config/rules.yaml and support three condition types:
| Type | Description | Example |
|---|---|---|
port |
Matches destination port and TCP flags | SSH scan detection on port 22 with SYN flag |
payload |
Regex search inside packet payload | SQL injection patterns like UNION SELECT |
rate |
Packet count threshold within a time window | SYN flood: 100+ SYN packets per second from one source |
- Python 3.10+
- Scapy — low-level packet capture and dissection
- PyYAML — rule configuration
- Rich — terminal UI, tables, colored output
pip install -r requirements.txtpython main.py pcap data/sample.pcap
python main.py pcap data/sample.pcap --min-severity lowpython main.py live Ethernet
python main.py live Ethernet --count 1000 --min-severity high┌─ [CRITICAL] syn_flood ──────────────────────────────┐
│ Time: 2025-04-20 15:30:12 │
│ Source: 192.168.1.105 -> 10.0.0.1 │
│ Category: denial_of_service │
│ Detail: SYN flood attack │
└─────────────────────────────────────────────────────┘
After analysis, a full report is saved to the reports/ directory in both JSON and plain text formats.
- Integration with external logging systems (syslog, ELK stack)
- Machine learning-based anomaly detection module
- Web-based dashboard with real-time WebSocket updates
- PCAP replay with configurable speed for testing
- IP reputation database integration
MIT