main.zeek

DNS

Base DNS analysis script which tracks and logs DNS queries along with their responses.

Namespace:: DNS
Imports:: base/protocols/conn/removal-hooks.zeek, base/protocols/dns/consts.zeek, base/utils/queue.zeek

Summary

Runtime Options

`DNS::max_pending_msgs`: `count` `&redef`	Give up trying to match pending DNS queries or replies for a given query/transaction ID once this number of unmatched queries or replies is reached (this shouldn’t happen unless either the DNS server/resolver is broken, Zeek is not seeing all the DNS traffic, or an AXFR query response is ongoing).
`DNS::max_pending_query_ids`: `count` `&redef`	Give up trying to match pending DNS queries or replies across all query/transaction IDs once there is at least one unmatched query or reply across this number of different query IDs.
`DNS::multicast_subnets`: `set` `&redef`	Multicast subnets.

Redefinable Options

DNS::ports: set &redef

Well-known ports for DNS traffic.

Types

`DNS::Info`: `record`	The record type which contains the column fields of the DNS log.
`DNS::PendingMessages`: `table`	Yields a queue of `DNS::Info` objects for a given DNS message query/transaction ID.
`DNS::State`: `record`	A record type which tracks the status of DNS queries for a given `connection`.

Redefinitions

Log::ID: enum

The DNS logging stream identifier.

DNS::LOG

connection: record

New Fields:

connection

dns: DNS::Info &optional

dns_state: DNS::State &optional

Events

DNS::log_dns: event

An event that can be handled to access the DNS::Info record as it is sent to the logging framework.

Hooks

`DNS::do_reply`: `hook`	This is called by the specific dns_*_reply events with a “reply” which may not represent the full data available from the resource record, but it’s generally considered a summarization of the responses.
`DNS::finalize_dns`: `Conn::RemovalHook`	DNS finalization hook.
`DNS::log_policy`: `Log::PolicyHook`	A default logging policy hook for the stream.
`DNS::set_session`: `hook`	A hook that is called whenever a session is being set.

Detailed Interface

Runtime Options

DNS::max_pending_msgs 

Type:: count
Attributes:: &redef
Default:: 50

Give up trying to match pending DNS queries or replies for a given query/transaction ID once this number of unmatched queries or replies is reached (this shouldn’t happen unless either the DNS server/resolver is broken, Zeek is not seeing all the DNS traffic, or an AXFR query response is ongoing).

DNS::max_pending_query_ids 

Type:: count
Attributes:: &redef
Default:: 50

Give up trying to match pending DNS queries or replies across all query/transaction IDs once there is at least one unmatched query or reply across this number of different query IDs.

DNS::multicast_subnets 

Type:

set [subnet]

Attributes:

&redef

Default:

{
   224.0.0.0/4,
   ff00::/8
}

Multicast subnets. DNS messages sent to multicast destinations (e.g. mDNS, LLMNR) cannot be correlated by transaction ID since replies arrive on different connections. Messages to these destinations are logged individually without query/response pairing.

Redefinable Options

DNS::ports 

Type:

set [port]

Attributes:

&redef

Default:

{
   5353/udp,
   137/udp,
   5355/udp,
   53/udp,
   53/tcp
}

Well-known ports for DNS traffic.

Types

DNS::Info 

Type:

record

Fields:

ts: time &log: The earliest time at which a DNS protocol message over the associated connection is observed.

uid: string &log: A unique identifier of the connection over which DNS messages are being transferred.

id: conn_id &log: The connection’s 4-tuple of endpoint addresses/ports.

proto: transport_proto &log: The transport layer protocol of the connection.

trans_id: count &log &optional: A 16-bit identifier assigned by the program that generated the DNS query. Also used in responses to match up replies to outstanding queries.

rtt: interval &log &optional: Round trip time for the query and response. This indicates the delay between when the request was seen until the answer started.

query: string &log &optional: The domain name that is the subject of the DNS query.

qclass: count &log &optional: The QCLASS value specifying the class of the query.

