DNS

Handler type: dns

• Example of policy
• Metrics Group
• Filters
• Configurations

Example of policy with input pcap and handler DNS(v2)

handlers:
  window_config:
    deep_sample_rate: 100
    num_periods: 5
  modules:
    default_dns:
      type: dns
      require_version: "2.0"
      config:
        public_suffix_list: true
        topn_count: 25
        topn_percentile_threshold: 10
      filter:
        only_rcode: 0
        only_dnssec_response: true
        answer_count: 1
        only_qtype: [1, 2]
        only_qname_suffix: [".example.com", ".example.net"]
        geoloc_notfound: false
        asn_notfound: false
        dnstap_msg_type: "auth"
      metric_groups:
        enable:
          - cardinality
          - counters
          - quantiles
          - top_rcodes
          - top_qnames
          - top_qtypes
        disable:
          - top_size
          - top_ports
          - xact_times
          - top_ecs
input:
  input_type: pcap
  tap: default_pcap
  filter:
    bpf: udp port 53
  config:
    iface: wlo1
    host_spec: 192.168.1.167/24
    pcap_source: libpcap
    debug: true
config:
    merge_like_handlers: true
kind: collection

Monitoring authoritative DNS

For a server answering queries for its own zones, public_suffix_list groups qnames by registrable domain rather than by every distinct label, and the top_ecs metric group surfaces which client subnets the queries carry. Narrowing the capture to port 53 keeps the handler off unrelated traffic. Both settings exist in the 1.0 handler too; drop require_version to use it.

handlers:
  modules:
    dns_traffic:
      type: dns
      require_version: "2.0"
      config:
        public_suffix_list: true
      metric_groups:
        enable:
          - top_ecs
    net_traffic:
      type: net
input:
  input_type: pcap
  tap: dns_pcap
  filter:
    bpf: "port 53"
kind: collection

Metrics Group (2.0)

• Check the dns metrics belonging to each group

Filters (2.0)

only_rcode (v2)

Type: int or str[]

Input: PCAP

When a DNS server returns a response to a query made, one of the properties of the response is the "response code" (rcode), a code that describes what happened to the query that was made.

Most response codes indicate why the query failed and when the query succeeds, the return is an RCODE:0, whose name is NOERROR.

Supported types are in the table below (if you use any other code that is not in the table below, your policy will fail):

The only_rcode filter usage syntax is:

only_rcode: int

or

only_rcode:
  - str
  - str

A single response code may be given as a bare integer. A list may mix numeric codes, written as strings, with the names from the table above, which are matched case insensitively.

only_rcode: 3

only_rcode:
  - "3"
  - nxdomain
  - SRVFAIL

exclude_noerror (v2)

Type: bool

Input: PCAP

You may still want to filter out only responses with any kind of error. For this, there is the exclude_noerror filter, which removes from its results all responses that did not return any type of error. The exclude_noerror filter usage syntax is:

exclude_noerror: true

Attention: exclude_noerror is dominant over only_rcode, that is, if exclude_noerror is true then even if only_rcode is set, the results will be composed only of responses that returned some kind of error. NOERROR responses are dropped.

only_dnssec_response (v2)

Type: bool

Input: PCAP

When you make a DNS query, the response you get may have a DNSSEC signature, which authenticates that DNS records originate from an authorized sender, thus protecting DNS from falsified information.

To filter only responses signed by an authorized sender, use: The only_dnssec_response filter usage syntax is:

only_dnssec_response: true

answer_count (v2)

Type: int

Input: PCAP

One of the properties present in the query message structure is Answer RRs, which is the count of entries in the responses section (RR stands for “resource record”).

The number of answers in the query is always zero, as a query message has only questions and no answers, and when the server sends the answer to that query, the value is set to the amount of entries in the answers section.

The answer_count filter usage syntax is:

answer_count: int

with the int referring to the desired amount of answer.

Note that any value greater than zero that is defined will exclude queries from the results, since in queries the number of answers is always 0.

As the answers count of queries is 0, whenever the value set for the answer_count is 0, both queries and responses will compose the result.

A special case is the concept of NODATA, which is one of the possible returns to a query made to a DNS server is known as. This happens when the query is successful (so rcode:0), but there is no data as a response, so the number of answers is 0.

In this case, to have in the results only the cases of NODATA, that is, the responses, the filter must be used together with the filter exclude_noerror.

Important information is that only one answer_count is possible for each handler. So, in order to have multiple counts on the same policy, multiple handlers must be created, each with an amount of answers.

only_qtype (v2)

Type: str[]

Input: PCAP

DNS record types are records that provide important information about a hostname or domain. Supported default types can be seen here.

The only_qtype filter usage syntax is:

only_qtype:
  - str
  - str

If you want to filter only IPV4 record types, for example, you should use:

only_qtype:
  - "A"

or

only_qtype:
  - 1

Multiple types are also supported and both queries and responses that have any of the values in the array will be considered.

only_qtype:
  - 1
  - 2
  - "A"

only_qname (v2)

Type: str[]

Input: PCAP

