Skip to content

Commit

Permalink
Output/TLS: Allow logging of client/server handshake parameters
Browse files Browse the repository at this point in the history
Add new custom log fields:
- "client_handshake" which logs the following:
1. TLS version used during handshake
2. TLS extensions, excluding GREASE, SNI and ALPN
3. All cipher suites, excluding GREASE
4. All signature algorithms, excluding GREASE

- "server_handshake" which logs the following:
1. TLS version used during handshake
2. The chosen cipher suite, excluding GREASE
3. TLS extensions, excluding GREASE

The use-case is for logging TLS handshake parameters in order to survey
them, and so that JA4(S) hashes can be computed offline (in the case that
they're not already computed for the purposes of rule matching).
  • Loading branch information
gtedesco-r7 authored and rmcconnell-r7 committed Jan 29, 2025
1 parent cfbf8fd commit c2df226
Show file tree
Hide file tree
Showing 7 changed files with 333 additions and 73 deletions.
5 changes: 5 additions & 0 deletions doc/userguide/output/eve/eve-json-format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1040,6 +1040,11 @@ If extended logging is enabled the following fields are also included:
* "ja4": The JA4 client fingerprint for TLS
* "client_alpns": array of strings with ALPN values
* "server_alpns": array of strings with ALPN values
* "client_handshake": structure containing "version", "ciphers", "exts", "sig_algs", for client
hello supported cipher suites, extensions, and signature algorithms,
respectively, in the order that they're mentioned (ie. unsorted)
* "server_handshake": structure containing "version", "chosen cipher", "exts", for server hello
in the order that they're mentioned (ie. unsorted)

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').

Expand Down
51 changes: 51 additions & 0 deletions etc/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -6722,13 +6722,61 @@
"type": "string"
}
},
"client_handshake": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"ciphers": {
"description": "TLS client cipher(s)",
"type": "array",
"items": {
"type": "integer"
}
},
"exts": {
"description": "TLS client extension(s)",
"type": "array",
"items": {
"type": "integer"
}
},
"sig_algs": {
"description": "TLS client signature algorithm(s)",
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"server_alpns": {
"description": "TLS server ALPN field(s)",
"type": "array",
"items": {
"type": "string"
}
},
"server_handshake": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"cipher": {
"description": "TLS server's chosen cipher",
"type": "integer"
},
"exts": {
"description": "TLS server extension(s)",
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"fingerprint": {
"type": "string"
},
Expand Down Expand Up @@ -6792,6 +6840,9 @@
},
"ja4": {
"type": "string"
},
"ja4s": {
"type": "string"
}
},
"additionalProperties": false
Expand Down
Loading

0 comments on commit c2df226

Please sign in to comment.