subixonfire/winbox-terminal-protocol

Purpose and Entry Point

This repository is a single-process Python CLI client for encrypted MikroTik RouterOS terminal sessions over the WinBox TCP protocol (default port 8291). It implements the text terminal protocol only, not WinBox GUI functionality.

• Executable entry point and all protocol/session logic: winbox_terminal_client.py

• Protocol reference/specification: PROTOCOL.md

Runtime and Dependencies

The client runs under Python 3 as a terminal-attached process. It relies on:

• TCP sockets to a MikroTik RouterOS device.

• pycryptodome for AES-128-CBC encryption.

• ecdsa for modern EC-SRP5 authentication.

• Local TTY, standard input/output, and Unix signal handling for interactive behavior.

There is no server, database, web layer, or persistent local state.

Connection and Authentication Stage

The program parses router address, port, username, and password from command-line arguments, opens a TCP connection, then negotiates authentication.

• Client orchestration: winbox_terminal_client.py

• Wire/authentication details: PROTOCOL.md

Authentication has a firmware-version compatibility boundary:

• RouterOS 6.43+ uses EC-SRP5 challenge/response and derives shared session material.

• Older RouterOS uses legacy MD5 challenge-response.

Successful authentication transitions the connection from handshake messages to encrypted session traffic.

M2 Protocol Encoding Boundary

WinBox terminal traffic is represented as MikroTik M2 binary messages: an M2 header plus typed fields used for routing, commands, request IDs, and terminal payloads.

• M2 implementation: winbox_terminal_client.py

• M2 format documentation: PROTOCOL.md

This layer isolates binary field serialization/parsing from authentication and terminal interaction. It is the primary compatibility boundary with MikroTik’s proprietary protocol.

Encryption and Framing Stage

After authentication, the client derives AES-128-CBC session keys and wraps terminal protocol messages in encrypted, length-prefixed frames with sequence tracking.

• Crypto/session framing implementation: winbox_terminal_client.py

• Encryption protocol details: PROTOCOL.md

Plain TCP carries only handshake traffic before this boundary; interactive terminal data is sent and received through the encrypted framing layer afterward.

Terminal Session Lifecycle

The client opens a RouterOS terminal configured as vt102, including current terminal dimensions. It maintains one remote terminal session per process.

• Terminal lifecycle and I/O loop: winbox_terminal_client.py

The lifecycle is:

1. Establish TCP connection.

2. Authenticate and enable encryption.

3. Request/open terminal session.

4. Relay local input to the encrypted remote stream.

5. Render decrypted remote output to stdout.

6. Disconnect on Ctrl+], EOF, error, or session termination.

Interactive I/O and Resize Handling

Local TTY handling places the terminal in an interactive mode suitable for raw keystrokes, command history, and tab completion as interpreted by RouterOS. Bidirectional I/O bridges local stdin/stdout with the encrypted protocol channel.

• TTY, stream relay, and resize handling: winbox_terminal_client.py

A SIGWINCH handler detects local terminal-size changes and sends updated dimensions to RouterOS, keeping the remote CLI layout synchronized.