doc: update configuration with flow rate-tracking

Feature 5647

util: add initial flow rate tracking implementation

In order to track flow rate and thus determine a course of action or
categorize it as elephant flow, track a flow's byte count per direction
in a ring buffer for a given time interval.

The implementation is simple and keeps overwriting the buffer and
updating the final sum. The sum of all the elements in the ring buffer
at any point in time should reflect the number of bytes for the
respective flow in the last of a given configured interval.
e.g. if the definition says that the flows must be tracked by a rate of
100k bytes in 10 seconds, the ring buffer at any point in time should
carry the total number of bytes seen by the respective flow in the last
10 seconds.

So far, the implementation only supports reading the flow rate
definition from suricata.yaml and using it to track the flows.

This solution adds up a space complexity to the existing Flow struct.
However, the added space complexity should only take effect if the
feature is in use. Since this buffer extends the Flow struct, it does
not impact the usual business logic or complexity of the code.

This implementation is currently limited to defining the time interval
of flow rate in seconds only. However, the number of seconds defined are
directly proportional to the aforementioned added space complexity as
that's the size of the ring buffer.

Feature 5647

jsonbuilder: prefix C API with SC

detect: add email.x_mailer keyword

email.x_mailer matches on MIME EMAIL X-Mailer
This keyword maps to the EVE field email.x_mailer
It is a sticky buffer
Supports prefiltering

Ticket: #7598

detect: add email.message_id keyword

email.message_id matches on MIME EMAIL Message-Id
This keyword maps to the EVE field email.message_id
It is a sticky buffer
Supports prefiltering

Ticket: #7593

mime/email: remove unnecessary logs

fields 'date' and 'subject' are logged by enabling extended logging mode

detect/flowbits: implement prefilter support

Allow for more efficient rules that 'prefilter' on flowbits with 'isset' logic.

This prefilter is enabled by default, which means that if no mpm is present or
no explicit prefilter is used, the flowbits prefilter will be set up for a rule.

flowbits 'isset' prefilter

For rules that have a 'flowbits:isset,<bit>' statement, a "regular" prefilter
facility is created. It means that the rules are removed from the normal
match list(s) and added to a prefilter engine that runs prior to the individual
rule inspection stage.

Implementation: the prefilter is implemented as an RB_TREE of flowbits, with the
rule id's they "enable" stored per tree node. The matching logic is walking the
list of bits set in the flow and looking each of them up in the RB_TREE, adding
the rule ids of each of the matching bits to the list of rule candidates.

The 'isset' prefilter has one important corner case, which is that bits can in
fact be set during the rule evaluation stage. This is different from all other
prefilter engines, that evaluate an immutable state (for the lifetime of the
packet inspection).

flowbits 'set' post-match prefilter

For flowbits 'set' action, special post-match 'prefilter' facilities deal with
this corner case. The high level logic is that these track which 'isset' sigs
depend on them, and add these dependencies to the candidates list when a 'set'
action occurs.

This is implemented in a few steps:

1. flowbits 'set' is flagged
2. when 'set' action occurs the flowbit is added to a "post rule
   match work queue"
3. when the rule evaluation ends, the post-match "prefilter" engine is run
   on each of the flowbits in the "post rule match work queue"
4. these engines ammend the candidates list with the rule id dependencies
   for the flowbit
5. the candidates list is sorted to make sure within the execution for that
   packet the inspection order is maintained

Ticket: #2486.

detect/prefilter: add post-match 'prefilter' engine

Add support for special post-match engines. This allows a rule to enable
other rules when it matches.

Implementation is similar to prefilter engines, however prefilter
engines run before individual rules while this post-match engine runs
after and individual rule match. It will then add the new rules to the
existing rule list.

detect/prefilter: fix pointer check

flowbits: allow setter to know if set is new

flowbits: toggle returns state of the bit

detect: generic callback for md5-like keywords

Ticket: 5634

detect: use buffer ptr in validate callback api

Ticket: 5634

Allows to share the same validator functions when only the buffer
id is changing like for urilen, while still accessing the buffer
name for error logs

detect/sdp: minor style fixup

doc: add sdp sticky buffers

sdp: add sdp.media.encryption_key sticky buffer

This adds a sticky (multi) buffer to match the "Encryption key" subfield
of the "Media description" field in both requests and responses.

Ticket #7291

sdp: add sdp.media.connection_data sticky buffer

This adds a sticky (multi) buffer to match the "Connection data"
subfield of the "Media description" field in both requests and
responses.

Ticket #7291

sdp: add sdp.media.media_info sticky buffer

This adds a stick (multi) buffer to match the "Session information"
subfield of the "Media description" field in both requests and
responses.

Ticket #7291

sdp: add sdp.media.media sticky buffer

