# sensepost/regeorg architecture

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

## Overview

##### The Client-Side Component
- The core Python script “reGeorgSocksProxy.py” is used as a SOCKS proxy server.
- It accepts command-line options for setting the listening address and port, a local read buffer size, and (critically) the URL of the tunnel script that is running on the remote host.
- It depends on Python 2.7 and uses the urllib3 module for HTTP connections among other tasks.

##### The Server-Side Component
- There are multiple “tunnel” files in different languages/formats (e.g., tunnel.ashx, tunnel.aspx, tunnel.jsp, tunnel.php, tunnel.js, tunnel.nosocket.php, tunnel.tomcat.5.jsp).
- These are designed to be uploaded to a target web server—this script acts as a tunnel endpoint that listens for HTTP requests from the reGeorg socks proxy.
- The remote "tunnel" script receives the HTTP/S uplink from the proxy client and forwards the traffic to the internal network as needed.

a. Client (Attacker Machine) – include “reGeorgSocksProxy.py” component.
b. Remote Web Server – this represents where the tunnel script is deployed (any one of the provided tunnel files will be used).
c. (Optionally) External tools (like proxychains) in case the local tool does not support SOCKS natively.
d. Communication Channel – the HTTP(S) communication link between the two components.

##### Interactions
- That the SOCKS proxy intercepts and directs local TCP/UDP connections into encapsulated HTTP(s) requests.
- Optionally, illustrate feedback from the tunnel script back to the Python script for proper tunnel communication.

##### Architectural Patterns and Technologies
- That this system uses an HTTP tunnelling pattern where the client proxies traffic over an HTTP channel.
- Decoupling of the client component (running on the attacker’s machine) from the server component (the web-based tunnel script).
- Point out that the design accommodates multiple languages/script formats for the tunnel on the server side, increasing deployment flexibility.
- That the project is built in Python 2.7 and leverages urllib3 for thread-safe HTTP communication.

##### Additional Advice
- Since this project isn’t a full-scale application with multiple microservices but rather a focused tool with just two main interacting parts, detail each element clearly and relate its role in the tunnelling process.
- Being as detailed as possible is beneficial. Break down both the local proxy’s functionality (handling incoming connection requests and forwarding them through HTTP(s)) and the server-side tunnel’s role in receiving these requests and bridging them back to local network access (e.g., “hacking the planet” as the README humorously puts it).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Side
    subgraph "Client (Attacker Machine)"
        client["reGeorgSocksProxy.py (Python 2.7)\n(uses urllib3)"]:::client
        proxy["Proxychains (Optional)"]:::external
    end

    %% HTTP Tunnel Channel
    subgraph "HTTP Tunnel Channel"
        channel["HTTP Tunnel Channel (HTTP(s) Tunnel)"]:::channel
    end

    %% Server Side
    subgraph "Remote Web Server"
        tunnel1["Tunnel Script (tunnel.ashx)"]:::server
        tunnel2["Tunnel Script (tunnel.aspx)"]:::server
        tunnel3["Tunnel Script (tunnel.js)"]:::server
        tunnel4["Tunnel Script (tunnel.jsp)"]:::server
        tunnel5["Tunnel Script (tunnel.nosocket.php)"]:::server
        tunnel6["Tunnel Script (tunnel.php)"]:::server
        tunnel7["Tunnel Script (tunnel.tomcat.5.jsp)"]:::server
    end

    %% Client internal connection
    proxy -- "Optional" --> client

    %% Data flow from client to HTTP Tunnel Channel
    client -->|"HTTP_POST/GET"| channel

    %% Forwarding requests from Channel to each Tunnel Script
    channel -->|"Forward_Request"| tunnel1
    channel -->|"Forward_Request"| tunnel2
    channel -->|"Forward_Request"| tunnel3
    channel -->|"Forward_Request"| tunnel4
    channel -->|"Forward_Request"| tunnel5
    channel -->|"Forward_Request"| tunnel6
    channel -->|"Forward_Request"| tunnel7

    %% Responses from Tunnel Scripts back to Channel
    tunnel1 -->|"HTTP_Response"| channel
    tunnel2 -->|"HTTP_Response"| channel
    tunnel3 -->|"HTTP_Response"| channel
    tunnel4 -->|"HTTP_Response"| channel
    tunnel5 -->|"HTTP_Response"| channel
    tunnel6 -->|"HTTP_Response"| channel
    tunnel7 -->|"HTTP_Response"| channel

    %% Data flow from Channel back to Client
    channel -->|"Return_Data"| client

    %% Click Events
    click client "https://github.com/sensepost/regeorg/blob/master/reGeorgSocksProxy.py"
    click tunnel1 "https://github.com/sensepost/regeorg/blob/master/tunnel.ashx"
    click tunnel2 "https://github.com/sensepost/regeorg/blob/master/tunnel.aspx"
    click tunnel3 "https://github.com/sensepost/regeorg/blob/master/tunnel.js"
    click tunnel4 "https://github.com/sensepost/regeorg/blob/master/tunnel.jsp"
    click tunnel5 "https://github.com/sensepost/regeorg/blob/master/tunnel.nosocket.php"
    click tunnel6 "https://github.com/sensepost/regeorg/blob/master/tunnel.php"
    click tunnel7 "https://github.com/sensepost/regeorg/blob/master/tunnel.tomcat.5.jsp"

    %% Styles
    classDef client fill:#A3BE8C,stroke:#2E3440,stroke-width:2px;
    classDef server fill:#BF616A,stroke:#2E3440,stroke-width:2px;
    classDef channel fill:#EBCB8B,stroke:#2E3440,stroke-width:2px;
    classDef external fill:#88C0D0,stroke:#2E3440,stroke-width:2px;
```
