Reorganized documentation. Added more description output during ssh auth failure

docs/source/commands/download.rst

@@ -0,0 +1,18 @@
+Download
+========
+
+The ``download`` command provides an easy way to exfiltrate files from the victim. All file transfers are made over
+the same connection as your shell, and there are no HTTP or raw socket ports needed to make these transfers.
+File transfers are accomplished by utilizing the ``gtfobins`` framework to locate file readers on the victim host and
+write the contents back over the pipe. In some cases, this includes and requires encoding the data on the victim end
+and automatically decoding on the attacking host.
+
+The ``download`` command has a simply syntax which specifies the source and destination files only. The source file is
+a file on the remote host, which will be tab-completed at the ``pwncat`` prompt. The destination is a local file path
+on your local host which will be created (or overwritten if existing) with the content of the remote file.
+
+.. code-block:: bash
+    :caption: Downloading the contents of /etc/hosts to a local file
+
+    download /etc/hosts ./victim-hosts
+

docs/source/commands/index.rst

@@ -10,3 +10,8 @@ Command index
     bruteforce.rst
     busybox.rst
     connect.rst
+    download.rst
+    persist.rst
+    privesc.rst
+    tamper.rst
+    upload.rst

docs/source/commands/persist.rst

@@ -2,8 +2,9 @@ Persistence
 ===========
 
 The ``pwncat.victim.persist`` module provides an abstract way to install various persistence methods
-on the target host. To view a list of available persistence methods, you can use the ``--list/-l``
+on the target host. The ``persist`` command provides an interface to this module to allow straightforward
-switch:
+installation and management of remote persistence. To view a list of available persistence methods,
+you can use the ``--list/-l`` switch:
 
 .. code-block:: bash
 
@@ -14,11 +15,10 @@ switch:
      - sshd as system (local)
 
 This output indicates a few things. First, if a given method specifies "as user", then the persistence
-method is installed as a specific user. If no user is specified during installation, ``root`` is
+method is installed as a specific user. If no user is specified during installation, the current user is
-attempted, but will likely only succeed if you do not currently have root permissions. Second,
+attempted. Second, persistence methods marked "local" allow a local user to escalate to that user (or to
-persistence methods marked "local" allow a local user to escalate to that user (or to root for system
+root for system persistence modules). This is in contrast to persistence methods which only allow remote
-persistence modules). This is in contrast to persistence methods which only allow remote access
+access as the specified user.
-as the specified user.
 
 To get more information on a specific module, you can pass the ``--method/-m`` option with the method
 name when using ``--list/-l``. This will provide the module specific documentation on what is being

docs/source/commands/privesc.rst

@@ -1,9 +1,6 @@
 Automated Privilege Escalation
 ==============================
 
-.. toctree::
-    :maxdepth: -1
-
 ``pwncat`` has the ability to attempt automated privilege escalation methods. A number of methods are implemented by
 default such as:
 

docs/source/commands/tamper.rst

@@ -1,5 +1,5 @@
-Remote Tampers
+Tamper
-==============
+======
 
 ``pwncat`` tracks modifications of the remote system through the ``tamper`` module. Programmatically, ``pwncat``
 interfaces with the tamper subsystem through the ``pwncat.victim.tamper`` object. This allows generic modifications

docs/source/commands/upload.rst

@@ -1,5 +1,5 @@
-File Upload
+Upload
-===========
+======
 
 ``pwncat`` makes file upload easy through the ``upload`` command. File upload is accomplished via
 the ``gtfobins`` modules, which will enumerate available local binaries capable of writing printable
@@ -12,16 +12,6 @@ At the local ``pwncat`` prompt, local and remote files are tab-completed to prov
 interface, and a progress bar is displayed.
 
 .. code-block:: bash
+    :caption: Upload a script to the remote host
 
-    (local) pwncat$ upload --help
+    upload ./malicious.sh /tmp/definitely-not-malicious
-    usage: upload [-h] source destination
-
-    Upload a file from the local host to the remote host
-
-    positional arguments:
-      source
-      destination
-
-    optional arguments:
-      -h, --help   show this help message and exit
-

docs/source/download.rst

@@ -1,22 +0,0 @@
-File Download
-=============
-
-File download is performed in a similar fashion to file upload. The interface is largely the same
-with the parameter order swapped ("source" is a remote file while "destination" is a local file).
-This command provides the same local and remote tab-completion and progress bar as with the upload
-command.
-
-.. code-block:: bash
-
-    (local) pwncat$ download --help
-    usage: download [-h] source destination
-
-    Download a file from the remote host to the local host
-
-    positional arguments:
-      source
-      destination
-
-    optional arguments:
-      -h, --help   show this help message and exit
-

docs/source/index.rst

@@ -69,11 +69,6 @@ well. Pull requests are always welcome!
     usage.rst
     configuration.rst
     commands/index.rst
-    upload.rst
-    download.rst
-    tamper.rst
-    privesc.rst
-    persist.rst
     api/index.rst
 
 Indices and tables

pwncat/commands/connect.py

@@ -200,18 +200,17 @@ class Command(CommandDefinition):
                     # Attempt authentication
                     try:
                         t.auth_publickey(args.user, key)
-                    except paramiko.ssh_exception.AuthenticationException:
+                    except paramiko.ssh_exception.AuthenticationException as exc:
-                        pass
+                        util.error(f"authentication failed: {exc}")
                 else:
                     try:
                         t.auth_password(args.user, args.password)
-                    except paramiko.ssh_exception.AuthenticationException:
+                    except paramiko.ssh_exception.AuthenticationException as exc:
-                        pass
+                        util.error(f"authentication failed: {exc}")
 
                 if not t.is_authenticated():
                     t.close()
                     sock.close()
-                    util.error("authentication failed")
                     return
 
                 # Open an interactive session