doc/userguide: add lua flowlib docs

Task #7489

doc: remove old lua flow methods

Task #7489

lua: remove old lua flow calls

Moving forward, the flowlib is to be used.

Task #7489

lua: add initial suricata.flow lib

Methods:
`get` creates the flow object.
`id`  returns the flow id.
`has_alerts` returns a boolean indicating if the flow triggered alerts.
`app_layer_proto` returns various app-layer related fields as 5 strings:
  alproto, alproto_ts, alproto_tc, alproto_orig, alproto_expect.
`stats` returns cnts for bytes and packets to sever and to client, as 4
  numbers.
`tuple` -- returns various fields: srcip, dstip, proto, sp, dp.
`timestamps` returns time as 4 numbers: seconds and microseconds, for
  first and last packet of the flow.
`timestring_legacy` returns the first packet from the flow's timestring
  as a string (like fastlog).
`timestring_iso8601` returns the first packet from the flow's
  timestring as an iso8601 compat timestring (like eve).

Example:

```
name = "lua-scflowstats.log"

local flow = require("suricata.flow")

function init(args)
    local needs = {}
    needs["type"] = "flow"
    return needs
end

function setup(args)
    filename = SCLogPath() .. "/" .. name
    file = assert(io.open(filename, "a"))
    SCLogInfo("lua SCFlowStats Log Filename " .. filename)
end

function log(args)
    local f = flow.get()
    timestring = f:timestring_legacy()
    tscnt, tsbytes, tccnt, tcbytes = f:stats()

   file:write ("[**] " .. timestring .. "\nSCFlowStats is\nPacket count to server:  " .. tscnt .. "\nByte count to server: " .. tsbytes .. "\nPacket count to client: " .. tccnt .. "\nByte count to client: " .. tcbytes .. "\n[**]")
    file:flush()
end

function deinit(args)
    file:close(file)
end
```

Task #7489

lua: fix typos

lua/dnp3: convert done and complete to boolean

These were integers, 1 of true, 0 for false. Convert to boolean as
that is how they are in eve, and Lua has boolean types.

Ticket: #7601

lua/dnp3: add is_request boolean

A DNP3 message can be a request or response, but not both. This is how
the transaction is structured.

Instead of having 2 values, "has_request" and "has_response", just
provide one field, "is_request" as a boolean.

Ticket: #7601

lua: convert dnp3 to suricata.dnp3 lib

This is an initial 1:1 conversion which is rather simple, as DNP3 only
had one function which converted the whole transaction to a DNP3
table.

Ticket: #7601

lua: remove buffer type dns.rrname, not needed

DNS is transaction based, Lua scripts need only express interest in
the request or the response.

lua: allow for real booleans in "needs" expression

In addition to

    function init (args)
        local needs = {}
        needs["dnp3"] = tostring(true)
        return needs
    end

allow for

    function init (args)
        return {dnp3=true}
    end

with the idea that the former will be completely removed for 8.0.

This works with all existing SV tests and as a string value, any value
is considered "truthy".

script/dnp3_gen.py: use current clang style

script/dnp3-gen.py: update for newer versions of Python

More recent yaml loaders require the loader as an argument.

detect: add email.cc keyword

email.cc matches on MIME EMAIL Carbon Copy
This keyword maps to the EVE field email.cc[]
It is a sticky buffer
Supports prefiltering

Ticket: #7588

detect-email.c: don't return NULL for empty buffer

Just return NULL if tx->mime_state is NULL or if SCDetectMimeEmailGetData return 0

Fixes:
09db7c7 ("detect: add mime email.subject keyword")
90aab0d ("detect: add email.from")

doc: add keywords to the multi-buffer-matching list

rust: fixes for breaking change on deranged crate

Deranged v0.4.1 (a dependency of the time crate) has implemented
PartialOrd for some integer types that conflict with the
implementation in the standard library creating an ambiguity as such
implementation are global. For more info see
https://github.com/jhpratt/deranged/issues/18.

To fix, use "::from" directly, instead of using .into() which is where
we run into amgibuity.

doc/userguide: group af-packet upgrade notes together

Also fix the rendering of the sip nest list.

doc/userguide: upgrade note about defrag now off for inline use

Ticket: #7617

af-packet: don't default to defrag when inline

