# jofpin/trape architecture

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

- Interactive diagram: https://gitdiagram.com/jofpin/trape
- Repository: https://github.com/jofpin/trape

## Overview

##### Project type and purpose
- Trape is a monolithic, full-stack Python web application designed for real-time OSINT tracking and social-engineering attacks.
- It combines a CLI entry-point (trape.py) with an HTTP/WS server, a small “database” layer, a dynamic front-end, and integration with external services (ngrok, target-site cloning, REST APIs).

##### File structure
Top-level
– trape.py            ← CLI entry-point, starts the server
– requirements.txt    ← Python dependencies
– static/             ← CSS, JS, image assets that run in the browser
– templates/          ← HTML views (login, home, error)
– core/               ← Python modules that implement business logic
- db.py           ← data-storage interface (in-memory or flat files)
- sockets.py      ← WebSocket server for real-time events
- ngrok.py        ← wrapper to manage public tunnels
- user*.py        ← user/session modeling
- stats.py        ← data-aggregation and reporting
- trape.py        ← core HTTP server/router and request handlers
- utils.py        ← shared helper functions

##### Key insights from README
- Real-time geolocation + path tracking (JS → WS → Python → JS)
- REST API injection for remote control & social engineering
- Public tunnel management via ngrok API
- Two distinct user-flows:
a) Operator’s panel (login → dashboard → live data)
b) Victim’s browser (cloned page with injected JS hooks)