The only_qname filters dns packets based on queries and responses whose names exactly matches the strings present in the array.

The only_qname filter usage syntax is:

only_qname:
  - str
  - str

Examples:

only_qname:
  - www.example.com
  - .example.net

only_qname_suffix (v2)

Type: str[]

Input: PCAP

The only_qname_suffix filters queries and responses whose endings (suffixes) of the names match the strings present in the array.

The only_qname_suffix filter usage syntax is:

only_qname_suffix:
  - str
  - str

Examples:

only_qname_suffix:
  - .example.com

or

only_qname_suffix:
  - example.com
  - .example.net

geoloc_notfound (v2)

Type: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the geolocation of where the query is being made. When the Subnet refers to a region found in the standard databases, the city, state and country (approximated) are returned. However, when based on the subnet it is not possible to determine the geolocation, a not found is returned.

The geoloc_notfound filter only keeps responses whose geolocations were not found.

The geoloc_notfound filter usage syntax is:

geoloc_notfound: true

asn_notfound (v2)

Type: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the ASN (Autonomous System Number). When the IP of the subnet belongs to some not known ASN in the standard databases, a not found is returned.

The asn_notfound filter only keeps responses whose asn were not found.

The asn_notfound filter usage syntax is:

asn_notfound: true

only_xact_directions (v2)

Not currently usable. The 2.0 handler implements this filter but does not list it among its accepted keys, so a policy that sets it is rejected with only_xact_directions is an invalid/unsupported config or filter. Tracked against pktvisor; the filter is documented here for when that is corrected.

Type: str[]

Input: PCAP

Filters metrics according to the direction of the transaction. Options are: in, out and unknown.

only_xact_directions:
  - str
  - str

Example:

only_xact_directions:
- in
- unknown

dnstap_msg_type (v2)

Type: str

Input: DNSTAP

With a dnstap protocol it is possible to know the type of message that must be resolved in the request to the server. This filter therefore allows you to filter by response types. Supported message types are: auth, resolver, client, forwarder, stub, tool and update.

The dnstap_msg_type filter usage syntax is:

dnstap_msg_type: str

Example:

dnstap_msg_type: auth

Example of policy with input pcap and handler DNS(v1)

handlers:
  window_config:
    deep_sample_rate: 100
    num_periods: 5
  modules:
    default_dns:
      type: dns
      config:
        public_suffix_list: true
        topn_count: 25
        topn_percentile_threshold: 10
      filter:
        only_rcode: 0
        only_dnssec_response: true
        answer_count: 1
        only_qtype: [1, 2]
        only_qname_suffix: [".example.com", ".example.net"]
        geoloc_notfound: false
        asn_notfound: false
        dnstap_msg_type: "auth"
      metric_groups:
        enable:
          - top_ecs
          - top_qnames_details
        disable:
          - histograms
          - quantiles
          - cardinality
          - counters
          - dns_transaction
          - top_qnames
          - top_ports
input:
  input_type: pcap
  tap: default_pcap
  filter:
    bpf: udp port 53
  config:
    iface: wlo1
    host_spec: 192.168.1.167/24
    pcap_source: libpcap
    debug: true
config:
    merge_like_handlers: true
kind: collection

Metrics Group (1.0)

• Check the dns metrics belonging to each group

Filters (1.0)

only_rcode (v1)

Type: int or str[]

Input: PCAP

When a DNS server returns a response to a query made, one of the properties of the response is the "response code" (rcode), a code that describes what happened to the query that was made.

Most response codes indicate why the query failed and when the query succeeds, the return is an RCODE:0, whose name is NOERROR.

Supported types are in the table below (if you use any other code that is not in the table below, your policy will fail):

The only_rcode filter usage syntax is:

only_rcode: int

or

only_rcode:
  - str
  - str

A single response code may be given as a bare integer. A list may mix numeric codes, written as strings, with the names from the table above, which are matched case insensitively.

only_rcode: 3

only_rcode:
  - "3"
  - nxdomain
  - SRVFAIL

exclude_noerror (v1)

Type: bool

Input: PCAP

The exclude_noerror filter removes from its results all responses that did not return any type of error (RCODE=0)

The exclude_noerror filter usage syntax is:

exclude_noerror: true

exclude_noerror takes precedence over the "only_rcode" filter. If exclude_noerror = True, then the results will be composed only of responses WITH an error, that is, responses with RCODE=0 will not be returned.

only_dnssec_response (v1)

Type: bool

Input: PCAP

When you make a DNS query, the response you get may have a DNSSEC signature, which authenticates that DNS records originate from an authorized sender, thus protecting DNS from falsified information.

To filter only responses signed by an authorized sender, use: The only_dnssec_response filter usage syntax is:

only_dnssec_response: true

answer_count (v1)

Type: int

Input: PCAP

One of the properties present in the query message structure is Answer RRs, which is the count of entries in the responses section (RR stands for “resource record”).

The number of answers in the query is always zero, as a query message has only questions and no answers, and when the server sends the answer to that query, the value is set to the amount of entries in the answers section.

