How banothshiva33/zeroshield works
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: app.py App · zeroshield-ui Dashboard · docker-compose.yml Compose · baseline.csv Baseline Data
Components 13
Offline ML
Telemetry capture, baseline data, and model training
- Collector · Builds baseline workload metrics from host/cloud-like signals
backend/collector.py - Baseline Data · Captured normal-workload telemetry used for training
data/baseline.csv - Train Model · Trains the anomaly model and persists the artifact
backend/train_model.py - Model Artifact · Serialized IsolationForest model loaded at runtime
backend/model.pkl
Runtime Security
Live scoring, response, and event state
- App · Central Flask/Socket.IO service that scores telemetry and drives response
backend/app.py - Scorer · Turns telemetry into normal, suspicious, or high-risk decisions
- Response Engine · Maps confidence tiers to monitoring, recovery, or quarantine
- REST API · Serves current state, history, isolation log, and control actions
- Live Stream · Pushes update events to the dashboard
- Event Log · Holds detection history and isolation events separate from live state
Attack Simulation
Synthetic hostile telemetry generation
- Simulator · Generates CPU, auth, memory, and slowdown attack telemetry
simulator/attack_sim.py
Dashboard
Operator console and live visualization
- Dashboard · Read-only operator console for live threats, isolation, and trends
frontend/zeroshield-ui
Deployment
Local compose wiring for demo runtime
- Compose · Wires backend and frontend services for local demo runs
docker-compose.yml
Connections 16
- 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