##### Main components
A. Actors (external)
1. Operator (security researcher)
2. Victim (target’s browser)
B. Backend (Python, single process)
1. CLI/Launcher (trape.py, core/trape.py)
2. HTTP Server (Flask/Custom router in core/trape.py)
3. WebSocket Server (core/sockets.py)
4. Data Store (core/db.py + in-memory structures)
5. Modules: ngrok manager, stats engine, user/session manager
C. Frontend (served static assets)
1. HTML Templates (templates/*.html)
2. JavaScript bundles (static/js/*.js)
D. External Services
1. ngrok.com API (public tunnel)
2. Cloned target website (--url)
3. Optional REST endpoints (speech, remote JS via --injectcode)

##### Relationships and interactions
1. Operator CLI invokes trape.py → starts HTTP + WS server
2. Operator’s browser ↔ HTTP (login, dashboard, REST API calls)
3. Server ↔ Data Store (CRUD of session, stats, hook logs)
4. Victim’s browser ↔ HTTP (serves cloned page + injected JS)
5. Victim’s browser ↔ WebSocket (push events: geolocation, network info, keylogger data)
6. Server ↔ ngrok API (manage public forwarding)
7. Server → External cloned URL (if --url is used)

##### Architectural patterns & design principles
- Monolithic client-server with clear separation of concerns:
– HTTP routing vs. WS routing
– Business logic (core/) vs. presentation (templates/static/)
- Event-driven real-time updates via WebSockets
- Plugin-style modules for extensibility (ngrok, speech, injection)
- Minimal persistence layer for captured data

##### Relevant technologies & libraries
- Python 3 (core application)
- colorama (CLI coloring)
- urllib2 shim (core/dependence)
- WebSockets (real-time comms)
- HTML5 geolocation & Web Speech (client JS APIs)
- ngrok.com API (public tunnels)
- Vanilla JS/CSS for frontend

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Actors
    subgraph "External Actors"
        direction TB
        Operator["Operator (Security Researcher)"]:::external
        Victim["Victim (Target Browser)"]:::external
    end

    %% Backend Components
    subgraph "Backend Services"
        direction TB
        CLI["CLI/Launcher\n(trape.py)"]:::cli
        HTTP["HTTP Server & Router\n(core/trape.py)"]:::backend
        WS["WebSocket Server\n(core/sockets.py)"]:::backend
        DB["Data Store\n(core/db.py)"]:::backend
        NGROK["ngrok Manager\n(core/ngrok.py)"]:::backend
        STATS["Statistics Engine\n(core/stats.py)"]:::backend
        USERS["User/Session Management\n(core/user.py\ncore/user_objects.py)"]:::backend
        UTILS["Shared Utilities\n(core/utils.py)"]:::backend
        COLORAMA["CLI Coloring Library\n(core/colorama/)"]:::backend
        URLLIB["HTTP Shim\n(core/dependence/urllib2.py)"]:::backend
    end

    %% Frontend Components
    subgraph "Frontend Components"
        direction TB
        subgraph "HTML Templates" 
            LOGIN["login.html"]:::frontend
            HOME["home.html"]:::frontend
            ERROR404["404.html"]:::frontend
        end
        subgraph "JavaScript Bundles"
            BASEJS["base.js"]:::frontend
            CUSTOMJS["custom.js"]:::frontend
            INJECTJS["inject.js"]:::frontend
            LOGINJS["login.js"]:::frontend
            PAYLOADJS["payload.js"]:::frontend
            TRAPEJS["trape.js"]:::frontend
            VSCRIPTJS["vscript.js"]:::frontend
        end
        subgraph "CSS & Icons"
            STYLES["styles.css"]:::frontend
            BASEICONS["base-icons.css"]:::frontend
            SERVICICONS["services-icons.css"]:::frontend
            FONTS["fonts/"]:::frontend
        end
        IMG["Misc Assets (img/)"]:::frontend
        FILES["Misc Files (files.md)"]:::frontend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NGROKAPI["ngrok.com API"]:::externalService
        CLONED["Cloned Target URL"]:::externalService
        RESTEXT["Optional REST Endpoints"]:::externalService
    end

    %% Connections
    Operator -->|"invoke"| CLI
    CLI -->|starts| HTTP
    CLI -->|starts| WS
    Operator -->|HTTP requests| HTTP
    Victim -->|HTTP requests| HTTP
    Victim -.->|WS events| WS
    HTTP -->|CRUD| DB
    WS -->|store events| DB
    HTTP -->|manage tunnel| NGROK
    NGROK -->|calls| NGROKAPI
    HTTP -->|fetch| CLONED
    HTTP -->|inject| RESTEXT
    HTTP -->|serve templates| LOGIN
    HTTP -->|serve templates| HOME
    HTTP -->|serve templates| ERROR404
    HTTP -->|serve JS| BASEJS
    HTTP -->|serve JS| CUSTOMJS
    HTTP -->|serve JS| INJECTJS
    HTTP -->|serve JS| LOGINJS
    HTTP -->|serve JS| PAYLOADJS
    HTTP -->|serve JS| TRAPEJS
    HTTP -->|serve JS| VSCRIPTJS
    HTTP -->|serve CSS| STYLES
    HTTP -->|serve CSS| BASEICONS
    HTTP -->|serve CSS| SERVICICONS
    HTTP -->|serve fonts| FONTS
    HTTP -->|serve assets| IMG
    HTTP -->|serve files| FILES
    HTTP -->|use utils| UTILS
    HTTP -->|use stats| STATS
    HTTP -->|use users| USERS
    HTTP -->|use urllib2| URLLIB
    HTTP -->|use colorama| COLORAMA

    %% Click Events
    click CLI "https://github.com/jofpin/trape/blob/master/trape.py"
    click HTTP "https://github.com/jofpin/trape/blob/master/core/trape.py"
    click WS "https://github.com/jofpin/trape/blob/master/core/sockets.py"
    click DB "https://github.com/jofpin/trape/blob/master/core/db.py"
    click NGROK "https://github.com/jofpin/trape/blob/master/core/ngrok.py"
    click STATS "https://github.com/jofpin/trape/blob/master/core/stats.py"
    click USERS "https://github.com/jofpin/trape/blob/master/core/user.py"
    click USERS "https://github.com/jofpin/trape/blob/master/core/user_objects.py"
    click UTILS "https://github.com/jofpin/trape/blob/master/core/utils.py"
    click COLORAMA "https://github.com/jofpin/trape/tree/master/core/colorama/"
    click URLLIB "https://github.com/jofpin/trape/blob/master/core/dependence/urllib2.py"
    click LOGIN "https://github.com/jofpin/trape/blob/master/templates/login.html"
    click HOME "https://github.com/jofpin/trape/blob/master/templates/home.html"
    click ERROR404 "https://github.com/jofpin/trape/blob/master/templates/404.html"
    click BASEJS "https://github.com/jofpin/trape/blob/master/static/js/base.js"
    click CUSTOMJS "https://github.com/jofpin/trape/blob/master/static/js/custom.js"
    click INJECTJS "https://github.com/jofpin/trape/blob/master/static/js/inject.js"
    click LOGINJS "https://github.com/jofpin/trape/blob/master/static/js/login.js"
    click PAYLOADJS "https://github.com/jofpin/trape/blob/master/static/js/payload.js"
    click TRAPEJS "https://github.com/jofpin/trape/blob/master/static/js/trape.js"
    click VSCRIPTJS "https://github.com/jofpin/trape/blob/master/static/js/vscript.js"
    click STYLES "https://github.com/jofpin/trape/blob/master/static/css/styles.css"
    click BASEICONS "https://github.com/jofpin/trape/blob/master/static/css/base-icons.css"
    click SERVICICONS "https://github.com/jofpin/trape/blob/master/static/css/services-icons.css"
    click FONTS "https://github.com/jofpin/trape/tree/master/static/css/fonts/"
    click IMG "https://github.com/jofpin/trape/tree/master/static/img/"
    click FILES "https://github.com/jofpin/trape/blob/master/static/files/files.md"

    %% Styles
    classDef backend fill:#D0E8FF,stroke:#005B9A,color:#000;
    classDef frontend fill:#E0FFD8,stroke:#2E7D32,color:#000;
    classDef external fill:#FFF4C1,stroke:#B28704,color:#000;
    classDef externalService fill:#FFF0C1,stroke:#B26A00,color:#000;
    classDef cli fill:#E0E0E0,stroke:#424242,color:#000;
```
