docs: Update Suricata page to VyOS 1.5 standards (#2118)

* docs: Update Suricata page to VyOS 1.5 standards

* Update suricata.md

* Update suricata.md

* Update suricata.md

1 files changed, 247 insertions, 54 deletions

diff --git a/docs/configuration/service/suricata.md b/docs/configuration/service/suricata.md
index ca9ae968..85af45a8 100644
--- a/docs/configuration/service/suricata.md
+++ b/docs/configuration/service/suricata.md
@@ -1,93 +1,286 @@
+---
+myst:
+  html_meta:
+    description: |
+      Suricata is an open-source network threat detection engine
+      integrated in VyOS as a managed service. It performs intrusion
+      detection, inline intrusion prevention, and network security
+      monitoring by matching live traffic against rules.
+    keywords: suricata, ids, ips, nsm, intrusion detection, intrusion
+      prevention, network security monitoring, eve, address group, port group
+---
+
 (suricata)=
 
-# suricata
+# Suricata
+
+[Suricata](https://suricata.io/) is an open-source network threat
+detection engine that performs intrusion detection
+({abbr}`IDS (Intrusion Detection System)`), inline intrusion
+prevention ({abbr}`IPS (Intrusion Prevention System)`), and network
+security monitoring ({abbr}`NSM (Network Security Monitoring)`) by
+matching live traffic against a set of rules, also called signatures.
+Each event is recorded in the {abbr}`EVE (Extensible Event Format)`
+event log in {abbr}`JSON (JavaScript Object Notation)` format.
+
+VyOS integrates Suricata as a managed service, configurable under
+`service suricata`. When the configuration is committed, VyOS generates
+Suricata configuration from these settings and starts the service.
+
+Under `service suricata`, you can configure the following:
+
+- **Monitored interfaces**: One or more interfaces on which Suricata
+  captures traffic.
+- **Address groups**: Named lists of IPv4/IPv6 addresses or prefixes,
+  used in place of literal IP addresses in Suricata rules. 
+- **Port groups**: Named lists of ports or port ranges, used in place
+  of literal ports in Suricata rules. 
+- **EVE log**: Destination (regular file or syslog), file name or
+  path, and the event types to log.
+
+Rules are fetched separately by running `update suricata` from
+operational mode. Until this command is run, the service has no rules
+to match against.
+
+```{note}
+A Suricata configuration is committable only when at least one
+interface, one address group, and one port group are defined.
+Otherwise, the commit fails.
+```
+
+## Configuration
+
+### Monitored interfaces
 
-Suricata and VyOS are powerful tools for ensuring network security and traffic management.
-Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time.
+Use the following command to configure the interfaces Suricata
+monitors.
 
-## Suricata Features
+```{cfgcmd} set service suricata interface \<interface\>
 
-Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic.
-Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network.
-Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats.
-Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others.
-In configuration mode, the commands are as follows:
+**Configure an interface on which Suricata captures and inspects
+traffic.**
+
+Repeat the command to monitor several interfaces. At least one
+interface must be configured for a successful commit.
+```
+
+Example:
 
 ```none
-vyos@vyos# set service suricata
-Possible completions:
-+> address-group        Address group name
-+  interface            Interface to use
- > log                  Suricata log outputs
-+> port-group           Port group name
+set service suricata interface eth1
 ```
 
-These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports,
-and logging parameters.
+### Address groups
 
-After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created,
-into which all specified parameters are added. Then, to ensure proper operation, the command {opcmd}`update suricata` must be run
-from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks.
+Use the following commands to configure address groups.
 
-## Configuration
+```{note}
+Group names must be lowercase letters, digits, or hyphens. 
+```
 
-```{cfgcmd} set service suricata address-group \<text\> \<address | group\>
+```{note}
+Suricata rules reference a conventional set of group names, such as
+`home-net`, `external-net`, `http-servers`, and others. Defining a
+group with a non-standard name is allowed, but no shipped rules will
+reference it. Typical address groups include:
 
-   Address groups are useful when you need to create rules that apply to specific IP addresses.
-   For example, if you want to create a rule that monitors traffic going to or from a specific IP address,
-   you can use the group name instead of the actual IP address. This simplifies rule management and makes the
-   configuration more flexible.
+- `home-net`: the networks Suricata should treat as internal (for
+  example, `192.0.2.0/24` and `2001:db8::/32`).
+- `external-net`: everything not in `home-net`.
+- `http-servers`, `sql-servers`, `dns-servers`: hosts running the
+  corresponding services.
+```
+
+```{cfgcmd} set service suricata address-group \<name\> address \<address\>
+
+**Configure an IPv4 or IPv6 address or prefix as a member of the
+specified address group.**
 
-   * ``address`` IP address or subnet.
+`<address>` accepts an IPv4 or IPv6 address, an IPv4 or IPv6 prefix,
+or any of these prefixed with `!` to exclude it from matches.
 
-   * ``group``  Address group.
+Repeat the command to add more addresses or prefixes to the same
+group.
 ```
 
+Example:
 
-```{cfgcmd} set service suricata port-group \<text\> \<address | group\>
+```none
+set service suricata address-group home-net address 192.0.2.0/24
+set service suricata address-group home-net address 2001:db8::/32
+set service suricata address-group home-net address !192.0.2.5
+```
 
-Port groups are useful when you need to create rules that apply to specific ports.
-For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports,
-you can use the group name instead of the actual port. This also simplifies rule management and makes
-the configuration more flexible.
+```{cfgcmd} set service suricata address-group \<name\> group \<name\>
 
-* ``port``  Port number.
+**Configure another address group as a member of the specified
+address group.**
 
-* ``group``  Port group.
+Prefix the referenced name with `!` to exclude that group's members.
+The referenced group must be defined at commit time, and cyclic
+references between groups are rejected.
+
+Repeat the command to add more groups to the same parent group.
+```
+
+Example:
+
+```none
+set service suricata address-group home-net address 192.0.2.0/24
+set service suricata address-group external-net group !home-net
 ```
 
+### Port groups
 
-```{cfgcmd} set service suricata interface \<text\>
+Use the following commands to configure port groups.
 
-The interface that will be monitored by the Suricata service.
+```{note}
+Group names must be lowercase letters, digits, or hyphens. 
 ```
-```{cfgcmd} set service suricata log eve \<filename | filetype | type\>
 
-   Configuration of the logging file.
+```{note}
+Suricata rules reference a conventional set of port-group names, such
+as `http-ports`, `ssh-ports`, `oracle-ports`, `shellcode-ports`, and
+others. Defining a port group with a non-standard name is allowed,
+but no shipped rules will reference it. Typical port groups include:
+
+- `http-ports`: ports where HTTP services run.
+- `ssh-ports`: ports where SSH services listen.
+- `oracle-ports`: ports used by Oracle database services.
+- `shellcode-ports`: ports inspected by shellcode-detection rules.
+```
+
+```{cfgcmd} set service suricata port-group \<name\> port \<port\>
+
+**Configure a port or port range as a member of the specified port
+group.**
+
+`<port>` accepts a single port (1–65535), a numeric range in
+`start-end` form (e.g., `1001-1005`), or either form prefixed with
+`!` to exclude it from matches.
 
-   * ``filename``  Log file (default: eve.json).
+Repeat the command to add more ports or port ranges to the same
+group.
+```
 
-   * ``filetype``  EVE logging destination (default: regular).
+Example:
 
-   * ``type``  Log types.
+```none
+set service suricata port-group http-ports port 80
+set service suricata port-group http-ports port 443
+set service suricata port-group http-ports port 8000-8999
+set service suricata port-group http-ports port !8080
 ```
 
-## Operation Mode
+```{cfgcmd} set service suricata port-group \<name\> group \<name\>
+
+**Configure another port group as a member of the specified port
+group.**
 
-```{cfgcmd} update suricata
+Prefix the referenced name with `!` to exclude that group's members
+from matches. The referenced group must be defined at commit time,
+and cyclic references between groups are rejected.
 
-Checks for the existence of the Suricata configuration file, updates the service,
-and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured.
+Repeat the command to add multiple groups to the same parent group.
 ```
-```{cfgcmd} restart suricata
 
-Restarts the service. It checks if the Suricata service is active before attempting to restart it.
-If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually.
+Example:
+
+```none
+set service suricata port-group http-ports port 80
+set service suricata port-group shellcode-ports group !http-ports
 ```
 
-## Conclusion
+### EVE log
 
-Using address and port groups allows you to make your Suricata configuration more flexible and manageable.
-Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then
-reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses
-and ports need to be monitored.
+Use the following commands to configure the EVE log.
+
+```{cfgcmd} set service suricata log eve filename \<filename\>
+
+**Configure the filename or path for the Suricata EVE log.**
+
+A bare filename (e.g., `eve.json`) places the log in Suricata's
+default log directory, `/var/log/suricata/`. An absolute path is used
+as-is.
+
+The default is `eve.json`.
+```
+
+Example:
+
+```none
+set service suricata log eve filename eve.json
+set service suricata log eve filename /var/log/custom/suricata-eve.json
+```
+
+```{cfgcmd} set service suricata log eve filetype \<regular | syslog\>
+
+**Configure the destination for the Suricata EVE log:**
+
+- `regular`: Writes the EVE log to the file specified by
+  `set service suricata log eve filename`.
+- `syslog`: Sends the EVE log to syslog.
+
+The default is `regular`.
+```
+
+Example:
+
+```none
+set service suricata log eve filetype syslog
+```
+
+```{cfgcmd} set service suricata log eve type \<type\>
+
+**Configure which EVE event types are logged.**
+
+Accepted values:
+
+- General event types: `alert`, `anomaly`, `drop`, `files`, `flow`,
+  `netflow`.
+- Per-protocol event types: `http`, `http2`, `dns`, `tls`, `smtp`,
+  `ftp`, `smb`, `ssh`, `dhcp`, `tftp`, `nfs`, `rdp`, `sip`, `snmp`,
+  `ikev2`, `krb5`, `dcerpc`, `dnp3`, `rfb`, `mqtt`.
+
+Repeat the command to log multiple event types.
+```
+
+Example:
+
+```none
+set service suricata log eve type alert
+set service suricata log eve type flow
+set service suricata log eve type http
+```
+
+## Operation
+
+```{opcmd} update suricata
+
+**Fetch the current rule set with `suricata-update` and restart the
+Suricata service to load it.**
+
+If `service suricata` is not configured, the command outputs an error
+message and exits.
+```
+
+Example:
+
+```none
+update suricata
+```
+
+```{opcmd} restart suricata
+
+**Restart the Suricata service.**
+
+If the service is not configured (no `service suricata` configuration
+exists), or a configuration commit is in progress, the command prints
+an error message and exits.
+```
+
+Example:
+
+```none
+restart suricata
+```