next/152/20231028/v1

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,9 @@
 Make sure these boxes are signed before submitting your Pull Request -- thank you.
 
-- [ ] I have read the contributing guide lines at https://docs.suricata.io/en/latest/devguide/codebase/contributing/contribution-process.html
-- [ ] I have signed the Open Information Security Foundation contribution agreement at https://suricata.io/about/contribution-agreement/
+- [ ] I have read the contributing guide lines at
+   https://docs.suricata.io/en/latest/devguide/codebase/contributing/contribution-process.html
+- [ ] I have signed the Open Information Security Foundation contribution agreement at
+   https://suricata.io/about/contribution-agreement/ (note: this is only required once)
 - [ ] I have updated the user guide (in doc/userguide/) to reflect the changes made (if applicable)
 
 Link to [redmine](https://redmine.openinfosecfoundation.org/projects/suricata/issues) ticket:

doc/userguide/install.rst

@@ -90,18 +90,20 @@ Rust support::
 Ubuntu/Debian
 """""""""""""
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 Minimal::
 
     # Installed Rust and cargo as indicated above
-    apt-get install build-essential git libjansson-dev libpcap-dev \
+    sudo apt-get install build-essential git libjansson-dev libpcap-dev \
                     libpcre2-dev libtool libyaml-dev make pkg-config zlib1g-dev
     # On most distros installing cbindgen with package manager should be enough
-    apt-get install cbindgen # alternative: cargo install --force cbindgen
+    sudo apt-get install cbindgen # alternative: cargo install --force cbindgen
 
 Recommended::
 
     # Installed Rust and cargo as indicated above
-    apt-get install autoconf automake build-essential ccache clang curl git \
+    sudo apt-get install autoconf automake build-essential ccache clang curl git \
                     gosu jq libbpf-dev libcap-ng0 libcap-ng-dev libelf-dev \
                     libevent-dev libgeoip-dev libhiredis-dev libjansson-dev \
                     liblua5.1-dev libmagic-dev libnet1-dev libpcap-dev \
@@ -112,39 +114,41 @@ Recommended::
 
 Extra for iptables/nftables IPS integration::
 
-    apt-get install libnetfilter-queue-dev libnetfilter-queue1  \
+    sudo apt-get install libnetfilter-queue-dev libnetfilter-queue1  \
                     libnetfilter-log-dev libnetfilter-log1      \
                     libnfnetlink-dev libnfnetlink0
 
 CentOS, AlmaLinux, RockyLinux, Fedora, etc
 """"""""""""""""""""""""""""""""""""""""""
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 To install all minimal dependencies, it is required to enable extra package
 repository in most distros. You can enable it possibly by
 one of the following ways::
 
-    dnf -y update
-    dnf -y install dnf-plugins-core
+    sudo dnf -y update
+    sudo dnf -y install dnf-plugins-core
     # AlmaLinux 8
-    dnf config-manager --set-enabled powertools
+    sudo dnf config-manager --set-enabled powertools
     # AlmaLinux 9
-    dnf config-manager --set-enable crb
+    sudo dnf config-manager --set-enable crb
     # Oracle Linux 8
-    dnf config-manager --set-enable ol8_codeready_builder
+    sudo dnf config-manager --set-enable ol8_codeready_builder
     # Oracle Linux 9
-    dnf config-manager --set-enable ol9_codeready_builder
+    sudo dnf config-manager --set-enable ol9_codeready_builder
 
 Minimal::
 
     # Installed Rust and cargo as indicated above
-    dnf install -y gcc gcc-c++ git jansson-devel libpcap-devel libtool \
+    sudo dnf install -y gcc gcc-c++ git jansson-devel libpcap-devel libtool \
                    libyaml-devel make pcre2-devel which zlib-devel
     cargo install --force cbindgen
 
 Recommended::
 
     # Installed Rust and cargo as indicated above
-    dnf install -y autoconf automake diffutils file-devel gcc gcc-c++ git \
+    sudo dnf install -y autoconf automake diffutils file-devel gcc gcc-c++ git \
                    jansson-devel jq libcap-ng-devel libevent-devel \
                    libmaxminddb-devel libnet-devel libnetfilter_queue-devel \
                    libnfnetlink-devel libpcap-devel libtool libyaml-devel \
@@ -202,6 +206,8 @@ Ubuntu from Personal Package Archives (PPA)
 For Ubuntu, OISF maintains a PPA ``suricata-stable`` that always contains the
 latest stable release.
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 Setup to install the latest stable Suricata::
 
     sudo apt-get install software-properties-common
@@ -236,6 +242,8 @@ To remove Suricata from your system::
 Getting Debug or Pre-release Versions
 """""""""""""""""""""""""""""""""""""
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 If you want Suricata with built-in (enabled) debugging, you can install the
 debug package::
 
@@ -256,6 +264,8 @@ Suricata will then always be the latest release, stable or beta.
 Daily Releases
 """"""""""""""
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 If you would like to help test the daily build packages from our latest git(dev)
 repository, the same procedures as above apply, just using another PPA,
 ``suricata-daily``::
@@ -281,6 +291,8 @@ repository, the same procedures as above apply, just using another PPA,
 Debian
 ^^^^^^
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 In Debian 9 (stretch) and later do::
 
     sudo apt-get install suricata
@@ -298,6 +310,8 @@ For Debian 10 (buster), for instance, run the following as ``root``::
     apt-get update
     apt-get install suricata -t buster-backports
 
+.. _RPM packages:
+
 CentOS, AlmaLinux, RockyLinux, Fedora, etc
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -314,29 +328,31 @@ Installing From Package Repositories
 CentOS, RHEL, AlmaLinux, RockyLinux, etc Version 8+
 '''''''''''''''''''''''''''''''''''''''''''''''''''
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 .. code-block:: none
 
-   dnf install epel-release dnf-plugins-core
-   dnf copr enable @oisf/suricata-7.0
-   dnf install suricata
+   sudo dnf install epel-release dnf-plugins-core
+   sudo dnf copr enable @oisf/suricata-7.0
+   sudo dnf install suricata
 
 CentOS 7
 ''''''''
 
 .. code-block:: none
 
-   yum install epel-release yum-plugin-copr
-   yum copr enable @oisf/suricata-7.0
-   yum install suricata
+   sudo yum install epel-release yum-plugin-copr
+   sudo yum copr enable @oisf/suricata-7.0
+   sudo yum install suricata
 
 Fedora
 ''''''
 
 .. code-block:: none
 
-    dnf install dnf-plugins-core
-    dnf copr enable @oisf/suricata-7.0
-    dnf install suricata
+    sudo dnf install dnf-plugins-core
+    sudo dnf copr enable @oisf/suricata-7.0
+    sudo dnf install suricata
 
 Additional Notes for RPM Installations
 """"""""""""""""""""""""""""""""""""""
@@ -357,21 +373,23 @@ Starting Suricata On-Boot
 
 The Suricata RPMs are configured to run from Systemd.
 
+.. note:: The following instructions require ``sudo`` to be installed.
+
 To start Suricata::
 
-  systemctl start suricata
+  sudo systemctl start suricata
 
 To stop Suricata::
 
-  systemctl stop suricata
+  sudo systemctl stop suricata
 
 To have Suricata start on-boot::
 
-  systemctl enable suricata
+  sudo systemctl enable suricata
 
 To reload rules::
 
-   systemctl reload suricata
+  sudo systemctl reload suricata
 
 .. _install-advanced:
 

rust/src/applayer.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-//! Parser registration functions and common interface
+//! Parser registration functions and common interface module.
 
 use std;
 use crate::core::{self,DetectEngineState,Flow,AppLayerEventType,AppProto,Direction};

rust/src/applayertemplate/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Application layer template parser and logger module.
+
 mod parser;
 pub mod template;
 /* TEMPLATE_START_REMOVE */

rust/src/asn1/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! ASN.1 parser module.
+
 use der_parser::ber::{parse_ber_recursive, BerObject, BerObjectContent, Tag};
 use nom7::Err;
 use std::convert::TryFrom;

rust/src/bittorrent_dht/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! BitTorrent DHT application layer, logger and parser module.
+
 pub mod bittorrent_dht;
 pub mod logger;
 pub mod parser;

rust/src/common.rs

@@ -1,3 +1,5 @@
+//! Utility library module for commonly used strings, hexadecimals and other elements.
+
 use super::build_slice;
 use crate::jsonbuilder::HEX;
 use std::ffi::CString;

rust/src/conf.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for retrieving configuration details.
+
 use std::os::raw::c_char;
 use std::os::raw::c_void;
 use std::os::raw::c_int;

rust/src/core.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-// This file exposes items from the core "C" code to Rust.
+//! This module exposes items from the core "C" code to Rust.
 
 use std;
 use crate::filecontainer::*;

rust/src/dcerpc/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DCE/RPC protocol parser, logger and detection module.
+
 pub mod dcerpc;
 pub mod dcerpc_udp;
 pub mod parser;

rust/src/detect/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for rule parsing.
+
 pub mod byte_math;
 pub mod error;
 pub mod iprep;

rust/src/dhcp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DHCP parser, detection and logger module.
+
 pub mod dhcp;
 pub mod parser;
 pub mod logger;

rust/src/dns/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DNS parser, detection, logger and application layer module.
+
 pub mod detect;
 pub mod dns;
 pub mod log;

rust/src/ffi/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module that exposes C bindings to the Suricata Rust library.
+
 pub mod hashing;
 pub mod base64;
 pub mod strings;

rust/src/filecontainer.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! This module handles file container operations (open, append, close).
+
 use std::ptr;
 use std::os::raw::{c_void};
 

rust/src/filetracker.rs

@@ -15,18 +15,17 @@
  * 02110-1301, USA.
  */
 
-/**
- *  \file
- *  \author Victor Julien <victor@inliniac.net>
- *
- * Tracks chunk based file transfers. Chunks may be transferred out
- * of order, but cannot be transferred in parallel. So only one
- * chunk at a time.
- *
- * GAP handling. If a data gap is encountered, the file is truncated
- * and new data is no longer pushed down to the lower level APIs.
- * The tracker does continue to follow the file.
- */
+//! Gap handling and Chunk-based file transfer tracker module.
+//!
+//! GAP handling. If a data gap is encountered, the file is truncated
+//! and new data is no longer pushed down to the lower level APIs.
+//! The tracker does continue to follow the file
+//
+//! Tracks chunk based file transfers. Chunks may be transferred out
+//! of order, but cannot be transferred in parallel. So only one
+//! chunk at a time.
+//!
+//! Author: Victor Julien <victor@inliniac.net>
 
 use crate::core::*;
 use std::collections::HashMap;

rust/src/frames.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for bindings to the Suricata C frame API.
+
 use crate::applayer::StreamSlice;
 use crate::core::Flow;
 #[cfg(not(test))]

rust/src/ftp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! FTP parser and application layer module.
+
 use nom7::bytes::complete::{tag, take_until};
 use nom7::character::complete::{digit1, multispace0};
 use nom7::combinator::{complete, map_res, opt, verify};

rust/src/http2/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! HTTP/2 parser, detection, logger and application layer module.
+
 #![allow(clippy::result_unit_err)]
 
 mod decompression;

rust/src/ike/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! IKE parser, detection, logger and application layer module.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 extern crate ipsec_parser;

rust/src/jsonbuilder.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+ //! Module for building JSON documents.
+
 #![allow(clippy::missing_safety_doc)]
 
 use std::cmp::max;

rust/src/kerberos.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Kerberos parser wrapper module.
+
 use nom7::IResult;
 use nom7::error::{ErrorKind, ParseError};
 use nom7::number::streaming::le_u16;