3. The Reliability Layer

Because ICMP and UDP provide no delivery guarantees, Spoof Tunnel implements a custom TCP-like reliability layer in user space. This is mandatory for maintaining stable TLS handshakes and in-order stream delivery.

• Packet Sequencing and ACKs: Every payload packet is wrapped in a SeqDataPacket format containing a monotonic sequence number (4 bytes). The recipient acknowledges data via AckPacket, utilizing a 64-bit acknowledgment bitmap for handling blocks of data efficiently.
• Flow Control & Buffers: The RecvBuffer maintains an internal map of sequences. Out-of-order packets are buffered and data is strictly delivered to the target socket in-order.
• Retransmission Engine: An active background goroutine sweeps the SendBuffer every 100ms. Unacknowledged packets exceeding the retransmit_timeout are resent using exponential backoff up to a defined max_retries limit.

4. Session Multiplexing

Establishing a new tunnel session incurs significant latency. To mitigate this, Spoof Tunnel implements an internal multiplexer (Mux).

A single "Master Session" is established over the unreliable link. All incoming local TCP SOCKS5 connections are assigned a virtual 4-byte StreamID and multiplexed within this single master session.

• 0x01 MuxStreamOpen: Followed by [StreamID:4][TargetLen:2][Target String]
• 0x02 MuxStreamData: Followed by [StreamID:4][Raw Payload]
• 0x03 MuxStreamClose: Followed by [StreamID:4]
• 0x04 MuxStreamAck: Server acknowledgment for successful proxy stream creation.

5. Cryptography

Security and obfuscation are enforced via ChaCha20-Poly1305 AEAD. AEAD ensures that not a single byte of the IP payload or tunnel header structure is visible or modifiable by an active MITM attacker without immediately dropping the connection.

Each session initializes a randomized nonce mechanism to prevent replay attacks, while the static pre-shared Base64 keys act as the master cryptographic secret.

6. Asymmetric Transport Protocols

Each client or server can independently choose a different transport protocol for each direction. For example, the client sends via TCP while the server responds via ICMPv6. Choose based on your specific server's censorship constraints.

7. Simple UDP-Pipe

Starting from v2, to improve performance and reduce processing overhead, the core has been refactored into a simple UDP pipe. It listens on a UDP port; you send any UDP traffic to it, the core tunnels the packet to the server, and on the server side it forwards to any endpoint you configure.

As a result, features like FEC, ChaCha20 crypto, SOCKS, ACK/TCP-like system, etc. have been removed from the core.

The recommended approach is to create a local IPv4/IPv6 tunnel using WireGuard. You can refer to this WireGuard local IPv6 setup script: https://github.com/ParsaKSH/TAQ-BOSTAN/blob/main/wireguard.sh

On the client side, set the endpoint in /etc/wireguard/TAQBOSTANwg.conf to 127.0.0.1 and the port the client core is listening on. An MTU of 1280 is recommended.

8. Spoof IP List Support

Starting from v3, instead of a single spoof IP, you can provide a list of IPs. The core will cycle through them in round-robin order, using a new IP from the list for each outgoing packet.

The reason for this feature: the infrastructure firewall may enforce bandwidth or volume limits on whitelisted IPs. Using a single IP means its limits directly degrade your tunnel quality.

To learn how to find valid spoof IPs, see the Spoof Tester section below.

9. Low-Level Modules Rewritten in Rust

Starting from v2, the high-load parts of the core responsible for packet-level processing and IP header manipulation have been rewritten in Rust for minimum CPU overhead and maximum performance.

10. Built-in Spoof Packet Tester & IP Discovery Tool

10.1 Supported Transports: ICMP & TCP

The tester module currently supports two protocols — TCP and ICMP — which you can choose based on your needs.

10.2 IP Range Input Support

You can provide individual IPs or IP ranges to test which ones can be used for spoofing. The module expands the ranges and sends spoofed packets from each IP individually. The receiver side waits for packets and records any that arrive successfully.

Supported input formats:

• Single IP → 192.168.1.1
• IP range → 192.168.1.1-192.168.1.255
• CIDR range → 192.168.1.0/24

10.3 Configurable Packet Loss Threshold

You can specify the maximum acceptable packet loss percentage per spoof IP on each side.

10.4 Sender & Receiver Modes

This module requires two servers (nodes) — one acts as sender, the other as receiver.

How to use:

1. Set the client (Iran server) to sender mode. Configure: protocol, IP range file, target IP (foreign server), attempts per IP, max allowed packet loss, and timeout.
2. Set the server (foreign server) to receiver mode with the same settings.
3. Start the receiver first, then immediately start the sender.
4. After the timeout, the receiver will have a list of IPs whose spoofed packets arrived, along with each IP's packet loss rate.
5. Repeat the process in reverse — client becomes receiver, server becomes sender.
6. If both servers support spoofing, you'll have a list of valid spoof IPs for each direction.

Important: The output of the client in receiver mode should be used as the spoof IP list on the server side, and vice versa.

Starting from v2, a web management panel is included for ease of use. Install it using the install script at: https://github.com/ParsaKSH/spoof-tunnel/blob/main/panel/install.sh

On Iran-based servers, you may need to run the script steps manually.

All core features — including the tunnel instances and the tester module — are fully accessible through the panel.

Usage Instructions

1. Build the Binary

Spoof Tunnel is written in Go. You can build it using the standard Go toolchain:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o spoof ./cmd/spoof/

2. Generate Cryptographic Keys

Before starting the tunnel, generate a pair of Base64 private/public keys for both the server and the client.

./spoof keygen

Take note of the Private Key and Public Key. The Server's Public Key must be placed in the Client's peer_public_key field, and vice versa.

3. Running the Service

Note: Raw sockets require elevated privileges. You must execute both binaries as root (or assign the CAP_NET_RAW capability).

On the Server:

sudo ./spoof -c server-config.json

On the Client:

sudo ./spoof -c client-config.json

Once connected, the client opens a SOCKS5 proxy on 127.0.0.1:1080 (by default) that routes all traffic through the spoofed tunnel.

Client Config (v1)

Server Config (v1)

Usage Instructions

Spoof Tunnel is developed in both Go and Rust. To build from source yourself (instead of using GitHub Actions releases), you need both compilers installed.

Clone the repository:

git clone --depth=1 https://github.com/ParsaKSH/spoof-tunnel.git

Enter the project directory:

cd spoof-tunnel

Build using make:

make core

To build both the panel and the core (requires Node.js and npm):

make all

Note: Building manually is not required — you can use pre-built releases from GitHub.

Client (Local) Config

Server (Remote) Config

All config parameters can be provided either in a JSON file and run with ./spoof run -c config.json, or as command-line flags:

./spoof remote --forward 127.0.0.1:51820 --spoof-ip-file /path/to/src.txt ...