gonc

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

---

Related Projects

• 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:

1. 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
   

2. 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"
  
  # The left side f://127.0.0.1:1080?to=1.2.3.4:80
  # means listening locally on port 1080 and forwarding traffic to 1.2.3.4:80 on the remote side.
  # The right side 'none' indicates that no port is opened remotely.
  gonc -p2p <passphrase> -link "f://127.0.0.1:1080?to=1.2.3.4:80;none"
  
  # The right side f://0.0.0.0:80?to=127.0.0.1:80
  # means listening on port 80 on the remote side and forwarding traffic back to 127.0.0.1:80 locally.
  gonc -p2p <passphrase> -link "none;f://0.0.0.0:80?to=127.0.0.1:80"
  
  # The left side x+tls means the proxy protocol with TLS encryption and allows for certificate configuration. The right side specifies the outbound IP address via `outbound_bind` (suitable for multi-IP environments).
  gonc -p2p <口令> -link "x+tls://user:[email protected]:1080?cert=ca.pem&key=key.pem;none?outbound_bind=10.0.0.5"
  

Flexible Service Configuration

• Use -exec to flexibly configure the application to provide services for each connection. For example, instead of specifying /bin/bash for shell commands, it can also be used for port forwarding. However, the following example starts a new gonc process for each connection:

  gonc -keep-open -exec "gonc -tls www.baidu.com 443" -l 8000
  

• To avoid spawning multiple child processes, use the built-in nc module:

  gonc -keep-open -exec ":nc -tls www.baidu.com 443" -l 8000
  

Socks5 Proxy Service

• Configure client mode:

  gonc -x s.s.s.s:port x.x.x.x 1234
  

• Built-in Socks5 server: Use -e :s5s to provide standard Socks5 service. Support -auth to set a username and password for Socks5. Use -keep-open to continuously accept client connections to the Socks5 server. Thanks to Golang's goroutines, it achieves good multi-client concurrency performance:

  gonc -e ":s5s -auth user:passwd" -keep-open -l 1080
  

• Secure Socks5 over TLS: Since standard Socks5 is unencrypted, use -e :s5s with -tls and -psk to customize secure Socks5 over TLS communication. Use -P to monitor connection transmission information, and -acl to implement access control for incoming connections and proxy destinations. For the acl.txt file format, see acl-example.txt.

  gonc.exe -tls -psk passphrase -e :s5s -keep-open -acl acl.txt -P -l 1080

  On the other side, use :s5c (built-in s5c command) to convert Socks5 over TLS to standard Socks5, providing local client access on 127.0.0.1:3080:

  gonc.exe -e ":s5c -tls -psk passphrase x.x.x.x 1080" -keep-open -l -local 127.0.0.1:3080

Establishing a Tunnel for Other Applications

• Assist WireGuard in NAT Traversal to Form a VPN

  On the passive (listening) side, PC-S, run the following command (using the WireGuard peer’s public key as the passphrase, and assuming WireGuard is listening on port 51820):

  gonc -p2p <PublicKey-of-PS-S> -mqtt-wait -u -k -e ":nc -u 127.0.0.1 51820"

  On the active (initiating) side, PC-C, set the WireGuard peer (PS-S)'s Endpoint to 127.0.0.1:51821, with its own WireGuard interface listening on 51820. Then run the following command. The -k flag allows gonc to automatically reconnect if the network drops:

  gonc -p2p <PublicKey-of-PS-S> -mqtt-hello -u -k -e ":nc -u -local 127.0.0.1:51821 127.0.0.1 51820"

P2P NAT Traversal Capabilities

How does gonc establish a P2P connection?

• Concurrently uses multiple public STUN servers to detect local TCP/UDP NAT mappings and intelligently determine NAT type
• Exchanges address information securely via public MQTT servers, using a hash derived from the SessionKey as the shared topic
• Attempts direct connection in the following priority order: IPv6 TCP > IPv4 TCP > IPv4 UDP, aiming for true peer-to-peer communication
• No relay servers are used, and no fallback mechanisms are provided — either the connection fails, or it's a real P2P success

How to Deploy a Relay Server for Cases Where P2P Is Not Feasible

• A SOCKS5 server with UDP ASSOCIATE support running on a public IP is sufficient as a relay. You can also run gonc's built-in SOCKS5 proxy on your own VPS to act as a relay server.

  The following command starts a SOCKS5 proxy that only supports UDP forwarding. The -psk and -tls options enable encryption and PSK-based authentication. Note: Don’t just open port 1080 in your firewall—UDP forwarding uses random ports for each session.

  gonc -e ":s5s -u -c=0" -psk <password> -tls -k -l 1080

• When P2P fails, you only need one side of gonc to retry the P2P process using the -x option to route through the SOCKS5 relay:

  gonc -p2p <passphrase> -x "-psk <password> -tls <socks5server-ip>:1080"

  Alternatively, you can use a standard SOCKS5 proxy server that supports UDP forwarding:

  gonc -p2p <passphrase> -x "<socks5server-ip>:1080" -auth "user:password"

For example, if both peers are behind symmetric NATs and P2P fails, having just one side use a SOCKS5 UDP relay effectively changes its NAT behavior to “easy,” making it much easier to establish a connection. The data remains end-to-end encrypted.

Used public servers（STUN & MQTT）：

"tcp://turn.cloudflare.com:80",
"udp://turn.cloudflare.com:53",
"udp://stun.l.google.com:19302",
"stun.gonc.cc:3478",
"global.turn.twilio.com:3478",
"stun.nextcloud.com:443",

"tcp://broker.hivemq.com:1883",
"tcp://broker.emqx.io:1883",
"tcp://test.mosquitto.org:1883",
"tcp://mqtt.gonc.cc:1883"

How effective is gonc at NAT traversal?

Except in symmetric NAT scenarios on both ends, gonc achieves a very high success rate

gonc classifies NAT types into three categories:

1. Easy: A single internal port maps to the same external port across multiple STUN servers

2. Hard: A single internal port maps to a consistent but different external port across STUN servers — harder than type 1

3. Symmetric: A single internal port maps to different external ports depending on the destination — the most difficult type

To handle these NAT types, gonc employs several traversal strategies:

• Uses multiple STUN servers to detect NAT behavior and identify multi-exit IP scenarios

• Prefers IPv6 connections when both sides support it (e.g., TCP6-to-TCP6 direct dial)

• Both peers listen on TCP while simultaneously dialing each other to increase TCP hole punching success

• The peer with the easier NAT delays its initial UDP packet to avoid triggering port changes on the harder side

• The peer with the harder NAT sends UDP packets with a low TTL to reduce interference from the remote firewall

• As a last resort, uses a "birthday paradox" strategy: the harder side uses 600 random source ports, and the other side tries 600 random destination ports, increasing the chance of a successful UDP port collision