How rathalos1234/ai-ids works
Project type and purpose
• Full-stack network intrusion detection system (IDS)
• Python CLI & long-running service for live capture, training, verification, monitoring
• Vue.js single-page app for real-time alerts, logs, firewall controls
• Docker-Compose deployment with Nginx reverse proxy
File structure (key components)
• Top-level Python modules:
– main.py: CLI entrypoint (train, verify, monitor)
– packet_processor.py → feature engineering
– anomaly_detector.py → IsolationForest scoring
– signature_engine.py → rule-based signature hits
– network_monitor.py, firewall.py → live-capture loop, iptables blocking
– api.py → REST/WebSocket API server (health, alert stream, banlist, settings)
– webdb.py → lightweight persistent store (bans, settings)
• “models/iforest.joblib”: serialized trained model bundle
• “data/rolling.parquet”: optional Parquet store of engineered rows
• UI folder (“ui/…”): Vue.js app (App.vue, router.js, api.js, views/*.vue)
• docker-compose.yml, nginx.conf → container definitions, routing
• ops/*.service & scripts/ → systemd units & helper scripts for install, backup, retention
• tests/ & tests/ui/ → Python pytest modules + Playwright end-to-end UI tests
README for architectural patterns
• Pipeline stages: capture → feature-engineer → train → save/verify → monitor
• SignatureEngine as plug-in stage in monitoring loop
• REST and event-stream API feeding UI
• Optional firewall bridge using Linux iptables
• Deployment via Docker + Compose behind Nginx
Main components
a. Network Interface (eth0 or lo)
b. Python Backend Service (container):
• Packet Capture + Processor
• Feature Engineering Module
• Anomaly Detector (IsolationForest)
• Signature Engine (rule evaluator)
• Local Persistence: Model Store, Parquet Store, WebDB
• REST & WebSocket API Endpoints
• Firewall Controller (iptables)
c. Vue.js Frontend (container):
• HTTP(S) & WebSocket client
• UI Views: Dashboard, Alerts, Logs, Settings, BanList
d. Nginx Reverse Proxy (container or host):
• TLS termination (optional)
• HTTP routing → API vs. static UI assets
e. External Systems:
• Systemd services for backup/retention timers
• CI/CD pipeline (GitHub Actions → Docker image → SSH deploy)
• Linux host firewall subsystem (iptables)
Relationships and data flows
• Packets flow from Network Interface → Packet Processor → Feature Engineering →
→ Anomaly Detector & Signature Engine → generate Alert/Signature events
• Events pushed to API’s event stream (WebSocket or Server-Sent Events)
• Frontend subscribes to event stream & polls REST endpoints for history, logs, banlist
• User actions in UI (e.g., “Block IP”) → REST API call → Firewall Controller → iptables → WebDB updated
• Training & verification invoked via CLI (main.py) reading/writing model bundles in “models/”
• Optional Parquet persistence writes to “data/rolling.parquet” for offline retraining
Architectural patterns and principles
• Modular pipeline: decoupled processing stages (processor → anomaly → signatures)
• Separation of concerns: CLI vs. long-running service vs. UI vs. persistence
• Single backend monolith (in one container) exposing microservice-style API
• Event-driven UI via WebSocket/SSE for real-time alerts
• Infrastructure as code: Compose + systemd units + setup scripts