How bishopfox/eyeballer works
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)