This adds a sticky (multi) buffer to match the "Media" subfield of the
"Media description" field in both requests and responses.

Ticket #7291

sdp: add sdp.attribute sticky buffer

This adds a sticky (multi) buffer to match the "Attribute" field in both
requests and responses.

Ticket #7291

sdp: add sdp.encryption_key sticky buffer

This adds a sticky buffer to match the "Encryption key" field in both
requests and responses.

Ticket #7291

sdp: add sdp.timezone sticky buffer

This adds a sticky bufffer to match the "Timezone" field in both
requests and responses.

Ticket #7291

sdp: add sdp.repeat_time sticky buffer

This adds a sticky buffer to match the "Repeat time" field in both
requests and responses.

Ticket #7291

sdp: add sdp.time sticky buffer

This adds a sticky buffer to match the "Time" field in both requests and
responses.

Ticket #7291

sdp: add sdp.bandwidth sticky buffer

This adds a sticky (multi) buffer to match the "Bandwidth" field in both
requests and responses.

Ticket #7291

sdp: add sdp.connection_data sticky buffer

This adds a sticky buffer to match the "Connection data" field in both
requests and responses.

Ticket #7291

sdp: add sdp.phone_number sticky buffer

This adds a sticky buffer to match the "Phone number" field in both
requests and responses.

Ticket #7291

sdp: add sdp.email sticky buffer

This adds a sticky buffer to match the "Email" field in both requests
and responses.

Ticket #7291

sdp: add sdp.uri sticky buffer

This adds a sticky buffer to match the "Uri" field in both requests and
responses.

Ticket #7291

sdp: add sdp.origin sticky buffer

This adds a sticky buffer to match the "Origin" field in both requests
and responses.

Ticket #7291

sdp: add sdp.session_info sticky buffer

This adds a sticky buffer to match the "Session information" field in
both requests and responses.

Ticket #7291

sdp: add sdp.session_name sticky buffer

This adds a sticky buffer to match the "Session name" field in both
requests and responses.

Ticket #7291

sdp: parse time and repeat_time multiple times

As defined in RFC4566, the time and repeat_time fields can be present
multiple times but they are currently parsed only once.

Ticket #7325

sdp: stringify structured fields

The current parser implementations take a field, such as connection data, and
split it into subfields for a specific structure (e.g., struct ConnectionData).
However, following this approach requires several sticky buffers to match the
whole field, which can make a rule a bit verbose and doesn't offer any advantage
for matching specific parts of a field.

With this patch, a single line is still split into pieces if it makes sense for
parsing purposes, but these pieces are then reassembled into a single string.
This way, only one sticky buffer is needed to match the entire field.

Ticket #7291

sdp: log media's encryption key

The encryption key subfield of the media description field is not
logged when it should be.

Ticket #7305

