idnits 2.17.1 draft-reddy-dots-telemetry-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 903 has weird spacing: '...rw unit uni...' == Line 910 has weird spacing: '...er-port ine...' -- The document date (October 18, 2019) is 1650 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'Enterprise-Numbers' == Outdated reference: A later version (-14) exists of draft-ietf-dots-signal-call-home-06 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-37 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-20 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair 5 Expires: April 20, 2020 Orange 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 October 18, 2019 12 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 13 draft-reddy-dots-telemetry-04 15 Abstract 17 This document aims to enrich DOTS signal channel protocol with 18 various telemetry attributes allowing optimal DDoS attack mitigation. 19 This document specifies the normal traffic baseline and attack 20 traffic telemetry attributes a DOTS client can convey to its DOTS 21 server in the mitigation request, the mitigation status telemetry 22 attributes a DOTS server can communicate to a DOTS client, and the 23 mitigation efficacy telemetry attributes a DOTS client can 24 communicate to a DOTS server. The telemetry attributes can assist 25 the mitigator to choose the DDoS mitigation techniques and perform 26 optimal DDoS attack mitigation. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 20, 2020. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. DOTS Telemetry: Overview & Purpose . . . . . . . . . . . . . 5 65 4. Generic Considerations . . . . . . . . . . . . . . . . . . . 8 66 4.1. DOTS Client Identification . . . . . . . . . . . . . . . 8 67 4.2. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 8 68 5. DOTS Telemetry Attributes . . . . . . . . . . . . . . . . . . 9 69 5.1. Pre-mitigation DOTS Telemetry Attributes . . . . . . . . 9 70 5.1.1. Total Traffic Normal Baseline . . . . . . . . . . . . 9 71 5.1.2. Total Pipe Capability . . . . . . . . . . . . . . . . 9 72 5.1.3. Total Attack Traffic . . . . . . . . . . . . . . . . 10 73 5.1.4. Total Traffic . . . . . . . . . . . . . . . . . . . . 10 74 5.1.5. Total Connections Capacity . . . . . . . . . . . . . 10 75 5.1.6. Total Attack Connections . . . . . . . . . . . . . . 11 76 5.1.7. Attack Details . . . . . . . . . . . . . . . . . . . 11 77 5.2. DOTS Client to Server Mitigation Efficacy DOTS Telemetry 78 Attributes . . . . . . . . . . . . . . . . . . . . . . . 13 79 5.2.1. Total Attack Traffic . . . . . . . . . . . . . . . . 14 80 5.2.2. Attack Details . . . . . . . . . . . . . . . . . . . 14 81 5.3. DOTS Server to Client Mitigation Status DOTS Telemetry 82 Attributes . . . . . . . . . . . . . . . . . . . . . . . 14 83 5.3.1. Mitigation Status . . . . . . . . . . . . . . . . . . 14 84 6. DOTS Telemetry Configuration . . . . . . . . . . . . . . . . 14 85 6.1. Convey DOTS Telemetry Configuration . . . . . . . . . . . 14 86 6.2. Delete DOTS Telemetry Configuration . . . . . . . . . . . 17 87 7. DOTS Telemetry YANG Module . . . . . . . . . . . . . . . . . 17 88 7.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 17 89 7.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 23 90 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 91 8.1. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 38 92 8.2. DOTS Signal Telemetry YANG Module . . . . . . . . . . . . 38 94 9. Security Considerations . . . . . . . . . . . . . . . . . . . 39 95 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 39 96 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 97 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 98 12.1. Normative References . . . . . . . . . . . . . . . . . . 39 99 12.2. Informative References . . . . . . . . . . . . . . . . . 40 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 102 1. Introduction 104 The Internet security 'battle' between the adversary and security 105 countermeasures is an everlasting one. DDoS attacks have become more 106 vicious and sophisticated in almost all aspects of their maneuvers 107 and malevolent intentions. IT organizations and service providers 108 are facing DDoS attacks that fall into two broad categories: Network/ 109 Transport layer attacks and Application layer attacks. Network/ 110 Transport layer attacks target the victim's infrastructure. These 111 attacks are not necessarily aimed at taking down the actual delivered 112 services, but rather to eliminate various network elements (routers, 113 switches, firewalls, transit links, and so on) from serving 114 legitimate user traffic. The main method of such attacks is to send 115 a large volume or high PPS of traffic toward the victim's 116 infrastructure. Typically, attack volumes may vary from a few 100 117 Mbps/PPS to 100s of Gbps or even Tbps. Attacks are commonly carried 118 out leveraging botnets and attack reflectors for amplification 119 attacks, such as NTP, DNS, SNMP, SSDP, and so on. Application layer 120 attacks target various applications. Typical examples include 121 attacks against HTTP/HTTPS, DNS, SIP, SMTP, and so on. However, all 122 valid applications with their port numbers open at network edges can 123 be attractive attack targets. Application layer attacks are 124 considered more complex and hard to categorize, therefore harder to 125 detect and mitigate efficiently. 127 To compound the problem, attackers also leverage multi-vectored 128 attacks. These merciless attacks are assembled from dynamic attack 129 vectors (Network/Application) and tactics. As such, multiple attack 130 vectors formed by multiple attack types and volumes are launched 131 simultaneously towards a victim. Multi-vector attacks are harder to 132 detect and defend. Multiple and simultaneous mitigation techniques 133 are needed to defeat such attack campaigns. It is also common for 134 attackers to change attack vectors right after a successful 135 mitigation, burdening their opponents with changing their defense 136 methods. 138 The ultimate conclusion derived from these real scenarios is that 139 modern attacks detection and mitigation are most certainly 140 complicated and highly convoluted tasks. They demand a comprehensive 141 knowledge of the attack attributes, the targeted normal behavior/ 142 traffic patterns, as well as the attacker's on-going and past 143 actions. Even more challenging, retrieving all the analytics needed 144 for detecting these attacks is not simple to obtain with the 145 industry's current capabilities. 147 The DOTS signal channel protocol [I-D.ietf-dots-signal-channel] is 148 used to carry information about a network resource or a network (or a 149 part thereof) that is under a Distributed Denial of Service (DDoS) 150 attack. Such information is sent by a DOTS client to one or multiple 151 DOTS servers so that appropriate mitigation actions are undertaken on 152 traffic deemed suspicious. Various use cases are discussed in 153 [I-D.ietf-dots-use-cases]. 155 Typically, DOTS clients can be integrated within a DDoS attack 156 detector, or network and security elements that have been actively 157 engaged with ongoing attacks. The DOTS client mitigation environment 158 determines that it is no longer possible or practical for it to 159 handle these attacks. This can be due to lack of resources or 160 security capabilities, as derived from the complexities and the 161 intensity of these attacks. In this circumstance, the DOTS client 162 has invaluable knowledge about the actual attacks that need to be 163 handled by the DOTS server. By enabling the DOTS client to share 164 this comprehensive knowledge of an ongoing attack under specific 165 circumstances, the DOTS server can drastically increase its abilities 166 to accomplish successful mitigation. While the attack is being 167 handled by the DOTS server associated mitigation resources, the DOTS 168 server has the knowledge about the ongoing attack mitigation. The 169 DOTS server can share this information with the DOTS client so that 170 the client can better assess and evaluate the actual mitigation 171 realized. 173 In some deployments, DOTS clients can send mitigation hints derived 174 from attack details to DOTS servers, with the full understanding that 175 the DOTS server may ignore mitigation hints, as described in 176 [RFC8612] (Gen-004). Mitigation hints will be transmitted across the 177 DOTS signal channel, as the data channel may not be functional during 178 an attack. How a DOTS server is handling normal and attack traffic 179 attributes, and mitigation hints is implementation-specific. 181 Both DOTS client and server can benefit this information by 182 presenting various information in relevant management, reporting, and 183 portal systems. 185 This document defines DOTS telemetry attributes the DOTS client can 186 convey to the DOTS server, and vice versa. The DOTS telemetry 187 attributes are not mandatory fields. Nevertheless, when DOTS 188 telemetry attributes are available to a DOTS agent, and absent any 189 policy, it can signal the attributes in order to optimize the overall 190 mitigation service provisioned using DOTS. Some of the DOTS 191 telemetry data are not shared during an attack time. 193 2. Terminology 195 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 196 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 197 "OPTIONAL" in this document are to be interpreted as described in BCP 198 14 [RFC2119][RFC8174] when, and only when, they appear in all 199 capitals, as shown here. 201 The reader should be familiar with the terms defined in [RFC8612]. 203 "DOTS Telemetry" is defined as the collection of attributes that are 204 used to characterize normal traffic baseline, attacks and their 205 mitigation measures, and any related information that may help in 206 enforcing countermeasures. The DOTS Telemetry is an optional set of 207 attributes that can be signaled in the DOTS signal channel protocol. 209 The meaning of the symbols in YANG tree diagrams is defined in 210 [RFC8340]. 212 3. DOTS Telemetry: Overview & Purpose 214 When signaling a mitigation request, it is most certainly beneficial 215 for the DOTS client to signal to the DOTS server any knowledge 216 regarding ongoing attacks. This can happen in cases where DOTS 217 clients are asking the DOTS server for support in defending against 218 attacks that they have already detected and/or mitigated. These 219 actions taken by DOTS clients are referred to as "signaling the DOTS 220 Telemetry". 222 If attacks are already detected and categorized by the DOTS client 223 domain, the DOTS server, and its associated mitigation services, can 224 proactively benefit this information and optimize the overall service 225 delivered. It is important to note that DOTS client and server 226 detection and mitigation approaches can be different, and can 227 potentially outcome different results and attack classifications. 228 The DDoS mitigation service treats the ongoing attack details from 229 the client as hints and cannot completely rely or trust the attack 230 details conveyed by the DOTS client. 232 A basic requirement of security operation teams is to be aware and 233 get visibility into the attacks they need to handle. The DOTS server 234 security operation teams benefit from the DOTS telemetry, especially 235 from the reports of ongoing attacks. Even if some mitigation can be 236 automated, operational teams can use the DOTS telemetry to be 237 prepared for attack mitigation and to assign the correct resources 238 (operation staff, networking and mitigation) for the specific 239 service. Similarly, security operation personnel at the DOTS client 240 side ask for feedback about their requests for protection. 241 Therefore, it is valuable for the DOTS server to share DOTS telemetry 242 with the DOTS client. Thus mutual sharing of information is crucial 243 for "closing the mitigation loop" between the DOTS client and server. 244 For the server side team, it is important to realize that the same 245 attacks that the DOTS server's mitigation resources are seeing are 246 those that the DOTS client is asking to mitigate. For the DOTS 247 client side team, it is important to realize that the DOTS clients 248 receive the required service. For example: understanding that "I 249 asked for mitigation of two attacks and my DOTS server detects and 250 mitigates only one...". Cases of inconsistency in attack 251 classification between DOTS client and server can be high-lighted, 252 and maybe handled, using the DOTS telemetry attributes. 254 In addition, management and orchestration systems, at both DOTS 255 client and server sides, can potentially use DOTS telemetry as a 256 feedback to automate various control and management activities 257 derived from ongoing information signaled. 259 If the DOTS server's mitigation resources have the capabilities to 260 facilitate the DOTS telemetry, the DOTS server adopts its protection 261 strategy and activates the required countermeasures immediately 262 (automation enabled). The overall results of this adoption are 263 optimized attack mitigation decisions and actions. 265 The DOTS telemetry can also be used to tune the DDoS mitigators with 266 the correct state of the attack. During the last few years, DDoS 267 attack detection technologies have evolved from threshold-based 268 detection (that is, cases when all or specific parts of traffic cross 269 a pre-defined threshold for a certain period of time is considered as 270 an attack) to an "anomaly detection" approach. In anomaly detection, 271 the main idea is to maintain rigorous learning of "normal" behavior 272 and where an "anomaly" (or an attack) is identified and categorized 273 based on the knowledge about the normal behavior and a deviation from 274 this normal behavior. Machine learning approaches are used such that 275 the actual "traffic thresholds" are "automatically calculated" by 276 learning the protected entity normal traffic behavior during peace 277 time. The normal traffic characterization learned is referred to as 278 the "normal traffic baseline". An attack is detected when the 279 victim's actual traffic is deviating from this normal baseline. 281 In addition, subsequent activities toward mitigating an attack are 282 much more challenging. The ability to distinguish legitimate traffic 283 from attacker traffic on a per packet basis is complex. This 284 complexity originates from the fact that the packet itself may look 285 "legitimate" and no attack signature can be identified. The anomaly 286 can be identified only after detailed statistical analysis. DDoS 287 attack mitigators use the normal baseline during the mitigation of an 288 attack to identify and categorize the expected appearance of a 289 specific traffic pattern. Particularly the mitigators use the normal 290 baseline to recognize the "level of normality" needs to be achieved 291 during the various mitigation process. 293 Normal baseline calculation is performed based on continuous learning 294 of the normal behavior of the protected entities. The minimum 295 learning period varies from hours to days and even weeks, depending 296 on the protected application behavior. The baseline cannot be 297 learned during active attacks because attack conditions do not 298 characterize the protected entities' normal behavior. 300 If the DOTS client has calculated the normal baseline of its 301 protected entities, signaling this attribute to the DOTS server along 302 with the attack traffic levels is significantly valuable. The DOTS 303 server benefits from this telemetry by tuning its mitigation 304 resources with the DOTS client's normal baseline. The DOTS server 305 mitigators use the baseline to familiarize themselves with the attack 306 victim's normal behavior and target the baseline as the level of 307 normality they need to achieve. Consequently, the overall mitigation 308 performances obtained are dramatically improved in terms of time to 309 mitigate, accuracy, false-negative, false-positive, and other 310 measures. 312 Mitigation of attacks without having certain knowledge of normal 313 traffic can be inaccurate at best. This is especially true for 314 recursive signaling (see Section 3.2.3 in [I-D.ietf-dots-use-cases]). 315 In addition, the highly diverse types of use-cases where DOTS clients 316 are integrated also emphasize the need for knowledge of client 317 behavior. Consequently, common global thresholds for attack 318 detection practically cannot be realized. Each DOTS client can have 319 its own levels of traffic and normal behavior. Without facilitating 320 normal baseline signaling, it may be very difficult for DOTS servers 321 in some cases to detect and mitigate the attacks accurately. It is 322 important to emphasize that it is practically impossible for the 323 server's mitigators to calculate the normal baseline, in cases they 324 do not have any knowledge of the traffic beforehand. In addition, 325 baseline learning requires a period of time that cannot be afforded 326 during active attack. Of course, this information can provided using 327 out-of-band mechanisms or manual configuration at the risk to 328 maintain inaccurate information as the network evolves and "normal" 329 patterns change. The use of a dynamic and collaborative means 330 between the DOTS client and server to identify and share key 331 parameters for the sake of efficient DDoS protect is valuable. 333 During a high volume attack, DOTS client pipes can be totally 334 saturated. The DOTS client asks the DOTS server to handle the attack 335 upstream so that DOTS client pipes return to a reasonable load level 336 (normal pattern, ideally). At this point, it is essential to ensure 337 that the mitigator does not overwhelm the DOTS client pipes by 338 sending back "clean traffic", or what it believes is "clean". This 339 can happen when the mitigator has not managed to detect and mitigate 340 all the attacks launched towards the client. In this case, it can be 341 valuable to clients to signal to server the "Total pipe capacity", 342 which is the level of traffic the DOTS client domain can absorb from 343 the upstream network. Dynamic updating of the condition of pipes 344 between DOTS agents while they are under a DDoS attack is essential. 345 For example, for cases of multiple DOTS clients share the same 346 physical connectivity pipes. It is important to note, that the term 347 "pipe" noted here does not necessary represent physical pipe, but 348 rather represents the current level of traffic client can observe 349 from server. The server should activate other mechanisms to ensure 350 it does not saturate the client's pipes unintentionally. The rate- 351 limit action defined in [I-D.ietf-dots-data-channel] can be a 352 reasonable candidate to achieve this objective; the client can ask 353 for the type of traffic (such as ICMP, UDP, TCP port 80) it prefers 354 to limit. 356 To summarize, timely and effective signaling of up-to-date DOTS 357 telemetry to all elements involved in the mitigation process is 358 essential and absolutely improves the overall service effectiveness. 359 Bi-directional feedback between DOTS agents is required for the 360 increased awareness of each party, supporting superior and highly 361 efficient attack mitigation service. 363 4. Generic Considerations 365 4.1. DOTS Client Identification 367 Following the rules in [I-D.ietf-dots-signal-channel], a unique 368 identifier is generated by a DOTS client to prevent request 369 collisions. 371 4.2. DOTS Gateways 373 DOTS gateways may be located between DOTS clients and servers. The 374 considerations elaborated in [I-D.ietf-dots-signal-channel] must be 375 followed. In particular, 'cdid' attribute is used to unambiguously 376 identify a DOTS client domain. 378 5. DOTS Telemetry Attributes 380 There are two broad types of DDoS attacks, one is bandwidth consuming 381 attack, the other is target resource consuming attack. This section 382 outlines the set of DOTS telemetry attributes that covers both the 383 types of attacks. The ultimate objective of these attributes is to 384 allow for the complete knowledge of attacks and the various 385 particulars that can best characterize attacks. 387 The description and motivation behind each attribute were presented 388 in Section 3. DOTS telemetry attributes are optionally signaled and 389 therefore MUST NOT be treated as mandatory fields in the DOTS signal 390 channel protocol. 392 5.1. Pre-mitigation DOTS Telemetry Attributes 394 The pre-mitigation telemetry attributes are indicated by the path- 395 suffix '/telemetry'. The '/telemetry' is appended to the path-prefix 396 to form the URI used with a CoAP request to signal the DOTS 397 telemetry. The following pre-mitigation telemetry attributes can be 398 signaled from the DOTS client to the DOTS server. 400 o DISCUSSION NOTES: (1) Some telemetry can be communicated using 401 DOTS data channel. (2) Evaluate the risk of fragmentation,. Some 402 of the information is not specific to each mitigation request. (3) 403 Should we define other configuration parameters to be controlled 404 by a DOTS client, e.g., Indicate a favorite measurement unit? 405 Indicate a minimum notification interval? 407 5.1.1. Total Traffic Normal Baseline 409 The low percentile (10th percentile), mid percentile (50th 410 percentile), high percentile (90th percentile) and peak values (100th 411 percentile) of "Total traffic normal baselines" measured in packets 412 per second (PPS) or kilo packets per second (Kpps) and Bits per 413 Second (BPS), and kilobytes per second or megabytes per second or 414 gigabytes per second. For example, 90th percentile says that 90% of 415 the time, the total normal traffic is below the limit specified. The 416 traffic normal baseline is represented for a target and is transport- 417 protocol specific. 419 5.1.2. Total Pipe Capability 421 The limit of traffic volume, in packets per second (PPS) or kilo 422 packets per second (Kpps) and Bits per Second (BPS), and in kilobytes 423 per second or megabytes per second or gigabytes per second. These 424 attributes represents the DOTS client domain pipe limit. 426 o NOTE: Multi-homing case to be considered. 428 5.1.3. Total Attack Traffic 430 The total attack traffic can be identified by the DOTS client 431 domain's DDoS Mitigation System (DMS) or DDoS Detector. The low 432 percentile (10th percentile), mid percentile (50th percentile), high 433 percentile (90th percentile) and peak values of total attack traffic 434 measured in packets per second (PPS) or kilo packets per second 435 (Kpps) and Bits per Second (BPS), and kilobytes per second or 436 megabytes per second or gigabytes per second. The total attack 437 traffic is represented for a target and is transport-protocol 438 specific. 440 5.1.4. Total Traffic 442 The low percentile (10th percentile), mid percentile (50th 443 percentile), high percentile (90th percentile) and peak values of 444 total traffic during a DDoS attack measured in packets per second 445 (PPS) or kilo packets per second (Kpps) and Bits per Second (BPS), 446 and kilobytes per second or megabytes per second gigabytes per 447 second. The total traffic is represented for a target and is 448 transport-protocol specific. 450 5.1.5. Total Connections Capacity 452 If the target is subjected to resource consuming DDoS attack, the 453 following optional attributes for the target per transport-protocol 454 are useful to detect resource consuming DDoS attacks: 456 o The maximum number of simultaneous connections that are allowed to 457 the target server. The threshold is transport-protocol specific 458 because the target server could support multiple protocols. 460 o The maximum number of simultaneous connections that are allowed to 461 the target server per client. 463 o The maximum number of simultaneous embryonic connections that are 464 allowed to the target server. The term "embryonic connection" 465 refers to a connection whose connection handshake is not finished 466 and embryonic connection is only possible in connection-oriented 467 transport protocols like TCP or SCTP. 469 o The maximum number of simultaneous embryonic connections that are 470 allowed to the target server per client. 472 o The maximum number of connections allowed per second to the target 473 server. 475 o The maximum number of connections allowed per second to the target 476 server per client. 478 o The maximum number of requests allowed per second to the target 479 server. 481 o The maximum number of requests allowed per second to the target 482 server per client. 484 o The maximum number of partial requests allowed per second to the 485 target server. 487 o The maximum number of partial requests allowed per second to the 488 target server per client. 490 5.1.6. Total Attack Connections 492 If the target is subjected to resource consuming DDoS attack, the low 493 percentile (10th percentile), mid percentile (50th percentile), high 494 percentile (90th percentile) and peak values of following optional 495 attributes for the target per transport-protocol are included to 496 represent the attack characteristics: 498 o The number of simultaneous attack connections to the target 499 server. 501 o The number of simultaneous embryonic connections to the target 502 server. 504 o The number of attack connections per second to the target server. 506 o The number of attack requests to the target server. 508 5.1.7. Attack Details 510 Various information and details that describe the on-going attacks 511 that needs to be mitigated by the DOTS server. The attack details 512 need to cover well-known and common attacks (such as a SYN Flood) 513 along with new emerging or vendor-specific attacks. The attack 514 details can also be signaled from the DOTS server to the DOTS client. 515 For example, the DOTS server co-located with a DDoS detector collects 516 monitoring information from the target network, identifies DDoS 517 attack using statistical analysis or deep learning techniques, and 518 signals the attack details to the DOTS client. The client can use 519 the attack details to decide whether to trigger the mitigation 520 request or not. Further, the security operation personnel at the 521 DOTS client domain can use the attack details to determine the 522 protection strategy and select the appropriate DOTS server for 523 mitigating the attack. The DOTS client can receive asynchronous 524 notifications of the attack details from the DOTS server using the 525 Observe option defined in [RFC7641]. 527 The following new fields describing the on-going attack are 528 discussed: 530 vendor-id: Vendor ID is a security vendor's Enterprise Number as 531 registered with IANA [Enterprise-Numbers]. It is a four-byte 532 integer value. 534 This is a mandatory sub-attribute. 536 attack-id: Unique identifier assigned by the vendor for the attack. 538 This is a mandatory sub-attribute. 540 attack-name: Textual representation of attack description. Natural 541 Language Processing techniques (e.g., word embedding) can possibly 542 be used to map the attack description to an attack type. Textual 543 representation of attack solves two problems (a) avoids the need 544 to create mapping tables manually between vendors (2) Avoids the 545 need to standardize attack types which keep evolving. 547 This is a mandatory sub-attribute 549 attack-severity: Attack severity. Emergency (0), critical (1) and 550 alert (2). 552 This is an optional sub-attribute 554 start-time: The time the attack started. The attack start time is 555 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 556 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 557 that the leading tag 1 (epoch-based date/time) MUST be omitted. 559 This is a mandatory sub-attribute 561 end-time: The time the attack-id attack ended. The attack 562 end time is expressed in seconds relative to 1970-01-01T00:00Z in 563 UTC time (Section 2.4.1 of [RFC7049]). The CBOR encoding is 564 modified so that the leading tag 1 (epoch-based date/time) MUST be 565 omitted. 567 This is an optional sub-attribute 569 The following existing fields are re-defined describing the on-going 570 attack are discussed: 572 o The target resource is identified using the attributes 'target- 573 prefix', 'target-port-range', 'target-protocol', 'target- 574 fqdn','target-uri', or 'alias-name' defined in the base DOTS 575 signal channel protocol and at least one of the attributes 576 'target-prefix', 'target-fqdn','target-uri', or 'alias-name' MUST 577 be present in the attack details. 579 A. If the target is subjected to bandwidth consuming attack, the 580 attributes representing the low percentile (10th percentile), 581 mid percentile (50th percentile), high percentile (90th 582 percentile) and peak values of the attack-id attack traffic 583 measured in packets per second (PPS) or kilo packets per 584 second (Kpps) and Bits per Second (BPS), and kilobytes per 585 second or megabytes per second or gigabytes per second are 586 included. 588 B. If the target is subjected to resource consuming DDoS attacks, 589 the same attributes defined for Section 5.1.6 are applicable 590 for representing the attack. 592 This is an optional sub-attribute. 594 o A count of sources involved in the attack targeting the victim and 595 a list of top talkers among those sources. The top talkers are 596 represented using the 'source-prefix' defined in 597 [I-D.ietf-dots-signal-call-home]. If the top talkers are spoofed 598 IP addresses (e.g., reflection attacks) or not. If the target is 599 subjected to bandwidth consuming attack, the attack traffic from 600 each of the top talkers represented in the low percentile (10th 601 percentile), mid percentile (50th percentile), high percentile 602 (90th percentile) and peak values of traffic measured in packets 603 per second (PPS) or kilo packets per second (Kpps) and Bits per 604 Second (BPS), and kilobytes per second or megabytes per second 605 gigabytes per second. If the target is subjected to resource 606 consuming DDoS attacks, the same attributes defined for 607 Section 5.1.6 are applicable here for representing the attack per 608 talker. This is an optional sub-attribute. 610 5.2. DOTS Client to Server Mitigation Efficacy DOTS Telemetry 611 Attributes 613 The mitigation efficacy telemetry attributes can be signaled from the 614 DOTS client to the DOTS server as part of the periodic mitigation 615 efficacy updates to the server. 617 5.2.1. Total Attack Traffic 619 The low percentile (10th percentile), mid percentile (50th 620 percentile), high percentile (90th percentile), and peak values of 621 total attack traffic the DOTS client still sees during the active 622 mitigation service measured in packets per second (PPS) or kilo 623 packets per second (Kpps) and Bits per Second (BPS), and kilobytes 624 per second or megabytes per second or gigabytes per second. 626 5.2.2. Attack Details 628 The overall attack details as observed from the DOTS client 629 perspective during the active mitigation service. The same 630 attributes defined in Section 5.1.7 are applicable here. 632 5.3. DOTS Server to Client Mitigation Status DOTS Telemetry Attributes 634 The mitigation status telemetry attributes can be signaled from the 635 DOTS server to the DOTS client as part of the periodic mitigation 636 status update. 638 5.3.1. Mitigation Status 640 As defined in [RFC8612], the actual mitigation activities can include 641 several countermeasure mechanisms. The DOTS server SHOULD signal the 642 current operational status to each relevant countermeasure. A list 643 of attacks detected by each countermeasure. The same attributes 644 defined for Section 5.1.7 are applicable here for describing the 645 attacks detected and mitigated. 647 6. DOTS Telemetry Configuration 649 6.1. Convey DOTS Telemetry Configuration 651 PUT request is used to convey the configuration parameters for the 652 telemetry data (e.g., low, mid, or high percentile values). For 653 example, a DOTS client may contact its DOTS server to change the 654 default percentiles values used as baseline for telemetry data. In 655 reference to the example shown in Figure 1, the DOTS client modifies 656 all percentile reference values. 658 Header: PUT (Code=0.03) 659 Uri-Path: ".well-known" 660 Uri-Path: "dots" 661 Uri-Path: "telemetry" 662 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 663 Uri-Path: "tcid=123" 664 Content-Format: "application/dots+cbor" 666 { 667 "ietf-dots-telemetry:telemetry-config": { 668 "low-percentile": 5.00, 669 "mid-percentile": 65.00, 670 "high-percentile": 95.00 671 } 672 } 674 Figure 1: PUT to Convey the DOTS Telemetry Configuration 676 'cuid' is a mandatory Uri-Path parameter for PUT requests. 678 The following additional Uri-Path parameter is defined: 680 tcid: Telemetry Configuration Identifier is an identifier for the 681 DOTS telemetry configuration data represented as an integer. 682 This identifier MUST be generated by DOTS clients. 'tcid' 683 values MUST increase monotonically (when a new PUT is generated 684 by a DOTS client to convey the configuration parameters for the 685 telemetry). 687 This is a mandatory attribute. 689 At least one configurable attribute MUST be present in the PUT 690 request. 692 Attributes and Uri-Path parameters with empty values MUST NOT be 693 present in a request and render the entire request invalid. 695 The PUT request with a higher numeric 'tcid' value overrides the DOTS 696 telemetry configuration data installed by a PUT request with a lower 697 numeric 'tcid' value. To avoid maintaining a long list of 'tcid' 698 requests from a DOTS client, the lower numeric 'tcid' MUST be 699 automatically deleted and no longer available at the DOTS server. 701 The DOTS server indicates the result of processing the PUT request 702 using CoAP response codes: 704 o If the request is missing a mandatory attribute, does not include 705 'cuid' or 'tcid' Uri-Path parameters, or contains one or more 706 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 707 in the response. 709 o If the DOTS server does not find the 'tcid' parameter value 710 conveyed in the PUT request in its configuration data and if the 711 DOTS server has accepted the configuration parameters, then a 712 response code 2.01 (Created) MUST be returned in the response. 714 o If the DOTS server finds the 'tcid' parameter value conveyed in 715 the PUT request in its configuration data and if the DOTS server 716 has accepted the updated configuration parameters, 2.04 (Changed) 717 MUST be returned in the response. 719 o If any of the enclosed configurable attribute values are not 720 acceptable to the DOTS server, 4.22 (Unprocessable Entity) MUST be 721 returned in the response. 723 The DOTS client may re-try and send the PUT request with updated 724 attribute values acceptable to the DOTS server. 726 A DOTS client may issue a GET message with 'tcid' Uri-Path parameter 727 to retrieve the negotiated configuration. The response does not need 728 to include 'tcid' in its message body. 730 Setting 'low-percentile' to '0.00' indicates that the DOTS client is 731 not interested in receiving low-percentiles. Likewise, setting 'mid- 732 percentile' (or 'high-percentile') to the same value as 'low- 733 percentile' (or 'mid-percentile') indicates that the DOTS client is 734 not interested in receiving mid-percentiles (or high-percentiles). 735 For example, a DOTS client can send the request depicted in Figure 2 736 to inform the server that it is interested in receiving only high- 737 percentiles. 739 Notes: Should the server be able to indicate its preference too? 740 If the DOTS server and client cannot agree on a common telemetry 741 config, the client does not have to send the telemetry (it will 742 anyway be ignored by the server). 744 Header: PUT (Code=0.03) 745 Uri-Path: ".well-known" 746 Uri-Path: "dots" 747 Uri-Path: "telemetry" 748 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 749 Uri-Path: "tcid=569" 750 Content-Format: "application/dots+cbor" 752 { 753 "ietf-dots-telemetry:telemetry-config": { 754 "low-percentile": 0.00, 755 "mid-percentile": 0.00, 756 "high-percentile": 95.00 757 } 758 } 760 Figure 2: PUT to Disable Low- and Mid-Percentiles 762 6.2. Delete DOTS Telemetry Configuration 764 A DELETE request is used to delete the installed DOTS telemetry 765 configuration data (Figure 3). 767 Header: DELETE (Code=0.04) 768 Uri-Path: ".well-known" 769 Uri-Path: "dots" 770 Uri-Path: "telemetry" 771 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 772 Uri-Path: "tcid=123" 774 Figure 3: Delete Telemetry Configuration 776 The DOTS server resets the DOTS telemetry configuration back to the 777 default values and acknowledges a DOTS client's request to remove the 778 DOTS telemetry configuration using 2.02 (Deleted) response code. 780 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 781 to set the telemetry parameters to default values. Such a request 782 does not include any 'tcid'. 784 7. DOTS Telemetry YANG Module 786 7.1. Tree Structure 788 This document defines the YANG module "ietf-dots-telemetry". 790 Notes: (1) Check naming conflict to ease CBOR mapping (e.g, low- 791 percentile is defined as yang:gauge64, list, or container). 793 Distinct names may be considered. (2) "protocol" is not indicated 794 in the telemetry data of "mitigation-scope" message type because 795 the mitigation request may include a "protocol". Similarly, 796 "target-*" attributes are not included in the in the telemetry 797 data of "mitigation-scope" message type because the mitigation 798 request must include at least one of the "target-*" attribute. 800 The "ietf-dots-telemetry" YANG module augments the "mitigation-scope" 801 type message defined in "ietf-dots-signal" with telemetry data as 802 depicted in following tree structure: 804 augment /ietf-signal:dots-signal/ietf-signal:message-type 805 /ietf-signal:mitigation-scope/ietf-signal:scope: 806 +--rw total-attack-traffic* [unit] {dots-telemetry}? 807 | +--rw unit unit 808 | +--rw low-percentile? yang:gauge64 809 | +--rw mid-percentile? yang:gauge64 810 | +--rw high-percentile? yang:gauge64 811 | +--rw peak? yang:gauge64 812 +--rw total-attack-connection {dots-telemetry}? 813 | +--rw low-percentile 814 | | +--rw connection? yang:gauge64 815 | | +--rw embryonic? yang:gauge64 816 | | +--rw connection-ps? yang:gauge64 817 | | +--rw request-ps? yang:gauge64 818 | | +--rw partial-request-ps? yang:gauge64 819 | +--rw mid-percentile 820 | | +--rw connection? yang:gauge64 821 | | +--rw embryonic? yang:gauge64 822 | | +--rw connection-ps? yang:gauge64 823 | | +--rw request-ps? yang:gauge64 824 | | +--rw partial-request-ps? yang:gauge64 825 | +--rw high-percentile 826 | | +--rw connection? yang:gauge64 827 | | +--rw embryonic? yang:gauge64 828 | | +--rw connection-ps? yang:gauge64 829 | | +--rw request-ps? yang:gauge64 830 | | +--rw partial-request-ps? yang:gauge64 831 | +--rw peak 832 | +--rw connection? yang:gauge64 833 | +--rw embryonic? yang:gauge64 834 | +--rw connection-ps? yang:gauge64 835 | +--rw request-ps? yang:gauge64 836 | +--rw partial-request-ps? yang:gauge64 837 +--rw attack-detail {dots-telemetry}? 838 +--rw vendor-id? uint32 839 +--rw attack-id? string 840 +--rw attack-name? string 841 +--rw attack-severity? attack-severity 842 +--rw start-time? uint64 843 +--rw end-time? uint64 844 +--rw source-count 845 | +--rw low-percentile? yang:gauge64 846 | +--rw mid-percentile? yang:gauge64 847 | +--rw high-percentile? yang:gauge64 848 | +--rw peak? yang:gauge64 849 +--rw top-talker 850 +--rw source-prefix* [source-prefix] 851 +--rw spoofed-status? boolean 852 +--rw source-prefix inet:ip-prefix 853 +--rw total-attack-traffic* [unit] 854 | +--rw unit unit 855 | +--rw low-percentile? yang:gauge64 856 | +--rw mid-percentile? yang:gauge64 857 | +--rw high-percentile? yang:gauge64 858 | +--rw peak? yang:gauge64 859 +--rw total-attack-connection 860 +--rw low-percentile 861 | +--rw connection? yang:gauge64 862 | +--rw embryonic? yang:gauge64 863 | +--rw connection-ps? yang:gauge64 864 | +--rw request-ps? yang:gauge64 865 | +--rw partial-request-ps? yang:gauge64 866 +--rw mid-percentile 867 | +--rw connection? yang:gauge64 868 | +--rw embryonic? yang:gauge64 869 | +--rw connection-ps? yang:gauge64 870 | +--rw request-ps? yang:gauge64 871 | +--rw partial-request-ps? yang:gauge64 872 +--rw high-percentile 873 | +--rw connection? yang:gauge64 874 | +--rw embryonic? yang:gauge64 875 | +--rw connection-ps? yang:gauge64 876 | +--rw request-ps? yang:gauge64 877 | +--rw partial-request-ps? yang:gauge64 878 +--rw peak 879 +--rw connection? yang:gauge64 880 +--rw embryonic? yang:gauge64 881 +--rw connection-ps? yang:gauge64 882 +--rw request-ps? yang:gauge64 883 +--rw partial-request-ps? yang:gauge64 885 Also, the "ietf-dots-telemetry" YANG module augments the "ietf-dots- 886 signal" with a new message type called "telemetry". The tree 887 structure of the "telemetry" message type is shown below: 889 augment /ietf-signal:dots-signal/ietf-signal:message-type: 890 +--:(telemetry) {dots-telemetry}? 891 +--rw telemetry* [cuid tcid] 892 +--rw cuid string 893 +--rw cdid? string 894 +--rw tcid uint32 895 +--rw telemetry-config 896 | +--rw low-percentile? percentile 897 | +--rw mid-percentile? percentile 898 | +--rw high-percentile? percentile 899 | +--rw unit-config* [unit] 900 | +--rw unit unit 901 | +--rw status? boolean 902 +--rw total-pipe-capability* [unit] 903 | +--rw unit unit 904 | +--rw pipe? uint64 905 +--rw pre-mitigation* [telemetry-id] 906 +--rw telemetry-id uint32 907 +--rw target 908 | +--rw target-prefix* inet:ip-prefix 909 | +--rw target-port-range* [lower-port] 910 | | +--rw lower-port inet:port-number 911 | | +--rw upper-port? inet:port-number 912 | +--rw target-protocol* uint8 913 | +--rw target-fqdn* inet:domain-name 914 | +--rw target-uri* inet:uri 915 +--rw total-traffic-normal-baseline* [unit protocol] 916 | +--rw unit unit 917 | +--rw protocol uint8 918 | +--rw low-percentile? yang:gauge64 919 | +--rw mid-percentile? yang:gauge64 920 | +--rw high-percentile? yang:gauge64 921 | +--rw peak? yang:gauge64 922 +--ro total-attack-traffic* [unit protocol] 923 | +--ro unit unit 924 | +--ro protocol uint8 925 | +--ro low-percentile? yang:gauge64 926 | +--ro mid-percentile? yang:gauge64 927 | +--ro high-percentile? yang:gauge64 928 | +--ro peak? yang:gauge64 929 +--ro total-traffic* [unit protocol] 930 | +--ro unit unit 931 | +--ro protocol uint8 932 | +--ro low-percentile? yang:gauge64 933 | +--ro mid-percentile? yang:gauge64 934 | +--ro high-percentile? yang:gauge64 935 | +--ro peak? yang:gauge64 936 +--rw total-connection-capacity* [protocol] 937 | +--rw protocol uint8 938 | +--rw connection? uint64 939 | +--rw connection-client? uint64 940 | +--rw embryonic? uint64 941 | +--rw embryonic-client? uint64 942 | +--rw connection-ps? uint64 943 | +--rw connection-client-ps? uint64 944 | +--rw request-ps? uint64 945 | +--rw request-client-ps? uint64 946 | +--rw partial-request-ps? uint64 947 | +--rw partial-request-client-ps? uint64 948 +--ro total-attack-connection 949 | +--ro low-percentile* [protocol] 950 | | +--ro protocol uint8 951 | | +--ro connection? yang:gauge64 952 | | +--ro embryonic? yang:gauge64 953 | | +--ro connection-ps? yang:gauge64 954 | | +--ro request-ps? yang:gauge64 955 | | +--ro partial-request-ps? yang:gauge64 956 | +--ro mid-percentile* [protocol] 957 | | +--ro protocol uint8 958 | | +--ro connection? yang:gauge64 959 | | +--ro embryonic? yang:gauge64 960 | | +--ro connection-ps? yang:gauge64 961 | | +--ro request-ps? yang:gauge64 962 | | +--ro partial-request-ps? yang:gauge64 963 | +--ro high-percentile* [protocol] 964 | | +--ro protocol uint8 965 | | +--ro connection? yang:gauge64 966 | | +--ro embryonic? yang:gauge64 967 | | +--ro connection-ps? yang:gauge64 968 | | +--ro request-ps? yang:gauge64 969 | | +--ro partial-request-ps? yang:gauge64 970 | +--ro peak* [protocol] 971 | +--ro protocol uint8 972 | +--ro connection? yang:gauge64 973 | +--ro embryonic? yang:gauge64 974 | +--ro connection-ps? yang:gauge64 975 | +--ro request-ps? yang:gauge64 976 | +--ro partial-request-ps? yang:gauge64 977 +--ro attack-detail 978 +--ro vendor-id? uint32 979 +--ro attack-id? string 980 +--ro attack-name? string 981 +--ro attack-severity? attack-severity 982 +--ro start-time? uint64 983 +--ro end-time? uint64 984 +--ro source-count 985 | +--ro low-percentile? yang:gauge64 986 | +--ro mid-percentile? yang:gauge64 987 | +--ro high-percentile? yang:gauge64 988 | +--ro peak? yang:gauge64 989 +--ro top-talker 990 +--ro source-prefix* [source-prefix] 991 +--ro spoofed-status? boolean 992 +--ro source-prefix inet:ip-prefix 993 +--ro total-attack-traffic* [unit] 994 | +--ro unit unit 995 | +--ro low-percentile? yang:gauge64 996 | +--ro mid-percentile? yang:gauge64 997 | +--ro high-percentile? yang:gauge64 998 | +--ro peak? yang:gauge64 999 +--ro total-attack-connection 1000 +--ro low-percentile* [protocol] 1001 | +--ro protocol uint8 1002 | +--ro connection? yang:gauge64 1003 | +--ro embryonic? yang:gauge64 1004 | +--ro connection-ps? yang:gauge64 1005 | +--ro request-ps? yang:gauge64 1006 | +--ro partial-request-ps? yang:gauge64 1007 +--ro mid-percentile* [protocol] 1008 | +--ro protocol uint8 1009 | +--ro connection? yang:gauge64 1010 | +--ro embryonic? yang:gauge64 1011 | +--ro connection-ps? yang:gauge64 1012 | +--ro request-ps? yang:gauge64 1013 | +--ro partial-request-ps? yang:gauge64 1014 +--ro high-percentile* [protocol] 1015 | +--ro protocol uint8 1016 | +--ro connection? yang:gauge64 1017 | +--ro embryonic? yang:gauge64 1018 | +--ro connection-ps? yang:gauge64 1019 | +--ro request-ps? yang:gauge64 1020 | +--ro partial-request-ps? yang:gauge64 1021 +--ro peak* [protocol] 1022 +--ro protocol uint8 1023 +--ro connection? yang:gauge64 1024 +--ro embryonic? yang:gauge64 1025 +--ro connection-ps? yang:gauge64 1026 +--ro request-ps? yang:gauge64 1027 +--ro partial-request-ps? yang:gauge64 1029 7.2. YANG Module 1031 This module uses types defined in [RFC6991]. 1033 file "ietf-dots-telemetry@2019-10-14.yang" 1034 module ietf-dots-telemetry { 1035 yang-version 1.1; 1036 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 1037 prefix dots-telemetry; 1039 import ietf-dots-signal-channel { 1040 prefix ietf-signal; 1041 reference 1042 "RFC SSSS: Distributed Denial-of-Service Open Threat 1043 Signaling (DOTS) Signal Channel Specification"; 1044 } 1045 import ietf-dots-data-channel { 1046 prefix ietf-data; 1047 reference 1048 "RFC DDDD: Distributed Denial-of-Service Open Threat 1049 Signaling (DOTS) Data Channel Specification"; 1050 } 1051 import ietf-yang-types { 1052 prefix yang; 1053 reference "Section 3 of RFC 6991"; 1054 } 1055 import ietf-inet-types { 1056 prefix inet; 1057 reference "Section 4 of RFC 6991"; 1058 } 1060 organization 1061 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 1062 contact 1063 "WG Web: 1064 WG List: 1066 Author: Mohamed Boucadair 1067 1069 Author: Konda, Tirumaleswar Reddy 1070 "; 1071 description 1072 "This module contains YANG definitions for the signaling 1073 of DOTS telemetry exchanged between a DOTS client and 1074 a DOTS server, by means of the DOTS signal channel. 1076 Copyright (c) 2019 IETF Trust and the persons identified as 1077 authors of the code. All rights reserved. 1079 Redistribution and use in source and binary forms, with or 1080 without modification, is permitted pursuant to, and subject 1081 to the license terms contained in, the Simplified BSD License 1082 set forth in Section 4.c of the IETF Trust's Legal Provisions 1083 Relating to IETF Documents 1084 (http://trustee.ietf.org/license-info). 1086 This version of this YANG module is part of RFC XXXX; see 1087 the RFC itself for full legal notices."; 1089 revision 2019-10-14 { 1090 description 1091 "Initial revision."; 1092 reference 1093 "RFC XXXX: Distributed Denial-of-Service Open Threat 1094 Signaling (DOTS) Telemetry"; 1095 } 1097 feature dots-telemetry { 1098 description 1099 "This feature means that the DOTS signal channel is able 1100 to convey DOTS telemetry data between DOTS clients and 1101 servers."; 1102 } 1104 typedef attack-severity { 1105 type enumeration { 1106 enum "emergency" { 1107 value 1; 1108 description 1109 "The attack is severe: emergency."; 1110 } 1111 enum "critical" { 1112 value 2; 1113 description 1114 "The atatck is critical."; 1115 } 1116 enum "alert" { 1117 value 3; 1118 description 1119 "This is an alert."; 1120 } 1121 } 1122 description 1123 "Enumeration for attack severity."; 1124 } 1125 typedef unit { 1126 type enumeration { 1127 enum "pps" { 1128 value 1; 1129 description 1130 "Packets per second (PPS)."; 1131 } 1132 enum "kilo-pps" { 1133 value 2; 1134 description 1135 "Kilo packets per second (Kpps)."; 1136 } 1137 enum "bps" { 1138 value 3; 1139 description 1140 "Bits per Second (BPS)."; 1141 } 1142 enum "kilobytes-ps" { 1143 value 4; 1144 description 1145 "Kilobytes per second."; 1146 } 1147 enum "megabytes-ps" { 1148 value 5; 1149 description 1150 "Megabytes per second."; 1151 } 1152 enum "gigabytes-ps" { 1153 value 6; 1154 description 1155 "Gigabytes per second."; 1156 } 1157 } 1158 description 1159 "Enumeration to indicate which unit is used."; 1160 } 1162 typedef percentile { 1163 type decimal64 { 1164 fraction-digits 2; 1165 } 1166 description 1167 "The nth percentile of a set of data is the 1168 value at which n percent of the data is below it."; 1169 } 1171 grouping percentile-config { 1172 description 1173 "Configuration of low, mid, and high percentile values."; 1174 leaf low-percentile { 1175 type percentile; 1176 default "10.00"; 1177 description 1178 "Low percentile. If set to '0', this means low-percentiles 1179 are disabled."; 1180 } 1181 leaf mid-percentile { 1182 type percentile; 1183 must '. >= ../low-percentile' { 1184 error-message 1185 "The mid-percentile must be greater than 1186 or equal to the low-percentile."; 1187 } 1188 default "50.00"; 1189 description 1190 "Mid percentile. If set to the same value as low-percentiles, 1191 this means mid-percentiles are disabled."; 1192 } 1193 leaf high-percentile { 1194 type percentile; 1195 must '. >= ../mid-percentile' { 1196 error-message 1197 "The high-percentile must be greater than 1198 or equal to the mid-percentile."; 1199 } 1200 default "90.00"; 1201 description 1202 "High percentile. If set to the same value as mid-percentiles, 1203 this means high-percentiles are disabled."; 1204 } 1205 } 1207 grouping percentile { 1208 description 1209 "Generic grouping for percentile."; 1210 leaf low-percentile { 1211 type yang:gauge64; 1212 description 1213 "Low traffic."; 1214 } 1215 leaf mid-percentile { 1216 type yang:gauge64; 1217 description 1218 "Mid percentile."; 1219 } 1220 leaf high-percentile { 1221 type yang:gauge64; 1222 description 1223 "High percentile."; 1224 } 1225 leaf peak { 1226 type yang:gauge64; 1227 description 1228 "Peak"; 1229 } 1230 } 1232 grouping traffic-unit { 1233 description 1234 "Grouping of traffic as a function of measurement unit."; 1235 leaf unit { 1236 type unit; 1237 description 1238 "The traffic can be measured in packets per 1239 second (PPS) or kilo packets per second (Kpps) and Bits per 1240 Second (BPS), and kilobytes per second or megabytes per second 1241 or gigabytes per second."; 1242 } 1243 uses percentile; 1244 } 1246 grouping traffic-unit-protocol { 1247 description 1248 "Grouping of traffic of a given transport protocol as 1249 a function of measurement unit."; 1250 leaf unit { 1251 type unit; 1252 description 1253 "The traffic can be measured in packets per 1254 second (PPS) or kilo packets per second (Kpps) and Bits per 1255 Second (BPS), and kilobytes per second or megabytes per second 1256 or gigabytes per second."; 1257 } 1258 leaf protocol { 1259 type uint8; 1260 description 1261 "The transport protocol. 1262 Values are taken from the IANA Protocol Numbers registry: 1263 . 1265 For example, this field contains 6 for TCP, 1266 17 for UDP, 33 for DCCP, or 132 for SCTP."; 1267 } 1268 uses percentile; 1270 } 1272 grouping total-connection-capacity { 1273 description 1274 "Total Connections Capacity. If the target is subjected 1275 to resource consuming DDoS attack, these attributes are 1276 useful to detect resource consuming DDoS attacks"; 1277 leaf connection { 1278 type uint64; 1279 description 1280 "The maximum number of simultaneous connections that 1281 are allowed to the target server. The threshold is 1282 transport-protocol specific because the target server 1283 could support multiple protocols."; 1284 } 1285 leaf connection-client { 1286 type uint64; 1287 description 1288 "The maximum number of simultaneous connections that 1289 are allowed to the target server per client."; 1290 } 1291 leaf embryonic { 1292 type uint64; 1293 description 1294 "The maximum number of simultaneous embryonic connections 1295 that are allowed to the target server. The term 'embryonic 1296 connection' refers to a connection whose connection handshake 1297 is not finished and embryonic connection is only possible in 1298 connection-oriented transport protocols like TCP or SCTP."; 1299 } 1300 leaf embryonic-client { 1301 type uint64; 1302 description 1303 "The maximum number of simultaneous embryonic connections 1304 that are allowed to the target server per client."; 1305 } 1306 leaf connection-ps { 1307 type uint64; 1308 description 1309 "The maximum number of connections allowed per second 1310 to the target server."; 1311 } 1312 leaf connection-client-ps { 1313 type uint64; 1314 description 1315 "The maximum number of connections allowed per second 1316 to the target server per client."; 1317 } 1318 leaf request-ps { 1319 type uint64; 1320 description 1321 "The maximum number of requests allowed per second 1322 to the target server."; 1323 } 1324 leaf request-client-ps { 1325 type uint64; 1326 description 1327 "The maximum number of requests allowed per second 1328 to the target server per client."; 1329 } 1330 leaf partial-request-ps { 1331 type uint64; 1332 description 1333 "The maximum number of partial requests allowed per 1334 second to the target server."; 1335 } 1336 leaf partial-request-client-ps { 1337 type uint64; 1338 description 1339 "The maximum number of partial requests allowed per 1340 second to the target server per client."; 1341 } 1342 } 1344 grouping connection { 1345 description 1346 "A set of attributes which represent the attack 1347 characteristics"; 1348 leaf connection { 1349 type yang:gauge64; 1350 description 1351 "The number of simultaneous attack connections to 1352 the target server."; 1353 } 1354 leaf embryonic { 1355 type yang:gauge64; 1356 description 1357 "The number of simultaneous embryonic connections to 1358 the target server."; 1359 } 1360 leaf connection-ps { 1361 type yang:gauge64; 1362 description 1363 "The number of attack conenctions per second to 1364 the target server."; 1365 } 1366 leaf request-ps { 1367 type yang:gauge64; 1368 description 1369 "The number of attack requests per second to 1370 the target server."; 1371 } 1372 leaf partial-request-ps { 1373 type yang:gauge64; 1374 description 1375 "The number of attack partial requests to 1376 the target server."; 1377 } 1378 } 1380 grouping connection-percentile { 1381 description 1382 "Total attack connections."; 1383 container low-percentile { 1384 description 1385 "Low percentile of attack connections."; 1386 uses connection; 1387 } 1388 container mid-percentile { 1389 description 1390 "Mid percentile of attack connections."; 1391 uses connection; 1392 } 1393 container high-percentile { 1394 description 1395 "High percentile of attack connections."; 1396 uses connection; 1397 } 1398 container peak { 1399 description 1400 "Peak attack connections."; 1401 uses connection; 1402 } 1403 } 1405 grouping connection-protocol-percentile { 1406 description 1407 "Total attack connections."; 1408 list low-percentile { 1409 key "protocol"; 1410 description 1411 "Low percentile of attack connections."; 1412 leaf protocol { 1413 type uint8; 1414 description 1415 "The transport protocol. 1416 Values are taken from the IANA Protocol Numbers registry: 1417 ."; 1418 } 1419 uses connection; 1420 } 1421 list mid-percentile { 1422 key "protocol"; 1423 description 1424 "Mid percentile of attack connections."; 1425 leaf protocol { 1426 type uint8; 1427 description 1428 "The transport protocol. 1429 Values are taken from the IANA Protocol Numbers registry: 1430 ."; 1431 } 1432 uses connection; 1433 } 1434 list high-percentile { 1435 key "protocol"; 1436 description 1437 "Highg percentile of attack connections."; 1438 leaf protocol { 1439 type uint8; 1440 description 1441 "The transport protocol. 1442 Values are taken from the IANA Protocol Numbers registry: 1443 ."; 1444 } 1445 uses connection; 1446 } 1447 list peak { 1448 key "protocol"; 1449 description 1450 "Peak attack connections."; 1451 leaf protocol { 1452 type uint8; 1453 description 1454 "The transport protocol. 1455 Values are taken from the IANA Protocol Numbers registry: 1456 ."; 1457 } 1458 uses connection; 1459 } 1460 } 1461 grouping attack-detail { 1462 description 1463 "Various information and details that describe the on-going 1464 attacks that needs to be mitigated by the DOTS server. 1465 The attack details need to cover well-known and common attacks 1466 (such as a SYN Flood) along with new emerging or vendor-specific 1467 attacks."; 1468 leaf vendor-id { 1469 type uint32; 1470 description 1471 "Vendor ID is a security vendor's Enterprise Number."; 1472 } 1473 leaf attack-id { 1474 type string; 1475 description 1476 "Unique identifier assigned by the vendor for the attack."; 1477 } 1478 leaf attack-name { 1479 type string; 1480 description 1481 "Textual representation of attack description. Natural Language 1482 Processing techniques (e.g., word embedding) can possibly be used 1483 to map the attack description to an attack type."; 1484 } 1485 leaf attack-severity { 1486 type attack-severity; 1487 description 1488 "Severity level of an attack"; 1489 } 1490 leaf start-time { 1491 type uint64; 1492 description 1493 "The time the attack started. Start time is represented in seconds 1494 relative to 1970-01-01T00:00:00Z in UTC time."; 1495 } 1496 leaf end-time { 1497 type uint64; 1498 description 1499 "The time the attack ended. End time is represented in seconds 1500 relative to 1970-01-01T00:00:00Z in UTC time."; 1501 } 1502 container source-count { 1503 description 1504 "Indicates the count of unique sources involved 1505 in the attack."; 1506 uses percentile; 1507 } 1508 } 1509 grouping top-talker-aggregate { 1510 description 1511 "Top attack sources."; 1512 list source-prefix { 1513 key "source-prefix"; 1514 description 1515 "IPv4 or IPv6 prefix identifying the attacker(s)."; 1516 leaf spoofed-status { 1517 type boolean; 1518 description 1519 "Indicates whether this address is spoofed."; 1520 } 1521 leaf source-prefix { 1522 type inet:ip-prefix; 1523 description 1524 "IPv4 or IPv6 prefix identifying the attacker(s)."; 1525 } 1526 list total-attack-traffic { 1527 key "unit"; 1528 description 1529 "Total attack traffic issued from this source."; 1530 uses traffic-unit; 1531 } 1532 container total-attack-connection { 1533 description 1534 "Total attack connections issued from this source."; 1535 uses connection-percentile; 1536 } 1537 } 1538 } 1540 grouping top-talker { 1541 description 1542 "Top attack sources."; 1543 list source-prefix { 1544 key "source-prefix"; 1545 description 1546 "IPv4 or IPv6 prefix identifying the attacker(s)."; 1547 leaf spoofed-status { 1548 type boolean; 1549 description 1550 "Indicates whether this address is spoofed."; 1551 } 1552 leaf source-prefix { 1553 type inet:ip-prefix; 1554 description 1555 "IPv4 or IPv6 prefix identifying the attacker(s)."; 1556 } 1557 list total-attack-traffic { 1558 key "unit"; 1559 description 1560 "Total attack traffic issued from this source."; 1561 uses traffic-unit; 1562 } 1563 container total-attack-connection { 1564 description 1565 "Total attack connections issued from this source."; 1566 uses connection-protocol-percentile; 1567 } 1568 } 1569 } 1571 grouping pre-mitigation { 1572 description 1573 "Grouping for the telemetry data."; 1574 list total-traffic-normal-baseline { 1575 key "unit protocol"; 1576 description 1577 "Total traffic normal baselines."; 1578 uses traffic-unit-protocol; 1579 } 1580 list total-attack-traffic { 1581 key "unit protocol"; 1582 config false; 1583 description 1584 "Total attack traffic per protocol."; 1585 uses traffic-unit-protocol; 1586 } 1587 list total-traffic { 1588 key "unit protocol"; 1589 config false; 1590 description 1591 "Total traffic."; 1592 uses traffic-unit-protocol; 1593 } 1594 list total-connection-capacity { 1595 key "protocol"; 1596 description 1597 "Total connection capacity."; 1598 leaf protocol { 1599 type uint8; 1600 description 1601 "The transport protocol. 1602 Values are taken from the IANA Protocol Numbers registry: 1603 ."; 1604 } 1605 uses total-connection-capacity; 1606 } 1607 container total-attack-connection { 1608 config false; 1609 description 1610 "Total attack connections."; 1611 uses connection-protocol-percentile; 1612 } 1613 container attack-detail { 1614 config false; 1615 description 1616 "Attack details."; 1617 uses attack-detail; 1618 container top-talker { 1619 description 1620 "Top attack sources."; 1621 uses top-talker; 1622 } 1623 } 1624 } 1626 augment "/ietf-signal:dots-signal/ietf-signal:message-type/" 1627 + "ietf-signal:mitigation-scope/ietf-signal:scope" { 1628 if-feature "dots-telemetry"; 1629 description 1630 "Extends mitigation scope with telemetry update data."; 1631 list total-attack-traffic { 1632 key "unit"; 1633 description 1634 "Total attack traffic."; 1635 uses traffic-unit; 1636 } 1637 container total-attack-connection { 1638 description 1639 "Total attack connections."; 1640 uses connection-percentile; 1641 } 1642 container attack-detail { 1643 description 1644 "Atatck details"; 1645 uses attack-detail; 1646 container top-talker { 1647 description 1648 "Top attack sources."; 1649 uses top-talker-aggregate; 1650 } 1651 } 1652 } 1653 augment "/ietf-signal:dots-signal/ietf-signal:message-type" { 1654 if-feature "dots-telemetry"; 1655 description 1656 "Add a new choice to enclose telemetry data in DOTS 1657 signal channel."; 1658 case telemetry { 1659 description 1660 "Indicates the message is about telemetry."; 1661 list telemetry { 1662 key "cuid tcid"; 1663 description 1664 "The telemetry data per DOTS client."; 1665 leaf cuid { 1666 type string; 1667 description 1668 "A unique identifier that is 1669 generated by a DOTS client to prevent 1670 request collisions. It is expected that the 1671 cuid will remain consistent throughout the 1672 lifetime of the DOTS client."; 1673 } 1674 leaf cdid { 1675 type string; 1676 description 1677 "The cdid should be included by a server-domain 1678 DOTS gateway to propagate the client domain 1679 identification information from the 1680 gateway's client-facing-side to the gateway's 1681 server-facing-side, and from the gateway's 1682 server-facing-side to the DOTS server. 1684 It may be used by the final DOTS server 1685 for policy enforcement purposes."; 1686 } 1687 leaf tcid { 1688 type uint32; 1689 description 1690 "An identifier for the DOTS telemetry configuration 1691 data."; 1692 } 1693 container telemetry-config { 1694 description 1695 "Uses to set low, mid, and high percentile values."; 1696 uses percentile-config; 1697 list unit-config { 1698 key "unit"; 1699 description 1700 "Controls which units are allowed when sharing telemetry 1701 data."; 1702 leaf unit { 1703 type unit; 1704 description 1705 "The traffic can be measured in packets per 1706 second (PPS) or kilo packets per second (Kpps) and Bits per 1707 Second (BPS), and kilobytes per second or megabytes per second 1708 or gigabytes per second."; 1709 } 1710 leaf status { 1711 type boolean; 1712 description 1713 "Enable/disable the use of the measurement unit."; 1714 } 1715 } 1716 } 1717 list total-pipe-capability { 1718 key "unit"; 1719 description 1720 "Total pipe capacity of a DOTS client domain."; 1721 leaf unit { 1722 type unit; 1723 description 1724 "The traffic can be measured in packets per 1725 second (PPS) or kilo packets per second (Kpps) and Bits per 1726 Second (BPS), and kilobytes per second or megabytes per second 1727 or gigabytes per second."; 1728 } 1729 leaf pipe { 1730 type uint64; 1731 description 1732 "Mid traffic percentile."; 1733 } 1734 } 1735 list pre-mitigation { 1736 key "telemetry-id"; 1737 description 1738 "Pre-mitigation telemetry."; 1739 leaf telemetry-id { 1740 type uint32; 1741 description 1742 "An identifier to uniquely demux telemetry data send using 1743 the same message."; 1744 } 1745 container target { 1746 description 1747 "Indicates the target."; 1748 uses ietf-data:target; 1750 } 1751 uses pre-mitigation; 1752 } 1753 } 1754 } 1755 } 1756 } 1758 1760 8. IANA Considerations 1762 8.1. DOTS Signal Channel CBOR Mappings Registry 1764 This specification registers the DOTS telemetry attributes in the 1765 IANA "DOTS Signal Channel CBOR Mappings" registry established by 1766 [I-D.ietf-dots-signal-channel]. 1768 The DOTS telemetry attributes defined in this specification are 1769 comprehension-optional parameters. 1771 o Note to the RFC Editor: Please delete (TBD1)-(TBD5) once CBOR keys 1772 are assigned from the 0x8000 - 0xBFFF range. 1774 +-------------------+------------+--------+---------------+--------+ 1775 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 1776 | | Type | Key | Type & | Type | 1777 | | | | Information | | 1778 +-------------------+------------+--------+---------------+--------+ 1779 | TODO | | | | | 1780 +-------------------+------------+--------+---------------+--------+ 1782 8.2. DOTS Signal Telemetry YANG Module 1784 This document requests IANA to register the following URI in the "ns" 1785 subregistry within the "IETF XML Registry" [RFC3688]: 1787 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 1788 Registrant Contact: The IESG. 1789 XML: N/A; the requested URI is an XML namespace. 1791 This document requests IANA to register the following YANG module in 1792 the "YANG Module Names" subregistry [RFC7950] within the "YANG 1793 Parameters" registry. 1795 name: ietf-dots-telemetry 1796 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 1797 maintained by IANA: N 1798 prefix: dots-telemetry 1799 reference: RFC XXXX 1801 9. Security Considerations 1803 Security considerations in [I-D.ietf-dots-signal-channel] need to be 1804 taken into consideration. 1806 10. Contributors 1808 The following individuals have contributed to this document: 1810 o Li Su, CMCC, Email: suli@chinamobile.com 1812 o Jin Peng, CMCC, Email: pengjin@chinamobile.com 1814 11. Acknowledgements 1816 The authors would like to thank Flemming Andreasen, Liang Xia, and 1817 Kaname Nishizuka co-authors of https://tools.ietf.org/html/draft- 1818 doron-dots-telemetry-00 draft and everyone who had contributed to 1819 that document. 1821 Authors would like to thank Kaname Nishizuka, Jon Shallow, Wei Pan 1822 and Yuuhei Hayashi for comments and review. 1824 12. References 1826 12.1. Normative References 1828 [Enterprise-Numbers] 1829 "Private Enterprise Numbers", 2005, . 1832 [I-D.ietf-dots-data-channel] 1833 Boucadair, M. and R. K, "Distributed Denial-of-Service 1834 Open Threat Signaling (DOTS) Data Channel Specification", 1835 draft-ietf-dots-data-channel-31 (work in progress), July 1836 2019. 1838 [I-D.ietf-dots-signal-call-home] 1839 K, R., Boucadair, M., and J. Shallow, "Distributed Denial- 1840 of-Service Open Threat Signaling (DOTS) Signal Channel 1841 Call Home", draft-ietf-dots-signal-call-home-06 (work in 1842 progress), September 2019. 1844 [I-D.ietf-dots-signal-channel] 1845 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 1846 Teague, "Distributed Denial-of-Service Open Threat 1847 Signaling (DOTS) Signal Channel Specification", draft- 1848 ietf-dots-signal-channel-37 (work in progress), July 2019. 1850 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1851 Requirement Levels", BCP 14, RFC 2119, 1852 DOI 10.17487/RFC2119, March 1997, 1853 . 1855 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1856 DOI 10.17487/RFC3688, January 2004, 1857 . 1859 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1860 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1861 . 1863 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1864 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1865 October 2013, . 1867 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1868 Application Protocol (CoAP)", RFC 7641, 1869 DOI 10.17487/RFC7641, September 2015, 1870 . 1872 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1873 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1874 . 1876 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1877 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1878 May 2017, . 1880 12.2. Informative References 1882 [I-D.ietf-dots-use-cases] 1883 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 1884 L., and K. Nishizuka, "Use cases for DDoS Open Threat 1885 Signaling", draft-ietf-dots-use-cases-20 (work in 1886 progress), September 2019. 1888 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1889 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1890 . 1892 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 1893 Threat Signaling (DOTS) Requirements", RFC 8612, 1894 DOI 10.17487/RFC8612, May 2019, 1895 . 1897 Authors' Addresses 1899 Tirumaleswar Reddy 1900 McAfee, Inc. 1901 Embassy Golf Link Business Park 1902 Bangalore, Karnataka 560071 1903 India 1905 Email: kondtir@gmail.com 1907 Mohamed Boucadair 1908 Orange 1909 Rennes 35000 1910 France 1912 Email: mohamed.boucadair@orange.com 1914 Ehud Doron 1915 Radware Ltd. 1916 Raoul Wallenberg Street 1917 Tel-Aviv 69710 1918 Israel 1920 Email: ehudd@radware.com 1922 Meiling Chen 1923 CMCC 1924 32, Xuanwumen West 1925 BeiJing, BeiJing 100053 1926 China 1928 Email: chenmeiling@chinamobile.com