added some chapters

Author: manfred-kaiser

doc/_static/assets/css/toctree-icons.css

@@ -19,23 +19,37 @@
     content: "\f502";
 }
 
-/* Advanced usage */
+/* SSH Agent */
 #docs-nav .toctree-l1:nth-child(4):before,
 #docs-cards .toctree-l1:nth-child(4) i:before {
     font-family: FontAwesome;
-    content: "\f0e8";
+    content: "\f084";
 }
 
-/* Port Forwarding */
+/* File transfer */
 #docs-nav .toctree-l1:nth-child(5):before,
 #docs-cards .toctree-l1:nth-child(5) i:before {
     font-family: FontAwesome;
-    content: "\f542";
+    content: "\f56f";
 }
 
-/* SSH Vurnabilities */
+/* Port Forwarding */
 #docs-nav .toctree-l1:nth-child(6):before,
 #docs-cards .toctree-l1:nth-child(6) i:before {
+    font-family: FontAwesome;
+    content: "\f542";
+}
+
+/* Advanced usage */
+#docs-nav .toctree-l1:nth-child(7):before,
+#docs-cards .toctree-l1:nth-child(7) i:before {
+    font-family: FontAwesome;
+    content: "\f0e8";
+}
+
+/* SSH Vurnabilities */
+#docs-nav .toctree-l1:nth-child(8):before,
+#docs-cards .toctree-l1:nth-child(8) i:before {
     font-family: FontAwesome;
     content: "\f714";
 }

doc/advanced-usage.rst

@@ -1,5 +1,5 @@
-Advanced usage
-==============
+Advanced usage cases
+====================
 
 SSH-MITM is capable of advanced man-in-the-middle attacks. It
 can be used in scenarios where the remote host is not known or a single

doc/authentication.rst

@@ -1,2 +1,69 @@
 Authentication
 ==============
+
+
+none Authentication
+-------------------
+
+The none authentication takes a special position among the authentication methods.
+The reason is that this authentication method is used to tell the client which methods are accepted by the server. For this reason, none-Authentication is executed before all other authentication methods.
+
+However, it can also be used to give a user access to a system without requiring an explicit login.
+
+password authentication
+-----------------------
+
+Password authentication is one of the most common login methods. Almost all current operating systems support this method both for local logins and over the network. By default, OpenSSH and many other SSH servers have this type of authentication active.
+
+With SSH, within the encrypted channel, the password is transmitted in clear text. If a client connects to a Man in the Middle server, the server is able to read the username and password in clear text. This information can then be used to log in to other servers if the user exists and uses the same password.
+
+Another problem is that accounts with weak passwords can be compromised relatively easily through a brute force attack. This happens very often with IoT devices because they often have the same username on many devices and they are protected by a default password or only a weak password is set.
+
+.. warning::
+
+    Password authentication should not be used for these reasons!
+
+
+Example SSH-MITM session intercepting password authentication:
+
+.. code-block:: none
+
+    $ ssh-mitm
+    2021-09-02 09:51:35,354 [INFO]  starting SSH-MITM 0.5.13
+    2021-09-02 09:51:38,590 [INFO]  connected client version: SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.3
+    2021-09-02 09:51:48,629 [INFO]  Client connection established with parameters:
+        Remote Address: 127.0.0.1
+        Port: 22
+        Username: testuser
+        Password: secret
+        Key: None
+        Agent: no agent
+
+
+keyboard-interactive authentication
+-----------------------------------
+
+keyboard-interactive is similar to password authentication. The main difference is that the server can send any number of requests to the client, which are necessary for the login process. The server defines both the prompt text and whether the value is visible or not when entered.
+
+In many cases keyboard-interactive is used for 2 factor authentication. In the first step a password is requested and then e.g. the input of a time-based token is necessary (TOTP).
+
+Unless special tools are used to create cryptographically secured input, all input via keyboard-interactive can be reused during a man in the middle attack to login to another server.
+
+
+
+publickey authentication
+------------------------
+
+In contrast to password authentication, where the password is transmitted in plain text, publickey authentication is based on asymmetric encryption. In asymmetric encryption, a key pair consisting of a private part and a public part is created.
+
+With SSH, the public key is stored on the server while the private key remains in the possession of the user.
+
+With OpenSSH, the private key can be additionally protected by a password in case it is stolen. Starting with OpenSSH 8.2, FIDO2 tokens are supported and can be used for a 2 factor confirmation when using the key.
+
+As an alternative to a FIDO2 token, SSH-Askpass can also be used to confirm cryptographic operations. If there is an increased need for security, SSH-Askpass should only be used if the use of a FIDO2 token is not possible.
+
+Publickey authentication is only partially suitable for a man-in-the-middle attack. Unlike password authentication, no data is exchanged that can be used for a complete login.
+
+Another problem is that the key that should be used for the login is not known. This can lead to FIDO2 and SSH-Askpass protected keys displaying a prompt for an incorrect key to the user.
+
+An attacker should use PublicKey authentication only if the client does not accept other authentication methods.

