Demo implementation of TCP/UDP tunnel over HTTP using Chisel

This is a minimal Go example using Chisel-UDS to tunnel traffic over HTTP.

This repo uses my own custom chisel fork (github.com/thomasbruninx/chisel-uds) as a direct module dependency for reverse Unix Domain Socket modes and telemetry extensions.

Usage

Server

Starting a server instance can be as simple as providing a configuration file (server.conf in the same folder as the executable, or using the -c /path/to/server.conf argument in the CLI)

go run ./cmd/server
go run ./cmd/server -c /path/to/server.conf

Alternatively, you can override any configuration using commandline parameters, for more info use the -h parameter.

go run ./cmd/server -h

Client

Starting a client instance can be as simple as providing a configuration file (client.conf in the same folder as the executable, or using the -c /path/to/client.conf argument in the CLI)

go run ./cmd/client

Alternatively, you can override any configuration using commandline parameters, for more info use the -h parameter.

go run ./cmd/client -h

Configuration

You can either use configuration files or CLI parameters to set up both servers and clients. Example configrations for both are provided in the examples directory of this repository.

Reverse endpoint configuration

R:18080:192.168.1.33:80 means:

• server listens on 127.0.0.1:18080
• traffic is tunneled through the connected client
• client-side destination is 192.168.1.33:80

Additional reverse UDS remotes are supported:

• R:uds-listen:<socket_path>:<target_host>:<target_port>
• R:uds-pair:<socket_path>:<target_host>:<target_port>

Examples:

• R:uds-listen:/tmp/chisel-api.sock:127.0.0.1:8080
• R:uds-pair:/tmp/chisel-pair.sock:127.0.0.1:9000

Build

make build-all

The project includes a root Makefile with cross-platform build targets. All artifacts are written to bin/ and use the naming format:

• server-<arch>-<os>
• client-<arch>-<os>

Build all targets:

make build-all

Available targets:

• Server - (Apple Silicon) MacOS: make build-server-macos-arm64
• Server - X86_64 Linux: make build-server-linux-x86_64
• Server - ARMv7 Linux: make build-server-linux-arm7
• Client - (Apple Silicon) MacOS: make build-client-macos-arm64
• Client - X86_64 Linux: make build-client-linux-x86_64
• Client - ARMv5 Linux: make build-client-linux-arm5
• Client - ARMv7 Linux: make build-client-linux-arm7
• Client - MIPS (little endian) Linux: make build-client-linux-mipsle
• Client - X86 Windows: make build-client-windows-x86
• Client - X86_64 Windows: make build-client-windows-x86_64

Examples:

make build-server-linux-x86_64
make build-client-windows-x86_64

Telemetry

The server can emit Opentelemetry compatible metrics. However this is disabled by default. You can enable this by adding this to you config:

otel_enabled=true
otel_host=127.0.0.1   # IP/Hostname of Opentelemetry collector
otel_port=4318        # Port of Opentelemetry collector

Or you can set these directly from the commandline using the --otel, --otel-host and --otel-port parameters. When you just enable Opentelemetry, it will emit metrics/tracing by default to 127.0.0.1:4318.

Alternatively, there's also a built-in monitor, which you can enable by using the --monitor parameter.

Signals included:

• traces for session handshake/config lifecycle, endpoint lifecycle, and stream events
• metrics for session/endpoint status gauges and failure/stream counters and duration histograms

Metric attributes are intentionally low-cardinality (status/protocol/mode only).

In the examples folder is an example Opentelemetry collector configuration otel-collector.yaml. Using the Docker command below you can start an Operntelemetry collector instance with this config and check out the generated metrics and tracing data.

docker run --rm -p 4318:4318 -v "$PWD/examples/otel-collector.yml:/etc/otelcol/config.yaml" otel/opentelemetry-collector:latest --config /etc/otelcol/config.yaml

Connection statuses

Session statuses

• pending: handshake started, config/auth not fully completed yet
• connected: session authenticated and tunnel is active
• failed: handshake/config/validation failed (error shown in monitor)
• disconnected: session previously connected and then closed

Endpoint statuses

• pending: endpoint is being set up
• active: endpoint listener/pair registration is live
• failed: endpoint setup failed (error shown in monitor)
• closed: endpoint was active/pending and then closed due to shutdown/session end