From 2e2132a16f91a610ef3278b560cbcfc701b9ab31 Mon Sep 17 00:00:00 2001 From: Victor Julien Date: Tue, 17 Mar 2026 15:23:38 +0100 Subject: [PATCH] doc/userguide: improve pkthdr docs --- doc/userguide/rules/intro.rst | 16 +++++++++++++++- doc/userguide/upgrade.rst | 3 +++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst index 212c2485e7..fa10ece24a 100644 --- a/doc/userguide/rules/intro.rst +++ b/doc/userguide/rules/intro.rst @@ -78,7 +78,7 @@ The protocol value will limit what protocol(s) the signature will be applied to: * icmpv6 * ipv4/ip4 - just IPv4 * ipv6/ip6 - just IPv6 -* pkthdr (for inspecting packets w/o invalid headers) +* pkthdr (for matching on packets with decoder events) There are a couple of additional TCP related protocol options: @@ -133,6 +133,20 @@ is enabled in the configuration file, suricata.yaml. If you have a signature with the protocol declared as 'http', Suricata makes sure the signature will only match if the TCP stream contains http traffic. +Matching on non-IP packets +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Traditionally the rule language was only about matching on IP packets. For packets +that caused decoder events in the layers before IP a special protocol `pkthdr` was +added. + +.. container:: example-rule + + alert :example-rule-emphasis:`pkthdr` any any -> any any (msg:"SURICATA IPv4 packet too small"; decode-event:ipv4.pkt_too_small; classtype:protocol-command-decode; sid:2200000; rev:2;) + +Up until Suricata 8 this protocol was an alias for `alert ip`, but in Suricata 9 it +is only to be used in decoder event rules. + Explicit rule hooks ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst index 723c8837b7..70619367c1 100644 --- a/doc/userguide/upgrade.rst +++ b/doc/userguide/upgrade.rst @@ -84,6 +84,9 @@ Other Changes ``app-layer.protocols.sip.tcp.enabled`` would be read and preferred over ``app-layer.protocols.sip.enabled``. +- `alert pkthdr` is now only available for decoder event rules. Previously it acted + like `alert ip`. + Changes for Library Users and Plugin Developers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~