b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// dnstap: flexible, structured event replication format for DNS software
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// This file contains the protobuf schemas for the "dnstap" structured event
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// replication format for DNS software.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// Written in 2013-2014 by Farsight Security, Inc.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// To the extent possible under law, the author(s) have dedicated all
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// copyright and related and neighboring rights to this file to the public
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// domain worldwide. This file is distributed without any warranty.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// You should have received a copy of the CC0 Public Domain Dedication along
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// with this file. If not, see:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// <http://creativecommons.org/publicdomain/zero/1.0/>.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Huntpackage dnstap;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// "Dnstap": this is the top-level dnstap type, which is a "union" type that
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// contains other kinds of dnstap payloads, although currently only one type
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// of dnstap payload is defined.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// See: https://developers.google.com/protocol-buffers/docs/techniques#union
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Huntmessage Dnstap {
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // DNS server identity.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // If enabled, this is the identity string of the DNS server which generated
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // this message. Typically this would be the same string as returned by an
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // "NSID" (RFC 5001) query.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes identity = 1;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // DNS server version.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // If enabled, this is the version string of the DNS server which generated
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // this message. Typically this would be the same string as returned by a
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes version = 2;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // Extra data for this payload.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This field can be used for adding an arbitrary byte-string annotation to
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // the payload. No encoding or interpretation is applied or enforced.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes extra = 3;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // Identifies which field below is filled in.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt MESSAGE = 1;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt required Type type = 15;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // One of the following will be filled in.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional Message message = 14;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// SocketFamily: the network protocol family of a socket. This specifies how
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// to interpret "network address" fields.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Huntenum SocketFamily {
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt INET = 1; // IPv4 (RFC 791)
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt INET6 = 2; // IPv6 (RFC 2460)
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// SocketProtocol: the transport protocol of a socket. This specifies how to
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// interpret "transport port" fields.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Huntenum SocketProtocol {
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt UDP = 1; // User Datagram Protocol (RFC 768)
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt TCP = 2; // Transmission Control Protocol (RFC 793)
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// Message: a wire-format (RFC 1035 section 4) DNS message and associated
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// metadata. Applications generating "Message" payloads should follow
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// certain requirements based on the MessageType, see below.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Huntmessage Message {
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // There are eight types of "Message" defined that correspond to the
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // four arrows in the following diagram, slightly modified from RFC 1035
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // section 2:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // +---------+ +----------+ +--------+
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // | | query | | query | |
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // | Stub |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth. |
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // | Resolver| | Server | | Name |
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // | |<-SR--------CR-| |<-RR----AR-| Server |
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // +---------+ response | | response | |
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // +----------+ +--------+
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // Each arrow has two Type values each, one for each "end" of each arrow,
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // because these are considered to be distinct events. Each end of each
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // arrow on the diagram above has been marked with a two-letter Type
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // mnemonic. Clockwise from upper left, these mnemonic values are:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // SQ: STUB_QUERY
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // CQ: CLIENT_QUERY
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // RQ: RESOLVER_QUERY
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // AQ: AUTH_QUERY
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // AR: AUTH_RESPONSE
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // RR: RESOLVER_RESPONSE
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // CR: CLIENT_RESPONSE
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // SR: STUB_RESPONSE
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // Two additional types of "Message" have been defined for the
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // "forwarding" case where an upstream DNS server is responsible for
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // further recursion. These are not shown on the diagram above, but have
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // the following mnemonic values:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // FQ: FORWARDER_QUERY
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // FR: FORWARDER_RESPONSE
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The "Message" Type values are defined below.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // AUTH_QUERY is a DNS query message received from a resolver by an
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // authoritative name server, from the perspective of the authorative
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // name server.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt AUTH_QUERY = 1;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // AUTH_RESPONSE is a DNS response message sent from an authoritative
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // name server to a resolver, from the perspective of the authoritative
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // name server.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt AUTH_RESPONSE = 2;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // RESOLVER_QUERY is a DNS query message sent from a resolver to an
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // authoritative name server, from the perspective of the resolver.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // Resolvers typically clear the RD (recursion desired) bit when
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // sending queries.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt RESOLVER_QUERY = 3;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // RESOLVER_RESPONSE is a DNS response message received from an
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // authoritative name server by a resolver, from the perspective of
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // the resolver.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt RESOLVER_RESPONSE = 4;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // CLIENT_QUERY is a DNS query message sent from a client to a DNS
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // server which is expected to perform further recursion, from the
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // perspective of the DNS server. The client may be a stub resolver or
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // forwarder or some other type of software which typically sets the RD
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // (recursion desired) bit when querying the DNS server. The DNS server
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // may be a simple forwarding proxy or it may be a full recursive
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // resolver.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt CLIENT_QUERY = 5;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // CLIENT_RESPONSE is a DNS response message sent from a DNS server to
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // a client, from the perspective of the DNS server. The DNS server
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // typically sets the RA (recursion available) bit when responding.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt CLIENT_RESPONSE = 6;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // FORWARDER_QUERY is a DNS query message sent from a downstream DNS
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // server to an upstream DNS server which is expected to perform
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // further recursion, from the perspective of the downstream DNS
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt FORWARDER_QUERY = 7;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // FORWARDER_RESPONSE is a DNS response message sent from an upstream
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // DNS server performing recursion to a downstream DNS server, from the
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // perspective of the downstream DNS server.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt FORWARDER_RESPONSE = 8;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // STUB_QUERY is a DNS query message sent from a stub resolver to a DNS
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // server, from the perspective of the stub resolver.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt STUB_QUERY = 9;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // STUB_RESPONSE is a DNS response message sent from a DNS server to a
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // stub resolver, from the perspective of the stub resolver.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt STUB_RESPONSE = 10;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // TOOL_QUERY is a DNS query message sent from a DNS software tool to a
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // DNS server, from the perspective of the tool.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt TOOL_QUERY = 11;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // TOOL_RESPONSE is a DNS response message received by a DNS software
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // tool from a DNS server, from the perspective of the tool.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt TOOL_RESPONSE = 12;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // One of the Type values described above.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt required Type type = 1;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // One of the SocketFamily values described above.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional SocketFamily socket_family = 2;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // One of the SocketProtocol values described above.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional SocketProtocol socket_protocol = 3;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The network address of the message initiator.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // For SocketFamily INET, this field is 4 octets (IPv4 address).
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // For SocketFamily INET6, this field is 16 octets (IPv6 address).
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes query_address = 4;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The network address of the message responder.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // For SocketFamily INET, this field is 4 octets (IPv4 address).
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // For SocketFamily INET6, this field is 16 octets (IPv6 address).
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes response_address = 5;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The transport port of the message initiator.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional uint32 query_port = 6;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The transport port of the message responder.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional uint32 response_port = 7;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The time at which the DNS query message was sent or received, depending
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is the number of seconds since the UNIX epoch.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional uint64 query_time_sec = 8;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The time at which the DNS query message was sent or received.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is the seconds fraction, expressed as a count of nanoseconds.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional fixed32 query_time_nsec = 9;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The initiator's original wire-format DNS query message, verbatim.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes query_message = 10;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The "zone" or "bailiwick" pertaining to the DNS query message.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is a wire-format DNS domain name.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes query_zone = 11;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The time at which the DNS response message was sent or received,
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // CLIENT_RESPONSE.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is the number of seconds since the UNIX epoch.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional uint64 response_time_sec = 12;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The time at which the DNS response message was sent or received.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // This is the seconds fraction, expressed as a count of nanoseconds.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional fixed32 response_time_nsec = 13;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt // The responder's original wire-format DNS response message, verbatim.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt optional bytes response_message = 14;
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// All fields except for 'type' in the Message schema are optional.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// It is recommended that at least the following fields be filled in for
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// particular types of Messages.
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// AUTH_QUERY:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_address, query_port
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// AUTH_RESPONSE:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_address, query_port
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_time_sec, response_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// RESOLVER_QUERY:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_zone
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_address, response_port
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// RESOLVER_RESPONSE:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_zone
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_address, response_port
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_time_sec, response_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// CLIENT_QUERY:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// CLIENT_RESPONSE:
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// socket_family, socket_protocol
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// query_time_sec, query_time_nsec
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_message
b66b333f59cf51ef87f973084a5023acd9317fb2Evan Hunt// response_time_sec, response_time_nsec