Lightweight Network Intrusion Detection System (NIDS)
中文版说明 | English
heidsoft-nids is a high-performance, lightweight NIDS written in C, supporting macOS and Linux. It provides real-time packet capture, protocol parsing, rule-based detection, machine learning anomaly detection, and a Web Dashboard.
AGPL-3.0 License — If you run heidsoft-nids as a network service, you must make your source code available under the same license.
- Network layer: IPv4/IPv6 header parsing
- Transport layer: TCP/UDP/ICMP protocol parsing
- Application layer: HTTP, DNS, TLS/SSL, QUIC, SMTP, SSH
- Fingerprinting: JA3/TLS fingerprint, HTTP User-Agent analysis
| Module | Capabilities |
|---|---|
| Rule Engine | Snort-style rules: content, uricontent, PCRE, threshold detection |
| App-layer Attack | SQL injection, XSS, command injection, path traversal, Web shell |
| Scan Detection | TCP NULL/Xmas/FIN scan, port scan, SYN Flood |
| Tunnel Detection | DNS Tunnel (Base32/Hex/Subdomain), DoH (DNS-over-HTTPS) |
| Container Security | Docker API unauthorized, XMRig/TEAMTNT mining, Tor network, container escape |
| Cloud Security | Cloud metadata service access (AWS/GCP/Azure), credential theft detection |
| Brute Force | SSH/RDP brute force frequency detection |
| Protocol Anomaly | NTP amplification, SSDP abuse, mDNS/LLMNR spoofing |
- EWMA traffic modeling: Packet rate, byte rate, packet size baseline
- Z-Score detection: Multi-dimensional anomaly scoring
- Protocol deviation detection: HTTP status distribution, DNS NXDOMAIN rate, TLS SNI length anomaly
- Lightweight design: O(1) per-packet detection, no external ML framework dependency
- VirusTotal API v3: IP/Domain/URL/JA3 reputation lookup
- AlienVault OTX: Community threat intelligence (no API key required)
- Shodan: IP vulnerability information
- Local cache: 1-hour TTL to avoid duplicate queries
- Real-time statistics (throughput, protocol distribution, Top N connections)
- Alert management (level filtering, deduplication)
- Connection tracking view
- Rule management and hot reload
- RESTful API + Prometheus metrics export (
/metrics)
macOS:
brew install glib json-c pkg-configUbuntu/Debian:
sudo apt install libpcap-dev libglib2.0-dev libjson-c-dev libsqlite3-dev libcurl4-openssl-devCentOS/RHEL:
sudo yum install glib2-devel libcap-devel libnetfilter_queue-devel json-c-devel sqlite-devel libcurl-develgit clone https://github.com/heidsoft/heidsoft-nids.git
cd heidsoft-nids
make clean && makeOn macOS with Homebrew GCC:
make CC=gccLive capture (requires root):
sudo ./heidsoft-nids -i en0 -R config/rules.conf -jOffline replay:
./heidsoft-nids -r /path/to/capture.pcap -R config/rules.conf -j -vDashboard only:
./heidsoft-nids -w 8080Docker:
docker-compose up -d-i <iface> Live capture interface (requires root)
-r <file> Offline pcap file replay
-c <file> JSON configuration file
-R <file> Snort-style rule file
-I Enable IPS mode (send TCP RST to block)
-o <file> Alert output file
-w <port> Web Dashboard port (default 8080)
-j JSON-formatted alert output
-v Verbose mode
-S Output to syslog
-h Show help
heidsoft-nids
├── src/
│ ├── main.c # Entry point, signal handling, init
│ ├── nids.h # Core header (types, global context)
│ ├── core/ # Core modules
│ │ ├── init.c # CLI parsing, initialization
│ │ ├── logging.c # Log system (INFO/WARN/ERR/DEBUG)
│ │ └── utils.c # Utilities (IP parsing, checksum, URL decode)
│ ├── capture/
│ │ └── pcap.c # libpcap wrapper (live + offline)
│ ├── net/ # Protocol parsing
│ │ ├── parser_tcp.c # TCP + SYN Flood + port scan + SSH brute force
│ │ ├── parser_udp.c # UDP + QUIC + NTP + mDNS/SSDP
│ │ ├── parser_icmp.c # ICMP parsing
│ │ ├── parser_http.c # HTTP + OWASP LLM security detection
│ │ ├── parser_dns.c # DNS + tunnel + malicious domain
│ │ └── parser_tls.c # TLS JA3/JA4 fingerprint
│ ├── stream/
│ │ └── conntrack.c # 5-tuple hash table, TCP state machine
│ ├── detection/
│ │ ├── rules.c # Snort-style rule parser + matcher
│ │ ├── pii.c # PII sensitive data detection
│ │ ├── container/ # Container security
│ │ └── correlation/ # Alert correlation (attack chain)
│ ├── ml/ # ML anomaly detection
│ │ └── ml.c # EWMA baseline, Z-Score detection
│ ├── threat_intel/ # Threat intelligence
│ │ └── threat_intel.c # VirusTotal/OTX/Shodan API
│ ├── alert/ # Alert system
│ ├── ips/ # IPS (TCP RST rejection)
│ ├── stats/ # Statistics + Prometheus metrics
│ ├── storage/ # SQLite + PCAP writer
│ ├── config/ # JSON configuration
│ ├── http/ # Web Dashboard + embedded HTML
│ └── os/ # Platform abstraction (Linux/macOS)
├── config/
│ ├── config.json # Main configuration
│ └── rules.conf # Detection rules
├── tests/
│ └── run_tests.sh # Smoke tests
├── Dockerfile
└── Makefile
| Endpoint | Description |
|---|---|
GET / |
Dashboard home |
GET /api/health |
Health check |
GET /api/stats |
Real-time statistics |
GET /api/alerts?max=50&level=3 |
Alert list |
GET /api/conns |
Active connections |
GET /api/rules |
Rule list |
POST /api/rules/reload |
Hot reload rules |
GET /api/ml/stats |
ML baseline statistics |
GET /api/threat-intel/stats |
Threat intel statistics |
GET /metrics |
Prometheus metrics |
| Metric | Value |
|---|---|
| Packet processing latency | < 1ms/pkt |
| Memory footprint | ~50MB (idle) |
| CPU (1Gbps traffic) | ~15% single core |
| Max concurrent connections | 65,536 |
Test environment: macOS M1, 8GB RAM, 1Gbps capture
- v0.2 — eBPF zero-copy capture support
- v0.3 — PostgreSQL storage + cluster mode
- v0.4 — MITRE ATT&CK alert mapping
- v0.5 — Suricata rule compatibility
- v1.0 — Production-ready release
See CONTRIBUTING.md for development workflow, code style, and module integration guidelines.
See SECURITY.md for vulnerability reporting. Do NOT file public GitHub issues for security vulnerabilities.
GNU Affero General Public License v3 (AGPL-3.0)
Copyright (c) 2024-2026 heidsoft
If you run this software as a network service, you must make the source code available under AGPL-3.0.