From a80f705d4bdb3a25ff209af0223e959f07d8a0fb Mon Sep 17 00:00:00 2001
From: Vadym Malakhatko <v.malakhatko@sirinsoftware.com>
Date: Tue, 30 Jun 2020 14:42:26 +0300
Subject: [PATCH] userguide: add documentation for Hassh usage

1. Rules keywords
2. Json keywords
3. Usage in lua
4. Enabling in configuration file
---
 doc/userguide/lua/lua-functions.rst          | 66 ++++++++++++++++++++
 doc/userguide/output/eve/eve-json-format.rst |  8 +++
 doc/userguide/rules/ssh-keywords.rst         | 62 ++++++++++++++++++
 suricata.yaml.in                             |  1 +
 4 files changed, 137 insertions(+)

diff --git a/doc/userguide/lua/lua-functions.rst b/doc/userguide/lua/lua-functions.rst
index 9b5fb48d44..5bd7151379 100644
--- a/doc/userguide/lua/lua-functions.rst
+++ b/doc/userguide/lua/lua-functions.rst
@@ -672,6 +672,72 @@ Example:
       end
   end
 
+
+HasshGet
+~~~~~~~~
+
+Get MD5 of hassh algorithms used by the client through HasshGet.
+
+Example:
+
+::
+
+  function log (args)
+      hassh = HasshGet()
+      if hassh == nil then
+          return 0
+      end
+  end
+
+HasshGetString
+~~~~~~~~~~~~~~
+
+Get hassh algorithms used by the client through HasshGetString.
+
+Example:
+
+::
+
+  function log (args)
+      hassh_string = HasshGetString()
+      if hassh == nil then
+          return 0
+      end
+  end
+  
+HasshServerGet
+~~~~~~~~~~~~~~
+
+Get MD5 of hassh algorithms used by the server through HasshServerGet.
+
+Example:
+
+::
+
+  function log (args)
+      hassh_string = HasshServerGet()
+      if hassh == nil then
+          return 0
+      end
+  end
+  
+HasshServerGetString
+~~~~~~~~~~~~~~~~~~~~
+
+Get hassh algorithms used by the server through HasshServerGetString.
+
+Example:
+
+::
+
+  function log (args)
+      hassh_string = HasshServerGetString()
+      if hassh == nil then
+          return 0
+      end
+  end
+
+
 Files
 -----
 
diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index 5f950fc883..0b58c1df8e 100644
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/doc/userguide/output/eve/eve-json-format.rst
@@ -980,6 +980,10 @@ Fields
 
 * "proto_version": The protocol version transported with the ssh protocol (1.x, 2.x)
 * "software_version": The software version used by end user
+* "hassh": MD5 of hassh algorithms of client or server
+* "hassh.string": hassh algorithms of client or server
+
+Hassh must be enabled in the Suricata config file (set 'app-layer.protocols.ssh.hassh' to 'yes').
 
 Example of SSH logging:
 
@@ -989,10 +993,14 @@ Example of SSH logging:
     "client": {
         "proto_version": "2.0",
         "software_version": "OpenSSH_6.7",
+        "hassh": "ec7378c1a92f5a8dde7e8b7a1ddf33d1",
+        "hassh.string": "curve25519-sha256,diffie-hellman-group14-sha256,diffie-hellman-group14-sha1,ext-info-c",
      },
     "server": {
         "proto_version": "2.0",
         "software_version": "OpenSSH_6.7",
+        "hassh": "ec7378c1a92f5a8dde7e8b7a1ddf33d1",
+        "hassh.string": "curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp256",
      }
   }
 
diff --git a/doc/userguide/rules/ssh-keywords.rst b/doc/userguide/rules/ssh-keywords.rst
index 543bd2817c..526aa06d7b 100644
--- a/doc/userguide/rules/ssh-keywords.rst
+++ b/doc/userguide/rules/ssh-keywords.rst
@@ -85,3 +85,65 @@ Example:
   alert ssh any any -> any any (msg:"match SSH software string"; :example-rule-emphasis:`ssh.softwareversion:"OpenSSH";` sid:10000040;)
 
 
+Suricata comes with a Hassh integration (https://github.com/salesforce/hassh). Hassh is used to fingerprint ssh clients and servers.
+
+Hassh must be enabled in the Suricata config file (set 'app-layer.protocols.ssh.hassh' to 'yes').
+
+ssh.hassh
+---------
+
+Match on hassh (md5 of of hassh algorithms of client).
+
+Example::
+
+  alert ssh any any -> any any (msg:"match hassh"; \
+      ssh.hassh; content:"ec7378c1a92f5a8dde7e8b7a1ddf33d1";\
+      sid:1000010;)
+      
+``ssh.hassh`` is a 'sticky buffer'.
+
+``ssh.hassh`` can be used as ``fast_pattern``.
+
+ssh.hassh.string
+----------------
+
+Match on Hassh string (hassh algorithms of client).
+
+Example::
+
+  alert ssh any any -> any any (msg:"match hassh-string"; \
+      ssh.hassh.string; content:"none,zlib@openssh.com,zlib"; \
+      sid:1000030;
+
+``ssh.hassh.string`` is a 'sticky buffer'.
+
+``ssh.hassh.string`` can be used as ``fast_pattern``.
+
+ssh.hassh.server
+----------------
+
+Match on hassh (md5 of hassh algorithms of server).
+
+Example::
+
+  alert ssh any any -> any any (msg:"match SSH hash-server"; \
+      ssh.hassh.server; content:"b12d2871a1189eff20364cf5333619ee"; \
+      sid:1000020;)
+
+``ssh.hassh.server`` is a 'sticky buffer'.
+
+``ssh.hassh.server`` can be used as ``fast_pattern``.
+
+ssh.hassh.server.string
+-----------------------
+
+Match on hassh string (hassh algorithms of server).
+
+Example::
+  alert ssh any any -> any any (msg:"match SSH hash-server-string"; \
+      ssh.hassh.server.string; content:"umac-64-etm@openssh.com,umac-128-etm@openssh.com"; \
+      sid:1000040;)
+
+``ssh.hassh.server.string`` is a 'sticky buffer'.
+
+``ssh.hassh.server.string`` can be used as ``fast_pattern``.
diff --git a/suricata.yaml.in b/suricata.yaml.in
index df67380d62..d29aa77d38 100644
--- a/suricata.yaml.in
+++ b/suricata.yaml.in
@@ -743,6 +743,7 @@ app-layer:
       #enabled: yes
     ssh:
       enabled: yes
+      #hassh: yes
     smtp:
       enabled: yes
       raw-extraction: no