# bishopfox/eyeballer architecture

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

- Interactive diagram: https://gitdiagram.com/bishopfox/eyeballer
- Repository: https://github.com/bishopfox/eyeballer

## Overview

##### Project Type and Purpose
- Eyeballer is a Python-based, command-line ML classification tool.
- It ingests website screenshots, runs them through a TensorFlow/Keras model, and outputs human- and machine-readable predictions to assist in large-scale penetration tests.

##### High-Level Component Breakdown
a. External Screenshot Sources
– EyeWitness / GoWitness (or any screenshot tool)
– Filesystem directory of PNG/JPG screenshots
b. CLI Orchestration
– Entry point: eyeballer.py
– Commands: train, predict, evaluate
c. Data Preprocessing / Augmentation
– Module: eyeballer/augmentation.py
– Steps: resize, normalize, data‐augmentation (for training)
d. Model Definition & Persistence
– Module: eyeballer/model.py
– Defines network architecture, loads/saves .h5 weight files
e. Inference & Training Engine
– Predict path (loads pretrained weights, runs forward pass)
– Train path (loads images & labels.csv, runs backprop)
– Evaluate path (computes metrics on hold-out set)
f. Reporting / Visualization
– Module: eyeballer/visualization.py
– Templates: prediction_output_template.html → results.html + results.csv
g. Utilities & Data Tools
– utils/labelbox_to_labels.py, utils/resizer.sh, utils/reroll.py, utils/verify.py
h. Testing Suite
– tests/PredictTest.py + test data & test_weights.h5
i. External Dependencies
– Kaggle dataset (images/, labels.csv)
– GitHub (pretrained weights releases)
– Python packages (TensorFlow/Keras, NumPy, etc. from requirements.txt)

##### Component Relationships & Data Flow
1. Screenshots (external) → Filesystem
2. CLI (eyeballer.py) → invokes Preprocessor
3. Preprocessor → emits model-ready tensors
4. Model loader (model.py) + weights → Inference/Training
5. Inference → raw predictions → Visualization
6. Visualization → results.html & results.csv on disk
7. Train/Evaluate → metrics back to CLI console
8. Utilities → support any step with format conversions or sanity checks

##### Architectural Patterns & Principles
- Pipeline pattern: chained modules for data prep → model → reporting
- Separation of concerns: CLI vs. core logic vs. visualization vs. utilities
- Modularity for testability (tests directory, utils scripts)
- Config-by-convention (weight files, data folders, template files)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Sources"
        ExtTools["Screenshot Tools"]:::external
        KaggleData["Kaggle Dataset"]:::external
        GitHub["GitHub Releases"]:::external
    end

    subgraph "Filesystem"
        FSImages["Screenshot Dir (PNG/JPG)"]:::datastore
        KaggleImages["images/"]:::datastore
        KaggleLabels["labels.csv"]:::datastore
        LocalWeights[".h5 Weight Files"]:::datastore
        ResultsHTML["results.html"]:::datastore
        ResultsCSV["results.csv"]:::datastore
        Template["prediction_output_template.html"]:::datastore
    end

    subgraph "Core Modules"
        CLI["eyeballer.py"]:::core
        Preproc["augmentation.py"]:::core
        Model["model.py"]:::core
        Engine["Inference/Training Engine"]:::core
        Viz["visualization.py"]:::core
    end

    subgraph "Utilities & Data Tools"
        LabelConv["labelbox_to_labels.py"]:::util
        Reroll["reroll.py"]:::util
        Resizer["resizer.sh"]:::util
        Verify["verify.py"]:::util
    end

    subgraph "Testing Suite"
        PredictTest["PredictTest.py"]:::test
        TestData["tests/data"]:::test
        TestWeights["tests/models/test_weights.h5"]:::test
    end

    subgraph "Project Dependencies"
        ReqCPU["requirements.txt"]:::external
        ReqGPU["requirements-gpu.txt"]:::external
    end

    ExtTools -->|"screenshots"| FSImages
    FSImages -->|"images"| CLI
    KaggleData -->|"download images"| KaggleImages
    KaggleData -->|"download labels"| KaggleLabels
    GitHub -->|"download weights"| LocalWeights

    CLI -->|"command"| Preproc
    Preproc -->|"tensors"| Engine
    Engine -->|"uses architecture"| Model
    LocalWeights -->|"loads weights"| Model
    Model -->|"configured model"| Engine
    Engine -->|"raw predictions"| Viz
    Viz -->|"html output"| ResultsHTML
    Viz -->|"csv output"| ResultsCSV
    Template -->|"template used"| Viz

    Engine -->|"metrics"| CLI

    LabelConv -->|"label conversion"| Preproc
    Resizer -->|"resize"| Preproc
    Reroll -->|"data reroll"| Engine
    Verify -->|"sanity check"| CLI

    PredictTest -->|"invokes predict"| Engine
    TestData -->|"test images"| PredictTest
    TestWeights -->|"test weights"| PredictTest

    ReqCPU --> CLI
    ReqGPU --> CLI

    %% Click Events
    click CLI "https://github.com/bishopfox/eyeballer/blob/master/eyeballer.py"
    click Preproc "https://github.com/bishopfox/eyeballer/blob/master/eyeballer/augmentation.py"
    click Model "https://github.com/bishopfox/eyeballer/blob/master/eyeballer/model.py"
    click Viz "https://github.com/bishopfox/eyeballer/blob/master/eyeballer/visualization.py"
    click Template "https://github.com/bishopfox/eyeballer/blob/master/prediction_output_template.html"
    click LabelConv "https://github.com/bishopfox/eyeballer/blob/master/utils/labelbox_to_labels.py"
    click Reroll "https://github.com/bishopfox/eyeballer/blob/master/utils/reroll.py"
    click Resizer "https://github.com/bishopfox/eyeballer/blob/master/utils/resizer.sh"
    click Verify "https://github.com/bishopfox/eyeballer/blob/master/utils/verify.py"
    click PredictTest "https://github.com/bishopfox/eyeballer/blob/master/tests/PredictTest.py"
    click TestData "https://github.com/bishopfox/eyeballer/tree/master/tests/data"
    click TestWeights "https://github.com/bishopfox/eyeballer/blob/master/tests/models/test_weights.h5"
    click ReqCPU "https://github.com/bishopfox/eyeballer/blob/master/requirements.txt"
    click ReqGPU "https://github.com/bishopfox/eyeballer/blob/master/requirements-gpu.txt"

    %% Legend
    subgraph "Legend"
        LegendExt["Green: External"]:::external
        LegendCore["Blue: Core"]:::core
        LegendData["Orange: Data Stores"]:::datastore
        LegendUtil["Gray: Utils/Tests"]:::util
    end

    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffa500,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef test fill:#d3d3d3,stroke:#333,stroke-width:1px
```
