# banothshiva33/zeroshield architecture

> Architecture diagram of the GitHub repository banothshiva33/zeroshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/banothshiva33/zeroshield
- Repository: https://github.com/banothshiva33/zeroshield

## Overview

ZeroShield is a small demo system with four clear boundaries: telemetry collection and model training, runtime detection/response, attack simulation, and the live dashboard. The architecture is built around a Python backend that owns all security logic, with a React frontend that is effectively a read-only operator console.

1. **Telemetry and model artifacts**
   - `data/baseline.csv` is the captured “normal” workload dataset.
   - `backend/collector.py` produces that baseline from real host/cloud-like metrics.
   - `backend/train_model.py` trains an IsolationForest anomaly model and writes `backend/model.pkl`.
   - These files form the offline ML pipeline: collect → train → persist model artifact.

2. **Runtime detection service**
   - `backend/app.py` is the central orchestrator.
   - It loads the trained model, generates or receives telemetry, scores it, and decides whether a workload is normal, suspicious, or high risk.
   - It also owns the response state machine that flips isolation posture between monitoring, recovered, and quarantined.

3. **Live API and event stream**
   - The backend exposes REST endpoints for current status and historical views: `/status`, `/history`, `/isolation-log`.
   - It also exposes action endpoints for control flow: `/simulate-attack` and `/stop-attack`.
   - A Socket.IO channel named `update` pushes live status objects to the UI, so the dashboard is event-driven rather than polling-only.

4. **Attack simulation subsystem**
   - `simulator/attack_sim.py` generates synthetic attack telemetry from the baseline dataset.
   - It emits typed attacks such as CPU spike, auth flood, memory exhaustion, and slowdown, each with mild/moderate/severe severity.
   - This simulator is the main source of “bad” telemetry for the demo and is invoked by the backend during attack mode.

5. **Response engine and isolation boundary**
   - The backend is not just scoring anomalies; it also converts scores into operational action.
   - High confidence causes quarantine/isolation, while lower tiers remain in monitoring mode.
   - The response output includes workload ID, confidence tier, chosen action, and isolation status, which is what the dashboard surfaces as the security decision layer.

6. **Frontend dashboard**
   - `frontend/zeroshield-ui` is a Vite/React application that renders the operator view.
   - It consumes REST data and Socket.IO updates from the backend.
   - The UI is organized around live threat score, workload isolation status, attack intelligence, response engine summary, and recent alerts/trend visualization.

7. **Data flow from normal state to attack state**
   - Baseline telemetry is collected first, then the model is trained offline.
   - At runtime, the backend continuously scores incoming or simulated telemetry against that baseline.
   - When `/simulate-attack` is triggered, the simulator shifts the telemetry pattern, the anomaly score rises, and the backend updates both the response state and the streamed dashboard payload.

8. **State and event history**
   - The backend keeps recent detection history and an isolation log.
   - Those logs are separate from the live status stream so the UI can show both “current state” and “what just happened.”
   - This is the main temporal boundary in the system: live telemetry versus durable recent event context.

9. **Cloud-workload-shaped metrics**
   - The system models metrics that resemble infrastructure telemetry rather than generic app events: CPU utilization, memory utilization, request throughput, auth failure rate, and service latency.
   - That metric shape matters because both the IsolationForest and the simulator operate on the same feature semantics.
   - The architecture is therefore centered on workload behavior, not network packets or endpoint malware.

10. **Deployment topology**
   - `docker-compose.yml` wires backend and frontend together for local/demo deployment.
   - The backend container serves the Flask/Socket.IO API; the frontend container serves the React UI.
   - This creates a two-tier runtime layout: one service for detection/response, one service for presentation.

11. **Tech stack boundaries**
   - Backend: Python, Flask, Flask-SocketIO, scikit-learn, pandas, psutil.
   - Simulator: Python with pandas/NumPy-style synthetic data generation.
   - Frontend: React, Vite, socket.io-client, Recharts.
   - These are not just implementation details; they define the runtime split between offline ML, live event processing, and visualization.

12. **What to show in an architecture diagram**
   - A pipeline from `collector.py` to `baseline.csv` to `train_model.py` to `model.pkl`.
   - A runtime backend box that ingests telemetry, scores anomalies, runs the response engine, and emits REST/WebSocket updates.
   - A simulator box feeding attack telemetry into the backend.
   - A React dashboard box consuming live updates and presenting status, alerts, and trends.
   - Docker Compose as the optional deployment wrapper around the backend and frontend services.

