Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

dns: more keywords; plus some eve/keyword parity tooling - v6 #12652

Draft
wants to merge 13 commits into
base: master
Choose a base branch
from
+1,021 −275
Draft

dns: more keywords; plus some eve/keyword parity tooling - v6 #12652

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
15dd20d
dns: add dns.response sticky buffer
scrivs86 Aug 19, 2024
f58267e
doc/userguide: document dns.response
scrivs86 Aug 20, 2024
364057c
dns: rename dns.response keyword to dns.response.rrname
jasonish Jan 28, 2025
5702306
detect-dns-response: disable clang-format around byte arrays
jasonish Jan 28, 2025
78e9c45
dns: refactor function to get rrname to be safe
jasonish Jan 28, 2025
b58ed81
detect: split new keyword id from registration
jasonish Jan 17, 2025
3fe80bd
dns: add keywords for additionals and authorities rrnames
jasonish Jan 28, 2025
76f5697
schema: add an object for mapping fields to keywords
jasonish Feb 19, 2025
38f5fda
script/eve-parity: add script for checking eve/keyword parity
jasonish Feb 19, 2025
9ba7a28
detect-dns-response: remove unit tests
jasonish Feb 20, 2025
298262b
schema: mark "stats" and "drop" as having no keywords
jasonish Feb 20, 2025
41e2534
schema: mark dns.version and dns.grouped as having no keywords
jasonish Feb 20, 2025
762e73e
eve-parity: skip transform keywords
jasonish Feb 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 87 additions & 26 deletions doc/userguide/rules/dns-keywords.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,6 @@ 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
----------

Expand Down Expand Up @@ -134,9 +118,9 @@ pkt_data is used or it reaches the end of the rule.

.. note:: **dns.query** will only match on DNS request messages, to
also match on DNS response message, see
`dns.query.name`_.
`dns.queries.rrname`_.

``dns.query.name`` supports :doc:`multi-buffer-matching`.
``dns.queries.rrname`` supports :doc:`multi-buffer-matching`.

Normalized Buffer
~~~~~~~~~~~~~~~~~
Expand All @@ -160,19 +144,96 @@ DNS query on the wire (snippet)::

mail.google.com

dns.query.name
---------------
dns.queries.rrname
------------------

``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.queries.rrname`` 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
``dns.queries.rrname`` 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.queries.rrname`` supports :doc:`multi-buffer-matching`.

``dns.queries.rrname`` was introduced in Suricata 8.0.0.

dns.answers.rrname
------------------

``dns.answers.rrname`` is a sticky buffer that is used to look at the
name field in DNS answer resource records.

``dns.answers.rrname`` 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.answers.rrname`` supports :doc:`multi-buffer-matching`.

``dns.answers.rrname`` was introduced in Suricata 8.0.0.

dns.authorities.rrname
----------------------

``dns.authorities.rrname`` is a sticky buffer that is used to look at the
rrname field in DNS authority resource records.

``dns.authorities.rrname`` 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.authorities.rrname`` supports :doc:`multi-buffer-matching`.

``dns.authorities.rrname`` was introduced in Suricata 8.0.0.

dns.additionals.rrname
----------------------

``dns.additionals.rrname`` is a sticky buffer that is used to look at
the rrname field in DNS additional resource records.

``dns.additionals.rrname`` 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.additionals.rrname`` supports :doc:`multi-buffer-matching`.

``dns.additionals.rrname`` was introduced in Suricata 8.0.0.

dns.response.rrname
-------------------

``dns.response.rrname`` is a sticky buffer that is used to look at all name
and rdata fields of DNS response (answer) resource records that are
represented as a resource name (hostname). It supports inspecting all
DNS response sections. Example::

alert dns any any -> any any (msg:"Test dns.response.rrname option"; \
dns.response.rrname; content:"google"; nocase; sid:1;)

``rdata`` field matching supports a subset of types that contain
domain name structured data, for example: "www.suricata.io". The list
of types inspected is:

* CNAME
* PTR
* MX
* NS
* SOA (mname data: primary name server)

The buffer being matched on contains the complete re-assembled
resource name, for example "www.suricata.io".

``dns.response.rrname`` supports :doc:`multi-buffer-matching`.

