base/protocols/dns/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.

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.

connection: record

New Fields

connection

dns: DNS::Info &optional

dns_state: DNS::State &optional

likely_server_ports: set &redef

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.

Types

DNS::Info
Type

record

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.

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

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.