# nhas/reverse_ssh architecture

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

- Interactive diagram: https://gitdiagram.com/nhas/reverse_ssh
- Repository: https://github.com/nhas/reverse_ssh

## Overview

Based on your project’s file tree and the README, this is a reverse SSH tool that functions as both a server and client. The tool’s purpose is to allow reverse shells (and other SSH-like features such as port forwarding, SCP/SFTP transfers, tunneling, and even Windows DLL injection) using native SSH syntax over multiple transport types (HTTP, websockets, TLS, raw TCP, etc.). The project is written in Go and is organized in a modular way, with clear separations between client and server functionality.

##### Main Components
- Reverse SSH Server – implemented in cmd/server and internal/server. This handles incoming SSH connections, command processing (various commands like exec, access, link, etc.), session management, webhooks, and more.
- Reverse SSH Client – implemented in cmd/client and internal/client. Clients are built here, and they include various connection handlers (local/remote forwarding, tunneling, shell interactions, DLL generation for Windows, etc.).
- Shared Libraries & Utilities – these include packages like pkg/logger, pkg/mux (for multiplexing connections), pkg/storage, pkg/trie, pkg/observer, and others. These modules provide core functionality (logging, managing connections, buffering, protocol support, etc.).
- Auxiliary Components – the docker files, Makefile, and other scripts (e.g., docker-compose.dev.yml, shell scripts for web server support) that facilitate deployment, building cross-platform binaries, and testing.
- Testing & End-to-End Examples – as seen in the e2e directory, providing integration tests and example usage flows.
- Third-Party Transports & Subsystems – note the explicit support in the README for alternative transports (HTTP, websockets, TLS), tun/VPN capability, and subsystems for additional SSH functionalities (SFTP, setuid, windows service, etc.).

##### Out the Relationships and Interactions
- The server sits as the central hub accepting SSH (and alternative transport) connections.
- Clients reach out (or “connect back”) to the server.
- Human clients (administrators) interact with the server shell (using SSH jump host syntax) to issue commands such as “link,” “help,” “access,” etc.
- Within the server component:
- Within the client component:
- Connection handler, the embedded authentication keys, the routines for establishing channels (or subsystems), and the alternative transports (like websockets or TLS) used by the client.
- Shared libraries (pkg/*) should be depicted as common modules used by both client and server, representing services like logging, connection multiplexing, storage, and protocol handling.

##### Architectural Patterns & Design Principles
- Clear separation of concerns (server vs. client, internal logic vs. shared libraries).
- Modularity: components (client, server, multiplexing, logging, etc.) are clearly divided into their own directories and packages.
- Extensibility is built in (support for SSH subsystems, various transport layers, webhooks, etc.), so include annotations that this is designed for plug-and-play functionality.

##### Relevant Technologies
- Go language (with Go modules for dependency management).
- Docker – note Dockerfile, docker-compose for containerized deployment.
- Cross-compilation tools for Windows (mingw-w64, support for DLL generation).
- Underlying networking protocols: SSH, HTTP, websockets, TLS.
- Subsystems and utilities such as conpty, winpty for Windows shell support.

##### Detailed Elements
- “Multiplexer (pkg/mux)” as a shared library used to handle fragmented connections between components.
- “Web Server Module” (within internal/server/webserver) that handles “link” command and client binary hosting.
- “SSH Subsystems” (under internal/server/commands and internal/client/handlers/subsystems).
- Flow of data:
- A client binary’s compilation and hosting via link commands, which is initiated by an admin command on the server.
- Connection flows where a reverse SSH client makes an outbound connection, at which point the multiplexer divides the session into a control channel and additional data channels.
- Configuration paths such as environment variables (e.g., RSSH_HOMESERVER) that alter client/server behavior.

- Clearly separates the Reverse SSH Server and Client modules,
- Highlights their interactions and shared components,
- Displays the use of alternative transports, subsystems, and supporting utilities,
- And ultimately demonstrates the modular, extensible design that supports cross-platform reverse shells and secure command tunnels.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Admin["Administrator"]:::admin

    subgraph "Reverse SSH Server"
        RS_Server["Reverse SSH Server Core"]:::server
        CH["Command Handler"]:::server
        MP["Multiplexer"]:::server
        OB["Observers"]:::server
        WS["Web Server Module"]:::server
        RS_Server --> CH
        RS_Server --> MP
        RS_Server --> OB
        RS_Server --> WS
    end

    subgraph "Reverse SSH Client"
        RS_Client["Reverse SSH Client Core"]:::client
        CN["Connection Handler"]:::client
        SSH_CS["SSH Subsystems (Client)"]:::client
        RS_Client --> CN
        RS_Client --> SSH_CS
    end

    SL["Shared Libraries & Utilities"]:::shared

    subgraph "Deployment & Build Scripts"
        DF["Dockerfile"]:::aux
        DC["docker-compose.dev.yml"]:::aux
        MK["Makefile"]:::aux
        DE["docker-entrypoint.sh"]:::aux
    end

    TEST["Testing & End-to-End Examples"]:::test

    Admin -->|"issues_commands"| RS_Server
    RS_Client -->|"connects_to"| RS_Server
    RS_Server -->|"uses"| SL
    RS_Client -->|"uses"| SL
    RS_Server -->|"deploysWith"| DF
    RS_Server -->|"deploysWith"| DC
    RS_Server -->|"deploysWith"| MK
    RS_Server -->|"deploysWith"| DE
    RS_Server -->|"testedBy"| TEST

    click RS_Server "https://github.com/nhas/reverse_ssh/tree/main/cmd/server & internal/server"
    click CH "https://github.com/nhas/reverse_ssh/tree/main/internal/server/commands"
    click MP "https://github.com/nhas/reverse_ssh/tree/main/internal/server/multiplexer & pkg/mux"
    click OB "https://github.com/nhas/reverse_ssh/tree/main/internal/server/observers"
    click WS "https://github.com/nhas/reverse_ssh/tree/main/internal/server/webserver"
    click RS_Client "https://github.com/nhas/reverse_ssh/tree/main/cmd/client & internal/client"
    click SSH_CS "https://github.com/nhas/reverse_ssh/tree/main/internal/client/handlers/subsystems"
    click SL "https://github.com/nhas/reverse_ssh/tree/main/pkg"
    click DF "https://github.com/nhas/reverse_ssh/tree/main/Dockerfile"
    click DC "https://github.com/nhas/reverse_ssh/blob/main/docker-compose.dev.yml"
    click MK "https://github.com/nhas/reverse_ssh/tree/main/Makefile"
    click DE "https://github.com/nhas/reverse_ssh/blob/main/docker-entrypoint.sh"
    click TEST "https://github.com/nhas/reverse_ssh/tree/main/e2e"

    classDef admin fill:#ffccf2,stroke:#333,stroke-width:2px;
    classDef server fill:#a3c2f2,stroke:#333,stroke-width:2px;
    classDef client fill:#c2f2a3,stroke:#333,stroke-width:2px;
    classDef shared fill:#f2e1a3,stroke:#333,stroke-width:2px;
    classDef aux fill:#f2a3a3,stroke:#333,stroke-width:2px;
    classDef test fill:#a3f2f2,stroke:#333,stroke-width:2px;
```
