1// dnstap: flexible, structured event replication format for DNS software 2// 3// This file contains the protobuf schemas for the "dnstap" structured event 4// replication format for DNS software. 5 6// Written in 2013-2014 by Farsight Security, Inc. 7// 8// To the extent possible under law, the author(s) have dedicated all 9// copyright and related and neighboring rights to this file to the public 10// domain worldwide. This file is distributed without any warranty. 11// 12// You should have received a copy of the CC0 Public Domain Dedication along 13// with this file. If not, see: 14// 15// <http://creativecommons.org/publicdomain/zero/1.0/>. 16 17syntax = "proto2"; 18package dnstap; 19 20// "Dnstap": this is the top-level dnstap type, which is a "union" type that 21// contains other kinds of dnstap payloads, although currently only one type 22// of dnstap payload is defined. 23// See: https://developers.google.com/protocol-buffers/docs/techniques#union 24message Dnstap { 25 // DNS server identity. 26 // If enabled, this is the identity string of the DNS server which generated 27 // this message. Typically this would be the same string as returned by an 28 // "NSID" (RFC 5001) query. 29 optional bytes identity = 1; 30 31 // DNS server version. 32 // If enabled, this is the version string of the DNS server which generated 33 // this message. Typically this would be the same string as returned by a 34 // "version.bind" query. 35 optional bytes version = 2; 36 37 // Extra data for this payload. 38 // This field can be used for adding an arbitrary byte-string annotation to 39 // the payload. No encoding or interpretation is applied or enforced. 40 optional bytes extra = 3; 41 42 // Identifies which field below is filled in. 43 enum Type { 44 MESSAGE = 1; 45 } 46 required Type type = 15; 47 48 // One of the following will be filled in. 49 optional Message message = 14; 50} 51 52// SocketFamily: the network protocol family of a socket. This specifies how 53// to interpret "network address" fields. 54enum SocketFamily { 55 INET = 1; // IPv4 (RFC 791) 56 INET6 = 2; // IPv6 (RFC 2460) 57} 58 59// SocketProtocol: the protocol used to transport a DNS message. 60enum SocketProtocol { 61 UDP = 1; // DNS over UDP transport (RFC 1035 section 4.2.1) 62 TCP = 2; // DNS over TCP transport (RFC 1035 section 4.2.2) 63 DOT = 3; // DNS over TLS (RFC 7858) 64 DOH = 4; // DNS over HTTPS (RFC 8484) 65 DNSCryptUDP = 5; // DNSCrypt over UDP (https://dnscrypt.info/protocol) 66 DNSCryptTCP = 6; // DNSCrypt over TCP (https://dnscrypt.info/protocol) 67 DOQ = 7; // DNS over QUIC (RFC 9250) 68} 69 70// Policy: information about any name server operator policy 71// applied to the processing of a DNS message. 72message Policy { 73 74 // Match: what aspect of the message or message exchange 75 // triggered the application of the Policy. 76 enum Match { 77 QNAME = 1; // Name in question section of query 78 CLIENT_IP = 2; // Client IP address 79 RESPONSE_IP = 3; // Address in A/AAAA RRSet 80 NS_NAME = 4; // Authoritative name server, by name 81 NS_IP = 5; // Authoritative name server, by IP address 82 } 83 84 // The Action taken to implement the Policy. 85 enum Action { 86 NXDOMAIN = 1; // Respond with NXDOMAIN 87 NODATA = 2; // Respond with empty answer section 88 PASS = 3; // Do not alter the response (passthrough) 89 DROP = 4; // Do not respond. 90 TRUNCATE = 5; // Truncate UDP response, forcing TCP retry 91 LOCAL_DATA = 6; // Respond with local data from policy 92 } 93 94 // type: the type of policy applied, e.g. "RPZ" for a 95 // policy from a Response Policy Zone. 96 optional string type = 1; 97 98 // rule: the rule matched by the message. 99 // 100 // In a RPZ context, this is the owner name of the rule in 101 // the Reponse Policy Zone in wire format. 102 optional bytes rule = 2; 103 104 // action: the policy action taken in response to the 105 // rule match. 106 optional Action action = 3; 107 108 // match: the feature of the message exchange which matched the rule. 109 optional Match match = 4; 110 111 // The matched value. Format depends on the matched feature . 112 optional bytes value = 5; 113} 114 115// Message: a wire-format (RFC 1035 section 4) DNS message and associated 116// metadata. Applications generating "Message" payloads should follow 117// certain requirements based on the MessageType, see below. 118message Message { 119 120 // There are eight types of "Message" defined that correspond to the 121 // four arrows in the following diagram, slightly modified from RFC 1035 122 // section 2: 123 124 // +---------+ +----------+ +--------+ 125 // | | query | | query | | 126 // | Stub |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth. | 127 // | Resolver| | Server | | Name | 128 // | |<-SR--------CR-| |<-RR----AR-| Server | 129 // +---------+ response | | response | | 130 // +----------+ +--------+ 131 132 // Each arrow has two Type values each, one for each "end" of each arrow, 133 // because these are considered to be distinct events. Each end of each 134 // arrow on the diagram above has been marked with a two-letter Type 135 // mnemonic. Clockwise from upper left, these mnemonic values are: 136 // 137 // SQ: STUB_QUERY 138 // CQ: CLIENT_QUERY 139 // RQ: RESOLVER_QUERY 140 // AQ: AUTH_QUERY 141 // AR: AUTH_RESPONSE 142 // RR: RESOLVER_RESPONSE 143 // CR: CLIENT_RESPONSE 144 // SR: STUB_RESPONSE 145 146 // Two additional types of "Message" have been defined for the 147 // "forwarding" case where an upstream DNS server is responsible for 148 // further recursion. These are not shown on the diagram above, but have 149 // the following mnemonic values: 150 151 // FQ: FORWARDER_QUERY 152 // FR: FORWARDER_RESPONSE 153 154 // The "Message" Type values are defined below. 155 156 enum Type { 157 // AUTH_QUERY is a DNS query message received from a resolver by an 158 // authoritative name server, from the perspective of the authoritative 159 // name server. 160 AUTH_QUERY = 1; 161 162 // AUTH_RESPONSE is a DNS response message sent from an authoritative 163 // name server to a resolver, from the perspective of the authoritative 164 // name server. 165 AUTH_RESPONSE = 2; 166 167 // RESOLVER_QUERY is a DNS query message sent from a resolver to an 168 // authoritative name server, from the perspective of the resolver. 169 // Resolvers typically clear the RD (recursion desired) bit when 170 // sending queries. 171 RESOLVER_QUERY = 3; 172 173 // RESOLVER_RESPONSE is a DNS response message received from an 174 // authoritative name server by a resolver, from the perspective of 175 // the resolver. 176 RESOLVER_RESPONSE = 4; 177 178 // CLIENT_QUERY is a DNS query message sent from a client to a DNS 179 // server which is expected to perform further recursion, from the 180 // perspective of the DNS server. The client may be a stub resolver or 181 // forwarder or some other type of software which typically sets the RD 182 // (recursion desired) bit when querying the DNS server. The DNS server 183 // may be a simple forwarding proxy or it may be a full recursive 184 // resolver. 185 CLIENT_QUERY = 5; 186 187 // CLIENT_RESPONSE is a DNS response message sent from a DNS server to 188 // a client, from the perspective of the DNS server. The DNS server 189 // typically sets the RA (recursion available) bit when responding. 190 CLIENT_RESPONSE = 6; 191 192 // FORWARDER_QUERY is a DNS query message sent from a downstream DNS 193 // server to an upstream DNS server which is expected to perform 194 // further recursion, from the perspective of the downstream DNS 195 // server. 196 FORWARDER_QUERY = 7; 197 198 // FORWARDER_RESPONSE is a DNS response message sent from an upstream 199 // DNS server performing recursion to a downstream DNS server, from the 200 // perspective of the downstream DNS server. 201 FORWARDER_RESPONSE = 8; 202 203 // STUB_QUERY is a DNS query message sent from a stub resolver to a DNS 204 // server, from the perspective of the stub resolver. 205 STUB_QUERY = 9; 206 207 // STUB_RESPONSE is a DNS response message sent from a DNS server to a 208 // stub resolver, from the perspective of the stub resolver. 209 STUB_RESPONSE = 10; 210 211 // TOOL_QUERY is a DNS query message sent from a DNS software tool to a 212 // DNS server, from the perspective of the tool. 213 TOOL_QUERY = 11; 214 215 // TOOL_RESPONSE is a DNS response message received by a DNS software 216 // tool from a DNS server, from the perspective of the tool. 217 TOOL_RESPONSE = 12; 218 219 // UPDATE_QUERY is a Dynamic DNS Update request (RFC 2136) received 220 // by an authoritative name server, from the perspective of the 221 // authoritative name server. 222 UPDATE_QUERY = 13; 223 224 // UPDATE_RESPONSE is a Dynamic DNS Update response (RFC 2136) sent 225 // from an authoritative name server, from the perspective of the 226 // authoritative name server. 227 UPDATE_RESPONSE = 14; 228 } 229 230 // One of the Type values described above. 231 required Type type = 1; 232 233 // One of the SocketFamily values described above. 234 optional SocketFamily socket_family = 2; 235 236 // One of the SocketProtocol values described above. 237 optional SocketProtocol socket_protocol = 3; 238 239 // The network address of the message initiator. 240 // For SocketFamily INET, this field is 4 octets (IPv4 address). 241 // For SocketFamily INET6, this field is 16 octets (IPv6 address). 242 optional bytes query_address = 4; 243 244 // The network address of the message responder. 245 // For SocketFamily INET, this field is 4 octets (IPv4 address). 246 // For SocketFamily INET6, this field is 16 octets (IPv6 address). 247 optional bytes response_address = 5; 248 249 // The transport port of the message initiator. 250 // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. 251 optional uint32 query_port = 6; 252 253 // The transport port of the message responder. 254 // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. 255 optional uint32 response_port = 7; 256 257 // The time at which the DNS query message was sent or received, depending 258 // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY. 259 // This is the number of seconds since the UNIX epoch. 260 optional uint64 query_time_sec = 8; 261 262 // The time at which the DNS query message was sent or received. 263 // This is the seconds fraction, expressed as a count of nanoseconds. 264 optional fixed32 query_time_nsec = 9; 265 266 // The initiator's original wire-format DNS query message, verbatim. 267 optional bytes query_message = 10; 268 269 // The "zone" or "bailiwick" pertaining to the DNS query message. 270 // This is a wire-format DNS domain name. 271 optional bytes query_zone = 11; 272 273 // The time at which the DNS response message was sent or received, 274 // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or 275 // CLIENT_RESPONSE. 276 // This is the number of seconds since the UNIX epoch. 277 optional uint64 response_time_sec = 12; 278 279 // The time at which the DNS response message was sent or received. 280 // This is the seconds fraction, expressed as a count of nanoseconds. 281 optional fixed32 response_time_nsec = 13; 282 283 // The responder's original wire-format DNS response message, verbatim. 284 optional bytes response_message = 14; 285 286 // Operator policy applied to the processing of this message, if any. 287 optional Policy policy = 15; 288} 289 290// All fields except for 'type' in the Message schema are optional. 291// It is recommended that at least the following fields be filled in for 292// particular types of Messages. 293 294// AUTH_QUERY: 295// socket_family, socket_protocol 296// query_address, query_port 297// query_message 298// query_time_sec, query_time_nsec 299 300// AUTH_RESPONSE: 301// socket_family, socket_protocol 302// query_address, query_port 303// query_time_sec, query_time_nsec 304// response_message 305// response_time_sec, response_time_nsec 306 307// RESOLVER_QUERY: 308// socket_family, socket_protocol 309// query_message 310// query_time_sec, query_time_nsec 311// query_zone 312// response_address, response_port 313 314// RESOLVER_RESPONSE: 315// socket_family, socket_protocol 316// query_time_sec, query_time_nsec 317// query_zone 318// response_address, response_port 319// response_message 320// response_time_sec, response_time_nsec 321 322// CLIENT_QUERY: 323// socket_family, socket_protocol 324// query_message 325// query_time_sec, query_time_nsec 326 327// CLIENT_RESPONSE: 328// socket_family, socket_protocol 329// query_time_sec, query_time_nsec 330// response_message 331// response_time_sec, response_time_nsec 332