# ph4ntonn/stowaway architecture

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

## Overview

Based on our analysis of the file structure and the extensive README, this project is a multi-level proxy/tunneling tool called “Stowaway.” It is specifically designed for penetration testers to route external traffic through multiple “agent” nodes toward an internal network. In essence, the project’s goal is to create a tree-topology network where a command/control “admin” node manages and communicates with one or more “agent” nodes that in turn might have additional child agents. Communication between nodes can utilize various protocols (plain TCP, HTTP, WebSocket), and security can be provided through either AES-based encryption or full TLS encryption.

##### Main components and roles
- Two primary roles: “admin” (the control or master node) and “agent” (the controlled node).
- Additional shared infrastructure components such as the protocol layer (HTTP, raw TCP, websocket) and encryption utilities (crypto modules for AES, TLS, gzip).
- Supporting libraries/modules like “global,” “share,” “utils,” and “crypto” that are common dependencies for both roles.

##### Break down each major module into its sub-components
– For the admin side:
- CLI & Interactive Components: Within the admin directory you have “cli” which contains command-line interface files (e.g., cli.go, interactive.go). This is the entry point for administrator interactions.
- Handlers and Managers: The “handler” and “manager” directories show that admin commands for file transfer, forward/backward connections, shell commands, SSH, and topology management are encapsulated there.
- Topology and Process Management: The “topology” and “process” modules indicate the management of the agent tree layout and process tracking.
- Printer module: Likely used for formatted output and debugging.

– For the agent side:
- Similar handler, initial parsing, and manager directories mirror much of the admin’s structure. They manage incoming connections (both active and passive modes), command execution (shell, file transfer) and establishing tunnels.
- Process modules again cover process lifecycle (including offline cases) when communication is interrupted.

– For shared components and libraries:
- “crypto” provides encryption functions (AES, GZIP).
- “protocol” defines various transport protocols (HTTP, raw TCP, websocket).
- “share” has utilities for file transfer, pre-authorization, proxy, and transport wrappers which encapsulate secure transport (like TLS).
- “utils” provides helper functions that support various operations.

##### Relationships and data flow
- “SSH Tunnel” for secure channel setup.
- “Socks5,” “forward,” and “backward” connections that indicate local and remote port mapping.
- “Listen” commands used for creating new connections in passive mode.