github-actions: bump actions/upload-artifact from 4.6.1 to 4.6.2

Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 4.6.1 to 4.6.2.
- [Release notes](https://github.com/actions/upload-artifact/releases)
- [Commits](https://github.com/actions/upload-artifact/compare/4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1...ea165f8d65b6e75b540449e92b4886f43607fa02)

---
updated-dependencies:
- dependency-name: actions/upload-artifact
  dependency-version: 4.6.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

github-actions: bump actions/download-artifact from 4.1.9 to 4.2.1

Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.1.9 to 4.2.1.
- [Release notes](https://github.com/actions/download-artifact/releases)
- [Commits](https://github.com/actions/download-artifact/compare/cc203385981b70ca67e1cc392babf9cc229d5806...95815c38cf2ff2164869cbab79da8d1f422bc89e)

---
updated-dependencies:
- dependency-name: actions/download-artifact
  dependency-version: 4.2.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

github-actions: bump github/codeql-action from 3.28.10 to 3.28.13

Bumps [github/codeql-action](https://github.com/github/codeql-action) from 3.28.10 to 3.28.13.
- [Release notes](https://github.com/github/codeql-action/releases)
- [Commits](https://github.com/github/codeql-action/compare/v3.28.10...v3.28.13)

---
updated-dependencies:
- dependency-name: github/codeql-action
  dependency-version: 3.28.13
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

detect: remove unneeded NULL check

As spotted by cppcheck

fd is set only once, and DetectFlowSetup bails early if it is NULL

Fixes: c272a646c5ae ("detect: SigMatchAppendSMToList can fail")

rust/conf: rust format

rust/conf: use generated bindings to SCConf API

conf: prefix conf API with SC

threads/lib: fix coverity check for unchecked return code

In thread startup, return error of TmThreadsWaitForUnpause() fails.
Fixed coverity check as in all other places the return value of this
function is checked and acted on.

rust/rdp: namespace and visibility cleanups

Ticket: #7498

rust/smb: namespace and visibility cleanups

Ticket: #7498

doc/entropy: Add documentation for the entropy keyword

This commits adds documentation for the entropy keyword.
The entropy keyword calculates the Shannon entropy value for content
with the calculated value used to determine whether an alert occurs.

detect/entropy: Use entropy matching when needed

This commit causes the content inspection engine to recognize and
invoke the entropy "match" function when the entropy keyword is used.

Issue: 4162

detect/entropy: Add entropy keyword

This commit adds keyword/build support for the entropy keyword. The
entropy keyword compares an entropy value with a value calculated
according to the Shannon entropy on the available content.

Issue: 4162

rust/detect: Add entropy support

This commit adds
- Parser for the entropy keyword
- Calculation of content the Shannon entropy value

Issue: 4162

The entropy keyword syntax is the keyword entropy followed by options
and the entropy value for comparison.

The minimum entropy keyword specification is:
entropy: value <entropy-spec>

This results in the calculated entropy value being compared with
<entropy-spec> with the equality operator.

Calculated entropy values are between 0.0 and 8.0, inclusive.

A match occurs when the values and operator agree. This example matches
if the calculated and entropy value are the same.

When entropy keyword options are specified, all options and "value" must
be comma-separated. Options and value may be specified in any order.

Options have default values:
- bytes is equal to the current content length
- offset is 0
- comparison with value is equality

entropy: [bytes <byteval>] [offset <offsetval>] value <entropy-spec>

Using default values:
entropy: bytes 0, offset 0, value =<entropy-spec>

<entropy-spec> is: <operator> (see below) and a value, e.g., "< 4.1"

The following operators are available from the float crate:
    - =  (default): Match when calculated entropy value equals specified entropy value
    - <  Match when calculated entropy value is strictly less than specified entropy value
    - <= Match when calculated entropy value is less than or equal to specified entropy value
    - >  Match when calculated entropy value is strictly greater than specified entropy value
    - >= Match when calculated entropy value is greater than or equal to specified entropy value
    - != Match when calculated entropy value is not equal to specified entropy value
    - x-y Match when calculated entropy value is in the range, exclusive
    - !x-y Match when calculated entropy value is not in the range, exclusive

float: General purpose floating point functions

Issue: 4162

This commit adds a floating-point analog to `uint.rs` targeted
initially to be used by the forthcoming entropy keyword.

doc: add http library supported fns

Task 7604

doc: remove http cookie ua from list of buffers

as they are available via library using the tx
- tx:request_header("Cookie")
- tx:response_header("Cookie")
- tx:request_header("User-Agent")

lua: convert http fns into suricata.http lib

Expose the existing lua fns through the library as suricata.http module.
All existing fns are accessible like before with a transaction.

Task 7604

util/lua: change arg name to reflect correctness

lua fns do not care about the argument count, they work with the index of
the item in the stack. Before library, there was just one item on the stack
so it worked out, however, with the library, the first item in the stack is
the library userdata, so, the fn would fail with the existing hard coded
setting of 1 for argc which can easily be confused with the number of
arguments passed to the fn.

github-ci: add test for custom lib example

Ticket: #7240

examples/lib: include cleanup

Requires tm-threads.h.

Ticket: #7240

examples/lib: use packet setter functions

Instead of direct field access.

Ticket: #7240

packet: add set functions for some packet fields

- SCPacketSetReleasePacket
- SCPacketSetLiveDevice
- SCPacketSetDatalink
- SCPacketSetTime
- SCPacketSetSource

Prevents direct access by library users and provides more ABI
stability.

Ticket: #7240

lib: remove TmModuleLibHandlePacket

This is better handled directly in the library user program so the
user has more control of the Packet structure, before and after
handling.

Ticket: #7240

examples/lib: use a main loop to wait for exit

Instead of immediately entering shutdown, use SuricataMainLoop to wait
for the end of the pcap.

Ticket: #7240

lib: remove SCRunModeLibDestroyWorker

This was a one line wrapper around SCTmThreadsSlotPktAcqLoopFinish, so
library users can call that directly instead.

Ticket: #7240

examples/lib: create threadvars from main thread

This also allows us to remove the sleep, as the ThreadVars are now
guaranteed to be created before PostInit.

Ticket: #7240

examples/lib: update library example for ips drop

Add a release packet callback where the action can be checked for drop.

Ticket: #7240

runmodes: typedef runmode enum and use as type

Also remove function to set the library mode. This is easy enough to
do with SCRunmodeSet, and we don't want to add a specific setter for
each and every runmode.

Ticket: #7240

lib: reorganize to avoid static prototypes

Ticket: #7240

lib: consistent naming style

And add SC prefix.

Ticket: #7240

threads: refactor TmThreadsSlotPktAcqLoop for user threads

Refactor TmThreadsSlotPktAcqLoop for user provided thread by breaking
out the init and finish code into their own functions.

For user provided threads, Suricata should not "drive" the thread, but
the setup and finish code is the same.

The finish function is exported so it can be called by the user
application when its receive loop or equivalent is done.

Also remove obsolete comment.

Ticket: #7240

lib: take pointer to LiveDevice, not name

In the library capture example, show how the packet counter can be
updated.

Ticket: #7240

lib: remove global worker id variable

Update ThreadVars creation in lib mode to have the worker_id provided
by the user.

Ticket: #7240

lib: rename threadvars creation function

Also use a proper return type (ThreadVars *).

Ticket: #7240

examples/lib: better command line handling

Use the more conventional "--" command line handling to separate the
arguments. The first set will be passed to Suricata, and the args
after "--" will be handled by the example. Currently this is a single
PCAP filename, but will be extended to a list of PCAP filenames.

Also hard code logging to the current directory.

Ticket: #7240

threads: don't attempt to join threads with an id of 0

Worker threads not created by Suricata, but instead a library user
should not be joined, as Suricata does not have access to their thread
handle, and it may in-fact be an unjoinable thread, such as the main
process.

When the thread ID is 0, assume the thread is "externally" managed,
but still mark is as dead to satisfy Suricata's view of the thread.

Ticket: #7240

.gitignore: add more files

- the generated binaries for lib examples
- LSP files
- man pages

examples: rename lib capture example to custom

To keep the simple example simple, move the lib based capture method
example to its own example.

Ticket: #7240

libsuricata: add library runmode

Add library source and runmode modules. Reorganized
library example to create a worker thread and replay a pcap
file using the library mode.
No API layer is added at this stage.

Edits by Jason Ish:
- fix guard
- add copyright/license headers

Ticket: #7240

doc/exceptions: change stats counters names

As we've changed them for more search-friendly ones.

Related to
Task #7185

exceptions: move midstream stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

exceptions: move reassembly memcap stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

exceptions: move ssn memcap stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

exceptions: move flow memcap stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

exceptions: move defrag stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

exceptions: move app_layer stats to common counter

Part of making the exception policy stats counters more search
friendly.

Task #7185

output: Add linktype name

Issue: 6954

This commit adds the linktype name to the output stream. The name is
determined from the pcap utility function pcap_datalink_val_to_name

output/datalink: Use Rust-based linktype hashmap

Use the hasmap to gather linktype display names.

Issue: 6954

decode/datalink: Add datalink value/name logic

Issue: 6954

Add Rust based logic that maintains a hash map of link type values and
their associated output names.

github-ci: use git cli command for netmap instead of action

This action hits API limits often, however our other uses of git clone
do not seem to, so try use git clone here instead of the github
action.

detect: SC prefix for extern pub Rust functions

Ticket: #7498

snmp: rust naming and visibility cleanups

Ticket: #7498

dpdk: adjust auto mempool calculation when no TX queues set

dpdk: allow zero TX queues when running in IDS mode

When running in non-forwarding (IDS) mode, it is not required
to create TX queues for the interface.
This can be acheived by setting tx-descriptors configuration
field to 0.

Ticket: 7633

docs: double quote technical terms in DPDK section

dpdk: NULL freed variables

The DPDKDeviceResourcesDeinit function now accepts second-level
reference to NULL the provided variable after deinitialization..

dpdk: document vlan stripping offload

Ticket: 5838

dpdk: check for link up before full startup

ICE card (Intel E810) was not receiving packets immediatelly
after startup, Suricata workers would act as processing while
it was not. This eliminates the problem by only continuing
in the initialization if the link is already up.

The setting can be turned off manually from the configuraiton
file.

Ticket: 7381

dpdk: use default iface-copy value if not specified

Ticket: 7374

dpdk: replace global with per-thread mempools

It turned out that having global (interface-specific) mempool
that is shared by the threads of the interface is slower than
having individual mempools per queue for each interface.

The commit brings this change and should be user-invisible,
the config setting remains still as a number of objects of
all mempools summed (of that interface).

Ticket: 7382

dpdk: remove mempool pointer from the thread structure

dpdk: auto configure Rx/Tx descriptors and mempool size

Ticket: 7380
Ticket: 7373

detect: allow rule which need both directions to match

Ticket: 5665

This is done with `alert ip any any => any any`
The => operator means that we will need both directions

ndpi: ignore packets that have a different proto than the flow

This can happen when the flow is UDP, but an ICMP unreachable is
returned, which gets assigned to the same flow.

Reference: https://github.com/ntop/nDPI/issues/2762