# aashmitmckenzie/cyber-shield architecture

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

- Interactive diagram: https://gitdiagram.com/aashmitmckenzie/cyber-shield
- Repository: https://github.com/aashmitmckenzie/cyber-shield

## Overview

##### Project type and purpose
- This is an open-source research pipeline (CyberShield) that simulates broken access control (BAC) attacks in Dockerized web apps and then applies a machine-learning pipeline to detect and mitigate those attacks in real time. It is not a traditional full-stack web app but a data-driven ML framework with three phases: attack simulation, feature engineering, and model training/evaluation.

##### File structure
- Top-level scripts:
- bac_attack_automation.py → orchestrates BAC attack simulation against DVWA, WebGoat, Juice Shop
- get_ml_processed_features.py → transforms raw logs and JSON profiles into feature CSVs
- adv_model_training.ipynb & model_training.ipynb → Jupyter notebooks for training and comparing ML models
- Data artifacts:
- resource_access_patterns.json, user_behavior_profiles.json → JSON sources of simulated behavior
- *.csv Example files → intermediate and enhanced feature sets
- No nested directories—this is a linear, single-repo pipeline.

##### Insights from the README
- Three logical stages (Simulation, Preprocessing, Modeling)
- External dependencies: Dockerized target apps, JWT manipulation, multi-threading
- Key technologies: Python 3.8+, Jupyter, scikit-learn, XGBoost, JSON/CSV data stores

##### Diagramming the architecture
a. Main components
- External Targets (DVWA, WebGoat, JuiceShop in Docker)
- Attack Simulation Engine (bac_attack_automation.py)
- Raw Data Store (JSON logs, request traces)
- Feature Engineering Module (get_ml_processed_features.py)
- Feature Artifacts (ml_processed_features.csv, ml_enhanced_features.csv, ml_training_features.csv)
- Model Training & Evaluation (model_training.ipynb, adv_model_training.ipynb)
- Output Reports/Results (enhanced_bac_results.csv)
b. Relationships & interactions
1. Simulation Engine → sends HTTP requests / manipulates JWT → writes raw logs & JSON profiles
2. Raw Data → consumed by Feature Engineering → emits cleaned CSV feature sets
3. CSV Features → input to Model Training notebooks → produces trained models & evaluation metrics
4. Evaluation metrics → saved as CSV reports
c. Architectural patterns & principles
- Linear pipeline (batch processing)
- Modular separation: Simulation vs. Preprocessing vs. Modeling
- Data-driven research: raw data artifacts archived for reproducibility
d. Key technologies & frameworks
- Python scripts (automation, preprocessing)
- Jupyter Notebooks (interactive model training)
- Docker containers (target apps for simulation)
- scikit-learn, XGBoost, pandas for ML & data manipulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation Stage"
        direction TB
        AttackSimEngine["Attack Simulation Engine\nbac_attack_automation.py"]:::simulation
        subgraph "External Targets (Docker)" 
            direction TB
            DVWA["DVWA"]:::external
            WebGoat["WebGoat"]:::external
            JuiceShop["JuiceShop"]:::external
        end
        AttackSimEngine -->|"sends requests\nJWT manipulation"| DVWA
        AttackSimEngine -->|"sends requests\nJWT manipulation"| WebGoat
        AttackSimEngine -->|"sends requests\nJWT manipulation"| JuiceShop
        AttackSimEngine -->|"raw logs and profiles"| RawPatterns["resource_access_patterns.json"]:::dataartifact
        AttackSimEngine -->|"raw logs and profiles"| RawProfiles["user_behavior_profiles.json"]:::dataartifact
    end

    subgraph "Preprocessing Stage"
        direction TB
        RawPatterns --> FeatureEng["Feature Engineering Module\nget_ml_processed_features.py"]:::processing
        RawProfiles --> FeatureEng
        FeatureEng -->|"processed features"| ProcFeat["ml_processed_features.csv"]:::dataartifact
        FeatureEng -->|"enhanced features"| EnhFeat["ml_enhanced_features.csv"]:::dataartifact
        FeatureEng -->|"training features"| TrainFeat["ml_training_features.csv"]:::dataartifact
    end

    subgraph "Modeling Stage"
        direction TB
        ProcFeat --> ModelBaseline["Model Training & Evaluation\nmodel_training.ipynb"]:::modeling
        TrainFeat --> ModelBaseline
        ProcFeat --> ModelAdv["Advanced Model Training & Evaluation\nadv_model_training.ipynb"]:::modeling
        EnhFeat --> ModelAdv
        ModelBaseline -->|"evaluation metrics"| Reports["enhanced_bac_results.csv"]:::dataartifact
        ModelAdv -->|"evaluation metrics"| Reports
    end

    README["Project Documentation & Run Instructions\nREADME.md"]:::doc

    README -.-> AttackSimEngine

    click AttackSimEngine "https://github.com/aashmitmckenzie/cyber-shield/blob/main/bac_attack_automation.py"
    click FeatureEng "https://github.com/aashmitmckenzie/cyber-shield/blob/main/get_ml_processed_features.py"
    click ModelBaseline "https://github.com/aashmitmckenzie/cyber-shield/blob/main/model_training.ipynb"
    click ModelAdv "https://github.com/aashmitmckenzie/cyber-shield/blob/main/adv_model_training.ipynb"
    click RawPatterns "https://github.com/aashmitmckenzie/cyber-shield/blob/main/resource_access_patterns.json"
    click RawProfiles "https://github.com/aashmitmckenzie/cyber-shield/blob/main/user_behavior_profiles.json"
    click ProcFeat "https://github.com/aashmitmckenzie/cyber-shield/blob/main/ml_processed_features - Example.csv"
    click EnhFeat "https://github.com/aashmitmckenzie/cyber-shield/blob/main/ml_enhanced_features - Example.csv"
    click TrainFeat "https://github.com/aashmitmckenzie/cyber-shield/blob/main/ml_training_features - Example.csv"
    click Reports "https://github.com/aashmitmckenzie/cyber-shield/blob/main/enhanced_bac_results - Example.csv"
    click README "https://github.com/aashmitmckenzie/cyber-shield/blob/main/README.md"

    classDef simulation fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef external fill:#E3F2FD,stroke:#64B5F6,color:#000,shape:cloud
    classDef processing fill:#E8F5E9,stroke:#43A047,color:#000
    classDef modeling fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef dataartifact fill:#F5F5F5,stroke:#9E9E9E,color:#000,shape:cylinder
    classDef doc fill:#ECEFF1,stroke:#546E7A,color:#000,stroke-dasharray: 5 5
```
