From: Jeff Lucovsky Date: Wed, 5 Jun 2024 13:06:39 +0000 (-0400) Subject: output/ja4: Log ja4 hashes iff configured X-Git-Tag: suricata-7.0.6~20 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11288%2Fhead;p=thirdparty%2Fsuricata.git output/ja4: Log ja4 hashes iff configured This commit allows ja4 hashes to be logged iff enabled in the tls/quic section of the outputs. With the default setting ("off"), ja4 hashes will only be logged in alerts when the signatures uses the ja4.hash keyword. When enabled, ja4 hashes will be inclued in quic and tls logs. - tls: ja4: on - quic: ja4: on Issue: 7010 --- diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml index 96522571e0..4c8e4f6704 100644 --- a/doc/userguide/partials/eve-log.yaml +++ b/doc/userguide/partials/eve-log.yaml @@ -133,6 +133,9 @@ outputs: # output TLS transaction where the session is resumed using a # session id #session-resumption: no + # ja4 hashes in tls records will never be logged unless + # the following is set to on. (Default off) + # ja4: off # custom allows to control which tls fields that are included # in eve-log #custom: [subject, issuer, session_resumed, serial, fingerprint, sni, version, not_before, not_after, certificate, chain] @@ -164,6 +167,10 @@ outputs: - ike # BitTorrent DHT logging. - bittorrent-dht + - quic: + # ja4 hashes in crecords will never be logged unless + # the following is set to on. (Default off) + # ja4: off - ssh - stats: totals: yes # stats for all threads merged together diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst index 991e55ae75..d7b74a0275 100644 --- a/doc/userguide/upgrade.rst +++ b/doc/userguide/upgrade.rst @@ -59,6 +59,8 @@ Security changes ` and :ref:`Datasets File Locations ` for more information. - Lua rules are now disabled by default (change also introduced in 6.0.13), see :ref:`lua-detection`. +- Support for JA4 has been added. JA4 hashes will be computed when explicitly enabled or a rule uses + `ja4.hash`. JA4 hashes are output under a restricted set of conditions (see below): Removals ~~~~~~~~ @@ -133,6 +135,12 @@ Logging changes For more information, refer to: https://redmine.openinfosecfoundation.org/issues/1275. +- JA4 hashes are output under a restricted set of conditions when JA4 is dynamically or explicitly enabled: + + - Alerts: The signature causing the alert contains the `ja4.hash` keyword + - Logs: With QUIC logs iff outputs.quic.ja4 is enabled (default off) + - Logs: With TLS logs iff outputs.tls.ja4 is enabled (default off) + Deprecations ~~~~~~~~~~~~ - Multiple "include" fields in the configuration file will now issue a diff --git a/src/output-json-quic.c b/src/output-json-quic.c index 4970c31def..3934f1895d 100644 --- a/src/output-json-quic.c +++ b/src/output-json-quic.c @@ -35,6 +35,7 @@ #include "output.h" #include "output-json.h" #include "app-layer.h" +#include "app-layer-ssl.h" #include "app-layer-parser.h" #include "output-json-quic.h" #include "rust.h" @@ -42,6 +43,7 @@ typedef struct LogQuicFileCtx_ { LogFileCtx *file_ctx; OutputJsonCtx *eve_ctx; + bool log_ja4; } LogQuicFileCtx; typedef struct JsonQuicLogThread_ { @@ -59,7 +61,9 @@ static int JsonQuicLogger(ThreadVars *tv, void *thread_data, const Packet *p, Fl if (unlikely(js == NULL)) { return TM_ECODE_OK; } - if (!rs_quic_to_json(tx, false, js)) { + + LogQuicFileCtx *quic_ctx = thread->quiclog_ctx; + if (!rs_quic_to_json(tx, quic_ctx->log_ja4, js)) { jb_free(js); return TM_ECODE_FAILED; } @@ -93,6 +97,13 @@ static OutputInitResult OutputQuicLogInitSub(ConfNode *conf, OutputCtx *parent_c SCFree(quiclog_ctx); return result; } + + /* In 7.0.x, ja4 hash is only logged when requested */ + quiclog_ctx->log_ja4 = false; + const char *ja4 = ConfNodeLookupChildValue(conf, "ja4"); + if (ja4 && ConfValIsTrue(ja4)) { + quiclog_ctx->log_ja4 = true; + } output_ctx->data = quiclog_ctx; output_ctx->DeInit = OutputQuicLogDeInitCtxSub; diff --git a/src/output-json-tls.c b/src/output-json-tls.c index 4f5d07d49c..88d6bdbda0 100644 --- a/src/output-json-tls.c +++ b/src/output-json-tls.c @@ -479,11 +479,14 @@ static int JsonTlsLogger(ThreadVars *tv, void *thread_data, const Packet *p, } /* log extended */ else if (tls_ctx->flags & LOG_TLS_EXTENDED) { - JsonTlsLogJSONExtended(js, ssl_state, false); + JsonTlsLogJSONExtended(js, ssl_state, tls_ctx->fields & LOG_TLS_FIELD_JA4); } /* log basic */ else { JsonTlsLogJSONBasic(js, ssl_state); + /* add ja4 hash */ + if (tls_ctx->fields & LOG_TLS_FIELD_JA4) + JsonTlsLogSCJA4(js, ssl_state); } /* print original application level protocol when it have been changed @@ -586,6 +589,12 @@ static OutputTlsCtx *OutputTlsInitCtx(ConfNode *conf) } } + /* In 7.0.x, ja4 hash is only logged when requested */ + const char *ja4 = ConfNodeLookupChildValue(conf, "ja4"); + if (ja4 && ConfValIsTrue(ja4)) { + tls_ctx->fields = LOG_TLS_FIELD_JA4; + } + const char *session_resumption = ConfNodeLookupChildValue(conf, "session-resumption"); if (session_resumption == NULL || ConfValIsTrue(session_resumption)) { tls_ctx->flags |= LOG_TLS_SESSION_RESUMPTION; diff --git a/src/output-json-tls.h b/src/output-json-tls.h index 76a1190c21..4988abc6d4 100644 --- a/src/output-json-tls.h +++ b/src/output-json-tls.h @@ -29,6 +29,6 @@ void JsonTlsLogRegister(void); #include "app-layer-ssl.h" void JsonTlsLogJSONBasic(JsonBuilder *js, SSLState *ssl_state); -void JsonTlsLogJSONExtended(JsonBuilder *js, SSLState *ssl_state, bool is_alert); +void JsonTlsLogJSONExtended(JsonBuilder *js, SSLState *ssl_state, bool log_ja4); #endif /* __OUTPUT_JSON_TLS_H__ */ diff --git a/suricata.yaml.in b/suricata.yaml.in index 7c8d62a6cd..052eef93fd 100644 --- a/suricata.yaml.in +++ b/suricata.yaml.in @@ -251,6 +251,9 @@ outputs: # output TLS transaction where the session is resumed using a # session id #session-resumption: no + # ja4 hashes in tls records will never be logged unless + # the following is set to on. (Default off) + # ja4: off # custom controls which TLS fields that are included in eve-log #custom: [subject, issuer, session_resumed, serial, fingerprint, sni, version, not_before, not_after, certificate, chain, ja3, ja3s, ja4] - files: @@ -291,7 +294,10 @@ outputs: - snmp - rfb - sip - - quic + - quic: + # ja4 hashes in quic records will never be logged unless + # the following is set to on. (Default off) + # ja4: off - dhcp: enabled: yes # When extended mode is on, all DHCP messages are logged