# fkasler/cuddlephish architecture

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

- Interactive diagram: https://gitdiagram.com/fkasler/cuddlephish
- Repository: https://github.com/fkasler/cuddlephish

## Overview

##### Main Components
- Reverse Proxy (Caddy): Illustrated by the presence of a Caddyfile and Dockerfile, this component is responsible for TLS termination, handling SNI, and injecting custom headers (such as X-Real-IP). While Caddy is used in the example setup, note that Nginx or Apache could be substituted.
- Node.js Server: The entry point is index.js. The Node server is the heart of the application—it spawns new automated Chrome instances (via XVFB), handles websockets communication for pairing victims with browsers, relays WebRTC video feeds, and provides an admin interface.
- Automated Chrome Instances: For each visitor, a new Chrome instance is spawned with a dedicated user data directory (as implied by the “user_data” folder reference and existence of keylog.txt files per instance). These instances are driven using the Chrome DevTools Protocol (CDP) and run in a headless (or virtual) environment with xvfb.
- Admin Interface: Provided by admin.html (and supported by the Node server), the admin component allows a whitelisted admin (enforced by config.json public IPs) to view active connections, control browser instances (take over, boot user, give back control), and extract credential material.
- Victim Interface: Although there are multiple HTML pages present (e.g., cuddlephish.html, broadcast.html), they are used to serve a spoofed login page that victims see. This page has embedded scripts (smooth_criminal.js, resize_window.js, stealer.js possibly for payload and cookie extraction) that facilitate the interception and control operations.
- Target Configuration Add-ons: add_target.js lets users configure new target login pages, automatically extracting service metadata. Likewise, stealer.js is used for processing extracted cookies or payloads.
- External Services: WebRTC relies on external STUN (and potentially TURN) servers. The README recommends using stun.l.google.com and mentions configuration for TURN servers when needed.

##### Relationships and Data Flow
- The reverse proxy (Caddy) terminates TLS and forwards requests to the Node server.
- When a victim accesses the phishing URL (served through the reverse proxy), they are served the spoofed login page (cuddlephish.html or broadcast.html) that initiates a WebSocket connection to the Node server.
- Upon receiving a victim’s connection, the Node server pairs them with an automated Chrome instance (spawned via index.js and managed possibly by XVFB and CDP). Data flows bi-directionally—command messages (e.g., “start WebRTC”, “take over”, “boot user”) and media streams (video feed) travel over websockets and WebRTC.
- The admin interface (admin.html) connects to the Node server to receive status updates and to control running Chrome sessions.
- Scripts like add_target.js update target configuration (targets.json) and stealer.js processes downloaded data from captured sessions.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project cleanly distinguishes between components—the reverse proxy, the Node server handling business logic and browser control, and the user interfaces for victims and admins.
- Real-Time Communication: Use of WebSockets orchestrates the communication and state management between victims and browser instances (paired in real time).
- Modular and Scripted Configurations: The use of separate configuration files (config.json, targets.json) and deployment scripts (install_deps.sh) denote modularity.
- Automated Process Flow: Each connection creates a new automated Chrome instance which then has its own dedicated user data directory—a design suited for tracking and isolating sessions.

##### Technologies, Frameworks, and Libraries
- Node.js as the backend runtime.
- WebSockets for real-time signaling.
- Puppeteer/Chrome DevTools Protocol (CDP) for browser automation.
- XVFB for virtual display management.
- Caddy (Dockerized in this setup) for reverse proxy and TLS.
- Various JavaScript files and HTML interfaces to implement UI and control flows.
- WebRTC for streaming the automated browser’s video feed to the victim.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External & Proxy Layer
    subgraph "External & Proxy"
        C1["Reverse Proxy (Caddy)"]:::external
        C2["STUN/TURN Servers (WebRTC)"]:::external
    end

    %% User Interfaces
    subgraph "User Interfaces"
        V1["Victim Interface"]:::frontend
        A1["Admin Interface"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        N1["Node.js Server"]:::backend
        B1["Automated Chrome Instance(s)"]:::backend
    end

    %% Configuration & Scripts
    subgraph "Configuration & Scripts"
        T1["Target Config Add-ons"]:::config
    end

    %% Data Flow
    V1 -->|"HTTPS_Request"| C1
    C1 -->|"Forward_Request"| N1
    N1 -->|"Spawn_Control"| B1
    B1 -->|"Session_Data"| N1
    A1 -->|"Admin_Commands"| N1
    N1 -->|"WebRTC_Signaling"| C2
    N1 -->|"Config_Update"| T1
    V1 -->|"Embedded_Scripts"| N1

    %% Click Events for External & Proxy
    click C1 "https://github.com/fkasler/cuddlephish/tree/main/Caddyfile"
    click C1 "https://github.com/fkasler/cuddlephish/tree/main/Dockerfile"

    %% Click Events for Node.js Server
    click N1 "https://github.com/fkasler/cuddlephish/blob/main/index.js"
    click N1 "https://github.com/fkasler/cuddlephish/blob/main/package.json"

    %% Click Events for User Interfaces - Victim
    click V1 "https://github.com/fkasler/cuddlephish/blob/main/cuddlephish.html"
    click V1 "https://github.com/fkasler/cuddlephish/blob/main/broadcast.html"
    click V1 "https://github.com/fkasler/cuddlephish/blob/main/smooth_criminal.js"
    click V1 "https://github.com/fkasler/cuddlephish/blob/main/resize_window.js"
    click V1 "https://github.com/fkasler/cuddlephish/blob/main/stealer.js"

    %% Click Event for Admin Interface
    click A1 "https://github.com/fkasler/cuddlephish/blob/main/admin.html"

    %% Click Event for Target Configuration
    click T1 "https://github.com/fkasler/cuddlephish/blob/main/add_target.js"

    %% Styles
    classDef backend fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef frontend fill:#aed6f1,stroke:#21618c,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;
    classDef config fill:#fdebd0,stroke:#ca6f1e,stroke-width:2px;
```
