Skip to content

Protocol

Jump to bottom
Chokri Hammedi edited this page Apr 21, 2026 · 2 revisions

Protocol

This page describes the message protocol used between the server and agents, including encryption, framing, and all message types.

Transport

All messages are sent over a WebSocket connection. A wsNetConn adapter wraps the WebSocket as a net.Conn, allowing yamux to multiplex independent streams on top. Each proxied TCP connection gets its own yamux stream.

Framing

Each message is framed as:

+-------------------+-----------------------------+
| 4 bytes (big-end) | N bytes (encrypted payload) |
+-------------------+-----------------------------+
  length prefix        AES-256-GCM ciphertext

The 4-byte length prefix is a big-endian uint32 indicating the byte length of the encrypted payload that follows.

Encryption

Every message payload is encrypted with AES-256-GCM before sending.

Parameter Value
Algorithm AES-256-GCM
Key size 32 bytes
Key encoding Base64url, no padding
Nonce Random, 12 bytes, prepended to ciphertext
Scope Every message, independent nonce per message

The shared key is configured on both server and agent. There is no key exchange — the key must be distributed out of band.

Compression

Data payloads may optionally be compressed with DEFLATE (compress/flate) before encryption:

  • Only applied when payload size exceeds 256 bytes
  • Only applied when compression reduces the payload size
  • The receiver detects compression automatically from a flag in the message

Authentication Handshake

Before any data flows, a challenge-response handshake authenticates the agent:

Server                          Agent
  |                               |
  |--- auth_challenge ----------->|   encrypted nonce
  |                               |
  |<-- auth_response -------------|   agent decrypts, re-encrypts nonce
  |                               |
  | (verify match, proceed)       |

If the response does not match, the connection is closed immediately.

Message Format

All messages are JSON objects encrypted as described above. Common fields:

Field Description
type Message type string
conn_id Connection identifier for stream routing
original_agent_id Source agent for multi-hop relaying
target_agent_id Destination agent for multi-hop relaying

Message Types

Authentication

Type Direction Description
auth_challenge Server to Agent Server sends encrypted nonce
auth_response Agent to Server Agent decrypts and re-encrypts nonce

Registration

Type Direction Description
register Agent to Server Agent sends subnets, OS, hostname, username, internet status
register_ok Server to Agent Server confirms registration and returns assigned agent ID

Keepalive

Type Direction Description
heartbeat Agent to Server Sent every 10 seconds

TCP / UDP Proxy

Type Direction Description
connect Server to Agent Open a TCP or UDP connection to a target host and port
connect_response Agent to Server Success or failure of the connect request
data Bidirectional Raw payload for an open connection, optionally DEFLATE compressed

ICMP

Type Direction Description
icmp-request Server to Agent Ping a target host via the agent
icmp-response Agent to Server Result of the ping including RTT and success status
icmp_proxy Server to Agent Transparently proxy an ICMP echo request
icmp_proxy_response Agent to Server Result of the proxied ICMP echo

DNS

Type Direction Description
dns_request Server to Agent DNS query to resolve via the agent's resolver
dns_response Agent to Server DNS answer records

Discovery

Type Direction Description
ping-sweep-request Server to Agent Discover live hosts in a subnet using concurrent TCP probing
ping-sweep-response Agent to Server List of live hosts found
port-scan-request Server to Agent TCP or UDP port scan on a target
port-scan-response Agent to Server List of open ports found

Port Forwards

Type Direction Description
start-agent-listener Server to Agent Open a local TCP or UDP port forward on the agent
stop-agent-listener Server to Agent Close a port forward

Reverse Forwards

Type Direction Description
agent_fwd_open Agent to Server Agent requests to open a reverse forward
agent_fwd_ack Server to Agent Server acknowledges the reverse forward
agent_fwd_data Bidirectional Data relay for an active reverse forward

Control

Type Direction Description
reconnect Server to Agent Tell the agent to disconnect and reconnect
disconnect Server to Agent Tell the agent to exit

Multi-Hop Pivoting

Messages include original_agent_id and target_agent_id fields. When the server receives a message addressed to a different agent than the sender, it relays it to the target agent. This enables multi-hop pivoting where traffic can be routed through a chain of agents.

Use only on systems you own or have explicit written permission to test. Unauthorized use is prohibited.

Clone this wiki locally