Added ssl-bind and ssl-connect usage documentation

docs/source/usage.rst

@@ -34,6 +34,13 @@ with three different C2 protocols: ``bind``, ``connect``, and ``ssh``. The first
 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:`. For the ``ssl-bind`` protocol, you must also supply either
+the ``--certificate`` argument pointing to a PEM formatted bundled certificate and key file or two
+querystring parameters named ``certfile`` and ``keyfile``.
+
 pwncat exposes these different C2 channel protocols via the ``protocol`` field of the connection string
 discussed below.
 
@@ -42,22 +49,27 @@ 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]``
+``[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.
+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 and port are provided, assume protocol is ``connect``
+- If no user or host is provided (or host is ``0.0.0.0``) and the ``certfile`` or ``keyfile`` 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, the protocol is assumed to be ``connect``
   - This is the ``netcat`` syntax seen in the below examples for the ``connect`` protocol.
-- If the ``-l`` parameter is used, the protocol is assumed to be ``bind``.
-  - This is the ``netcat`` syntax seen in the below examples for the ``bind`` protocol.
+- If the ``-l`` parameter is used and the ``certfile`` or ``keyfile`` 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
 ---------------------------------
@@ -75,6 +87,18 @@ address which is routable (e.g. not NAT'd). The ``connect`` protocol provides th
     # Connection string with assumed protocol
     pwncat 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.
+
+.. code-block:: bash
+    :caption: Connecting to a bind shell at 1.1.1.1:4444
+
+    # Full connection string
+    pwncat connect://192.168.1.1:4444
+
 Catching a victim reverse shell
 -------------------------------
 
@@ -94,6 +118,29 @@ victim machine. This mode is accessed via the ``bind`` protocol.
     # Assumed protocol, assumed bind address
     pwncat :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 using the ``--cert/--certificate`` argument, you must provided a combined certificate and key file in PEM
+format. If your key and certificate are stored in separate files, you should specify the ``certfile`` and
+``keyfile`` querystring arguments instead.
+
+.. code-block:: bash
+    :caption: Catching a reverse shell
+
+    # netcat syntax
+    pwncat -l --cert /path/to/cert.pem  4444
+    # Full connection string
+    pwncat ssl-bind://0.0.0.0:4444?certfile=/path/to/cert.pem&keyfile=/path/to/key.pem
+    # Assumed protocol
+    pwncat --cert /path/to/cert.pem 0.0.0.0:4444
+    # Assumed protocol, assumed bind address
+    pwncat --cert /path/to/cert.pem :4444
+
 Connecting to a Remote SSH Server
 ---------------------------------