doc/conf.py

@@ -77,12 +77,14 @@
 }
 
 page_descriptions = {
-    'install.html': 'SSH-MITM is easy to install with Python and PIP',
     'quickstart.html': 'Short guide to setup an intercepting SSH-MITM server with a single command',
+    'fingerprint.html': 'Description of host fingerprints and how to detect if a client already knows a host fingerprint',
+    'authentication.html': 'SSH authentication methods explained and how to use them during audits',
+    'sshagent.html': 'SSH agent and agent forwarding explained and security considerations discussed',
+    'filetransfer.html': 'Description of the SCP/SFTP protocols and how to manipulate files during audits',
+    'portforwarding.html': 'Introduction to port forwarding features of SSH-MITM',
     'advanced-usage.html': 'Guide on how to setup a SSH-MITM server for advanced security audits in large networks and special use cases',
     'ssh_vulnerabilities.html': 'Explanation of vulnerabilities related to the ssh protocol',
-    'jumphosts.html': 'SSH-MITM should not be used as jump host. This page describes alternatives and security considerations when operating a jump host',
-    'portforwarding.html': 'Introduction to port forwarding features of SSH-MITM'
 }
 
 html_context = {

doc/filetransfer.rst

@@ -0,0 +1,2 @@
+SCP/SFTP iletransfers
+=====================

doc/index.rst

@@ -8,6 +8,8 @@ SSH-MITM Docs - Main Page
    quickstart
    fingerprint
    authentication
-   advanced-usage
+   sshagent
+   filetransfer
    portforwarding
+   advanced-usage
    ssh_vulnerabilities

doc/quickstart.rst

@@ -27,9 +27,69 @@ In cases, when no agent was forwarded, SSH-MITM can rediredt the session to a ho
 
     </p>
     </p>
-
-Installation
-------------
+    <section class="how-section py-5">
+        <div class="container">
+            <div class="row">
+                <div class="item col-12 col-md-4">
+                    <div class="icon-holder">
+                        <img src="https://www.ssh-mitm.at/assets/images/streamline-free/monitor-loading-progress.svg" alt="">
+                        <div class="arrow-holder d-none d-lg-inline-block"></div>
+                    </div><!--//icon-holder-->
+                    <div class="desc p-3">
+                        <h5><span class="step-count mr-2">1</span>Install SSH-MITM</h5>
+                        <p>
+                            To install SSH-MITM, simply run this command in your terminal of choice:<br/>
+                            <code>
+                                $ sudo snap install ssh-mitm
+                            </code>
+                        </p>
+                        <p><a href="https://snapcraft.io/ssh-mitm">
+                            <img alt="Get it from the Snap Store" src="https://snapcraft.io/static/images/badges/en/snap-store-black.svg" />
+                        </a></p>
+                    </div><!--//desc-->
+                </div><!--//item-->
+                <div class="item col-12 col-md-4">
+                    <div class="icon-holder">
+                        <img src="https://www.ssh-mitm.at/assets/images/streamline-free/programmer-male.svg" alt="">
+                        <div class="arrow-holder d-none d-lg-inline-block"></div>
+                    </div><!--//icon-holder-->
+                    <div class="desc p-3">
+                        <h5><span class="step-count mr-2">2</span>Connect to the network</h5>
+                        <p>
+                            To start an intercepting mitm-ssh server on Port 10022,
+                            all you have to do is run a single command.<br/>
+                            <code>$ ssh-mitm --remote-host 192.168.0.x</code>
+                        </p>
+                        <p>
+                            Now let's try to connect to the ssh-mitm server.<br/>
+                            <code>$ ssh -p 10022 user@proxyserver</code>
+                        </p>
+                    </div><!--//desc-->
+                </div><!--//item-->
+                <div class="item col-12 col-md-4">
+                    <div class="icon-holder">
+                        <img src="https://www.ssh-mitm.at/assets/images/streamline-free/customer-service-woman.svg" alt="">
+                    </div><!--//icon-holder-->
+                    <div class="desc p-3">
+                        <h5><span class="step-count mr-2">3</span>Hijack SSH sessions</h5>
+                        <p>
+                            When a client connects, the ssh-mitm starts a new server, which is used for session hijacking.<br/>
+                            <code>[INFO]  created injector shell on port 34463</code>
+                        </p><p>
+                            To hijack this session, you can use your favorite ssh client.
+                            All you have to do is to connect to the hijacked session.<br/>
+                            <code>$ ssh -p 34463 127.0.0.1</code>
+                        </p>
+                    </div><!--//desc-->
+                </div><!--//item-->
+            </div><!--//row-->
+        </div><!--//container-->
+    </section><!--//how-section-->
+
+
+
+Alternative installation methods
+--------------------------------
 
 This part of the documentation covers the installation of SSH-MITM.
 The first step to using any software package is getting it properly installed.
@@ -51,8 +111,17 @@ Install with pip
 
     $ python -m pip install ssh-mitm
 
-Start ssh-mitm proxy server
----------------------------
+Install as AppImage
+"""""""""""""""""""
+
+.. code-block:: bash
+
+    $ wget https://github.com/ssh-mitm/ssh-mitm/releases/latest/download/ssh-mitm-x86_64.AppImage
+    $ chmod +x ssh-mitm*.AppImage
+
+
+Start SSH-MITM
+--------------
 
 Let’s get started with some simple examples.
 

doc/sshagent.rst

@@ -0,0 +1,53 @@
+SSH Agent
+=========
+
+There are several ways in which SSH keys can be managed locally. One of the most common use cases is to store a key in the file system. SSH clients are able to read them from specific directories. For example, an RSA key may be stored as .ssh/id_rsa in the user's home directory.
+
+To protect these keys from unauthorized access after theft or loss, it is recommended to store them encrypted. For this purpose it is necessary to enter a password.
+
+The SSH Agent can be used to manage these keys. The password input, for decrypting is only necessary once during loading into the SSH Agent. All further cryptographic operations are then performed without the need to enter a password.
+
+For the communication between SSH Agent and SSH Client a Unix socket is created and stored in a new subdirectory in /tmp. Because of this design, any user with appropriate privileges, such as the root user, is able to access and use this Unix socket.
+
+For this reason, it is important that privileged users are trusted or that their accounts are not compromised.
+
+To protect against misuse, a key can be secured with SSH-Askpass or a FIDO2 key. In both cases, user confirmation is required.
+
+The big advantage of a FIDO2 key is that the confirmation is done via a separate hardware and cannot be compromised by a malware infected machine. SSH-Askpass is a software solution that can be bypassed by malware or an attacker who controls the victim's desktop.
+
+For this reason, the use of a FIDO2 key is recommended over the use of SSH-Askpass.
+
+
+SSH Agent Forwarding
+--------------------
+
+Many SSH clients offer the possibility to pass a local agent to a remote server. The corresponding protocol was defined in draft-ietf-secsh-agent-00. The corresponding draft was already defined in 2001 and almost all SSH clients support it.
+
+A passed SSH agent can then be used to login to another server.
+
+The advantage is that no sensitive data, such as private SSH keys, need to be stored permanently on the remote servers, but a secure login using Publickey authentication is still possible.
+
+In most cases, agent forwarding is only supported for a shell connection. Agent forwarding is theoretically also possible for file transfers using SCP and SFTP, but most programs do not support this feature.
+
+OpenSSH has implemented agent forwarding with version 8.4 for the client programs scp and sftp as well, in order to not have to copy these files via the local host for remote to remote file operations.
+
+However, SSH Agent Forwarding is associated with a security risk. This is because privileged users can access and abuse the forwarded agent sockets.
+
+For this reason, agent forwarding should not be used.
+
+However, there are use cases where working without agent forwarding, is more costly. One possibility is working on a development server. From this server, it is often necessary to access a Git server to synchronize changes. Without a forwarded agent, custom keys would have to be created to access the Git server. These, in turn, could be stolen and thus abused if the server were compromised.
+
+There is a tutorial on Github (https://docs.github.com/en/developers/overview/using-ssh-agent-forwarding) that describes how to configure OpenSSH to pass an agent through to a remote server.
+
+However, it does not address the risk that a leaked agent is a potential security risk. The only warning is that the configuration must only be done for a specific host, otherwise the agent will be passed through to all servers you connect to.
+In order to make it as difficult as possible to misuse the leaked keys, it is necessary to protect them with a FIDO2 token or SSH-Askpass. In the case of a passed-through agent, both solutions have a comparable level of security.
+
+Nevertheless, the use of FIDO2 keys is recommended because a vulnerability in the client could eventually leak them. An example of this was the experimental support for roaming in OpenSSH 5.4. This feature should make it possible for a client to resume an unexpectedly terminated connection. Although the OpenSSH server did not support roaming, roaming was enabled in the client by default.
+
+The roaming implementation had two vulnerabilities that allowed an attacker to access sensitive information such as private keys under certain circumstances.
+
+.. warning::
+
+    SSH Agent Forwarding should not be used. The reason is that it can prevent a lot of security risks. Agent forwarding often makes it easier to work with multiple servers. However, for most use cases there are ways to accomplish the same tasks without agent forwarding.
+
+    If agent forwarding is still required, an FIDO2 token should be used. If this is not possible, e.g. because the server does not support the required algorithms, SSH-Askpass can also be used.