# unlock-security/wshell architecture

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

- Interactive diagram: https://gitdiagram.com/unlock-security/wshell
- Repository: https://github.com/unlock-security/wshell

## Overview

##### Project Type and Purpose
- WShell is designed as a post-exploitation tool used to turn web-based code/command/template injections into an interactive shell over HTTP.
- The README clarifies that it wraps commands into HTTP requests and processes the responses, “injecting” commands into vulnerable endpoints. It is a CLI Python application targeting remote command execution (RCE) vulnerabilities.

##### File Structure
- The top-level directories and files include configuration files (.gitignore, LICENSE, CODE_OF_CONDUCT), the README, and a setup.py for installation.
- The core application is contained in the “wshell” directory. Notice several important components:
- __main__.py: Likely the entry point for running the tool as a command-line application.
- cli.py: Contains the code for command-line interface parsing and argument handling.
- core.py: Likely has the primary business logic that interprets commands, communicates with target URLs, and orchestrates execution.
- injectors.py: Responsible for wrapping commands in HTTP requests and sending them.
- errors.py, log.py, settings.py, validators.py, utils.py: Provide cross-cutting services (error handling, logging, configuration, input validation, and general utility functions).
- There is also a “scripts” folder under wshell/ which is divided into “input” and “output” subfolders. These script modules (like base64_encode, base64_decode, and unescape) are dynamically run to preprocess or postprocess commands and responses. This illustrates an extensible pipeline design.

##### README for Additional Insights
- The README clearly documents WShell’s mode of operation, installation instructions, usage examples, and even how to develop custom scripts.
- It also explains how the input and output scripts can be chained together, indicating a design where modularity and pluggability are key architectural principles.

a. Main Components:
- Command-Line Interface (CLI):
- Modules: __main__.py and cli.py.
- Role: Parses user input and arguments, displays usage help, and passes the parameters to the next layers.
- Core Application Logic:
- Modules: core.py.
- Role: Orchestrates the execution flow, manages command processing, and adjusts internal behavior based on target operating system detection.
- HTTP Injector:
- Module: injectors.py.
- Role: Wraps the command in an HTTP request (handling POST/GET methods, headers, timeout, etc.) and sends it to the target URL.
- Script Processing Pipelines:
- Locations: wshell/scripts/input and wshell/scripts/output.
- Role: Provide pre- and post-processing of commands (e.g., encoding before sending or decoding after response). They are extensible and chainable.
- Supporting Utilities and Cross-Cutting Concerns:
- Modules: log.py (logging), errors.py (error handling), validators.py (input validation), settings.py (configuration), utils.py (helper functions).
- Data Resource:
- File: data/user-agents.txt.
- Role: May be used to provide default or randomized User-Agent strings for HTTP requests.

b. Relationships and Interactions:
- User inputs commands and endpoints into the CLI.
- CLI (cli.py) passes the arguments to the Core (core.py).
- The Core module processes the command, selecting and invoking any necessary input scripts from the “input” pipeline.
- After input processing, the command is passed to the HTTP injector which wraps it in an HTTP request.
- The injector sends the request, receives the HTTP response, and hands it back to the Core.
- The response is processed by the output scripts chain (from wshell/scripts/output) to decode or unescape the output.
- Finally, logging (via log.py) and error-handling (errors.py) modules capture and manage outputs and potential issues.
- Utilities, settings, and validators operate across modules to ensure that user inputs and responses meet expected formats and configurations.

c. Architectural Patterns and Design Principles:
- Modularity and Extensibility: The script pipelines for input and output processing show a plug-in style architecture.
- Separation of Concerns: Different files handle CLI parsing, core logic, network requests, and auxiliary functions.
- Pipeline Processing: Chained execution of input/output scripts to systematically transform data and responses.
- Clear Dependency Direction: The CLI calls the core; core delegates to injector and script modules; centralized logging and error management support all layers.

d. Relevant Technologies and Frameworks:
- Python 3: Base programming language.
- Packaging tools: e.g., pipx installation via setup.py.
- HTTP libraries: While not explicitly mentioned, WShell likely uses a Python HTTP library (e.g., requests) inside its injectors.
- Scripting and dynamic module import techniques for extensible script support.

##### Overall Reminder
- The goal is to capture all essential components and their interactions, making sure no key part is omitted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Input"]:::cliStyle
    
    subgraph "CLI Layer"
        CLI["CLI Interface (cli.py)"]:::cliStyle
    end

    subgraph "Core Layer"
        CORE["Core Logic (core.py)"]:::coreStyle
    end

    subgraph "Processing Pipelines"
        INPUT["Input Script Pipeline"]:::pipelineStyle
        OUTPUT["Output Script Pipeline"]:::pipelineStyle
    end

    subgraph "Network Operations"
        INJ["HTTP Injector (injectors.py)"]:::injectorStyle
        UA["Data Resource (user-agents.txt)"]:::dataStyle
    end

    subgraph "Support Modules"
        LOG["Logging (log.py)"]:::supportStyle
        ERR["Error Handling (errors.py)"]:::supportStyle
        CONF["Configuration/Settings (settings.py)"]:::supportStyle
        VALID["Input Validation (validators.py)"]:::supportStyle
        UTILS["Utility Functions (utils.py)"]:::supportStyle
        SCRIPTS_UTILS["Script Utilities (wshell/scripts/utils.py)"]:::supportStyle
    end

    %% Main Flow
    U -->|"sends command"| CLI
    CLI -->|"parses & passes input"| CORE
    CORE -->|"pre-processes command"| INPUT
    INPUT -->|"formats command"| INJ
    INJ -->|"sends HTTP request"| CORE
    INJ -- "uses" --> UA
    CORE -->|"post-processes response"| OUTPUT
    OUTPUT -->|"displays result"| CLI

    %% Support Interactions
    CORE -->|"logs events"| LOG
    CORE -->|"handles errors"| ERR
    CORE -->|"reads config"| CONF
    CORE -->|"validates input"| VALID
    CORE -->|"calls utilities"| UTILS

    %% Class Definitions for Styling
    classDef cliStyle fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef coreStyle fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef injectorStyle fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef pipelineStyle fill:#ffe4e1,stroke:#333,stroke-width:2px;
    classDef supportStyle fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef dataStyle fill:#d3d3d3,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/unlock-security/wshell/blob/main/wshell/__main__.py"
    click CLI "https://github.com/unlock-security/wshell/blob/main/wshell/cli.py"
    click CORE "https://github.com/unlock-security/wshell/blob/main/wshell/core.py"
    click INJ "https://github.com/unlock-security/wshell/blob/main/wshell/injectors.py"
    click INPUT "https://github.com/unlock-security/wshell/blob/main/wshell/scripts/input/base64_encode.py"
    click OUTPUT "https://github.com/unlock-security/wshell/blob/main/wshell/scripts/output/base64_decode.py"
    click OUTPUT "https://github.com/unlock-security/wshell/blob/main/wshell/scripts/output/unescape.py"
    click LOG "https://github.com/unlock-security/wshell/blob/main/wshell/log.py"
    click ERR "https://github.com/unlock-security/wshell/blob/main/wshell/errors.py"
    click CONF "https://github.com/unlock-security/wshell/blob/main/wshell/settings.py"
    click VALID "https://github.com/unlock-security/wshell/blob/main/wshell/validators.py"
    click UTILS "https://github.com/unlock-security/wshell/blob/main/wshell/utils.py"
    click SCRIPTS_UTILS "https://github.com/unlock-security/wshell/blob/main/wshell/scripts/utils.py"
    click UA "https://github.com/unlock-security/wshell/blob/main/data/user-agents.txt"
```
