Introduction to gonc

README in 中文、 English

gonc is a Golang-based netcat tool designed to facilitate peer-to-peer communication. Its main features include:

🔁 Automated NAT Traversal: Zero configuration. Both sides only need to agree on a passphrase. By using the -p2p parameter, peers can automatically discover each other’s network addresses and establish a point-to-point connection through NAT traversal, leveraging public STUN and MQTT services for address exchange.
🔒 End-to-End Encrypted with Mutual Authentication: Supports TLS for TCP and DTLS for UDP encrypted transmission, with passphrase-based mutual identity authentication.
🧩 Flexible Service Configuration: With the -e parameter, you can flexibly set the application to serve each connection. For example, -e /bin/sh can provide a remote cmd shell. You can also use built-in virtual commands for convenient SOCKS5 service, HTTP file service, and traffic forwarding.

Latest version download

docs

gonc-gui — a desktop (Windows) and Android app built on gonc: convenient cross-device, cross-network P2P direct connection and secure file transfer. Just share a passphrase (or scan a QR code); no command line required.

Usage Examples

Basic Usage

Use it like nc:
```
gonc www.baidu.com 80
gonc -tls www.baidu.com 443
```
can only establish point-to-point connections based on IP and port.
Now, you can also establish point-to-point connections based on a shared passphrase, with automated NAT traversal.

The following diagram shows the process of gonc establishing a P2P connection between a home broadband network (hard NAT) and a peer on a mobile network (symmetric NAT). Since both sides have IPv6, the -4 option is used on both ends to force IPv4 in order to demonstrate NAT traversal.

P2P Tunnel and HTTP File Server

Both sides agree on the same passphrase. On the sender side, start an HTTP file server to expose the files or directories to be shared. The -httpserver option accepts multiple paths, each of which can be either a single file or a directory:
```
gonc -p2p <passphrase> -httpserver c:/RootDir1 c:/RootDir2
```
On the receiving side, there are two options:

Automatically download the entire directory

After running the following command, all files will be downloaded recursively to the local machine. If the process is interrupted, re-running the command will automatically resume from where it left off:
```
gonc -p2p <passphrase> -download c:/SavePath
```
Browse and selectively download via browser

This option does not start downloading automatically. Instead, you need to manually open a browser and visit http://127.0.0.1:9999 to view the peer’s file list and download files as needed:
```
gonc -p2p <passphrase> -httplocal-port 9999
```
If you need to download a specific subdirectory, the browser becomes inconvenient, but you can do it like this:
```
gonc -http-download c:/SavePath http://127.0.0.1:9999/subdir
```

Secure Encrypted P2P Communication

Establish secure encrypted P2P communication between two different networks by agreeing on a passphrase (use gonc -psk . to generate a high-entropy passphrase to replace passphrase). This passphrase is used for mutual discovery and certificate derivation, ensuring communication security with TLS 1.3.
```
gonc -p2p passphrase
```
On the other side, use the same parameters (the program will automatically attempt TCP or UDP communication (TCP preferred), negotiate roles (TLS client/server), and complete the TLS protocol):
```
gonc -p2p passphrase
```
Note that if the other end delays the running time, it will exit if it cannot find the other end to interact with information within about half a minute. Therefore, it also supports a waiting mechanism based on MQTT message subscription, using -mqtt-wait and -mqtt-hello to synchronize the timing of the two parties to start P2P. For example, the following uses -mqtt-wait to wait continuously，
```
gonc -p2p passphrase -mqtt-wait
```
On the other side,
```
gonc -p2p passphrase -mqtt-hello
```
Check your NAT type
```
gonc -nat-checker
```
This will check your IPv6 and IPv4 TCP and UDP NAT addresses and analyze port changes after NAT. If no TCP6 or UDP6 addresses are listed, it means you don't have IPv6. Each protocol address ends with "(easy)", indicating the highest success rate for hole punching; "(hard)" indicates a higher success rate; and "(symm)" is the most difficult. Symm requires the other end to be either "easy" or "hard" for P2P to work.

Reverse Shell (Pseudo-Terminal Support for UNIX-like Systems)

Listener (does not use -keep-open, accepts only one connection; no authentication with -psk):
```
gonc -tls -exec ":sh /bin/bash" -l 1234
```
Connect to obtain a shell (supports TAB, Ctrl+C, etc.):
```
gonc -tls -pty x.x.x.x 1234
```
Use P2P for reverse shell (passphrase is used for authentication, ensuring secure communication with TLS 1.3):
```
gonc -exec ":sh /bin/bash" -p2p passphrase
```
On the other side:
```
gonc -pty -p2p passphrase
```

Transmission Speed Test

Send data and measure transmission speed (built-in /dev/zero and /dev/urandom):

gonc.exe -send /dev/zero -P x.x.x.x 1234

Example output:

IN: 76.8 MiB (80543744 bytes), 3.3 MiB/s | OUT: 0.0 B (0 bytes), 0.0 B/s | 00:00:23

On the receiving side:

gonc -P -l 1234 > NUL

P2P Tunnel and SOCKS5 / HTTP Proxy

Wait for the tunnel to be established:
```
gonc -p2p passphrase -linkagent
```
On the other side, start a local SOCKS5 / HTTP proxy service on port 3080 to access the remote network:
```
# The link option controls how the local and remote proxy endpoints are created.
# Use none to indicate that no listening port is opened on that side:
gonc -p2p passphrase -link "3080;none"
```
Next, for example, if you want to connect to 10.0.0.1:3389 in the remote network, you can simply enter the following address in your local Remote Desktop client:
```
10.0.0.1-3389.gonc.cc:3080
```
This domain will be resolved into an IP in the form of 127.b.c.d. As a result, the Remote Desktop client will connect to the local SOCKS5 proxy on port 3080, and then gonc will reverse-parse the 127.b.c.d address to extract the information 10.0.0.1-3389 from the domain name.

link Configuration Format

# Based on the established tunnel, both local and remote sides listen on port 1080.
# The proxy supports both HTTP and SOCKS5 protocols, with transparent proxy capability enabled.
gonc -p2p <passphrase> -link "1080;1080"

# Below is the configuration method for the URL format. The parameter value of -link must be enclosed in quotes; otherwise, parsing problems may occur.
# The left side x://0.0.0.0:1080?tproxy=1 is equivalent to simply writing 1080.
# The right side enables port 1080 on the remote host, without transparent proxy support.
gonc -p2p <passphrase> -link "x://0.0.0.0:1080?tproxy=1;x://127.0.0.1:1080"

gonc

Most Popular