##### Important architectural patterns and design principles
- Modular design: Both admin and agent use similar sub-modules (handlers, managers) to organize functionality.
- Layered network abstraction: The protocol and crypto modules sit ‘underneath’ the application logic to abstract the details of data transport and encryption.
- Tree topology & multi-level tunneling: Clearly emphasize that an “agent” can have multiple connected child agents, forming a tree structure for multi-stage tunneling. This pattern is critical to the design.
- Extensibility: Note that despite the variety of commands and connection types, the consistent use of configuration (as seen in the Makefile and initial parsers) allows for scaling to multiple platforms (Linux, Windows, Mac, ARM, etc).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Admin Node Subgraph
    subgraph "Admin Node"
        AdminCLI("Admin CLI & Interactive") 
        AdminHandler("Admin Handlers")
        AdminManager("Admin Managers")
        AdminProcess("Admin Process Management")
        AdminTopology("Admin Topology Management")
        AdminPrinter("Admin Printer Module")
        AdminInitial("Admin Initial Parsing/Setup")
    end

    %% Agent Node Subgraph
    subgraph "Agent Node"
        AgentMain("Agent Main Executable")
        AgentHandler("Agent Handlers")
        AgentManager("Agent Managers")
        AgentProcess("Agent Process Management")
    end

    %% Shared Libraries Subgraph
    subgraph "Shared Libraries"
        Crypto("Crypto (AES, GZIP)")
        Protocol("Protocol Definitions (HTTP,TCP,WS)")
        Transport("Transport Wrappers (TLS)")
        ShareProxy("Proxy & File Transfer (Share)")
        Global("Global Settings")
        ShareUtils("Share File & Preauth")
        Utils("General Utilities")
    end

    %% Control Plane Flows (Admin internal commands)
    AdminCLI -->|"issuesCommand"| AdminHandler
    AdminHandler -->|"processes"| AdminManager
    AdminManager -->|"initializes"| AdminInitial
    AdminTopology -->|"managesTree"| AdminProcess
    AdminPrinter -->|"formatsOutput"| AdminCLI

    %% Data plane flows between Admin and Agent
    AdminCLI -->|"controlSignal"| AgentMain
    AdminHandler -->|"sshTunnel/socksCmd"| AgentHandler
    AdminManager ---|"syncTopology"| AgentManager
    AgentProcess -->|"statusReport"| AdminPrinter

    %% Intra-agent communication (simulate tree topology among agents)
    AgentManager -->|"childConnection"| AgentHandler

    %% Shared Libraries connections to Admin components
    AdminInitial -->|"uses"| Crypto
    AdminHandler -->|"transports"| Protocol
    AdminManager -->|"wrapsTLS"| Transport
    AdminPrinter -->|"assistsWith"| Utils

    %% Shared Libraries connections to Agent components
    AgentHandler -->|"protocolLayer"| Protocol
    AgentManager -->|"tlsWrapper"| Transport
    AgentProcess -->|"fileTransfer"| ShareProxy

    %% Shared utilities used by both Admin and Agent
    Global ---|"configures"| AdminCLI
    Global ---|"configures"| AgentMain
    ShareUtils ---|"supportsAuth"| AdminHandler
    ShareUtils ---|"supportsAuth"| AgentHandler

    %% Click Events for Admin Node
    click AdminCLI "https://github.com/ph4ntonn/stowaway/tree/master/admin/cli"
    click AdminHandler "https://github.com/ph4ntonn/stowaway/tree/master/admin/handler"
    click AdminManager "https://github.com/ph4ntonn/stowaway/tree/master/admin/manager"
    click AdminProcess "https://github.com/ph4ntonn/stowaway/tree/master/admin/process"
    click AdminTopology "https://github.com/ph4ntonn/stowaway/blob/master/admin/topology/topology.go"
    click AdminPrinter "https://github.com/ph4ntonn/stowaway/blob/master/admin/printer/printer.go"
    click AdminInitial "https://github.com/ph4ntonn/stowaway/tree/master/admin/initial"

    %% Click Events for Agent Node
    click AgentMain "https://github.com/ph4ntonn/stowaway/blob/master/agent/agent.go"
    click AgentHandler "https://github.com/ph4ntonn/stowaway/tree/master/agent/handler"
    click AgentManager "https://github.com/ph4ntonn/stowaway/tree/master/agent/manager"
    click AgentProcess "https://github.com/ph4ntonn/stowaway/tree/master/agent/process"

    %% Click Events for Shared Libraries
    click Crypto "https://github.com/ph4ntonn/stowaway/tree/master/crypto"
    click Protocol "https://github.com/ph4ntonn/stowaway/tree/master/protocol"
    click Transport "https://github.com/ph4ntonn/stowaway/tree/master/share/transport"
    click ShareProxy "https://github.com/ph4ntonn/stowaway/blob/master/share/proxy.go"
    click Global "https://github.com/ph4ntonn/stowaway/blob/master/global/global.go"
    click ShareUtils "https://github.com/ph4ntonn/stowaway/tree/master/share"
    click Utils "https://github.com/ph4ntonn/stowaway/blob/master/utils/utils.go"

    %% Styles
    class AdminCLI,AdminHandler,AdminManager,AdminProcess,AdminTopology,AdminPrinter,AdminInitial admin
    class AgentMain,AgentHandler,AgentManager,AgentProcess agent
    class Crypto,Protocol,Transport,ShareProxy,Global,ShareUtils,Utils shared

    %% Class Definitions
    classDef admin fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef agent fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef shared fill:#d4edda,stroke:#155724,stroke-width:2px;
```
