# urban20/marioneta-backdoor architecture

> Architecture diagram of the GitHub repository urban20/marioneta-backdoor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urban20/marioneta-backdoor
- Repository: https://github.com/urban20/marioneta-backdoor

## Overview

1. **Repository shape**
   - The repo contains two parallel implementations of the same remote-control tool: **V1.0 in Python** and **V2.0 in Go**.
   - Each version is split into two executables: a **host-side agent/backdoor** running on the target machine and a **controller/client** used by the operator.

2. **Top-level architecture**
   - The fundamental boundary is a **TCP link over a local network** between controller and host.
   - The controller sends commands; the host executes them and returns either text output or binary payloads such as screenshots.

3. **V1.0 (Python)**
   - `V1.0/bdor.pyw` is the target-side agent, packaged as a `.pyw` so it can run without an obvious console window.
   - `V1.0/cliente.py` is the operator client.
   - The README indicates V1.0 also includes **Startup/persistence behavior**, so this version has a stronger local-machine footprint than the Go rewrite.

4. **V2.0 host/backdoor**
   - `V2.0/backdoorV2.0/main.go` is the entry point for the Go agent.
   - `conexiones/conexiones.go` appears to own the network session lifecycle.
   - `ejecuciones/ejecuciones.go` handles command execution.
   - `ejecuciones/sys/sys.go` groups system-level actions such as shutdown or message display.

5. **V2.0 controller/client**
   - `V2.0/clienteV2.0/main.go` starts the operator-side CLI.
   - `conex/conexiones.go` manages the TCP connection from the client side.
   - `conex/comandos/comandos.go` is the command dispatcher.
   - `conex/comandos/ss/ss.go` is the screenshot-specific path.
   - `input/input.go` likely handles reading and validating operator input.
   - `consola/` contains the console abstraction, with platform-specific files for Windows and Linux.
   - `colores/colores.go` is presentation-only output formatting for the terminal UI.

6. **Command model**
   - The system supports a small command vocabulary plus passthrough execution:
     - clear console
     - shutdown remote machine
     - send system message
     - capture screen
     - change directory
     - quit client
     - arbitrary command execution
   - This implies a **command router** on the client and a **command handler/executor** on the host.

7. **Screenshot data flow**
   - Screenshot capture is an explicit binary-transfer path, not just text output.
   - The README shows a protocol where the host sends the **image size first**, then streams the screenshot in fragments, and the client reassembles and stores it as `screen.jpg`.
   - This is the main non-text payload flow in the system.

8. **Runtime and platform boundaries**
   - The repo is strongly **Windows-oriented**: PowerShell/CMD execution, system messages, hidden GUI execution, and a firewall script in `V2.0/backdoorV2.0/firewall.bat`.
   - The Go client includes cross-platform console files, but the host functionality is still tied to Windows behavior.
   - The Go version uses `github.com/kbinani/screenshot` for screen capture.

9. **Version differences that matter architecturally**
   - **V1.0** includes lightweight persistence and a simpler Python implementation.
   - **V2.0** is more modular, faster, and has better error handling and reconnection behavior.
   - The Go rewrite separates networking, execution, and system actions into distinct packages, which makes the boundaries clearer for diagramming.

10. **Operational boundaries and trust model**
   - Communication is described as **cleartext TCP** with **no authentication**, intended for local networks.
   - That means the architecture has very weak network trust assumptions: any party able to reach the port could potentially interact with the host.
   - For a diagram, it is important to show the link as a direct operator-to-agent channel rather than via a server, broker, or cloud service.

11. **What to show in an architecture diagram**
   - Two independent binaries on two machines.
   - A TCP connection between them.
   - On the host: connection management, command execution, and system-action handlers.
   - On the client: user input, command dispatch, console UI, and screenshot reassembly/storage.
   - A separate binary stream path for screenshots alongside normal text command/response traffic.

