rust: implement JA4 fingerprints for TLS and QUIC

Ticket: #6379
OISF · Oct 16, 2023 · 6920b87 · 6920b87
1 parent 1a132f4
commit 6920b87
Show file tree

Hide file tree

Showing 26 changed files with 997 additions and 49 deletions.
diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
@@ -739,8 +739,9 @@ If extended logging is enabled the following fields are also included:
 * "not_after": The NotAfter field from the TLS certificate
 * "ja3": The JA3 fingerprint consisting of both a JA3 hash and a JA3 string
 * "ja3s": The JA3S fingerprint consisting of both a JA3 hash and a JA3 string
+* "ja4": The JA4 client fingerprint for TLS
 
-JA3 must be enabled in the Suricata config file (set 'app-layer.protocols.tls.ja3-fingerprints' to 'yes').
+JA3 and JA4 must be enabled in the Suricata config file (set 'app-layer.protocols.tls.ja3-fingerprints'/'app-layer.protocols.tls.ja4-fingerprints' to 'yes').
 
 In addition to this, custom logging also allows the following fields:
 
@@ -2483,11 +2484,14 @@ Fields
 * "cyu": List of found CYUs in the packet
 * "cyu[].hash": CYU hash
 * "cyu[].string": CYU string
+* "ja3": The JA3 fingerprint consisting of both a JA3 hash and a JA3 string
+* "ja3s": The JA3S fingerprint consisting of both a JA3 hash and a JA3 string
+* "ja4": The JA4 client fingerprint for QUIC
 
 Examples
 ~~~~~~~~
 
-Example of QUIC logging with a CYU hash:
+Example of QUIC logging with CYU, JA3 and JA4 hashes (note that the JA4 hash is only an example to illustrate the format and does not correlate with the others):
 
 ::
 
@@ -2499,7 +2503,12 @@ Example of QUIC logging with a CYU hash:
             "hash": "7b3ceb1adc974ad360cfa634e8d0a730",
             "string": "46,PAD-SNI-STK-SNO-VER-CCS-NONC-AEAD-UAID-SCID-TCID-PDMD-SMHL-ICSL-NONP-PUBS-MIDS-SCLS-KEXS-XLCT-CSCT-COPT-CCRT-IRTT-CFCW-SFCW"
         }
-    ]
+    ],
+    "ja3": {
+        "hash": "324f8c50e267adba4b5dd06c964faf67",
+        "string": "771,4865-4866-4867,51-43-13-27-17513-16-45-0-10-57,29-23-24,"
+    },
+    "ja4": "q13d0310h3_55b375c5d22e_cd85d2d88918"
   }
 
 Event type: DHCP

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
@@ -257,7 +257,7 @@ YAML::
             extended: yes     # enable this for extended logging information
             # custom allows to control which tls fields that are included
             # in eve-log
-            #custom: [subject, issuer, serial, fingerprint, sni, version, not_before, not_after, certificate, chain, ja3, ja3s]
+            #custom: [subject, issuer, serial, fingerprint, sni, version, not_before, not_after, certificate, chain, ja3, ja3s, ja4]
 
 The default is to log certificate subject and issuer. If ``extended`` is
 enabled, then the log gets more verbose.

diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
@@ -17,6 +17,7 @@ Suricata Rules
    tls-keywords
    ssh-keywords
    ja3-keywords
+   ja4-keywords
    modbus-keyword
    dcerpc-keywords
    dhcp-keywords
@@ -42,4 +43,4 @@ Suricata Rules
    datasets
    lua-detection
    differences-from-snort
-   multi-buffer-matching
+   multi-buffer-matching
diff --git a/doc/userguide/rules/ja4-keywords.rst b/doc/userguide/rules/ja4-keywords.rst
@@ -0,0 +1,29 @@
+JA4 Keywords
+============
+
+Suricata comes with a JA4 integration (https://github.com/FoxIO-LLC/ja4). JA4,
+as part of the larger JA4+ suite of fingerprints, is used to fingerprint TLS
+clients.
+
+We might in the future consider adding raw and original order strings (JA4_r,
+JA4_o, JA4_ro) as non-hashed versions.
+
+JA4 support must be enabled in the Suricata config file (set
+``app-layer.protocols.tls.ja4-fingerprints`` to ``yes``). If it is not
+explicitly disabled (``no``) , it will enabled if a loaded rule requires it.
+
+ja4.hash
+--------
+
+Match on JA4 hash (e.g. ``q13d0310h3_55b375c5d22e_cd85d2d88918``).
+
+Example::
+
+  alert quic any any -> any any (msg:"match JA4 hash"; \
+      ja4.hash; content:"q13d0310h3_55b375c5d22e_cd85d2d88918"; \
+      sid:100001;)
+
+``ja4.hash`` is a 'sticky buffer'.
+
+``ja4.hash`` can be used as ``fast_pattern``.
+
diff --git a/etc/schema.json b/etc/schema.json
@@ -3035,6 +3035,9 @@
                     },
                     "additionalProperties": false
                 },
+                "ja4": {
+                    "type": "string"
+                },
                 "sni": {
                     "type": "string"
                 },
@@ -5419,6 +5422,9 @@
                         }
                     },
                     "additionalProperties": false
+                },
+                "ja4": {
+                    "type": "string"
                 }
             },
             "additionalProperties": false