base/protocols/dns/main.bro

DNS

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

Namespace:DNS Imports:base/frameworks/notice/weird.bro, base/protocols/dns/consts.bro, base/utils/queue.bro Source File:/scripts/base/protocols/dns/main.bro

Summary

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, Bro 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::pending_msg_expiry_interval: interval &redef	The amount of time that DNS queries or replies for a given query/transaction ID are allowed to be queued while waiting for a matching reply or query.

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
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::set_session: hook	A hook that is called whenever a session is being set.

Detailed Interface

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, Bro 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::pending_msg_expiry_interval

Type:interval Attributes:&redef Default:2.0 mins

The amount of time that DNS queries or replies for a given query/transaction ID are allowed to be queued while waiting for a matching reply or query.

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 usually zero in queries and responses.

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.bro is loaded)

Authoritative responses for the query.

addl: set [string] &log &optional

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

Additional responses for the query.

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_queries: DNS::PendingMessages

Indexed by query id, returns Info record corresponding to queries that haven’t been matched with a response yet.

pending_replies: DNS::PendingMessages

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.

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::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.

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.