next/178/20231117/v1

.github/workflows/authors-done.yml

@@ -44,8 +44,7 @@ jobs:
           script: |
             let fs = require('fs');
             let issue_number = Number(fs.readFileSync('./pr-number.txt'));
-            let new_authors = String(fs.readFileSync('./new-authors.txt'));
-            let msg = 'NOTE: This PR may contain new authors:\n\n```\n' + new_authors + '```';
+            let msg = 'NOTE: This PR may contain new authors.';
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,

.github/workflows/builds.yml

@@ -12,6 +12,10 @@ on:
       SV_REPO:
       SV_BRANCH:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions: read-all
 
 env:
@@ -284,6 +288,18 @@ jobs:
           test -e /usr/local/lib/suricata/python/suricata/update/configs/modify.conf
           test -e /usr/local/lib/suricata/python/suricata/update/configs/threshold.in
           test -e /usr/local/lib/suricata/python/suricata/update/configs/update.yaml
+      - name: Build C json filetype plugin
+        working-directory: examples/plugins/c-json-filetype
+        run: make
+      - name: Check C json filetype plugin
+        run: test -e examples/plugins/c-json-filetype/.libs/json-filetype.so.0.0.0
+      - name: Installing headers and library
+        run: |
+          make install-headers
+          make install-library
+      - name: Test plugin build with Makefile.example
+        working-directory: examples/plugins/c-json-filetype
+        run: PATH=/usr/local/bin:$PATH make -f Makefile.example
 
   almalinux-9-templates:
     name: AlmaLinux 9 Test Templates

Makefile.am

@@ -10,6 +10,7 @@ EXTRA_DIST = ChangeLog COPYING LICENSE suricata.yaml.in \
 	     scripts/generate-images.sh
 SUBDIRS = $(HTP_DIR) rust src qa rules doc contrib etc python ebpf \
           $(SURICATA_UPDATE_DIR)
+DIST_SUBDIRS = examples/plugins/c-json-filetype $(SUBDIRS)
 
 CLEANFILES = stamp-h[0-9]*
 

configure.ac

