From: jason taylor <jtfas90@gmail.com>
Date: Thu, 1 Feb 2024 22:39:12 +0000 (+0000)
Subject: doc: update http.header_names keyword information
X-Git-Tag: suricata-8.0.0-beta1~1535
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c2783e93918a4a5f4f41e14e363f83ebfe64a7eb;p=thirdparty%2Fsuricata.git

doc: update http.header_names keyword information

Ticket: 3025

Signed-off-by: jason taylor <jtfas90@gmail.com>
---

diff --git a/doc/userguide/rules/http-keywords.rst b/doc/userguide/rules/http-keywords.rst
index 6d8c8ba406..896cbdfb17 100644
--- a/doc/userguide/rules/http-keywords.rst
+++ b/doc/userguide/rules/http-keywords.rst
@@ -718,35 +718,75 @@ Example HTTP Response::
 http.header_names
 -----------------
 
-Inspect a buffer only containing the names of the HTTP headers. Useful
-for making sure a header is not present or testing for a certain order
-of headers.
+The ``http.header_names`` keyword is used to match on the names of the headers
+in an HTTP request or response. This is useful for checking for a headers
+presence, absence and/or header order. Use ``flow:to_server`` or
+``flow:to_client`` to force inspection of the request or response respectively.
+
+It is possible to use any of the :doc:`payload-keywords` with the
+``http.header_names`` keyword.
+
+Example HTTP Request::
+
+  GET / HTTP/1.1
+  Host: suricata.io
+  Connection: Keep-Alive
+
+Example HTTP Response::
+
+  HTTP/1.1 200 OK
+  Content-Type: text/html
+  Server: nginx/0.8.54
+
+Examples to match exactly on header order:
+
+.. container:: example-rule
 
-Buffer starts with a \\r\\n and ends with an extra \\r\\n.
+  alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP Header Names Request \
+  Example"; flow:established,to_server; :example-rule-options:`http.header_names; \
+  content:"|0d 0a|Host|0d 0a|Connection|0d 0a 0d 0a|";` bsize:22; \
+  classtype:bad-unknown; sid:110; rev:1;)
 
-Example buffer::
+  alert http $EXTERNAL_NET any -> $HOME_NET any (msg:"HTTP Header Names Response \
+  Example"; flow:established,to_client; :example-rule-options:`http.header_names; \
+  content:"|0d 0a|Content-Type|0d 0a|Server|0d 0a 0d a0|";` bsize:26; \
+  classtype:bad-unknown; sid:111; rev:1;)
 
-    \\r\\nHost\\r\\n\\r\\n
+Examples to match on header existence:
 
-Example rule::
+.. container:: example-rule
+
+  alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP Header Names Request \
+  Example 2"; flow:established,to_server; :example-rule-options:`http.header_names; \
+  content:"|0d 0a|Host|0d 0a|";` classtype:bad-unknown; sid:112; rev:1;)
+
+  alert http $EXTERNAL_NET any -> $HOME_NET any (msg:"HTTP Header Names Response \
+  Example 2"; flow:established,to_client; :example-rule-options:`http.header_names; \
+  content:"|0d 0a|Content-Type|0d 0a|";` classtype:bad-unknown; sid:113; rev:1;)
 
-    alert http any any -> any any (http.header_names; content:"|0d 0a|Host|0d 0a|"; sid:1;)
+Examples to match on header absence:
 
-Example to make sure *only* Host is present::
+.. container:: example-rule
+
+  alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP Header Names Request \
+  Example 3"; flow:established,to_server; :example-rule-options:`http.header_names; \
+  content:!"|0d 0a|User-Agent|0d 0a|";` classtype:bad-unknown; sid:114; rev:1;)
 
-    alert http any any -> any any (http.header_names; \
-            content:"|0d 0a|Host|0d 0a 0d 0a|"; sid:1;)
+  alert http $EXTERNAL_NET any -> $HOME_NET any (msg:"HTTP Header Names Response \
+  Example 3"; flow:established,to_client; :example-rule-options:`http.header_names; \
+  content:!"|0d 0a|Date|0d 0a|";` classtype:bad-unknown; sid:115; rev:1;)
 
-Example to make sure *User-Agent* is directly after *Host*::
+Example to check for the ``User-Agent`` header and that the ``Host`` header is
+after ``User-Agent`` but not necessarily directly after.
 
-    alert http any any -> any any (http.header_names; \
-            content:"|0d 0a|Host|0d 0a|User-Agent|0d 0a|"; sid:1;)
+.. container:: example-rule
 
-Example to make sure *User-Agent* is after *Host*, but not necessarily directly after::
+  alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP Header Names Request \
+  Example 4"; flow:established,to_server; :example-rule-options:`http.header_names; \
+  content:"|0d 0a|Host|0d 0a|";` content:"User-Agent|0d 0a|"; distance:-2; \
+  classtype:bad-unknown; sid:114; rev:1;)
 
-    alert http any any -> any any (http.header_names; \
-            content:"|0d 0a|Host|0d 0a|"; content:"|0a 0d|User-Agent|0d 0a|"; \
-            distance:-2; sid:1;)
+.. note:: ``http.header_names`` starts with a \\r\\n and ends with an extra \\r\\n.
 
 .. _http.request_body: