How urban20/marioneta-backdoor works
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: conexiones.go session conn · main.go client main · ejecuciones.go executor · comandos.go command router
Components 14
V1.0 Python
Legacy Python implementation with host agent and operator client.
- bdor.pyw · Host-side target agent for V1.0.
V1.0/bdor.pyw - cliente.py · Operator-side controller for V1.0.
V1.0/cliente.py
V2 Host
Go backdoor side: networking, execution, and system actions.
- backdoor main · Starts the V2.0 host-side backdoor.
V2.0/backdoorV2.0/main.go - session conn · Owns host-side connection setup and session lifecycle.
V2.0/backdoorV2.0/conexiones/conexiones.go - executor · Runs received commands on the host.
V2.0/backdoorV2.0/ejecuciones/ejecuciones.go - system ops · Handles shutdown, message display, and other OS-level actions.
V2.0/backdoorV2.0/ejecuciones/sys/sys.go - firewall 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 · Starts the V2.0 operator CLI.
V2.0/clienteV2.0/main.go - client conn · Manages the operator-side TCP connection.
V2.0/clienteV2.0/conex/conexiones.go - command router · Maps operator choices to remote actions.
V2.0/clienteV2.0/conex/comandos/comandos.go - screenshot path · Handles screenshot request, receive, and reconstruction.
V2.0/clienteV2.0/conex/comandos/ss/ss.go - input parser · Reads and validates operator input.
V2.0/clienteV2.0/input/input.go - console UI · Cross-platform console behavior for Windows and Linux.
V2.0/clienteV2.0/consola/consola.go - colors · Terminal presentation and color formatting.
V2.0/clienteV2.0/colores/colores.go
Connections 16
- 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.