@@ -2613,6 +2613,8 @@ AC_CONFIG_FILES(suricata.yaml etc/Makefile etc/suricata.logrotate etc/suricata.s
 AC_CONFIG_FILES(python/Makefile python/suricata/config/defaults.py)
 AC_CONFIG_FILES(ebpf/Makefile)
 AC_CONFIG_FILES(libsuricata-config)
+AC_CONFIG_FILES(examples/plugins/c-json-filetype/Makefile)
+
 AC_OUTPUT
 
 SURICATA_BUILD_CONF="Suricata Configuration:

doc/userguide/output/eve/eve-json-format.rst

@@ -735,8 +735,8 @@ If extended logging is enabled the following fields are also included:
 * "fingerprint": The (SHA1) fingerprint of the TLS certificate
 * "sni": The Server Name Indication (SNI) extension sent by the client
 * "version": The SSL/TLS version used
-* "not_before": The NotBefore field from the TLS certificate
-* "not_after": The NotAfter field from the TLS certificate
+* "notbefore": The NotBefore field from the TLS certificate
+* "notafter": 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
 

doc/userguide/rules/mqtt-keywords.rst

@@ -163,6 +163,19 @@ Examples::
 ``mqtt.connect.password`` is a 'sticky buffer' and can be used as ``fast_pattern``.
 
 
+mqtt.connect.protocol_string
+----------------------------
+
+Match on the protocol string in the MQTT CONNECT message. In contrast to ``mqtt.protocol_version`` this is a property that is only really relevant in the initial CONNECT communication and never used again; hence it is organized under ``mqtt.connect``.
+
+Examples::
+
+  mqtt.connect.protocol_string; content:"MQTT";
+  mqtt.connect.protocol_string; content:"MQIsdp";
+
+``mqtt.connect.protocol_string`` is a 'sticky buffer' and can be used as ``fast_pattern``.
+
+
 mqtt.connect.username
 ---------------------
 

examples/plugins/README.md

@@ -0,0 +1,6 @@
+# Example Plugins
+
+## c-json-filetype
+
+An example plugin of an EVE/JSON filetype plugin. This type of plugin
+is useful if you want to send EVE output to custom destinations.

examples/plugins/c-json-filetype/.gitignore

@@ -0,0 +1,2 @@
+*.so
+*.la

examples/plugins/c-json-filetype/Makefile.am

@@ -0,0 +1,17 @@
+plugindir = ${libdir}/suricata/plugins
+
+if BUILD_SHARED_LIBRARY
+plugin_LTLIBRARIES = json-filetype.la
+json_filetype_la_LDFLAGS = -module -shared
+json_filetype_la_SOURCES = filetype.c
+
+json_filetype_la_CPPFLAGS = -I$(abs_top_srcdir)/rust/gen -I$(abs_top_srcdir)/rust/dist
+
+else
+
+all-local:
+	@echo
+	@echo "Shared library support must be enabled to build plugins."
+	@echo
+
+endif

examples/plugins/c-json-filetype/Makefile.example

@@ -0,0 +1,18 @@
+SRCS :=		filetype.c
+
+LIBSURICATA_CONFIG ?= libsuricata-config
+
+CPPFLAGS +=	`$(LIBSURICATA_CONFIG) --cflags`
+CPPFLAGS +=	-DSURICATA_PLUGIN -I.
+CPPFLAGS +=	"-D__SCFILENAME__=\"$(*F)\""
+
+OBJS :=		$(SRCS:.c=.o)
+
+filetype.so: $(OBJS)
+	$(CC) -fPIC -shared -o $@ $(OBJS)
+
+%.o: %.c
+	$(CC) -fPIC $(CPPFLAGS) -c -o $@ $<
+
+clean:
+	rm -f *.o *.so *~

examples/plugins/c-json-filetype/README.md

@@ -0,0 +1,123 @@
+# Example EVE Filetype Plugin
+
+## Building
+
+If in the Suricata source directory, this plugin can be built by
+running `make` and installed with `make install`.
+
+Note that Suricata must have been built without `--disable-shared`.
+
+## Building Standalone
+
+The file `Makefile.example` is an example of how you might build a
+plugin that is distributed separately from the Suricata source code.
+
+It has the following dependencies:
+
+- Suricata is installed
+- The Suricata library is installed: `make install-library`
+- The Suricata development headers are installed: `make install-headers`
+- The program `libsuricata-config` is in your path (installed with
+  `make install-library`)
+
+The run: `make -f Makefile.example`
+
+Before building this plugin you will need to build and install Suricata from the
+git master branch and install the development tools and headers:
+
+- `make install-library`
+- `make install-headers`
+
+then make sure the newly installed tool `libsuricata-config` can be
+found in your path, for example:
+```
+libsuricata-config --cflags
+```
+
+Then a simple `make` should build this plugin.
+
+Or if the Suricata installation is not in the path, a command like the following
+can be used:
+
+```
+PATH=/opt/suricata/bin:$PATH make
+```
+
+## Usage
+
+To run the plugin, first add the path to the plugin you just compiled to
+your `suricata.yaml`, for example:
+```
+plugins:
+  - /usr/lib/suricata/plugins/json-filetype.so
+```
+
+Then add an output for the plugin:
+```
+outputs:
+  - eve-log:
+      enabled: yes
+      filetype: json-filetype-plugin
+      threaded: true
+      types:
+        - dns
+        - tls
+        - http
+```
+
+In the example above we use the name specified in the plugin as the `filetype`
+and specify that all `dns`, `tls` and `http` log entries should be sent to the
+plugin.
+
+## Details
+
+This plugin demonstrates a Suricata JSON/EVE output plugin
+(file-type). The idea of a Suricata EVE output plugin is to provide a
+file like interface for the handling of rendered JSON logs. This is
+useful for custom destinations not builtin to Suricata or if the
+formatted JSON requires some post-processing.
+
+Note: EVE output plugins are not that useful just for reformatting the
+JSON output as the plugin does need to handle writing to a file once
+the file type has been delegated to the plugin.
+
+### Registering a Plugin
+
+All Suricata plugins make themselves known to Suricata by using a
+function named `SCPluginRegister` which is called after Suricata loads
+the plugin shared object file. This function must return a `SCPlugin`
+struct which contains basic information about the plugin.  For
+example:
+
+```c
+const SCPlugin PluginRegistration = {
+    .name = "eve-filetype",
+    .author = "Jason Ish",
+    .license = "GPLv2",
+    .Init = TemplateInit,
+};
+
+const SCPlugin *SCPluginRegister() {
+    return &PluginRegistration;
+}
+```
+
+### Initializing a Plugin
+
+After the plugin has been registered, the `Init` callback will be called. This
+is where the plugin will set itself up as a specific type of plugin such as an
+EVE output, or a capture method.
+
+This plugins registers itself as an EVE file type using the
+`SCRegisterEveFileType` struct. To register as an EVE file type the
+following must be provided:
+
+* name: This is the name of the output which will be used in the eve filetype
+  field in `suricata.yaml` to enable this output.
+* Init: The callback called when the output is "opened".
+* Deinit: The callback called the output is "closed".
+* ThreadInit: Callback called to initialize per thread data (if threaded).
+* ThreadDeinit: Callback called to deinitialize per thread data (if threaded).
+* Write: The callback called when an EVE record is to be "written".
+
+Please see the code in `filetype.c` for more details about this functions.