The answer_count filter usage syntax is:

answer_count: int

with the int referring to the desired amount of answer.

Note that any value greater than zero that is defined will exclude queries from the results, since in queries the number of answers is always 0.

As the answers count of queries is 0, whenever the value set for the answer_count is 0, both queries and responses will compose the result.

A special case is the concept of NODATA, which is one of the possible returns to a query made to a DNS server is known as. This happens when the query is successful (so rcode:0), but there is no data as a response, so the number of answers is 0.

In this case, to have in the results only the cases of NODATA, that is, the responses, the filter must be used together with the filter exclude_noerror.

Important information is that only one answer_count is possible for each handler. So, in order to have multiple counts on the same policy, multiple handlers must be created, each with an amount of answers.

only_qtype (v1)

Type: str[]

Input: PCAP

DNS record types are records that provide important information about a hostname or domain. Supported default types can be seen here.

The only_qtype filter usage syntax is:

only_qtype:
  - str
  - str

If you want to filter only IPV4 record types, for example, you should use:

only_qtype:
  - "A"

or

only_qtype:
  - 1

Multiple types are also supported and both queries and responses that have any of the values in the array will be considered.

only_qtype:
  - 1
  - 2
  - "A"

only_qname (v1)

Type: str[]

Input: PCAP

The only_qname filters dns packets based on queries and responses whose names exactly matches the strings present in the array.

The only_qname filter usage syntax is:

only_qname:
  - str
  - str

Examples:

only_qname:
  - www.example.com
  - .example.net

only_qname_suffix (v1)

Type: str[]

Input: PCAP

The only_qname_suffix filters queries and responses whose endings (suffixes) of the names match the strings present in the array.

The only_qname_suffix filter usage syntax is:

only_qname_suffix:
  - str
  - str

Examples:

only_qname_suffix:
  - .example.com

or

only_qname_suffix:
  - example.com
  - .example.net

geoloc_notfound (v1)

Type: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the geolocation of where the query is being made. When the Subnet refers to a region found in the standard databases, the city, state and country (approximated) are returned. However, when based on the subnet it is not possible to determine the geolocation, a not found is returned.

The geoloc_notfound filter only keeps responses whose geolocations were not found.

The geoloc_notfound filter usage syntax is:

geoloc_notfound: true

asn_notfound (v1)

Type: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the ASN (Autonomous System Number). When the IP of the subnet belongs to some not known ASN in the standard databases, a not found is returned.

The asn_notfound filter only keeps responses whose asn were not found.

The asn_notfound filter usage syntax is:

asn_notfound: true

only_queries (v1)

Type: bool

Input: PCAP

The only_queries filters out all dns response packets and its usage syntax is:

only_queries: true

only_responses (v1)

Type: bool

Input: PCAP

The only_responses filters out all dns queries packets and its usage syntax is:

only_responses: true

dnstap_msg_type (v1)

Type: str

Input: DNSTAP

With a dnstap protocol it is possible to know the type of message that must be resolved in the request to the server. This filter therefore allows you to filter by response types. Supported message types are: auth, resolver, client, forwarder, stub, tool and update.

The dnstap_msg_type filter usage syntax is:

dnstap_msg_type: str

Example:

dnstap_msg_type: auth

Configurations

• public_suffix_list: bool.
• recorded_stream. Presence-based.
• xact_ttl_secs: int.
• xact_ttl_ms: int.
• Abstract configurations.

public_suffix_list

Some names to be resolved by a dns server have public suffixes. These suffixes cause metrics to be generated considering non-relevant data.

The example below illustrates the benefit of using this type of configuration. The qnames consider each part of the name to be resolved. When a name has a public suffix, generic information is generated. Note that in the standard configuration, Qname2 and Qname3 are the same for both domains. With the public suffix setting true (which makes the entire public part be considered as a single part), Qname3 already displays relevant information about the name.

The list of suffixes considered public can be accessed here.

The public_suffix_list configuration usage syntax is:

public_suffix_list: true

recorded_stream

The key is presence-based: the handler checks only whether recorded_stream is set, never its value, so recorded_stream: false still enables it. Omit the key entirely to disable.

This configuration is useful when a pcap_file is used in taps/input configuration. Set it to True when you want to load an offline traffic (from a pcap_file).

The recorded_stream configuration usage syntax is:

recorded_stream: true

xact_ttl_ms or xact_ttl_secs

Type: int

Both configurations have the same functionality, that is, defines the time to live of transactions, and only change the unit of measurement to be configured. This configuration causes the metrics to be generated for complete transactions (query and response) within the established time limit.

• xact_ttl_ms: Defines the time to live of transactions in milliseconds.
• xact_ttl_secs: Defines the time to live of transactions in seconds.

Note that xact_ttl_ms is dominant over xact_ttl_secs, that is, if xact_ttl_ms exists, even if xact_ttl_secs also exists, the value of xact_ttl_ms will be considered.

The xact_ttl_ms or xact_ttl_secs configuration usage syntax is:

xact_ttl_ms: 5000

or

xact_ttl_secs: 5