:tocdepth: 3

base/protocols/dns/main.bro
===========================
.. bro:namespace:: DNS

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

:Namespace: DNS
:Imports: :doc:`base/protocols/dns/consts.bro </scripts/base/protocols/dns/consts.bro>`, :doc:`base/utils/queue.bro </scripts/base/utils/queue.bro>`
:Source File: :download:`/scripts/base/protocols/dns/main.bro`

Summary
~~~~~~~
Options
#######
=================================================================================== =======================================================================
:bro:id:`DNS::max_pending_msgs`: :bro:type:`count` :bro:attr:`&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).
:bro:id:`DNS::max_pending_query_ids`: :bro:type:`count` :bro:attr:`&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.
:bro:id:`DNS::pending_msg_expiry_interval`: :bro:type:`interval` :bro:attr:`&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
#####
=================================================== ================================================================
:bro:type:`DNS::Info`: :bro:type:`record`           The record type which contains the column fields of the DNS log.
:bro:type:`DNS::PendingMessages`: :bro:type:`table` Yields a queue of :bro:see:`DNS::Info` objects for a given
                                                    DNS message query/transaction ID.
:bro:type:`DNS::State`: :bro:type:`record`          A record type which tracks the status of DNS queries for a given
                                                    :bro:type:`connection`.
=================================================== ================================================================

Redefinitions
#############
================================================================= ==================================
:bro:type:`Log::ID`: :bro:type:`enum`                             The DNS logging stream identifier.
:bro:type:`connection`: :bro:type:`record`                        
:bro:id:`likely_server_ports`: :bro:type:`set` :bro:attr:`&redef` 
================================================================= ==================================

Events
######
========================================= ================================================================
:bro:id:`DNS::log_dns`: :bro:type:`event` An event that can be handled to access the :bro:type:`DNS::Info`
                                          record as it is sent to the logging framework.
========================================= ================================================================

Hooks
#####
============================================ =================================================================
:bro:id:`DNS::do_reply`: :bro:type:`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.
:bro:id:`DNS::set_session`: :bro:type:`hook` A hook that is called whenever a session is being set.
============================================ =================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: DNS::max_pending_msgs

   :Type: :bro:type:`count`
   :Attributes: :bro:attr:`&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).

.. bro:id:: DNS::max_pending_query_ids

   :Type: :bro:type:`count`
   :Attributes: :bro:attr:`&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.

.. bro:id:: DNS::pending_msg_expiry_interval

   :Type: :bro:type:`interval`
   :Attributes: :bro:attr:`&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
#####
.. bro:type:: DNS::Info

   :Type: :bro:type:`record`

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

      uid: :bro:type:`string` :bro:attr:`&log`
         A unique identifier of the connection over which DNS messages
         are being transferred.

      id: :bro:type:`conn_id` :bro:attr:`&log`
         The connection's 4-tuple of endpoint addresses/ports.

      proto: :bro:type:`transport_proto` :bro:attr:`&log`
         The transport layer protocol of the connection.

      trans_id: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&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.

      query: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         The domain name that is the subject of the DNS query.

      qclass: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
         The QCLASS value specifying the class of the query.

      qclass_name: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         A descriptive name for the class of the query.

      qtype: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
         A QTYPE value specifying the type of the query.

      qtype_name: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         A descriptive name for the type of the query.

      rcode: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
         The response code value in DNS response messages.

      rcode_name: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         A descriptive name for the response code value.

      AA: :bro:type:`bool` :bro:attr:`&log` :bro:attr:`&default` = ``F`` :bro:attr:`&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: :bro:type:`bool` :bro:attr:`&log` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         The Truncation bit specifies that the message was truncated.

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

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

      Z: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&default` = ``0`` :bro:attr:`&optional`
         A reserved field that is currently supposed to be zero in all
         queries and responses.

      answers: :bro:type:`vector` :bro:attr:`&log` :bro:attr:`&optional`
         The set of resource descriptions in the query answer.

      TTLs: :bro:type:`vector` :bro:attr:`&log` :bro:attr:`&optional`
         The caching intervals of the associated RRs described by the
         *answers* field.

      rejected: :bro:type:`bool` :bro:attr:`&log` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         The DNS query was rejected by the server.

      total_answers: :bro:type:`count` :bro:attr:`&optional`
         The total number of resource records in a reply message's
         answer section.

      total_replies: :bro:type:`count` :bro:attr:`&optional`
         The total number of resource records in a reply message's
         answer, authority, and additional sections.

      saw_query: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether the full DNS query has been seen.

      saw_reply: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether the full DNS reply has been seen.

      auth: :bro:type:`set` [:bro:type:`string`] :bro:attr:`&log` :bro:attr:`&optional`
         (present if :doc:`/scripts/policy/protocols/dns/auth-addl.bro` is loaded)

         Authoritative responses for the query.

      addl: :bro:type:`set` [:bro:type:`string`] :bro:attr:`&log` :bro:attr:`&optional`
         (present if :doc:`/scripts/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.

.. bro:type:: DNS::PendingMessages

   :Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`Queue::Queue`

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

.. bro:type:: DNS::State

   :Type: :bro:type:`record`

      pending_queries: :bro:type:`DNS::PendingMessages`
         Indexed by query id, returns Info record corresponding to
         queries that haven't been matched with a response yet.

      pending_replies: :bro:type:`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
   :bro:type:`connection`.

Events
######
.. bro:id:: DNS::log_dns

   :Type: :bro:type:`event` (rec: :bro:type:`DNS::Info`)

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

Hooks
#####
.. bro:id:: DNS::do_reply

   :Type: :bro:type:`hook` (c: :bro:type:`connection`, msg: :bro:type:`dns_msg`, ans: :bro:type:`dns_answer`, reply: :bro:type:`string`) : :bro:type:`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.

.. bro:id:: DNS::set_session

   :Type: :bro:type:`hook` (c: :bro:type:`connection`, msg: :bro:type:`dns_msg`, is_query: :bro:type:`bool`) : :bro:type:`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.


