How t3l3machus/hoaxshell works
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.