# yassinom/zeroshield architecture

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

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

## Overview

##### Project Type and Purpose
- ZeroShield is a specialized security tool (not a traditional web full-stack) built in Python. Its purpose is real-time zero-day attack detection on Linux systems using ML/DL. It includes network traffic monitoring, storage, model-based prediction, and a minimal GUI for reporting.

##### File Structure Analysis
- Top-level scripts:
- main.py – Orchestrator that initializes components
- sniffer.py – Captures live network traffic
- prediction.py & zerodayprediction.py – Load models and classify traffic
- gui.py – Presents alerts/results to the user
- models/
- autoencoder_model.keras – Pretrained deep autoencoder for anomaly detection
- tabnet_UGransome.zip – Pretrained TabNet model for threat classification
- requirements.txt – Python deps (Scapy, TensorFlow/Keras, PyMongo, PyQT or other GUI libs)
- Docker integration for MongoDB (README instructions)
- README provides architecture screenshot, ML focus, and deployment steps.

##### Key Components
a. Network Traffic Source
– Linux network interface (e.g., eth0)
– sniffer.py (Scapy or libpcap wrapper)
b. Message Bus / Data Buffer (optional)
– In-memory queue or direct hand-off from sniffer.py to prediction modules
c. ML Inference Pipeline
– prediction.py (loads autoencoder_model.keras)
– zerodayprediction.py (loads TabNet model)
– Preprocessing layer (feature extraction from raw packets)
d. Data Storage
– MongoDB container (stores raw traffic, features, prediction results)
– Access via PyMongo
e. User Interface / Reporting
– gui.py displays alerts, statistics, graphs
f. Orchestration
– main.py ties together the sniffer, prediction pipeline, DB, and GUI

##### Relationships & Data Flow
1) main.py starts MongoDB connection & GUI
2) sniffer.py captures packets → feature extractor
3) Extracted features → prediction.py & zerodayprediction.py
4) Predictions & metadata → MongoDB
5) gui.py queries MongoDB & displays real-time alerts
6) (Optional) CLI or logging subsystem for audit

##### Architectural Patterns & Design Principles
- Pipe-and-Filter: sniffer → features → models → DB/GUI
- Single Responsibility: each script focuses on one concern
- Loose Coupling via MongoDB as a persistence bus
- Modular ML Components: interchangeable models in models/

##### Technologies & Frameworks
- Python 3.x
- Scapy or libpcap (network capture)
- TensorFlow/Keras (autoencoder_model.keras)
- PyTorch/TabNet (tabnet_UGransome.zip)
- MongoDB (Docker container)
- PyMongo (DB client)
- PyQT or Tkinter (gui.py)
- Docker for database isolation

##### Detailed Breakdown
- Layer 1 (Infrastructure): Linux Host, Dockerized MongoDB
- Layer 2 (Capture & Ingestion): sniffer.py → feature extraction
- Layer 3 (ML Inference): autoencoder + TabNet modules
- Layer 4 (Data Persistence): MongoDB collections for raw packets, features, predictions
- Layer 5 (Presentation): gui.py, CLI logs, optional REST endpoint

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Infrastructure"
        LINUX["Linux Host"]:::external
        MONGO_DB_DOCKER[(MongoDB Docker Container)]:::storage
    end

    subgraph "Orchestration & Ingestion"
        MAIN["Orchestrator (main.py)"]:::orchestration
        SNF["Packet Capture (sniffer.py)"]:::processing
        FEAT["Feature Extraction"]:::processing
        LINUX --> MAIN
        MAIN --> SNF
        SNF --> FEAT
    end

    subgraph "ML Inference"
        AE["Autoencoder Predictor (prediction.py)"]:::processing
        AEModel["autoencoder_model.keras"]:::model
        ZT["TabNet Predictor (zerodayprediction.py)"]:::processing
        TabModel["tabnet_UGransome.zip"]:::model
        FEAT -->|features| AE
        FEAT -->|features| ZT
        AE -->|loads model| AEModel
        ZT -->|loads model| TabModel
    end

    subgraph "Persistence"
        MONGO_DB_STORAGE[(MongoDB Storage)]:::storage
        AE -->|predictions| MONGO_DB_STORAGE
        ZT -->|predictions| MONGO_DB_STORAGE
        FEAT -.->|raw data| MONGO_DB_STORAGE
    end

    subgraph "Presentation & Reporting"
        GUI["GUI (gui.py)"]:::ui
        CLI["CLI Logs"]:::external
        GUI -->|queries| MONGO_DB_STORAGE
        CLI -->|logs| MONGO_DB_STORAGE
    end

    %% Click Events
    click SNF "https://github.com/yassinom/zeroshield/blob/main/sniffer.py"
    click MAIN "https://github.com/yassinom/zeroshield/blob/main/main.py"
    click AE "https://github.com/yassinom/zeroshield/blob/main/prediction.py"
    click ZT "https://github.com/yassinom/zeroshield/blob/main/zerodayprediction.py"
    click AEModel "https://github.com/yassinom/zeroshield/blob/main/models/autoencoder_model.keras"
    click TabModel "https://github.com/yassinom/zeroshield/blob/main/models/tabnet_UGransome.zip"
    click README "https://github.com/yassinom/zeroshield/blob/main/README.md"
    click REQ "https://github.com/yassinom/zeroshield/blob/main/requirements.txt"
    click GUI "https://github.com/yassinom/zeroshield/blob/main/gui.py"
    click PREVIEW "https://github.com/yassinom/zeroshield/blob/main/screenshots/preview.mp4"

    %% Styles
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef storage fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef orchestration fill:#98FB98,stroke:#000,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#000,stroke-width:1px
    classDef model fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ui fill:#FFFF00,stroke:#000,stroke-width:1px
```
