Installation

The only system dependency for pwncat is python3 and pip. For pip to install all Python dependencies, you will likely need your distributions Python Development package (python3-dev for Debian-based distributions). Once you have a working pip installation, you can install pwncat with the provided setup script:

python setup.py --user install

It is recommended to use a virtual environment, however. This can be done easily with the Python3 venv module:

python -m venv env
source env/bin/activate
python setup.py install

When updating pwncat is it recommended to setup and update the virtual environment again.

After installation, you can use pwncat via the installed script:

$ pwncat --help
usage: pwncat [-h] [--config CONFIG] [--identity IDENTITY] [--listen] [--port PORT]
              [[protocol://][user[:password]@][host][:port]] [port]

    Connect to a remote victim. This command is only valid prior to an established
    connection. This command attempts to act similar to common tools such as netcat
    and ssh simultaneosly. Connection strings come in two forms. Firstly, pwncat
    can act like netcat. Using `connect [host] [port]` will connect to a bind shell,
    while `connect -l [port]` will listen for a reverse shell on the specified port.

    The second form is more explicit. A connection string can be used of the form
    `[protocol://][user[:password]@][host][:port]`. If a user is specified, the
    default protocol is `ssh`. If no user is specified, the default protocol is
    `connect` (connect to bind shell). If no host is specified or `host` is "0.0.0.0"
    then the `bind` protocol is used (listen for reverse shell). The currently available
    protocols are:

    - ssh
    - connect
    - bind

    The `--identity/-i` argument is ignored unless the `ssh` protocol is used.


positional arguments:
  [protocol://][user[:password]@][host][:port]
                        Connection string describing the victim to connect to
  port                  Alternative port number argument supporting netcat-like syntax

optional arguments:
  -h, --help            show this help message and exit
  --config CONFIG, -c CONFIG
                        Path to a configuration script to execute prior to connecting
  --identity IDENTITY, -i IDENTITY
                        The private key for authentication for SSH connections
  --listen, -l          Enable the `bind` protocol (supports netcat-like syntax)
  --port PORT, -p PORT  Alternative port number argument supporting netcat-like syntax

SSH Connection Errors

Due to the way that SSH channels are abstracted, a custom fork of paramiko was required to fit into pwncat. I submitted a pull request with Paramiko, but it was never merged. Therefore, pwncat is currently utilizing a custom fork of paramiko which provides an interface which is closer to a standard socket. pwncat is smart enough to tell you this is the problem, but for documentation’s sake, this command should fix your problems:

# Ensure that the correct paramiko is installed
pip install -U git+https://git+https://github.com/calebstewart/paramiko

If you installed pwncat within a virtual environment, this should obviously be done inside the virtual environment. If you did not install within a virtual environment, this change may break other python tools which depend on a later version of paramiko (however it should not affect things which depend on an equal version).

This problem is discussed here.

Development Environment

If you would like to develop modules for pwncat (such as privilege escalation or persistence module), you can use the setuptools “develop” target instead of “install”. This installs pwncat via symlinks, which means any modifications of the local code will be reflected in the installed package:

python setup.py develop