Main entry points: [`V2.0/backdoorV2.0/conexiones/conexiones.go`](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/conexiones/conexiones.go) (session conn), [`V2.0/clienteV2.0/main.go`](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/main.go) (client main), [`V2.0/backdoorV2.0/ejecuciones/ejecuciones.go`](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/ejecuciones/ejecuciones.go) (executor), [`V2.0/clienteV2.0/conex/comandos/comandos.go`](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/comandos/comandos.go) (command router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v1["V1.0 Python"]
  node_v1_agent["bdor.pyw<br/>python agent<br/>[bdor.pyw]"]
  node_v1_client["cliente.py<br/>python client<br/>[cliente.py]"]
end

subgraph group_v2host["V2 Host"]
  node_v2_host_main["backdoor main<br/>go entrypoint<br/>[main.go]"]
  node_v2_host_net["session conn<br/>tcp lifecycle<br/>[conexiones.go]"]
  node_v2_host_exec["executor<br/>command exec<br/>[ejecuciones.go]"]
  node_v2_host_sys["system ops<br/>system actions<br/>[sys.go]"]
  node_v2_host_firewall["firewall script<br/>windows script<br/>[firewall.bat]"]
end

subgraph group_v2client["V2 Client"]
  node_v2_client_main["client main<br/>go entrypoint<br/>[main.go]"]
  node_v2_client_net["client conn<br/>tcp client<br/>[conexiones.go]"]
  node_v2_client_cmd["command router<br/>dispatcher<br/>[comandos.go]"]
  node_v2_client_ss["screenshot path<br/>binary transfer<br/>[ss.go]"]
  node_v2_client_input["input parser<br/>cli input<br/>[input.go]"]
  node_v2_client_console["console UI<br/>terminal abstraction<br/>[consola.go]"]
  node_v2_client_colors["colors<br/>ui formatting<br/>[colores.go]"]
end

node_v1_client -->|"tcp commands"| node_v1_agent
node_v1_agent -->|"text/output"| node_v1_client
node_v2_client_main -->|"read input"| node_v2_client_input
node_v2_client_input -->|"dispatch"| node_v2_client_cmd
node_v2_client_cmd -->|"send cmd"| node_v2_client_net
node_v2_client_cmd -->|"screenshot"| node_v2_client_ss
node_v2_client_main -->|"ui"| node_v2_client_console
node_v2_client_main -->|"format output"| node_v2_client_colors
node_v2_client_net -->|"tcp link"| node_v2_host_net
node_v2_host_main -->|"start session"| node_v2_host_net
node_v2_host_net -->|"deliver cmd"| node_v2_host_exec
node_v2_host_exec -->|"system ops"| node_v2_host_sys
node_v2_host_exec -->|"text response"| node_v2_client_net
node_v2_host_net -->|"image size + chunks"| node_v2_client_ss
node_v2_client_ss -->|"store preview"| node_v2_client_console
node_v2_host_main -.->|"ops artifact"| node_v2_host_firewall

click node_v1_agent "https://github.com/urban20/marioneta-backdoor/blob/main/V1.0/bdor.pyw"
click node_v1_client "https://github.com/urban20/marioneta-backdoor/blob/main/V1.0/cliente.py"
click node_v2_host_main "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/main.go"
click node_v2_host_net "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/conexiones/conexiones.go"
click node_v2_host_exec "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/ejecuciones/ejecuciones.go"
click node_v2_host_sys "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/ejecuciones/sys/sys.go"
click node_v2_client_main "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/main.go"
click node_v2_client_net "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/conexiones.go"
click node_v2_client_cmd "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/comandos/comandos.go"
click node_v2_client_ss "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/comandos/ss/ss.go"
click node_v2_client_input "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/input/input.go"
click node_v2_client_console "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/consola/consola.go"
click node_v2_client_colors "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/colores/colores.go"
click node_v2_host_firewall "https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/firewall.bat"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v1_agent,node_v1_client toneBlue
class node_v2_host_main,node_v2_host_net,node_v2_host_exec,node_v2_host_sys,node_v2_host_firewall toneAmber
class node_v2_client_main,node_v2_client_net,node_v2_client_cmd,node_v2_client_ss,node_v2_client_input,node_v2_client_console,node_v2_client_colors toneMint
```

## Components

### V1.0 Python

Legacy Python implementation with host agent and operator client.

- [bdor.pyw](https://github.com/urban20/marioneta-backdoor/blob/main/V1.0/bdor.pyw): python agent · Host-side target agent for V1.0. · `V1.0/bdor.pyw`
- [cliente.py](https://github.com/urban20/marioneta-backdoor/blob/main/V1.0/cliente.py): python client · Operator-side controller for V1.0. · `V1.0/cliente.py`

### V2 Host

Go backdoor side: networking, execution, and system actions.

- [backdoor main](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/main.go): go entrypoint · Starts the V2.0 host-side backdoor. · `V2.0/backdoorV2.0/main.go`
- [session conn](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/conexiones/conexiones.go): tcp lifecycle · Owns host-side connection setup and session lifecycle. · `V2.0/backdoorV2.0/conexiones/conexiones.go`
- [executor](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/ejecuciones/ejecuciones.go): command exec · Runs received commands on the host. · `V2.0/backdoorV2.0/ejecuciones/ejecuciones.go`
- [system ops](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/ejecuciones/sys/sys.go): system actions · Handles shutdown, message display, and other OS-level actions. · `V2.0/backdoorV2.0/ejecuciones/sys/sys.go`
- [firewall script](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/backdoorV2.0/firewall.bat): windows script · Batch script related to host-side firewall handling. · `V2.0/backdoorV2.0/firewall.bat`

### V2 Client

Go operator side: input, dispatch, console UI, and screenshot handling.

- [client main](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/main.go): go entrypoint · Starts the V2.0 operator CLI. · `V2.0/clienteV2.0/main.go`
- [client conn](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/conexiones.go): tcp client · Manages the operator-side TCP connection. · `V2.0/clienteV2.0/conex/conexiones.go`
- [command router](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/comandos/comandos.go): dispatcher · Maps operator choices to remote actions. · `V2.0/clienteV2.0/conex/comandos/comandos.go`
- [screenshot path](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/conex/comandos/ss/ss.go): binary transfer · Handles screenshot request, receive, and reconstruction. · `V2.0/clienteV2.0/conex/comandos/ss/ss.go`
- [input parser](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/input/input.go): cli input · Reads and validates operator input. · `V2.0/clienteV2.0/input/input.go`
- [console UI](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/consola/consola.go): terminal abstraction · Cross-platform console behavior for Windows and Linux. · `V2.0/clienteV2.0/consola/consola.go`
- [colors](https://github.com/urban20/marioneta-backdoor/blob/main/V2.0/clienteV2.0/colores/colores.go): ui formatting · Terminal presentation and color formatting. · `V2.0/clienteV2.0/colores/colores.go`

## Connections

- cliente.py → bdor.pyw: tcp commands · Operator sends commands to the host agent.
- bdor.pyw → cliente.py: text/output · Host returns command results and responses.
- client main → input parser: read input · CLI starts by collecting operator input.
- input parser → command router: dispatch · Validated operator choices are routed to commands.
- command router → client conn: send cmd · Command router sends requests over the TCP link.
- command router → screenshot path: screenshot · Special command path for screenshot capture and assembly.
- client main → console UI: ui · Main client uses the console abstraction.
- client main → colors: format output · Presentation layer for terminal text.
- client conn → session conn: tcp link · Direct cleartext operator-to-host connection.
- backdoor main → session conn: start session · Host entrypoint initializes network session handling.
- session conn → executor: deliver cmd · Received commands are forwarded to the executor.
- executor → system ops: system ops · Executor delegates OS-level actions to system handlers.
- executor → client conn: text response · Command output is returned to the client over TCP.
- session conn → screenshot path: image size + chunks · Screenshot path streams size first, then binary fragments.
- screenshot path → console UI: store preview · Client-side screenshot workflow integrates with local UI/output.
- backdoor main → firewall script: ops artifact · Auxiliary script used by the host build/runtime environment.
