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
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). |
|
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
The record type which contains the column fields of the DNS log. |
|
Yields a queue of |
|
A record type which tracks the status of DNS queries for a given
|
Redefinitions
The DNS logging stream identifier. |
|
|
|
Events
An event that can be handled to access the |
Hooks
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 finalization hook. |
|
A default logging policy hook for the stream. |
|
A hook that is called whenever a session is being set. |
Detailed Interface
Runtime Options
- DNS::max_pending_msgs
-
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
-
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:
-
- 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
ofstring
&log
&optional
The set of resource descriptions in the query answer.
- TTLs:
vector
ofinterval
&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
- ts:
The record type which contains the column fields of the DNS log.
- DNS::PendingMessages
- Type:
table
[count
] ofQueue::Queue
Yields a queue of
DNS::Info
objects for a given DNS message query/transaction ID.
- DNS::State
- Type:
-
- 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.
- pending_query:
A record type which tracks the status of DNS queries for a given
connection
.
Events
- DNS::log_dns
-
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:
DNS finalization hook. Remaining DNS info may get logged when it’s called.
- DNS::log_policy
- Type:
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.