qclass_name: string &log &optional: A descriptive name for the class of the query.

qtype: count &log &optional: A QTYPE value specifying the type of the query.

qtype_name: string &log &optional: A descriptive name for the type of the query.

rcode: count &log &optional: The response code value in DNS response messages.

rcode_name: string &log &optional: A descriptive name for the response code value.

AA: bool &log &default = F &optional: The Authoritative Answer bit for response messages specifies that the responding name server is an authority for the domain name in the question section.

TC: bool &log &default = F &optional: The Truncation bit specifies that the message was truncated.

RD: bool &log &default = F &optional: The Recursion Desired bit in a request message indicates that the client wants recursive service for this query.

RA: bool &log &default = F &optional: The Recursion Available bit in a response message indicates that the name server supports recursive queries.

Z: count &log &default = 0 &optional: A reserved field that is zero in queries and responses unless using DNSSEC. This field represents the 3-bit Z field using the specification from RFC 1035.

answers: vector of string &log &optional: The set of resource descriptions in the query answer.

TTLs: vector of interval &log &optional: The caching intervals of the associated RRs described by the answers field.

rejected: bool &log &default = F &optional: The DNS query was rejected by the server.

opcode: count &optional: The opcode value of the DNS request/response.

opcode_name: string &optional: A descriptive string for the opcode.

total_answers: count &optional: The total number of resource records in a reply message’s answer section.

total_replies: count &optional: The total number of resource records in a reply message’s answer, authority, and additional sections.

saw_query: bool &default = F &optional: Whether the full DNS query has been seen.

saw_reply: bool &default = F &optional: Whether the full DNS reply has been seen.

auth: set [string] &log &optional

(present if policy/protocols/dns/auth-addl.zeek is loaded)

Authoritative responses for the query.

addl: set [string] &log &optional

(present if policy/protocols/dns/auth-addl.zeek is loaded)

Additional responses for the query.

original_query: string &log &optional

(present if policy/protocols/dns/log-original-query-case.zeek is loaded)

Query with original letter casing

The record type which contains the column fields of the DNS log.

DNS::PendingMessages 

Type:: table [count] of Queue::Queue

Yields a queue of DNS::Info objects for a given DNS message query/transaction ID.

DNS::State 

Type:

record

Fields:

pending_query: DNS::Info &optional: A single query that hasn’t been matched with a response yet. Note this is maintained separate from the pending_queries field solely for performance reasons – it’s possible that pending_queries contains further queries for which a response has not yet been seen, even for the same transaction ID.

pending_queries: DNS::PendingMessages &optional: Indexed by query id, returns Info record corresponding to queries that haven’t been matched with a response yet.

pending_replies: DNS::PendingMessages &optional: Indexed by query id, returns Info record corresponding to replies that haven’t been matched with a query yet.

A record type which tracks the status of DNS queries for a given connection.

Events

DNS::log_dns 

Type:: event (rec: DNS::Info)

An event that can be handled to access the DNS::Info record as it is sent to the logging framework.

Hooks

DNS::do_reply 

Type:: hook (c: connection, msg: dns_msg, ans: dns_answer, reply: string) : bool

This is called by the specific dns_*_reply events with a “reply” which may not represent the full data available from the resource record, but it’s generally considered a summarization of the responses.

Parameters:

c – The connection record for which to fill in DNS reply data.
msg – The DNS message header information for the response.
ans – The general information of a RR response.
reply – The specific response information according to RR type/class.

DNS::finalize_dns 

Type:: Conn::RemovalHook

DNS finalization hook. Remaining DNS info may get logged when it’s called.

DNS::log_policy 

Type:: Log::PolicyHook

A default logging policy hook for the stream.

DNS::set_session 

Type:: hook (c: connection, msg: dns_msg, is_query: bool) : bool

A hook that is called whenever a session is being set. This can be used if additional initialization logic needs to happen when creating a new session value.

Parameters:

c – The connection involved in the new session.
msg – The DNS message header information.
is_query – Indicator for if this is being called for a query or a response.