Main entry points: [`backend/app.py`](https://github.com/banothshiva33/zeroshield/blob/main/backend/app.py) (App), [`frontend/zeroshield-ui`](https://github.com/banothshiva33/zeroshield/tree/main/frontend/zeroshield-ui) (Dashboard), [`docker-compose.yml`](https://github.com/banothshiva33/zeroshield/blob/main/docker-compose.yml) (Compose), [`data/baseline.csv`](https://github.com/banothshiva33/zeroshield/blob/main/data/baseline.csv) (Baseline Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline_ml["Offline ML"]
  node_collector["Collector<br/>telemetry capture<br/>[collector.py]"]
  node_baseline_csv["Baseline Data<br/>dataset<br/>[baseline.csv]"]
  node_train_model["Train Model<br/>ml training<br/>[train_model.py]"]
  node_model_pkl["Model Artifact<br/>trained model<br/>[model.pkl]"]
end

subgraph group_runtime_sec["Runtime Security"]
  node_app["App<br/>runtime orchestrator<br/>[app.py]"]
  node_detector(("Scorer<br/>anomaly detection"))
  node_response{{"Response Engine<br/>isolation control"}}
  node_status_api["REST API<br/>status endpoints"]
  node_socket_stream["Live Stream<br/>socket.io channel"]
  node_history_log["Event Log<br/>recent history"]
end

subgraph group_attack_sim["Attack Simulation"]
  node_attack_simulator["Simulator<br/>synthetic attacks<br/>[attack_sim.py]"]
end

subgraph group_frontend_ui["Dashboard"]
  node_dashboard["Dashboard<br/>react ui"]
end

subgraph group_deployment["Deployment"]
  node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
end

node_collector -->|"writes"| node_baseline_csv
node_baseline_csv -->|"feeds"| node_train_model
node_train_model -->|"persists"| node_model_pkl
node_model_pkl -->|"loads"| node_app
node_app -->|"scores"| node_detector
node_detector -->|"classifies"| node_response
node_response -->|"records"| node_history_log
node_app -->|"serves"| node_status_api
node_app -->|"pushes"| node_socket_stream
node_status_api -->|"reads"| node_dashboard
node_socket_stream -->|"updates"| node_dashboard
node_history_log -->|"shows"| node_dashboard
node_app -->|"simulate-attack"| node_attack_simulator
node_attack_simulator -->|"telemetry"| node_app
node_compose -->|"starts"| node_app
node_compose -->|"starts"| node_dashboard

click node_collector "https://github.com/banothshiva33/zeroshield/blob/main/backend/collector.py"
click node_baseline_csv "https://github.com/banothshiva33/zeroshield/blob/main/data/baseline.csv"
click node_train_model "https://github.com/banothshiva33/zeroshield/blob/main/backend/train_model.py"
click node_model_pkl "https://github.com/banothshiva33/zeroshield/blob/main/backend/model.pkl"
click node_app "https://github.com/banothshiva33/zeroshield/blob/main/backend/app.py"
click node_attack_simulator "https://github.com/banothshiva33/zeroshield/blob/main/simulator/attack_sim.py"
click node_dashboard "https://github.com/banothshiva33/zeroshield/tree/main/frontend/zeroshield-ui"
click node_compose "https://github.com/banothshiva33/zeroshield/blob/main/docker-compose.yml"

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_collector,node_baseline_csv,node_train_model,node_model_pkl toneBlue
class node_app,node_detector,node_response,node_status_api,node_socket_stream,node_history_log toneAmber
class node_attack_simulator toneMint
class node_dashboard toneRose
class node_compose toneIndigo
```

## Components

### Offline ML

Telemetry capture, baseline data, and model training

- [Collector](https://github.com/banothshiva33/zeroshield/blob/main/backend/collector.py): telemetry capture · Builds baseline workload metrics from host/cloud-like signals · `backend/collector.py`
- [Baseline Data](https://github.com/banothshiva33/zeroshield/blob/main/data/baseline.csv): dataset · Captured normal-workload telemetry used for training · `data/baseline.csv`
- [Train Model](https://github.com/banothshiva33/zeroshield/blob/main/backend/train_model.py): ml training · Trains the anomaly model and persists the artifact · `backend/train_model.py`
- [Model Artifact](https://github.com/banothshiva33/zeroshield/blob/main/backend/model.pkl): trained model · Serialized IsolationForest model loaded at runtime · `backend/model.pkl`

### Runtime Security

Live scoring, response, and event state

- [App](https://github.com/banothshiva33/zeroshield/blob/main/backend/app.py): runtime orchestrator · Central Flask/Socket.IO service that scores telemetry and drives response · `backend/app.py`
- **Scorer**: anomaly detection · Turns telemetry into normal, suspicious, or high-risk decisions
- **Response Engine**: isolation control · Maps confidence tiers to monitoring, recovery, or quarantine
- **REST API**: status endpoints · Serves current state, history, isolation log, and control actions
- **Live Stream**: socket.io channel · Pushes update events to the dashboard
- **Event Log**: recent history · Holds detection history and isolation events separate from live state

### Attack Simulation

Synthetic hostile telemetry generation

- [Simulator](https://github.com/banothshiva33/zeroshield/blob/main/simulator/attack_sim.py): synthetic attacks · Generates CPU, auth, memory, and slowdown attack telemetry · `simulator/attack_sim.py`

### Dashboard

Operator console and live visualization

- [Dashboard](https://github.com/banothshiva33/zeroshield/tree/main/frontend/zeroshield-ui): react ui · Read-only operator console for live threats, isolation, and trends · `frontend/zeroshield-ui`

### Deployment

Local compose wiring for demo runtime

- [Compose](https://github.com/banothshiva33/zeroshield/blob/main/docker-compose.yml): deployment · Wires backend and frontend services for local demo runs · `docker-compose.yml`

## Connections

- Collector → Baseline Data: writes · Captures baseline telemetry into the training dataset
- Baseline Data → Train Model: feeds · Provides normal workload data for offline training
- Train Model → Model Artifact: persists · Stores the trained IsolationForest artifact
- Model Artifact → App: loads · Runtime service reads the trained model on startup
- App → Scorer: scores · Telemetry is evaluated for anomaly risk
- Scorer → Response Engine: classifies · Detection output drives operational posture
- Response Engine → Event Log: records · Response decisions are written to recent history
- App → REST API: serves · Exposes REST status, history, isolation, and actions
- App → Live Stream: pushes · Streams live updates to connected clients
- REST API → Dashboard: reads · Dashboard consumes REST views and controls
- Live Stream → Dashboard: updates · Dashboard receives live status events
- Event Log → Dashboard: shows · Provides recent detection and isolation context
- App → Simulator: simulate-attack · Backend triggers attack mode and synthetic telemetry generation
- Simulator → App: telemetry · Synthetic attack workload is fed back into the runtime scorer
- Compose → App: starts · Compose launches the backend detection service
- Compose → Dashboard: starts · Compose launches the frontend UI service
