How bittb/network-intrusion-detection-system works
What this project is (from README + tree)
This repo is a Network Intrusion Detection System (NIDS) with:
• A Python detection engine (nids1.py, nids2.py) that sniffs/ingests network traffic and performs:
• signature-based detection (using nids_signatures.db)
• anomaly/ML-based detection (per README; confirm in code/requirements)
• A UI dashboard (React-style file set: App.js, Dashboard.js, Logs.js, AnomaliesTable.js, Settings.js, AnalyticsContext.js, CSS files)
• Some form of backend/API layer (backend/ directory + api.js in the root) that the UI calls to fetch status/logs/anomalies and push config.
• A database + schema (schema.sql, nids_signatures.db) used for signatures and/or logging.
How to read the file structure into architecture components
Files/directories into *diagrammable* components:
Frontend (SPA dashboard)
Evidence: App.js, index.js, index.html, many UI components and CSS.
Key subcomponents to show (don’t just label “frontend”—split it):
• App Shell / Router: App.js, Home.js, Navbar.js, Footer.js
• Dashboard views:
• Dashboard: Dashboard.js, StatusCard.js
• Logs: Logs.js
• Anomalies: AnomaliesTable.js (+ Anomalies.css)
• Settings/Configuration: Settings.js, ConfigurationForm.js
• State/Analytics context: AnalyticsContext.js
• API client module: api.js (explicit seam between UI and backend)
Backend/API service
Evidence: backend/ directory + frontend has api.js.
Split into likely backend modules (confirm by inspecting backend/):
• REST API / Controllers: endpoints for /status, /logs, /anomalies, /config, etc.
• Data access layer (DAL): reads/writes SQLite
• NIDS orchestration: either:
1) spawns/controls nids1.py / nids2.py, or
2) reads outputs written by those scripts (DB/files), or
3) receives events from them (queue/socket)
Detection engine (Python runtime)
Evidence: nids1.py, nids2.py, requirements.txt.
Split the “engine” into pipeline stages (these are the core of a NIDS and should be diagrammed distinctly):
• Packet Capture / Traffic Ingest (e.g., Scapy sniff on NIC)
• Preprocessing / Feature Extraction (Pandas/NumPy style transforms)
• Signature Detection (lookup/match against signatures DB)
• Anomaly Detection / ML Inference (TensorFlow/PyTorch if actually used)
• Alert Generation (severity, metadata)
• Logging/Reporting Writer (persist alerts/events)
Data stores
Evidence: nids_signatures.db, schema.sql.
• Signature DB (SQLite): nids_signatures.db (known threats)
• Event/Alert/Logs DB (SQLite): implied by schema.sql + README logging/reporting
Config
README references config.json but it’s not in the tree. Treat config as a component anyway:
• Config file / Settings store (file-based or DB-based)
• UI Settings page updates it via API
Network Interface (NIC)
↓
Packet capture (nids1.py / nids2.py)
↓
Detection pipeline
• signature matcher → consults Signature DB
• anomaly detector → uses ML model (if present)
↓
Alerts + logs persisted → Logs/Alerts DB
↓
Backend API reads DB (or receives events)
↓
Frontend SPA fetches via api.js and renders
• Dashboard status cards
• Logs list
• Anomalies table
User changes thresholds / interface / rules in Settings / ConfigurationForm
↓
Frontend calls backend endpoint (e.g., POST /config)
↓
Backend writes config (file/DB)
↓
Real-time aspect (call it out)
• Polling from UI to backend (setInterval calls to api.js)
or
• Server push (WebSocket/SSE)
If unknown, put a “?” note and verify in backend/ + api.js.
Architectural patterns to highlight (specific to this repo)
• Pipeline architecture inside detection engine (capture → preprocess → detect → alert → persist)
• Separation of concerns:
• UI components vs api.js (API boundary)
• API service vs detection engine (process boundary)
• Signatures vs events/logging (data boundary)
• Event sourcing-ish logging (append alerts/logs, then query for dashboard)
• Potential multi-process design (engine runs separately from API/UI)
Frontend components (inside SPA)
• Pages: Home/Dashboard/Logs/Anomalies/Settings
• Shared: Navbar/Footer/StatusCard
• State: AnalyticsContext
• API client: api.js
Detection engine pipeline (inside Python engine)
• Capture
• Feature extraction
• Signature detector
• Anomaly detector
• Alert scorer
• Persistence writer
Example sequence:
Packet arrives → capture → detect → write DB → API query → UI refresh/render.
This resolves ambiguity about timing and ownership.
Elements explicitly:
• Clear labels: “REST /logs”, “SQL read”, “SQL write”, “Packet sniff (Scapy)”
• Rectangles: services/containers (SPA, API, Engine)
• Cloud/external: NIC / network traffic, optional external threat intel feeds (if added later)
• Trust boundaries:
• Host boundary: what runs on the same machine vs separate machines
• Privilege boundary: packet capture often requires elevated permissions—note that on the engine container