From 117b8f78cbc6e1b005aec81ebf96850633005207 Mon Sep 17 00:00:00 2001
From: Jason Ish <jason.ish@oisf.net>
Date: Wed, 15 Nov 2023 12:11:51 -0600
Subject: [PATCH] doc/userguide: document dns.query.name, dns.answer.name

With some other minor cleanups in the DNS keyword section.
---
 doc/userguide/rules/dns-keywords.rst | 63 +++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 14 deletions(-)

diff --git a/doc/userguide/rules/dns-keywords.rst b/doc/userguide/rules/dns-keywords.rst
index e62a25d40bed..a514ae25195b 100644
--- a/doc/userguide/rules/dns-keywords.rst
+++ b/doc/userguide/rules/dns-keywords.rst
@@ -1,10 +1,27 @@
 DNS Keywords
 ============
 
-There are some more content modifiers (If you are unfamiliar with
-content modifiers, please visit the page :doc:`payload-keywords` These
-ones make sure the signature checks a specific part of the
-network-traffic.
+Suricata supports sticky buffers as well as keywords for efficiently
+matching on specific fields in DNS messages.
+
+Note that sticky buffers are expected to be followed by one or more
+:doc:`payload-keywords`.
+
+dns.answer.name
+---------------
+
+``dns.answer.name`` is a sticky buffer that is used to look at the
+name field in DNS answer resource records.
+
+``dns.answer.name`` will look at both requests and responses, so
+``flow`` is recommended to confine to a specific direction.
+
+The buffer being matched on contains the complete re-assembled
+resource name, for example "www.suricata.io".
+
+``dns.answer.name`` supports :doc:`multi-buffer-matching`.
+
+``dns.answer.name`` was introduced in Suricata 8.0.0.
 
 dns.opcode
 ----------
@@ -32,20 +49,26 @@ Match on DNS requests where the **opcode** is NOT 0::
 dns.query
 ---------
 
-With **dns.query** the DNS request queries are inspected. The dns.query
-keyword works a bit different from the normal content modifiers. When
-used in a rule all contents following it are affected by it.  Example:
+``dns.query`` is a sticky buffer that is used to inspect DNS query
+names in DNS request messages. Example::
 
-  alert dns any any -> any any (msg:"Test dns.query option";
-  dns.query; content:"google"; nocase; sid:1;)
+  alert dns any any -> any any (msg:"Test dns.query option"; dns.query; content:"google"; nocase; sid:1;)
+
+Being a sticky buffer, payload keywords such as content are to be used after ``dns.query``:
 
 .. image:: dns-keywords/dns_query.png
 
-The **dns.query** keyword affects all following contents, until pkt_data
-is used or it reaches the end of the rule.
+The ``dns.query`` keyword affects all following contents, until
+pkt_data is used or it reaches the end of the rule.
 
 .. note:: **dns.query** is equivalent to the older **dns_query**.
 
+.. note:: **dns.query** will only match on DNS request messages, to
+          also match on DNS response message, see
+          `dns.query.name`_.
+
+``dns.query.name`` supports :doc:`multi-buffer-matching`.
+
 Normalized Buffer
 ~~~~~~~~~~~~~~~~~
 
@@ -68,7 +91,19 @@ DNS query on the wire (snippet)::
 
     mail.google.com
 
-Multiple Buffer Matching
-~~~~~~~~~~~~~~~~~~~~~~~~
+dns.query.name
+---------------
+
+``dns.query.name`` is a sticky buffer that is used to look at the name
+field in DNS query (question) resource records. It is nearly identical
+to ``dns.query`` but supports both DNS requests and responses.
+
+``dns.query.name`` will look at both requests and responses, so
+``flow`` is recommended to confine to a specific direction.
+
+The buffer being matched on contains the complete re-assembled
+resource name, for example "www.suricata.io".
+
+``dns.query.name`` supports :doc:`multi-buffer-matching`.
 
-``dns.query`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
\ No newline at end of file
+``dns.query.name`` was introduced in Suricata 8.0.0.