From 006fe7aba7d2400a3c626adadfc92177aaa72181 Mon Sep 17 00:00:00 2001 From: "Priyanka Bangalore Gurudev (prbg)" Date: Thu, 5 Dec 2024 02:06:35 +0000 Subject: [PATCH] Pull request #4535: build: generate and tag 3.6.0.0 Merge in SNORT/snort3 from ~PRBG/snort3:build_3.6.0.0 to master Squashed commit of the following: commit 8e251139bb57e5f6edcfaeaa96a48d70a169b0a1 Author: Priyanka Gurudev Date: Tue Dec 3 21:44:27 2024 -0500 build: generate and tag 3.6.0.0 --- CMakeLists.txt | 4 +- ChangeLog.md | 15 ++ doc/reference/snort_reference.text | 48 +++++- doc/upgrade/snort_upgrade.text | 2 +- doc/user/snort_user.text | 241 ++++++++++++++++------------- 5 files changed, 193 insertions(+), 117 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 165dec395..a1d6371df 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,8 +2,8 @@ cmake_minimum_required (VERSION 3.4.3) project (snort CXX C) set (VERSION_MAJOR 3) -set (VERSION_MINOR 5) -set (VERSION_PATCH 2) +set (VERSION_MINOR 6) +set (VERSION_PATCH 0) set (VERSION_SUBLEVEL 0) set (VERSION "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}.${VERSION_SUBLEVEL}") diff --git a/ChangeLog.md b/ChangeLog.md index 63010d524..7e79e5082 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,18 @@ +2024-12-03: 3.6.0.0 + +* analyzer: add logging for resource tuning progress +* appid: adding full path to read list of lua detectors +* build: update docs about the bump of C++ compiler supported feature set requirement +* connectors: add std I/O connector and connector API update +* connectors: fix cppcheck warning in std_connector test +* extractor: update logger +* file_api: add unit tests for fileinfo methods +* flow: publish flow end event +* http_inspect, mime: add hostname and url for http with mime +* http_inspect: remove semicolon http_param delimiter +* ips_options: update module::begin method and reset 'relative' flag +* main: remove mutex from snort command to show snort cpu + 2024-11-18: 3.5.2.0 * decompress: handle ZIP central directory diff --git a/doc/reference/snort_reference.text b/doc/reference/snort_reference.text index e84be128e..fb200ad42 100644 --- a/doc/reference/snort_reference.text +++ b/doc/reference/snort_reference.text @@ -8,7 +8,7 @@ Snort 3 Reference Manual The Snort Team Revision History -Revision 3.5.2.0 2024-11-18 20:48:07 EST TST +Revision 3.6.0.0 2024-12-03 21:38:11 EST TST --------------------------------------------------------------------- @@ -85,7 +85,8 @@ Table of Contents 4. Connector Modules 4.1. file_connector - 4.2. tcp_connector + 4.2. std_connector + 4.3. tcp_connector 5. Inspector Modules @@ -2578,7 +2579,31 @@ Peg counts: * file_connector.messages: total messages (sum) -4.2. tcp_connector +4.2. std_connector + +-------------- + +Help: implement the stdout/stdin based connector + +Type: connector + +Usage: global + +Configuration: + + * string std_connector[].connector: connector name + * enum std_connector[].direction: usage { receive | transmit | + duplex } + +Peg counts: + + * std_connector.messages_received: total number of messages + received (sum) + * std_connector.messages_transmitted: total number of messages + transmitted (sum) + + +4.3. tcp_connector -------------- @@ -3562,8 +3587,7 @@ Configuration: * enum extractor.formatting = csv: output format for extractor { csv | json } - * enum extractor.output = stdout: output destination for extractor - { stdout } + * string extractor.connector: output destination for extractor * enum extractor.protocols[].service: service to extract from { http | ftp } * int extractor.protocols[].tenant_id = 0: tenant_id of target @@ -9827,10 +9851,9 @@ libraries see the Getting Started section of the manual. ordering incoming events { priority|content_length } * bool event_queue.process_all_events = false: process just first action group or all action groups + * string extractor.connector: output destination for extractor * enum extractor.formatting = csv: output format for extractor { csv | json } - * enum extractor.output = stdout: output destination for extractor - { stdout } * string extractor.protocols[].fields: specify fields to log * string extractor.protocols[].on_events: specify events to log * enum extractor.protocols[].service: service to extract from { @@ -11305,6 +11328,9 @@ libraries see the Getting Started section of the manual. * implied ssl_version.!tls1.2: check for records that are not tls1.2 * implied ssl_version.tls1.2: check for tls1.2 + * string std_connector[].connector: connector name + * enum std_connector[].direction: usage { receive | transmit | + duplex } * bool stream.allowlist_cache.enable = false: enable allowlist cache * int stream.file_cache.idle_timeout = 180: maximum inactive time @@ -12591,6 +12617,10 @@ libraries see the Getting Started section of the manual. * ssl.server_key_exchange: total server key exchanges (sum) * ssl.sessions_ignored: total sessions ignore (sum) * ssl.unrecognized_records: total unrecognized records (sum) + * std_connector.messages_received: total number of messages + received (sum) + * std_connector.messages_transmitted: total number of messages + transmitted (sum) * stream.allowlist_flows: number of flows moved to the allow list (now) * stream.allowlist_memcap_prunes: number of allowlist flows pruned @@ -16668,6 +16698,8 @@ and are not applicable elsewhere. * ssl (inspector): ssl inspection * ssl_state (ips_option): detection option for ssl state * ssl_version (ips_option): detection option for ssl version + * std_connector (connector): implement the stdout/stdin based + connector * stream (inspector): common flow tracking * stream_file (inspector): stream inspector for file flow tracking and processing @@ -16771,6 +16803,8 @@ and are not applicable elsewhere. * codec::wlan: support for wireless local area network protocol (DLT 105) * connector::file_connector: implement the file based connector + * connector::std_connector: implement the stdout/stdin based + connector * connector::tcp_connector: implement the tcp stream connector * inspector::appid: application and service identification * inspector::appid_listener: log selected published data to diff --git a/doc/upgrade/snort_upgrade.text b/doc/upgrade/snort_upgrade.text index bd143d3da..49c2cafb8 100644 --- a/doc/upgrade/snort_upgrade.text +++ b/doc/upgrade/snort_upgrade.text @@ -8,7 +8,7 @@ Snort 3 Upgrade Manual The Snort Team Revision History -Revision 3.5.2.0 2024-11-18 20:48:58 EST TST +Revision 3.6.0.0 2024-12-03 21:38:50 EST TST --------------------------------------------------------------------- diff --git a/doc/user/snort_user.text b/doc/user/snort_user.text index 20022fec1..fe09b9784 100644 --- a/doc/user/snort_user.text +++ b/doc/user/snort_user.text @@ -8,7 +8,7 @@ Snort 3 User Manual The Snort Team Revision History -Revision 3.5.2.0 2024-11-18 20:48:24 EST TST +Revision 3.6.0.0 2024-12-03 21:38:24 EST TST --------------------------------------------------------------------- @@ -1074,7 +1074,7 @@ to figure out more advanced usage. Required: - * a compiler that supports the C++14 feature set + * a compiler that supports the C++17 feature set * cmake to build from source * daq from https://github.com/snort3/libdaq for packet IO * dnet from https://github.com/dugsong/libdnet.git for network @@ -2622,6 +2622,128 @@ amount of bytes to be extracted from payload can be less than specified by user. This might happen when the buffer has fewer bytes (from the cursor position) than specified in the option. +5.4.6. Connectors + +Connectors are a set of modules that are used to exchange +message-oriented data among Snort threads and the external world. A +typical use-case is HA (High Availability) message exchange. +Connectors serve to decouple the message transport from the message +creation/consumption. Connectors expose a common API for several +forms of message transport. + +Connectors are a Snort plugin type. + +5.4.6.1. Connector (parent plugin class) + +Connectors may either be a simplex channel and perform unidirectional +communications. Or may be duplex and perform bidirectional +communications. The TcpConnector is duplex while the FileConnector is +simplex. + +All subtypes of Connector have a direction configuration element and +a connector element. The connector string is the key used to identify +the element for client module configuration. The direction element +may have a default value, for instance TcpConnector is duplex. + +Currently there are the following implementations of the Connector: + + * TcpConnector - Exchange messages over a tcp channel. + * FileConnector - Write messages to files and read messages from + files. + * StdConnector - Exchange messages over a standard input/output. + +5.4.6.2. TcpConnector + +TcpConnector is a subclass of Connector and implements a DUPLEX type +Connector, able to send and receive messages over a tcp session. + +TcpConnector adds a few session setup configuration elements: + + * setup = call or answer - call is used to have TcpConnector + initiate the connection. answer is used to have TcpConnector + accept incoming connections. + * address = - used for call setup to specify the partner + * ports = "port port …" - used to pick a port number for call and + answer modes. If the ports list contains more than one port, the + "per-thread" destination mode will be assumed. In this mode, each + thread will connect to a corresponding destination port by + selecting a port number from the list based on the instance_id. + +An example segment of TcpConnector configuration: + +tcp_connector = +{ + { + connector = 'tcp_1', + address = '127.0.0.1', + setup = 'call', + ports = "11000 11001 11002 11003", + }, +} + +5.4.6.3. FileConnector + +FileConnector implements a Connector that can either read from files +or write to files. FileConnector’s are simplex and must be configured +to be CONN_TRANSMIT or CONN_RECEIVE. + +FileConnector configuration adds two additional element: + + * name = string - used as part of the message file name + * text_format = bool - FileConnector works in binary mode by + default, the option switches it to text mode + +The configured name string is used to construct the actual names as +in: + + * file_connector_NAME_transmit and file_connector_NAME_receive + +All messages for one Snort invocation are read and written to one +file. + +In the case of a receive FileConnector, all messages are read from +the file prior to the start of packet processing. This allows the +messages to establish state information for all processed packets. + +An example segment of FileConnector configuration: + +file_connector = +{ + { + connector = 'file_tx_1', + direction = 'transmit', + text_format = true, + name = 'HA' + }, + { + connector = 'file_rx_1', + direction = 'receive', + text_format = true, + name = 'HA' + }, +} + +5.4.6.4. StdConnector + +StdConnector is an implementation of a Connector that has the +capability to read from the standard input and write to the standard +output. Its principal purpose is testing. + +All messages transmitted through the stdout are automatically +appended with a new line. Therefore, it is expected that each message +read from the stdin will also be separated by a newline. + +The std_connector module automatically sets-up three default +connectors on startup: + + * stdout: the default transmit connector + * stdin: the default receive connector + * stdio: the default duplex connector. + +An example segment of a duplex StdConnector configuration: + +std_connector = { { connector = std_in_out, direction = duplex } } + 5.5. Consolidated Config @@ -3519,107 +3641,7 @@ message content. The stream HA content is always present in the messages while the ancillary module content is only present when requested via a status change request. -5.8.2. Connector - -Connectors are a set of modules that are used to exchange -message-oriented data among Snort threads and the external world. A -typical use-case is HA (High Availability) message exchange. -Connectors serve to decouple the message transport from the message -creation/consumption. Connectors expose a common API for several -forms of message transport. - -Connectors are a Snort plugin type. - -5.8.2.1. Connector (parent plugin class) - -Connectors may either be a simplex channel and perform unidirectional -communications. Or may be duplex and perform bidirectional -communications. The TcpConnector is duplex while the FileConnector is -simplex. - -All subtypes of Connector have a direction configuration element and -a connector element. The connector string is the key used to identify -the element for client module configuration. The direction element -may have a default value, for instance TcpConnector is duplex. - -There are currently two implementations of Connectors: - - * TcpConnector - Exchange messages over a tcp channel. - * FileConnector - Write messages to files and read messages from - files. - -5.8.2.2. TcpConnector - -TcpConnector is a subclass of Connector and implements a DUPLEX type -Connector, able to send and receive messages over a tcp session. - -TcpConnector adds a few session setup configuration elements: - - * setup = call or answer - call is used to have TcpConnector - initiate the connection. answer is used to have TcpConnector - accept incoming connections. - * address = - used for call setup to specify the partner - * ports = "port port …" - used to pick a port number for call and - answer modes. If the ports list contains more than one port, the - "per-thread" destination mode will be assumed. In this mode, each - thread will connect to a corresponding destination port by - selecting a port number from the list based on the instance_id. - -An example segment of TcpConnector configuration: - -tcp_connector = -{ - { - connector = 'tcp_1', - address = '127.0.0.1', - setup = 'call', - ports = "11000 11001 11002 11003", - }, -} - -5.8.2.3. FileConnector - -FileConnector implements a Connector that can either read from files -or write to files. FileConnector’s are simplex and must be configured -to be CONN_TRANSMIT or CONN_RECEIVE. - -FileConnector configuration adds two additional element: - - * name = string - used as part of the message file name - * text_format = bool - FileConnector works in binary mode by - default, the option switches it to text mode - -The configured name string is used to construct the actual names as -in: - - * file_connector_NAME_transmit and file_connector_NAME_receive - -All messages for one Snort invocation are read and written to one -file. - -In the case of a receive FileConnector, all messages are read from -the file prior to the start of packet processing. This allows the -messages to establish state information for all processed packets. - -An example segment of FileConnector configuration: - -file_connector = -{ - { - connector = 'file_tx_1', - direction = 'transmit', - text_format = true, - name = 'HA' - }, - { - connector = 'file_rx_1', - direction = 'receive', - text_format = true, - name = 'HA' - }, -} - -5.8.3. Side Channel +5.8.2. Side Channel SideChannel is a Snort module that uses Connectors to implement a messaging infrastructure that is used to communicate between Snort @@ -5796,7 +5818,8 @@ The module’s configuration consists of two parts: * global parameters + formatting - log record format - + output - where to write logs + + connector - Connector object through which logs will be sent. + See Connectors page for more details. * protocol-targeted parameters bind the targeted service and events with filters and a set of fields to log @@ -5814,7 +5837,7 @@ configurations. extractor = { formatting = 'csv', - output = 'stdout', + connector = 'stdout', protocols = { @@ -5884,10 +5907,12 @@ in CSV format. FTP sessions with basic fields: +std_connector = { } + extractor = { formatting = csv', - output = 'stdout', + connector = 'stdout', protocols = { {service = 'ftp', on_events = 'eot', fields = 'ts, command, user'} @@ -5906,10 +5931,12 @@ Output: Or FTP requests with the same set of fields: +std_connector = { } + extractor = { formatting = 'csv', - output = 'stdout', + connector = 'stdout', protocols = { {service = 'ftp', on_events = 'request', fields = 'ts, command, user'} -- 2.47.3