# cybsam/blackeye-v2 architecture

> Architecture diagram of the GitHub repository cybsam/blackeye-v2, 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/cybsam/blackeye-v2
- Repository: https://github.com/cybsam/blackeye-v2

## Overview

##### Project type and purpose
- This is a command-line phishing toolkit (“BlackEye”) written as a Bash script (blackeye.sh) that automates the deployment of prebuilt phishing site templates.
- Its purpose is to present a fake login page for a selected brand, capture visitor IP and credentials via PHP scripts, log them locally, and optionally expose the local server to the Internet via a tunneling service (ngrok, serveo, etc.).

##### File structure
- Top-level:
- blackeye.sh – the main orchestration script (CLI menu, environment setup, server launch, tunnel setup)
- package.json – (likely defines any Node-based helper dependencies, e.g. local HTTP-server)
- sites/ – directory of one subfolder per target brand. Each subfolder contains:
– static assets (HTML, CSS, JS, images) for the phishing page
– ip.php – captures/logs visitor IP
– login.php – captures/logs credentials
– auxiliary files (e.g. contentscript.js, themes, upload folders)
- No database layer – logs are flat files under each sites/<brand>/ folder.
- No external backend besides the optional tunneling endpoint.

##### README for additional insights
- Describes version history and lists supported sites.
- Usage is strictly “git clone; cd blackeye; bash blackeye.sh”.
- Relies on PHP’s built-in web server and 3rd-party tunnel service to expose port 8080/4444.

##### Main components
a. Orchestration Layer (CLI)
- Component: blackeye.sh (Bash)
- Responsibilities: show menu, select template, start PHP server, start tunnel, monitor logs.
b. Web Server Layer
- Component: PHP built-in server (php -S) and/or local HTTP-server (if package.json used)
- Responsibilities: serve static assets, process ip.php and login.php.
c. Template Store
- Component: sites/<brand>/ directories
- Responsibilities: host phishing pages (HTML, CSS, JS, images) and capture scripts.
d. Tunneling Service (External)
- Component: ngrok / serveo / LocalXpose
- Responsibilities: map local port to a public URL for victim access.
e. Victim Browser (External User)
- Component: End-user accessing the phishing URL
- Flow: requests page → served by local PHP server via tunnel → submits form → PHP logs data.
f. Data Store (Local Files)
- Component: files under sites/<brand>/ (e.g. usernames.txt, ip.txt)
- Responsibilities: persist captured IPs and credentials.

##### Relationships and interactions
- blackeye.sh → launches → PHP server
- blackeye.sh → launches → Tunnel service (binds to PHP server port)
- Victim Browser → HTTP(S) request → Tunnel service → local PHP server → serves phishing page
- Victim Browser → POST credentials → PHP scripts → write to local log files
- blackeye.sh monitors log files and prints captured data to console

##### Architectural patterns and principles
- Modular template storage: each site is a plug-and-play folder.
- Orchestration ‑- single point of control (the shell script).
- File-based logging: no database → simplifies dependency management.
- Stateless web server for assets + minimal dynamic endpoints for capture.

##### Key technologies, frameworks, and libraries
- Bash (blackeye.sh)
- PHP built-in web server (no Apache/nginx required)
- Optional Node HTTP-server (per package.json)
- 3rd-party tunnel services (ngrok, serveo)
- Static assets: HTML, CSS, JavaScript templates

##### Detail without overcomplication
- Of the sub-components (CLI, Web Server, Tunnel, Capture Endpoints, Logs).
- Essential interactions so that a reader can trace how a phishing session is bootstrapped, served, and data recorded.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Attack Machine
    subgraph "Local Attack Machine"
        direction TB
        Bash["Bash Orchestrator\n(blackeye.sh)"]:::orchestrator
        PHP["PHP Built-in Server"]:::server
        Node["Node HTTP-Server\n(package.json)"]:::server
        Templates["Template Store\n(sites/)"]:::store
        IP["IP Capture Endpoint\n(ip.php)"]:::service
        LOGIN["Credential Capture Endpoint\n(login.php)"]:::service
        Logs["Flat File Store\n(usernames.txt,\nip.txt)"]:::datastore
    end

    %% Internet / Victim
    subgraph "Internet / Victim"
        direction TB
        Tunnel["Tunnel Service\n(ngrok/serveo)"]:::external
        Victim["Victim Browser"]:::external
    end

    %% Control Flow
    Bash -->|"launches"| PHP
    Bash -->|"invokes tunnel"| Tunnel
    Bash -->|"(optional) starts"| Node
    Bash -->|"monitors"| Logs

    %% Serving Flow
    PHP -->|"serves templates"| Templates
    Templates --> IP
    Templates --> LOGIN

    %% Victim Interaction
    Victim -->|"HTTP request"| Tunnel
    Tunnel -->|"forwards request"| PHP
    Victim -->|"submits credentials"| Tunnel
    Tunnel -->|"forwards form"| PHP
    PHP -->|"writes IP"| Logs
    PHP -->|"writes creds"| Logs

    %% Click Events
    click Bash "https://github.com/cybsam/blackeye-v2/blob/main/./blackeye.sh"
    click Node "https://github.com/cybsam/blackeye-v2/blob/main/./package.json"
    click Templates "https://github.com/cybsam/blackeye-v2/tree/main/./sites/"
    click IP "https://github.com/cybsam/blackeye-v2/blob/main/./sites/apple/ip.php"
    click LOGIN "https://github.com/cybsam/blackeye-v2/blob/main/./sites/apple/login.php"

    %% Styling
    classDef orchestrator fill:#cce5ff,stroke:#66b0ff,stroke-width:1px
    classDef server fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef store fill:#fff3cd,stroke:#ffc107,stroke-width:1px
    classDef service fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef external fill:#f8f9fa,stroke:#adb5bd,stroke-width:1px
    classDef datastore fill:#f8d7da,stroke:#dc3545,stroke-width:1px
```