``dns.query.name`` was introduced in Suricata 8.0.0.
``dns.response.rrname`` was introduced in Suricata 8.0.0.
110 changes: 92 additions & 18 deletions etc/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,8 @@
"type": "integer"
},
"tx_guessed": {
"description": "the signature that triggered this alert didn't tie to a transaction, so the transaction (and metadata) logged is a forced estimation and may not be the one you expect",
"description":
"the signature that triggered this alert didn't tie to a transaction, so the transaction (and metadata) logged is a forced estimation and may not be the one you expect",
"type": "boolean"
},
"files": {
Expand Down Expand Up @@ -1033,7 +1034,12 @@
"type": "boolean"
},
"rcode": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.rcode"
]
}
},
"rd": {
"type": "boolean"
Expand All @@ -1052,7 +1058,10 @@
},
"version": {
"description": "The version of this EVE DNS event",
"type": "integer"
"type": "integer",
"suricata": {
"keywords": false
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it good to have this suricata.keyword that can either be a boolean or an array ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok with it, unless its going into something the hardcodes a schema based on whats first seen., so not in eve. Prevents conflict with another field as well..

"keywords": ["one", "two"],
"no-keywords": "true",

}
},
"opcode": {
"description": "DNS opcode as an integer",
Expand All @@ -1069,10 +1078,21 @@
"type": "object",
"properties": {
"rdata": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.response.rrname"
]
}
},
"rrname": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.answers.rrname",
"dns.response.rrname"
]
}
},
"rrtype": {
"type": "string"
Expand Down Expand Up @@ -1173,10 +1193,21 @@
"type": "integer"
},
"rrname": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.queries.rrname",
"dns.query"
]
}
},
"rrtype": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.rrtype"
]
}
},
"tx_id": {
"type": "integer"
Expand All @@ -1189,10 +1220,16 @@
},
"opcode": {
"description": "DNS opcode as an integer",
"type": "integer"
"type": "integer",
"suricata": {
"keywords": [
"dns.opcode"
]
}
},
"rrname_truncated": {
"description": "Set to true if the rrname was too long and truncated by Suricata",
"description":
"Set to true if the rrname was too long and truncated by Suricata",
"type": "boolean"
}
},
Expand Down Expand Up @@ -1246,7 +1283,11 @@
"additionalProperties": false
},
"grouped": {
"desription": "DNS fields grouped by type: alternative format, no direct keywords",
"type": "object",
"suricata": {
"keywords": false
},
"properties": {
"A": {
"type": "array",
Expand Down Expand Up @@ -1365,6 +1406,9 @@
},
"drop": {
"type": "object",
"suricata": {
"keywords": false
},
"properties": {
"ack": {
"type": "boolean"
Expand Down Expand Up @@ -4561,6 +4605,9 @@
"stats": {
"type": "object",
"optional": true,
"suricata": {
"keywords": false
},
"properties": {
"uptime": {
"description": "Suricata engine's uptime",
Expand Down Expand Up @@ -6613,7 +6660,8 @@
"type": "integer"
},
"tc_urgent_oob_data": {
"description": "Number of Out-of-Band bytes sent by server using TCP urgent packets",
"description":
"Number of Out-of-Band bytes sent by server using TCP urgent packets",
"type": "integer"
},
"tcp_flags": {
Expand All @@ -6632,7 +6680,8 @@
"type": "integer"
},
"ts_urgent_oob_data": {
"description": "Number of Out-of-Band bytes sent by client using TCP urgent packets",
"description":
"Number of Out-of-Band bytes sent by client using TCP urgent packets",
"type": "integer"
},
"urg": {
Expand Down Expand Up @@ -6901,7 +6950,8 @@
"type": "integer"
},
"mname_truncated": {
"description": "Set to true if the mname was too long and truncated by Suricata",
"description":
"Set to true if the mname was too long and truncated by Suricata",
"type": "boolean"
}
},
Expand All @@ -6914,10 +6964,21 @@
"type": "object",
"properties": {
"rdata": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.response.rrname"
]
}
},
"rrname": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.authorities.rrname",
"dns.response.rrname"
]
}
},
"rrtype": {
"type": "string"
Expand All @@ -6929,11 +6990,13 @@
"$ref": "#/$defs/dns.soa"
},
"rdata_truncated": {
"description": "Set to true if the rdata was too long and truncated by Suricata",
"description":
"Set to true if the rdata was too long and truncated by Suricata",
"type": "boolean"
},
"rrname_truncated": {
"description": "Set to true if the rrname was too long and truncated by Suricata",
"description":
"Set to true if the rrname was too long and truncated by Suricata",
"type": "boolean"
}
},
Expand All @@ -6947,10 +7010,21 @@
"type": "object",
"properties": {
"rdata": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.response.rrname"
]
}
},
"rrname": {
"type": "string"
"type": "string",
"suricata": {
"keywords": [
"dns.additionals.rrname",
"dns.response.rrname"
]
}
},
"rrtype": {
"type": "string"
Expand Down
Loading
Loading