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

@@ -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
 -----
 

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",
      }
   }
 

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``.

suricata.yaml.in

@@ -743,6 +743,7 @@ app-layer:
       #enabled: yes
     ssh:
       enabled: yes
+      #hassh: yes
     smtp:
       enabled: yes
       raw-extraction: no