# t3l3machus/hoaxshell architecture

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

## Overview

##### Project Type and Purpose
- Type: It’s a command-and-control tool focused on generating reverse shell payloads that abuse HTTP/HTTPS. It is also used as a standalone listener via the “revshells” component.
- Purpose: To generate obfuscated payloads for Windows reverse shells and handle incoming connections via customized HTTP headers and various tunneling options.

##### Analyzing the File Structure
- Top-Level Files:
- hoaxshell.py: The main script that ties everything together. It handles command-line options for configuring session parameters (randomized session ID, header names, etc.), protocol choices (HTTP/HTTPS), and additional options like tunneling or constraint language mode.
- README.md and LICENSE.md: Provide project description and legal information.
- Folders:
- payload_templates: Contains a variety of PowerShell payload scripts. Each file represents a different payload variant (HTTP, HTTPS, file-based, local tunnel, ngrok, trusted certificate payloads). This shows a modular design where the payload generation logic uses templates.
- revshells: Includes an alternative “standalone listener” implementation (hoaxshell-listener.py) and its own README and requirements, indicating a decoupled listener component.
- screenshots: Visual aids for the project workings (used for documentation and demonstration).
- Configuration Files:
- requirements.txt: Lists the Python dependencies, which could be important when representing how the system integrates with external libraries.

##### Main Components and Their Relationships
- Payload Generation Engine:
- Core Module: hoaxshell.py acts as the central engine.
- Template Module: Uses files under payload_templates to pick the appropriate payload variant based on the provided command-line arguments (such as –x for executing from a file, –cm for constraint mode, –H for custom header, etc.).
- Randomization Logic: Every instance automatically randomizes session IDs, URL paths, and header names for evasion.
- Reverse Shell Listener:
- Standalone Listener: The “revshells” module (hoaxshell-listener.py) functions as an independent session handler. This might be drawn as a distinct component that interacts with generated payloads established by hoaxshell.py.
- Communication Interface:
- Represents the network communication over HTTP/HTTPS. Indicate the utilization of custom HTTP headers and directional data flows (payload delivery to victim, reverse connection back to the listener).

##### Architectural Patterns and Design Principles
- Modularity: Separate payload templates and listener modules show a loose coupling between payload generation and session handling.
- Dynamic Configuration: The process that automatically randomizes session components implies that the system design emphasizes runtime customization to evade detection.
- Network-based Interaction: Clearly model the bi-directional HTTP/HTTPS flow between the attacker’s host (with hoaxshell.py running) and the victim machine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Attacker Side
    subgraph "Attacker Side"
        A["Payload Generation Engine"]:::python
        B["Payload Templates"]:::powershell
        A -->|"template_selection"| B
    end

    %% Optional Tunneling Proxy
    subgraph "Optional Tunneling"
        E["Tunneling Proxy (Ngrok/LocalTunnel)"]:::tunnel
    end

    %% Project Documentation & Configuration
    subgraph "Project Documentation & Configuration"
        D1["README.md"]:::documentation
        D2["LICENSE.md"]:::documentation
        D3["requirements.txt"]:::documentation
    end

    %% Communication Channel
    F["HTTP/HTTPS Communication Channel"]:::network

    %% Victim Side
    subgraph "Victim Environment"
        G["Victim Machine (Windows)"]:::network
    end

    %% Reverse Shell Listener
    subgraph "Listener"
        H["Reverse Shell Listener"]:::python
    end

    %% Listener Documentation & Configuration
    subgraph "Listener Documentation & Configuration"
        I1["revshell README"]:::documentation
        I2["revshell requirements"]:::documentation
    end

    %% Flow Connections
    A -->|"with_tunneling"| E
    E -->|"via_HTTP"| F
    %% Direct path alternative (if tunneling is not in use)
    A -- "direct_delivery" --> F
    F -->|"payload_delivery"| G
    G -->|"reverse_connection"| H

    %% Styles
    classDef python fill:#AEDFF7,stroke:#006,stroke-width:2px;
    classDef powershell fill:#D0F0C0,stroke:#080,stroke-width:2px;
    classDef network fill:#FFF2B2,stroke:#D58900,stroke-width:2px;
    classDef documentation fill:#F7E1AE,stroke:#B56400,stroke-width:2px;
    classDef tunnel fill:#E0BBE4,stroke:#9B59B6,stroke-width:2px;

    %% Click Events
    click A "https://github.com/t3l3machus/hoaxshell/blob/main/hoaxshell.py"
    click B "https://github.com/t3l3machus/hoaxshell/tree/main/payload_templates/"
    click H "https://github.com/t3l3machus/hoaxshell/blob/main/revshells/hoaxshell-listener.py"
    click D1 "https://github.com/t3l3machus/hoaxshell/blob/main/README.md"
    click D2 "https://github.com/t3l3machus/hoaxshell/blob/main/LICENSE.md"
    click D3 "https://github.com/t3l3machus/hoaxshell/blob/main/requirements.txt"
    click I1 "https://github.com/t3l3machus/hoaxshell/blob/main/revshells/README.md"
    click I2 "https://github.com/t3l3machus/hoaxshell/blob/main/revshells/requirements.txt"
```
