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.

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.

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.