mirror of
https://github.com/zeek/zeek.git
synced 2025-10-03 23:28:20 +00:00
7e9d48f532
The broxygen-generated files now live in the git repo, have tests that check that they are up-to-date, and a script to re-generate them on-demand.
268 lines
12 KiB
ReStructuredText
268 lines
12 KiB
ReStructuredText
: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>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Runtime 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.
|
|
========================================================================== =======================================================================
|
|
|
|
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
|
|
~~~~~~~~~~~~~~~~~~
|
|
Runtime 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.
|
|
|
|
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.
|
|
|
|
rtt: :bro:type:`interval` :bro:attr:`&log` :bro:attr:`&optional`
|
|
Round trip time for the query and response. This indicates
|
|
the delay between when the request was seen until the
|
|
answer started.
|
|
|
|
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 usually zero in
|
|
queries and responses.
|
|
|
|
answers: :bro:type:`vector` of :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The set of resource descriptions in the query answer.
|
|
|
|
TTLs: :bro:type:`vector` of :bro:type:`interval` :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.
|
|
|
|
|