# sreevathsans/hybrid-intrusion-detection-system architecture

> Architecture diagram of the GitHub repository sreevathsans/hybrid-intrusion-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sreevathsans/hybrid-intrusion-detection-system
- Repository: https://github.com/sreevathsans/hybrid-intrusion-detection-system

## Overview

IDS-Hybrid detects network attacks using flow-level ML plus behavioral and volumetric checks, then blocks malicious sources and exposes attack state through a SOC dashboard. The graph preserves the documented inline packet-to-mitigation workflow and the monitoring and blockchain capabilities. IPS orchestration and dashboard WebSocket behavior are visible in excerpts; some mitigation, logging, and dashboard-state relationships are documented only at a high level, so those links cite the README.

Main entry points: [`ips/main.py`](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/main.py) (IPS Orchestrator), [`ips/expiry_engine.py`](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/expiry_engine.py) (State Expiry), [`dashboard_backend/main.py`](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/main.py) (Dashboard API), [`ips/block_manager.py`](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/block_manager.py) (IP Blocking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Traffic Detection"]
  node_nfqueue["Packet Capture<br/>[nfqueue_handler.py]"]
  node_ips["IPS Orchestrator<br/>[main.py]"]
  node_flows["Flow Aggregation<br/>[flow_manager.py]"]
  node_behavior["Behavior Detection<br/>[behavior_engine.py]"]
  node_volumetric["Volumetric Detection"]
  node_ml["Flow Classifier<br/>[ml_engine.py]"]
  node_features["Feature Extraction"]
  node_host["Host Aggregation<br/>[host_aggregator.py]"]
  node_offlinepredict["Offline Prediction<br/>[predict.py]"]
end

subgraph group_response["Prevention and Logging"]
  node_sessions["Attack Sessions"]
  node_blocking["IP Blocking<br/>[block_manager.py]"]
  node_expiry["State Expiry<br/>[expiry_engine.py]"]
  node_attacklog["Attack Logging<br/>[attack_logger.py]"]
end

subgraph group_blockchain["Blockchain Audit"]
  node_chainlog["Blockchain Logger"]
  node_chainconfig["Chain Configuration<br/>[attack_config.py]"]
  node_chainservice["Blockchain Scripts<br/>[store_log.py]"]
end

subgraph group_monitoring["SOC Monitoring"]
  node_api["Dashboard API<br/>[main.py]"]
  node_state["Dashboard State<br/>[state.py]"]
  node_logreader["Log Reader<br/>[log_reader.py]"]
  node_dashboard["SOC Dashboard<br/>[App.js]"]
end

node_traffic(("Network Traffic"))
node_ethereum{{"Ethereum Network"}}
node_launcher["System Launcher<br/>[main.py]"]

node_traffic -->|"enters queue"| node_nfqueue
node_nfqueue -->|"delivers packets"| node_ips
node_ips -->|"updates flows"| node_flows
node_ips -->|"checks behavior"| node_behavior
node_ips -->|"checks volume"| node_volumetric
node_ips -->|"classifies flows"| node_ml
node_ips -.->|"extracts features"| node_features
node_ips -.->|"aggregates hosts"| node_host
node_flows -->|"requests prediction"| node_ml
node_ips -->|"blocks threats"| node_blocking
node_blocking -->|"updates sessions"| node_sessions
node_ips -->|"starts cleanup"| node_expiry
node_expiry -->|"expires flows"| node_flows
node_expiry -->|"expires sources"| node_behavior
node_expiry -->|"expires sources"| node_volumetric
node_expiry -->|"expires blocks"| node_blocking
node_expiry -->|"expires sessions"| node_sessions
node_blocking -->|"writes events"| node_attacklog
node_attacklog -.->|"records attacks"| node_chainlog
node_chainlog -.->|"stores logs"| node_chainservice
node_chainservice -->|"writes transactions"| node_ethereum
node_launcher -.->|"runs offline mode"| node_offlinepredict
node_api -->|"reads status"| node_state
node_api -->|"reads logs"| node_logreader
node_api -->|"streams WebSocket data"| node_dashboard
node_dashboard -->|"connects live"| node_api
node_api -.->|"reports chain status"| node_ethereum

click node_nfqueue "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/nfqueue_handler.py"
click node_ips "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/main.py"
click node_flows "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/flow_manager.py"
click node_behavior "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/behavior_engine.py"
click node_volumetric "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/volumetric_engine.py"
click node_ml "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/ml_engine.py"
click node_features "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/feature_extractor.py"
click node_host "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/host_aggregator.py"
click node_sessions "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/attack_session_manager.py"
click node_blocking "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/block_manager.py"
click node_expiry "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/expiry_engine.py"
click node_attacklog "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/attack_logger.py"
click node_chainlog "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/blockchain_logger.py"
click node_chainconfig "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/blockchain_module/config/attack_config.py"
click node_chainservice "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/blockchain_module/scripts/store_log.py"
click node_api "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/main.py"
click node_state "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/state.py"
click node_logreader "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/log_reader.py"
click node_dashboard "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_frontend/src/App.js"
click node_offlinepredict "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ML/predict.py"
click node_launcher "https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nfqueue,node_ips,node_flows,node_behavior,node_volumetric,node_ml,node_features,node_host,node_offlinepredict toneBlue
class node_sessions,node_blocking,node_expiry,node_attacklog toneAmber
class node_chainlog,node_chainconfig,node_chainservice toneMint
class node_api,node_state,node_logreader,node_dashboard toneRose
class node_traffic,node_ethereum toneIndigo
class node_launcher toneTeal
```

## Components

### Traffic Detection

- [Packet Capture](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/nfqueue_handler.py): `ips/nfqueue_handler.py`
- [IPS Orchestrator](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/main.py): `ips/main.py`
- [Flow Aggregation](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/flow_manager.py): `ips/flow_manager.py`
- [Behavior Detection](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/behavior_engine.py): `ips/behavior_engine.py`
- [Volumetric Detection](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/volumetric_engine.py): `ips/volumetric_engine.py`
- [Flow Classifier](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/ml_engine.py): `ips/ml_engine.py`
- [Feature Extraction](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/feature_extractor.py): `ips/feature_extractor.py`
- [Host Aggregation](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/host_aggregator.py): `ips/host_aggregator.py`
- [Offline Prediction](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ML/predict.py): `ML/predict.py`

### Prevention and Logging

- [Attack Sessions](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/attack_session_manager.py): `ips/attack_session_manager.py`
- [IP Blocking](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/block_manager.py): `ips/block_manager.py`
- [State Expiry](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/expiry_engine.py): `ips/expiry_engine.py`
- [Attack Logging](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/attack_logger.py): `ips/attack_logger.py`

### Blockchain Audit

- [Blockchain Logger](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/ips/blockchain_logger.py): `ips/blockchain_logger.py`
- [Chain Configuration](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/blockchain_module/config/attack_config.py): `blockchain_module/config/attack_config.py`
- [Blockchain Scripts](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/blockchain_module/scripts/store_log.py): `blockchain_module/scripts/store_log.py`

### SOC Monitoring

- [Dashboard API](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/main.py): `dashboard_backend/main.py`
- [Dashboard State](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/state.py): `dashboard_backend/state.py`
- [Log Reader](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_backend/log_reader.py): `dashboard_backend/log_reader.py`
- [SOC Dashboard](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/dashboard_frontend/src/App.js): `dashboard_frontend/src/App.js`

### Other components

- **Network Traffic**
- **Ethereum Network**
- [System Launcher](https://github.com/sreevathsans/hybrid-intrusion-detection-system/blob/main/main.py): `main.py`

## Connections

- Network Traffic → Packet Capture: enters queue
- Packet Capture → IPS Orchestrator: delivers packets (evidence: `ips/main.py`)
- IPS Orchestrator → Flow Aggregation: updates flows (evidence: `ips/main.py`)
- IPS Orchestrator → Behavior Detection: checks behavior (evidence: `ips/main.py`)
- IPS Orchestrator → Volumetric Detection: checks volume (evidence: `ips/main.py`)
- IPS Orchestrator → Flow Classifier: classifies flows (evidence: `ips/main.py`)
- IPS Orchestrator → Feature Extraction: extracts features
- IPS Orchestrator → Host Aggregation: aggregates hosts (evidence: `ips/main.py`)
- Flow Aggregation → Flow Classifier: requests prediction (evidence: `ips/flow_manager.py`)
- IPS Orchestrator → IP Blocking: blocks threats (evidence: `ips/main.py`)
- IP Blocking → Attack Sessions: updates sessions (evidence: `ips/block_manager.py`)
- IPS Orchestrator → State Expiry: starts cleanup (evidence: `ips/main.py`)
- State Expiry → Flow Aggregation: expires flows (evidence: `ips/expiry_engine.py`)
- State Expiry → Behavior Detection: expires sources (evidence: `ips/expiry_engine.py`)
- State Expiry → Volumetric Detection: expires sources (evidence: `ips/expiry_engine.py`)
- State Expiry → IP Blocking: expires blocks (evidence: `ips/expiry_engine.py`)
- State Expiry → Attack Sessions: expires sessions (evidence: `ips/expiry_engine.py`)
- IP Blocking → Attack Logging: writes events (evidence: `ips/block_manager.py`)
- Attack Logging → Blockchain Logger: records attacks
- Blockchain Logger → Blockchain Scripts: stores logs
- Blockchain Scripts → Ethereum Network: writes transactions
- System Launcher → Offline Prediction: runs offline mode
- Dashboard API → Dashboard State: reads status (evidence: `dashboard_backend/main.py`)
- Dashboard API → Log Reader: reads logs (evidence: `dashboard_backend/main.py`)
- Dashboard API → SOC Dashboard: streams WebSocket data (evidence: `dashboard_backend/main.py`)
- SOC Dashboard → Dashboard API: connects live (evidence: `dashboard_frontend/src/App.js`)
- Dashboard API → Ethereum Network: reports chain status
