docs: add firewall stats doc

Related to
Ticket #7699

doc/userguide/configuration/suricata-yaml.rst

@@ -2813,7 +2813,7 @@ Please read :ref:`Firewall Mode Design <firewall mode design>` before using this
 The existing yaml configuration options are listed below. If the engine is run
 in firewall mode, dedicated stats counters will be added to the stats logs.
 
-To see the stats counters reported for the firewall, refer to :ref:`firewall mode stats`.
+To see the stats reported for the firewall mode, refer to :ref:`firewall mode stats`.
 
 ::
 

doc/userguide/firewall/firewall-stats.rst

@@ -0,0 +1,34 @@
+.. _firewall mode stats:
+
+Firewall Mode Stats
+*******************
+
+Statistics counters for the firewall mode cover:
+
+    - drop reasons: ``stats.firewall.drop_reason``
+    - discarded alerts: ``stats.firewall.discarded_alerts``
+    - blocked packets: ``stats.firewall.blocked``
+    - accepted packets: ``stats.firewall.accepted``
+    - rejected packets: ``stats.firewall.rejected``
+
+These will be present in the stats logs if the engine is run in firewall mode,
+only.
+
+Drop reasons
+============
+
+If a drop was caused by the firewall, the corresponding counter will be incremented. The existing ones are:
+
+    - ``rules``: a firewall rule triggered the drop
+    - ``default_packet_policy``: drop caused by the default fail closed firewall behavior, on the packet hook level
+    - ``default_app_policy``: drop caused by the default fail close firewall behavior, on the app-layer hook level
+    - ``pre_flow_hook``: drop caused by the pre-flow hook
+    - ``pre_stream_hook``: drop caused by the pre-stream hook
+    - ``flow_drop``: the whole flow was dropped after a firewall action.
+
+Discarded alerts
+================
+
+In Firewall mode, alerts generated *after* a drop are discarded.
+These are reported with the counter ``stats.firewall.discarded_alerts``.
+Note that the drop may be caused by non-firewall rules.

doc/userguide/firewall/index.rst

@@ -5,3 +5,4 @@ Firewall Mode
 
    firewall-design
    firewall-example
+   firewall-stats