Don't default to defrag true when inline. It can still be enabled by
setting defrag to true however it is not recommended.

Ticket: #7617

doc/userguide: upgrade note about tpacket-v3 default for ids

Ticket: #4798

applayer: fix alp_ctx indexing in tests

Fix problem that some app-layer unittests regist failed.

detect: add email.to keyword

email.to matches on MIME EMAIL TO
This keyword maps to the EVE field email.to[]
It is a sticky buffer
Supports prefiltering

Ticket: #7596

fuzz: set flow flags as in Suricata

Fixes: d8ddef4c1485 ("detect: delay tx cleanup in some edge case")

detect: add mime email.subject keyword

email.subject matches on MIME EMAIL SUBJECT
This keyword maps to the EVE field email.subject
It is a sticky buffer
Supports prefiltering

Ticket: #7595

af-packet: use tpacket v3 by default for ids mode

If "tpacket-v3" is not present in the configuration file, and we are
in IDS mode, default to "tpacket-v3".

Required moving the check for tpacket-v3 after the copy-mode
configuration, so the warning about tpacket-v3 in active modes has
been moved as well.

Ticket: #4798

af-packet: remove use-mmap option

This option is obsolete and was not used in 7.0 as tpacket-v1 support
was removed (see ticket #4796).

af-packet: remove build conditional for tpacket-v3

All kernels on supported distrubtions should now support tpacket-v3,
so only enable af-packet if v2 and v3 are available.

pgsql/parser: use fn for length parsing...

... there was still one parser missing this conversion.

util/exception: fix coverity warning

CID 1644862:  Control flow issues  (UNREACHABLE)

In ExceptionPolicyTargetFlagToString, a statement cannot be reached
(line 113).

userguide/exceptions: clarify when stats are logged

The stats for exception policies are only logged/ present when any of
the exception policies are enabled (which means any value other than
"auto" or "ignore" in IDS mode, or "ignore" in IPS mode).

This wasn't clearly stated in the docs.

flow/output: log triggered exception policies

To accompany the Exception Policy stats, also add information about any
Exception Policy triggered and for which target to the flow log event.

Task #6215

tls: implement alert parser

Fatal alerts set the tx state to 'finished'.

Add event for malformed alerts.

dns: stop renaming DNSTransaction to RSDNSTransaction

Not needed anymore as there is no DNSTransaction in the C src to
conflict.

lua: document new suricata.dns lua library

Ticket: #7602

lua: convert dns function into suricata.dns lib

Notable changes from the previous API:
- rcode will return the rcode as an integer
- rcode_string will return the string representation

Also fixes an issue where an rcode of 0 was returned as nil.

Ticket: #7602

detect: add email.from

email.from matches on MIME EMAIL FROM
This keyword maps to the EVE field email.from
It is a sticky buffer
Supports prefiltering

Ticket: #7592

rustfmt: rust/src/mime/smtp.rs

Eve: use mac addresses from flow for flow timeout

Ethernet metadata is missing for events triggered on flow timeout
pseudopackets. Use the first set of mac addresses stored with the
flow to fill in the ether field.

Ticket: #5486

Doc: update eve-json-output ethernet description

Document getting mac addresses from flow when flow timeout.

af-packet: use actual snaplen in bpf

Avoids setting a 0 snaplen in BPF, leading to an error.

Fixes: b8b6ed550a6f ("af-packet: delay setting default-packet-size for af-packet")
Ticket: #7618.

datasets: work around scan-build warning

datasets.c:493:27: warning: Dereference of null pointer [core.NullDereference]
  493 |     DEBUG_VALIDATE_BUG_ON(set->hash->config.hash_size != hashsize);
      |                           ^~~~~~~~~~~~~~~~~~~~~~~~~~~
./util-validate.h:95:44: note: expanded from macro 'DEBUG_VALIDATE_BUG_ON'
   95 | #define DEBUG_VALIDATE_BUG_ON(exp) BUG_ON((exp))
      |                                            ^~~
./suricata-common.h:307:36: note: expanded from macro 'BUG_ON'
  307 |         #define BUG_ON(x) assert(!(x))
      |                                    ^
/usr/include/assert.h:109:7: note: expanded from macro 'assert'
  109 |     ((expr)                                                             \
      |       ^~~~
1 warning generated.

doc: explain priority port setting

Ticket 7329

doc: format and align suricata.yaml section

upgrade: list inspection recursion default limit

As the yaml indicated before that if no value was specified there were
no limits, and now there will be one.

doc/upgrade: add datasets hash size limit note

detect: add configurable limits for datasets

Ticket: 7615

Avoids signatures setting extreme hash sizes, which would lead to very
high memory use.

Default to allowing:
- 65536 per dataset
- 16777216 total

To override these built-in defaults:

```yaml
datasets:
  # Limits for per rule dataset instances to avoid rules using too many
  # resources.
  limits:
    # Max value for per dataset `hashsize` setting
    #single-hashsize: 65536
    # Max combined hashsize values for all datasets.
    #total-hashsizes: 16777216
```

datasets: improve default hashsize handling

Make hashsize default local to dataset code, instead of relying on the
thash code.

Use the same default value as before.

doc/userguide: af-packet upgrade notes

Add note about increased block size and how to change it back to old
defaults if needed.

Ticket: #7458

af-packet: delay setting default-packet-size for af-packet

AF_PACKET needs more information about its configuration before we can
set the default packet size, so on startup, leave unset in suricata.c
if in AF_PACKET mode.

If defrag is enabled, use a default packet size of 9k for tpacket-v2.
This can still lead to truncation events, then the user can increase
their 'default-packet-size'.

Tpacket-v3 does not need an increased packet size as it will handle
any size of packet that is smaller than the configured block size
which now has a default of 128k.

9k for the snap is somewhat arbitrary but is large enough for the
common 9000 jumbo frame plus some extra headers including tpacket
headers.

Ticket: #7458

af-packet: warn that tpacket-v3 is better for non-inline usage

Ticket: #7458

af-packet: add event for packets truncated by af-packet

Ticket: #7458

af-packet: warn if v3 block size is not large enough for defrag

If using tpacket-v3 and defrag, warn if the block size is not large
enough for a fully defragmented packet.

Ticket: #7458

af-packet: warn if v2 block size not large enough for defrag

If using tpacket-v2, defrag and a user provided v2-block-size, warn if
the block size is not large enough to hold one fully defragmented
packet.

Ticket: #7458

af-packet: make tpacket-v2 block size configurable

With the change of the default tpacket-v2 block size from 32k to 128k,
allow it to be configurable for users who may want to make it larger,
or revert it back to the pre 7.0.9 default of 32k.

Ticket: #7458

af-packet: increase default block size

Increase the default block size from 32k to 128k. This allows for a
fully defragmented packet to fit in the buffer.

Ticket: #7458

af-packet: warn if defrag not suitable for mode

AF_PACKET defrag should not be used for inline modes. Its possible that
a packet received could be larger than can be set when defrag is
enabled, so warn if disabled for inline use.

Likewise, warn if defrag is disabled for IDS use, or non-inline mode.

Ticket: #7458

af-packet: check defrag value even if cluster-type not set

If cluster-type was not set we default to "cluster_flow" with defrag
always on. Instead check for defrag value and disable defrag if disabled
by the user.

Ticket: #7458

detect: limit base64_decode `bytes` to 64KiB

Ticket: 7613

Avoids potential large per-thread memory allocation. A buffer with the
size of the largest decode_base64 buffer size setting would be allocated
per thread. As this was a u32, it could mean a per-thread 4GiB memory
allocation.

64KiB was already the built-in default for cases where bytes size wasn't
specified.

detect: non infinite default value for inspection-recursion-limit

So that empty config are protected by this setting as was intended.

Set to unlimited for fuzz testing.

detect/pcre: avoid infinite loop after negated pcre

Ticket: 7526

The usage of negated pcre, followed by other relative payload
content keywords could lead to an infinite loop.

This is because regular (not negated) pcre can test multiple
occurences, but negated pcre should be tried only once.

rust: pin once_cell to work with Rust 1.67.1

Clap uses once_cell which recently released v1.20 which updated its
MSRV to 1.70. Locally pin once_cell to 1.20.3 to maintain our MSRV.

pcap: skip pcap-config if pkgconfig in use

detect/action: minor action parsing cleanup

Preparation for explicit action scope parsing.

detect/loader: minor code cleanup

detect: constify rule file and lines in parsing and analyzer

tls: fix handshake handling being too strict

e.g. server hello done has no data

app-layer: constify AppLayerGetProtoByName

detect/tls: don't double register tls_validity generic list

detect/nfs: don't double register nfs_request generic list

detect: don't register duplicate app inspect engines

detect/analyzer: add policy

Example output:

    "match_policy": {
        "actions": [
            "alert",
            "drop"
        ],
        "scope": "flow"
    },

smtp/events: set direction on rules

Several rules matched on both directions even if events are set in a single direction.

github-ci: don't run builds on PR if only docs changed

github-ci: stop caching system packages

lua: remove script_api_ver

Not documented and never set to new values despite updates.

Ticket: #7492.

contrib: remove suri-graphite

Built for py2.

Remove now empty contrib dir.

Ticket: #6888.

contrib: remove file_processor

Has been developed for a now obsolete file log format.

Ticket: #6888.

detect/dcerpc.iface: remove commented out unittest

eve/schema: map tls fields to keywords

schema: add rule keyword mapping for dcerpc

userguide/header-keywords: fix typos, adjust format

doc/rule-types: remove trailing underscore

And other minor fixes that were overseen.

userguide/suricatactl: use suricata community page

We were mentioning "Suricata Support" page, which could be a bit
misleading -- and also used a link that is actually redirected to the
Suricata Community page, anyways.

github-ci: pin rust version for clippy tests

Prevents CI breakage after a new Rust release until we're ready to make
the changes.

github-ci: update rpm builder to fedora 41

github-ci: update Fedora non-root build to Fedora 41

github-ci: remove fedora 40 builds where 41 exists

Remove Fedora 40 builds where there is a Fedora 41 equivalent.

eve-parity: merge $ref props into current object

Allows for a "suricata" entry along with a "$ref".

eve-parity: handle arrays of scalars

And add an example with "client_alpns".

rust: Update sawp dependencies to 0.13.1 due to SPDX license compatibility.

detect/lua: Fix max value displayed in error msg

This commit corrects an error message displayed when the key length is
out of range.

var: Use 16-bit container for type

Issue: 6855: Match sigmatch type field in var and bit structs

Align the size and datatype of type, idx, and next members across:
- FlowVarThreshold
- FlowBit
- FlowVar
- GenericVar
- XBit
- DetectVarList

Note that the FlowVar structure has been intentionally constrained to
match the structure size prior to this commit. To achieve this, the
keylen member was restricted to 8 bits after it was confirmed its value
is checked against a max of 0xff.

detect: delay tx cleanup in some edge case

Ticket: 7552

f->sgh_toserver may be NULL but because FLOW_SGH_TOSERVER is unset
and thus, we want to delay cleanup until detection has really been
run with the right signature group head.

This may happen for a rule using
`alert tcp any any -> any any` and
a app-layer keyword to client
with a app-layer supporting both udp and tcp
with stream.midstream=true
and with the first packet of a flow being a server response

In this case, we swap the flow and reset its signature group heads

detect: reset signature groups when reversing flow

Ticket: 7552

When we use midstream, and the first packet we see of a flow is
a response from server, and we want to match on some signature
to client :
- we had first set sgh_toserver/FLOW_SGH_TOSERVER as we first
  thought this was a packet to server
- we then swap/reverse the flow, so sgh_toclient becomes sgh_toserver
  but it contains signatures to server and cannot match our
  to_client signature

The detect engine with DetectRunSetup will set again the
signatures group heads properly

eve-parity: skip transform keywords

schema: mark dns.version and dns.grouped as having no keywords

schema: mark "stats" and "drop" as having no keywords

detect-dns-response: remove unit tests

Should have coverage by S-V now.

script/eve-parity: add script for checking eve/keyword parity

Currently this script has two commands: "missing" and "having".

"missing" will show eve fields that do not map to any keywords.

"having" will sohw eve fields along with their keyword mappsings,
while also validating that those keywords really exist.

Related to tickets: #6463, #4772

schema: add an object for mapping fields to keywords

To some EVE fields and a "suricata" object that contains an array of
keywords. These are the keywords that map directly to this field, or
somehow cover this field.

This is an attempt at tooling to help with EVE and keyword parity.

Related to tickets: #5642, #6463, #4772