Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-06 08:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Change doc/ subdir into a git submodule

Browse source 
The docs now live at https://github.com/zeek/zeek-docs
This commit is contained in:
Jon Siwek 2019-01-17 14:09:29 -06:00
parent 0d685efbf5
commit 2ff746fea7
693 changed files with 26 additions and 105609 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/scripts/base/protocols/dns/__load__.bro.rst
View file

@ -1,14 +0,0 @@
:tocdepth: 3
base/protocols/dns/__load__.bro
===============================
:Imports: :doc:`base/protocols/dns/consts.bro </scripts/base/protocols/dns/consts.bro>`, :doc:`base/protocols/dns/main.bro </scripts/base/protocols/dns/main.bro>`
Summary
~~~~~~~
Detailed Interface
~~~~~~~~~~~~~~~~~~

264
doc/scripts/base/protocols/dns/consts.bro.rst
View file

@ -1,264 +0,0 @@
:tocdepth: 3
base/protocols/dns/consts.bro
=============================
.. bro:namespace:: DNS
Types, errors, and fields for analyzing DNS data. A helper file
for DNS analysis scripts.
:Namespace: DNS
Summary
~~~~~~~
Constants
#########
=============================================================================================================== ======================================================================
:bro:id:`DNS::ANY`: :bro:type:`count` A QTYPE value describing a request for all records.
:bro:id:`DNS::EDNS`: :bro:type:`count` An OPT RR TYPE value described by EDNS.
:bro:id:`DNS::PTR`: :bro:type:`count` RR TYPE value for a domain name pointer.
:bro:id:`DNS::algorithms`: :bro:type:`table` :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional` Possible values of the algorithms used in DNSKEY, DS and RRSIG records
:bro:id:`DNS::base_errors`: :bro:type:`table` :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional` Errors used for non-TSIG/EDNS types.
:bro:id:`DNS::classes`: :bro:type:`table` :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional` Possible values of the CLASS field in resource records or QCLASS
field in query messages.
:bro:id:`DNS::digests`: :bro:type:`table` :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional` Possible digest types used in DNSSEC.
:bro:id:`DNS::edns_zfield`: :bro:type:`table` :bro:attr:`&default` = ``"?"`` :bro:attr:`&optional` This deciphers EDNS Z field values.
:bro:id:`DNS::query_types`: :bro:type:`table` :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional` Mapping of DNS query type codes to human readable string
representation.
=============================================================================================================== ======================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Constants
#########
.. bro:id:: DNS::ANY
:Type: :bro:type:`count`
:Default: ``255``
A QTYPE value describing a request for all records.
.. bro:id:: DNS::EDNS
:Type: :bro:type:`count`
:Default: ``41``
An OPT RR TYPE value described by EDNS.
.. bro:id:: DNS::PTR
:Type: :bro:type:`count`
:Default: ``12``
RR TYPE value for a domain name pointer.
.. bro:id:: DNS::algorithms
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional`
:Default:
::
{
[2] = "Diffie_Hellman",
[6] = "DSA_NSEC3_SHA1",
[14] = "ECDSA_curveP384withSHA384",
[4] = "Elliptic_Curve",
[1] = "RSA_MD5",
[8] = "RSA_SHA256",
[7] = "RSA_SHA1_NSEC3_SHA1",
[15] = "Ed25519",
[252] = "Indirect",
[254] = "PrivateOID",
[255] = "reserved255",
[5] = "RSA_SHA1",
[10] = "RSA_SHA512",
[253] = "PrivateDNS",
[0] = "reserved0",
[3] = "DSA_SHA1",
[12] = "GOST_R_34_10_2001",
[13] = "ECDSA_curveP256withSHA256",
[16] = "Ed448"
}
Possible values of the algorithms used in DNSKEY, DS and RRSIG records
.. bro:id:: DNS::base_errors
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional`
:Default:
::
{
[2] = "SERVFAIL",
[9] = "NOTAUTH",
[17] = "BADKEY",
[6] = "YXDOMAIN",
[11] = "unassigned-11",
[14] = "unassigned-14",
[4] = "NOTIMP",
[22] = "BADTRUNC",
[1] = "FORMERR",
[8] = "NXRRSet",
[3842] = "BADSIG",
[7] = "YXRRSET",
[15] = "unassigned-15",
[5] = "REFUSED",
[19] = "BADMODE",
[10] = "NOTZONE",
[0] = "NOERROR",
[3] = "NXDOMAIN",
[12] = "unassigned-12",
[13] = "unassigned-13",
[18] = "BADTIME",
[21] = "BADALG",
[16] = "BADVERS",
[20] = "BADNAME"
}
Errors used for non-TSIG/EDNS types.
.. bro:id:: DNS::classes
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional`
:Default:
::
{
[2] = "C_CSNET",
[4] = "C_HESOD",
[1] = "C_INTERNET",
[254] = "C_NONE",
[255] = "C_ANY",
[3] = "C_CHAOS"
}
Possible values of the CLASS field in resource records or QCLASS
field in query messages.
.. bro:id:: DNS::digests
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional`
:Default:
::
{
[2] = "SHA256",
[4] = "SHA384",
[1] = "SHA1",
[0] = "reserved0",
[3] = "GOST_R_34_11_94"
}
Possible digest types used in DNSSEC.
.. bro:id:: DNS::edns_zfield
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = ``"?"`` :bro:attr:`&optional`
:Default:
::
{
[32768] = "DNS_SEC_OK",
[0] = "NOVALUE"
}
This deciphers EDNS Z field values.
.. bro:id:: DNS::query_types
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`string`
:Attributes: :bro:attr:`&default` = :bro:type:`function` :bro:attr:`&optional`
:Default:
::
{
[19] = "X25",
[10] = "NULL",
[3] = "MD",
[254] = "MAILA",
[43] = "DS",
[50] = "NSEC3",
[99] = "SPF",
[47] = "NSEC",
[251] = "IXFR",
[32768] = "TA",
[27] = "GPOS",
[6] = "SOA",
[20] = "ISDN",
[51] = "NSEC3PARAM",
[25] = "KEY",
[37] = "CERT",
[31] = "NIMLOC",
[28] = "AAAA",
[9] = "MR",
[32769] = "DLV",
[11] = "WKS",
[40] = "SINK",
[41] = "OPT",
[59] = "CDS",
[252] = "AXFR",
[46] = "RRSIG",
[5] = "CNAME",
[49] = "DHCID",
[103] = "UNSPEC",
[253] = "MAILB",
[45] = "IPSECKEY",
[8] = "MG",
[17] = "RP",
[48] = "DNSKEY",
[257] = "CAA",
[33] = "SRV",
[100] = "UINFO",
[24] = "SIG",
[23] = "NSAP-PTR",
[26] = "PX",
[101] = "UID",
[39] = "DNAME",
[16] = "TXT",
[34] = "ATMA",
[38] = "A6",
[18] = "AFSDB",
[35] = "NAPTR",
[42] = "APL",
[7] = "MB",
[15] = "MX",
[249] = "TKEY",
[36] = "KX",
[4] = "MF",
[44] = "SSHFP",
[52] = "TLSA",
[1] = "A",
[22] = "NSAP",
[250] = "TSIG",
[14] = "MINFO",
[102] = "GID",
[255] = "*",
[256] = "URI",
[21] = "RT",
[29] = "LOC",
[13] = "HINFO",
[30] = "EID",
[55] = "HIP",
[2] = "NS",
[32] = "NB",
[60] = "CDNSKEY",
[12] = "PTR",
[61] = "OPENPGPKEY"
}
Mapping of DNS query type codes to human readable string
representation.

20
doc/scripts/base/protocols/dns/index.rst
View file

@ -1,20 +0,0 @@
:orphan:
Package: base/protocols/dns
===========================
Support for Domain Name System (DNS) protocol analysis.
:doc:`/scripts/base/protocols/dns/__load__.bro`
:doc:`/scripts/base/protocols/dns/consts.bro`
Types, errors, and fields for analyzing DNS data. A helper file
for DNS analysis scripts.
:doc:`/scripts/base/protocols/dns/main.bro`
Base DNS analysis script which tracks and logs DNS queries along with
their responses.

268
doc/scripts/base/protocols/dns/main.bro.rst
View file

@ -1,268 +0,0 @@
: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.