idnits 2.17.1 draft-banghart-mile-rolie-csirt-02.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 29, 2017) is 2371 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-16) exists of draft-ietf-mile-rolie-10 ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MILE Working Group J. Field 3 Internet-Draft Pivotal 4 Intended status: Informational S. Banghart 5 Expires: May 2, 2018 NIST 6 October 29, 2017 8 Definition of ROLIE CSIRT Extension 9 draft-banghart-mile-rolie-csirt-02 11 Abstract 13 This document extends the Resource-Oriented Lightweight Information 14 Exchange (ROLIE) core to add the information type categories and 15 related requirements needed to support Computer Security Incident 16 Response Team (CSIRT) use cases. The indicator and incident 17 information types are defined as ROLIE extensions. Additional 18 supporting requirements are also defined that describe the use of 19 specific formats and link relations pertaining to the new information 20 types. 22 Status of This Memo 24 This Internet-Draft is submitted to IETF in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 2, 2018. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3. Additional Requirements for the Atom Publishing Protocol . . 4 56 3.1. Use of HTTP requests . . . . . . . . . . . . . . . . . . 4 57 3.1.1. / (forward slash) Resource URL . . . . . . . . . . . 4 58 3.1.2. User Authorization . . . . . . . . . . . . . . . . . 4 59 4. Additonal Requirements for the Atom Syndication Format . . . 4 60 4.1. Additonal Requirements for the atom:feed element . . . . 4 61 4.2. Additonal Requirements for the atom:entry element . . . . 5 62 4.3. Additional Requirements for the atom:content 63 element . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4.3.1. The IODEF Document . . . . . . . . . . . . . . . . . 5 65 5. Information-type Extensions . . . . . . . . . . . . . . . . . 6 66 5.1. The "incident" information type . . . . . . . . . . . . . 6 67 5.2. The "indicator" information type . . . . . . . . . . . . 6 68 5.3. Use of the rolie:format element . . . . . . . . . . . . . 7 69 5.3.1. IODEF Format . . . . . . . . . . . . . . . . . . . . 7 70 5.3.2. STIX Format . . . . . . . . . . . . . . . . . . . . . 7 71 6. rolie:property Extensions . . . . . . . . . . . . . . . . . . 7 72 6.1. urn:ietf:params:rolie:property:csirt:ID . . . . . . . . . 8 73 7. Use of the atom:link element . . . . . . . . . . . . . . . . 8 74 7.1. Link relations for the 'incident' 75 information-type . . . . . . . . . . . . . . . . . . . . 8 76 7.2. Link relations for the 'indicator' 77 information-type . . . . . . . . . . . . . . . . . . . . 8 78 7.3. Link relations for both information-types . . . . . . . . 9 79 8. Other Extensions . . . . . . . . . . . . . . . . . . . . . . 9 80 8.1. Use of atom:category . . . . . . . . . . . . . . . . . . 10 81 8.1.1. Newly registered category values . . . . . . . . . . 10 82 8.1.2. Expectation and Impact Classes . . . . . . . . . . . 10 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 84 9.1. information-type registrations . . . . . . . . . . . . . 10 85 9.1.1. incident information-type . . . . . . . . . . . . . . 11 86 9.1.2. indicator information-type . . . . . . . . . . . . . 11 87 9.2. atom:category scheme registrations . . . . . . . . . . . 11 88 9.2.1. category:csirt:iodef:purpose . . . . . . . . . . . . 11 89 9.2.2. category:csirt:iodef:restriction . . . . . . . . . . 11 90 9.3. rolie:property name registrations . . . . . . . . . . . . 12 91 9.3.1. property:csirt:id . . . . . . . . . . . . . . . . . . 12 92 10. Security Considerations . . . . . . . . . . . . . . . . . . . 12 93 11. Normative References . . . . . . . . . . . . . . . . . . . . 12 94 Appendix A. Non-Normative Examples . . . . . . . . . . . . . . . 13 95 A.1. Use of Link Relations . . . . . . . . . . . . . . . . . . 13 96 A.1.1. Use Case: Incident Sharing . . . . . . . . . . . . . 14 97 A.1.2. Use Case: Collaborative Investigation . . . . . . . . 16 98 A.1.3. Use Case: Cyber Data Repository . . . . . . . . . . 18 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 101 1. Introduction 103 Threats to computer security are evolving ever more rapidly as time 104 goes on. As software increases in complexity, the number of 105 vulnerabilities in systems and networks can increase exponentially. 106 Threat actors looking to exploit these vulnerabilities are making 107 more frequent and more widely distributed attacks across a large 108 variety of systems. The adoption of liberal information sharing 109 amongst attackers allows a discovered vulnerability to be shared and 110 used to attack a vulnerable system within a narrow window of time. 111 As the skills and knowledge required to identify and combat these 112 attacks become more and more specialized, even a well established and 113 secure system may find itself unable to quickly respond to an 114 incident. Effective identification of and response to a 115 sophisticated attack requires open cooperation and collaboration 116 between defending operators, software vendors, and end-users. To 117 improve the timeliness of responses, automation must be used to 118 acquire, contextualize, and put to use shared computer security 119 information. 121 CSIRTS share two primary forms of information: incidents and 122 indicators. Using these forms of information, analysts are able to 123 perform a wide range of activities both proactive and reactive to 124 ensure the security of their systems. 126 Incident information describes a cyber security incident. Such 127 information may include attack characteristics, information about the 128 attacker, and attack vector data. Sharing this information helps 129 analysts within the sharing community to inoculate their systems 130 against similar attacks, providing proactive protection. 132 Indicator information describes the symptoms or necessary pre- 133 conditions of an attack. Everything from system vulnerabilities to 134 unexpected network traffic can help analysts secure systems and 135 prepare for an attack. Making this information available for sharing 136 aids in the proactive defense of systems both within an operating 137 unit but also for any CSIRTs that are part of a sharing consortium. 139 As a means to bring automation of content discovery and dissemination 140 into the CSIRT domain, this specification provides an extension to 141 the Resource-Oriented Lightweight Information Exchange (ROLIE) core 142 [I-D.ietf-mile-rolie] designed to address CSIRT use cases. The 143 primary purpose of this extension is to define two new information 144 types: incident, and indicator, along with formats and link relations 145 that support these information-types. 147 2. Terminology 149 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 150 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 151 document are to be interpreted as described in [RFC2119]. 153 Definitions for some of the common computer security-related 154 terminology used in this document can be found in Section 2 of 155 [RFC5070]. 157 3. Additional Requirements for the Atom Publishing Protocol 159 This document specifies the following requirements for use of the 160 Atom Publishing Protocol. 162 3.1. Use of HTTP requests 164 This document defines the following requirements on HTTP request 165 behavior: 167 3.1.1. / (forward slash) Resource URL 169 The forward slash resource URL MUST be supported as defined in 170 Section 5.5 [I-D.ietf-mile-rolie]. Note that this is a stricter 171 requirement than [I-D.ietf-mile-rolie]. 173 3.1.2. User Authorization 175 When the content model for the Atom element of an Atom 176 Entry contains an , then authorization MUST be 177 adjudicated based upon the Atom element(s), whose values 178 have been mapped as per Section 8.1.1. 180 4. Additonal Requirements for the Atom Syndication Format 182 This document specifies the following additional requirements for the 183 Atom Syndication Format. 185 4.1. Additonal Requirements for the atom:feed element 187 A feed containing IODEF incident content MUST contain at least two 188 additional elements. One category element MUST have 189 the name attribute be equal to 190 'urn:ietf:params:rolie:category:csirt:iodef:purpose' and the other 191 'urn:ietf:params:rolie:category:csirt:iodef:restriction'. This 192 metadata provides valuable metadata for searching and organization 193 IODEF documents. 195 When the name attribute of this element is 196 'urn:ietf:params:rolie:category:csirt:iodef:purpose', the value 197 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 198 traceback, mitigation, reporting, or other. 200 When the name attribute of this element is 201 'urn:ietf:params:rolie:category:csirt:iodef:restriction', the value 202 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 203 public, need-to-know, private, default. 205 4.2. Additonal Requirements for the atom:entry element 207 An entry containing an IODEF payload MUST contain a 208 element with the following requirements: 210 The "name" attribute is urn:ietf:params:rolie:property:csirt:id. 212 The "value" attribute SHOULD be established via the concatenation of 213 the value of the name attribute from the IODEF element 214 and the corresponding value of the element. This 215 requirement ensures a simple and direct one-to-one relationship 216 between an IODEF incident ID and a corresponding Feed entry ID and 217 avoids the need for any system to maintain a persistent store of 218 these identity mappings. 220 4.3. Additional Requirements for the atom:content element 222 This document defines the following additional requirements for the 223 content element, and the content linked to by the href attribute of 224 the content element: 226 4.3.1. The IODEF Document 228 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 229 a element. Instead, the related activity SHOULD be 230 available via a link rel=related. 232 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 233 a element. Instead, the related history SHOULD be 234 available via a atom:link rel="history". 236 5. Information-type Extensions 238 5.1. The "incident" information type 240 The "incident" information type represents any information describing 241 or pertaining to a computer security incident. This document uses 242 the definition of incident provided by [RFC4949]. Provided below is 243 a non-exhaustive list of information that may be considered to be an 244 incident information type. 246 o Timing information: start and end times for the incident and/or 247 the response. 249 o Descriptive information: plain text or machine readable data that 250 provides some degree of description of the incident itself. 252 o Response information: the methods and results of a response to the 253 incident. 255 o Meta and contact information: data about the CSIRT that recorded 256 the information, or the operator that enacted the response. 258 o Effect and result information: data that describes the effects of 259 an incident, or what the final results of the incident are. 261 Note again that this list is not exhaustive, any information that in 262 is the abstract realm of an incident should be classified under this 263 information-type. 265 5.2. The "indicator" information type 267 The "indicator" information type represents computer security 268 indicators or any information surrounding them. This document uses 269 the definition of indicator provided by [RFC4949]. Some examples of 270 indicator information is provided below, but note that indicator is 271 defined in an abstract sense, to be understood as a flexible and 272 widely-applicable definition. 274 o Specific vulnerabilities that indicate a vector for attack. 276 o Signs of malicious reconnaissance. 278 o Definitions of patterns of other indicators. 280 o Events that may indicate an attack and information regarding those 281 events. 283 o Meta information about the collecting agent. 285 This list is intended to provide examples of the indicator 286 information-type, not to define it. 288 5.3. Use of the rolie:format element 290 This document does not contain any additional requirements for the 291 rolie:format element; the formats that follow are provided as 292 examples of formats that describe the incident and indicator 293 information type. The formats are in no particular order, and are 294 not requirements, nor suggestions by the authors. 296 5.3.1. IODEF Format 298 The Incident Object Description Exchange Format (IODEF) is a format 299 for representing computer security information commonly exchanged 300 between Computer Security Incident Response Teams (CSIRTs) or other 301 operational security teams. 303 IODEF conveys indicators, incident reports, response activities, and 304 related meta-data in an XML serialization. This information is 305 formally structured in order to support and encourage automated 306 machine-to-machine security communication, as well as enhanced 307 processing at the endpoint. 309 The full IODEF specification provides further high-level discussion 310 and technical details. 312 The use of the IODEF format imposes additional requirements on the 313 server. 315 5.3.2. STIX Format 317 STIX is a structured language for describing a wide range of security 318 resources. STIX approaches the problem with a focus on flexibility, 319 automation, readability, and extensibility. 321 The use of STIX as the content of an Entry does not impose any 322 additional requirements on ROLIE implementations. 324 6. rolie:property Extensions 326 This document provides new registrations for valid rolie:property 327 names. These properties provide optional exposure point for valuable 328 information in the linked content document. Exposing this 329 information in a rolie:property element means that clients do not 330 need to download the linked document to determine if it contains the 331 information they are looking for. 333 6.1. urn:ietf:params:rolie:property:csirt:ID 335 Provides an exposure point for an identifier from the indicator or 336 incident document. This value SHOULD be a uniquely identifying value 337 for the document linked to in this entry's atom:content element. 339 7. Use of the atom:link element 341 These sections define requirements for atom:link elements in Entries. 342 Note that the requirements are determined by the information type 343 that appears in either the Entry or in the parent Feed. 345 7.1. Link relations for the 'incident' information-type 347 If the category of an Entry is the incident information type, then 348 the following requirements MUST be followed for inclusion of 349 atom:link elements. 351 +------------+----------------------------------------+-------------+ 352 | Name | Description | Conformance | 353 +------------+----------------------------------------+-------------+ 354 | indicators | Provides a link to a collection of | SHOULD | 355 | | zero or more instances of cyber | | 356 | | security indicators that are | | 357 | | associated with the resource. | | 358 | evidence | Provides a link to a collection of | SHOULD | 359 | | zero or more resources that provides | | 360 | | some proof of attribution for an | | 361 | | incident. The evidence may or may not | | 362 | | have any identified chain of custody. | | 363 | attacker | Provides a link to a collection of | SHOULD | 364 | | zero or more resources that provides a | | 365 | | representation of the attacker. | | 366 | vector | Provides a link to a collection of | SHOULD | 367 | | zero or more resources that provides a | | 368 | | representation of the method used by | | 369 | | the attacker. | | 370 +------------+----------------------------------------+-------------+ 372 Table 1: Link Relations for Resource-Oriented Lightweight Indicator 373 Exchange 375 7.2. Link relations for the 'indicator' information-type 377 If the category of an Entry is the indicator information type, then 378 the following requirements MUST be followed for inclusion of 379 atom:link elements. 381 +-----------+-----------------------------------------+-------------+ 382 | Name | Description | Conformance | 383 +-----------+-----------------------------------------+-------------+ 384 | incidents | Provides a link to a collection of zero | SHOULD | 385 | | or more instances of incident | | 386 | | representations associated with the | | 387 | | resource. | | 388 +-----------+-----------------------------------------+-------------+ 390 Table 2: Link Relations for Resource-Oriented Lightweight Indicator 391 Exchange 393 7.3. Link relations for both information-types 395 If the category of an Entry is either information-type, the following 396 requirements MUST be followed for inclusion of atom:link elements. 398 +-----------------------+-----------------------------+-------------+ 399 | Name | Description | Conformance | 400 +-----------------------+-----------------------------+-------------+ 401 | assessments | Provides a link to a | MAY | 402 | | collection of zero or more | | 403 | | resources that represent | | 404 | | the results of executing a | | 405 | | benchmark. | | 406 | reports | Provides a link to a | MAY | 407 | | collection of zero or more | | 408 | | resources that represent | | 409 | | RID reports. | | 410 | traceRequests | Provides a link to a | MAY | 411 | | collection of zero or more | | 412 | | resources that represent | | 413 | | RID traceRequests. | | 414 | investigationRequests | Provides a link to a | MAY | 415 | | collection of zero or more | | 416 | | resources that represent | | 417 | | RID investigationRequests. | | 418 +-----------------------+-----------------------------+-------------+ 420 Table 3: Link Relations for Resource-Oriented Lightweight Indicator 421 Exchange 423 8. Other Extensions 425 This document defines additional extensions as follows: 427 8.1. Use of atom:category 429 8.1.1. Newly registered category values 431 This document registers two additional valid atom:category names: 432 'urn:ietf:params:rolie:category:csirt:iodef:purpose' and 433 'urn:ietf:params:rolie:category:csirt:iodef:restriction'. This IODEF 434 content exposure provides valuable metadata for the searching and 435 organization of IODEF documents. 437 When the name attribute of the category is 438 'urn:ietf:params:rolie:category:csirt:iodef:purpose', the value 439 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 440 traceback, mitigation, reporting, or other. 442 When the name attribute of the category is 443 'urn:ietf:params:rolie:category:csirt:iodef:restriction', the value 444 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 445 public, need-to-know, private, default. 447 8.1.2. Expectation and Impact Classes 449 It is frequently the case that an organization will need to triage 450 their investigation and response activities based upon, e.g., the 451 state of the current threat environment, or simply as a result of 452 having limited resources. 454 In order to enable operators to effectively prioritize their response 455 activity, it is RECOMMENDED that feed implementers provide Atom 456 categories that correspond to the IODEF Expectation and Impact 457 classes. The availability of these feed categories will enable 458 clients to more easily retrieve and prioritize cyber security 459 information that has already been identified as having a specific 460 potential impact, or having a specific expectation. 462 Support for these categories may also enable efficiencies for 463 organizations that already have established (or plan to establish) 464 operational processes and workflows that are based on these IODEF 465 classes. 467 9. IANA Considerations 469 9.1. information-type registrations 471 IANA has added the following entries to the "ROLIE Security Resource 472 Information Type Sub-Registry" registry located at 473 . 475 9.1.1. incident information-type 477 The entry is as follows: 479 name: incident 481 index: TBD 483 reference: This document, Section 5.1 485 9.1.2. indicator information-type 487 The entry is as follows: 489 name: indicator 491 index: TBD 493 reference: This document, Section 5.2 495 9.2. atom:category scheme registrations 497 IANA has added the following entries to the "ROLIE URN Parameters" 498 registry located in . 500 9.2.1. category:csirt:iodef:purpose 502 The entry is as follows: 504 name: category:csirt:iodef:purpose 506 Extension IRI: urn:ietf:params:rolie:category:csirt:iodef:purpose 508 Reference: This document, Section 8.1.1 510 Subregistry: None 512 9.2.2. category:csirt:iodef:restriction 514 The entry is as follows: 516 name: category:csirt:iodef:restriction 518 Extension IRI: 519 urn:ietf:params:rolie:category:csirt:iodef:restriction 521 Reference: This document, Section 8.1.1 522 Subregistry: None 524 9.3. rolie:property name registrations 526 IANA has added the following entries to the "ROLIE URN Parameters" 527 registry located in . 529 9.3.1. property:csirt:id 531 The entry is as follows: 533 name: property:csirt:id 535 Extension IRI: urn:ietf:params:rolie:property:csirt:id 537 Reference: This document, section 6.3.1 539 Subregistry: None 541 10. Security Considerations 543 This document implies the use of ROLIE in high-security use cases, as 544 such, added care should be taken to fortify and secure ROLIE 545 repositories and clients using this extension. The guidance in the 546 ROLIE core specification is strongly recommended, and implementers 547 should consider adding additional security measures as they see fit. 549 When providing a private workspace for closed sharing, it is 550 recommended that the ROLIE repository checks user authorization when 551 the user sends a GET request to the service document. If the user is 552 not authorized to send any requests to a given workspace or 553 collection, that workspace or collection should be truncated from the 554 service document in the response. In this way the existence of 555 unauthorized content remains unknown to potential attackers, 556 hopefully reducing attack surface. 558 11. Normative References 560 [I-D.ietf-mile-rolie] 561 Field, J., Banghart, S., and D. Waltermire, "Resource- 562 Oriented Lightweight Information Exchange", draft-ietf- 563 mile-rolie-10 (work in progress), September 2017. 565 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 566 Requirement Levels", BCP 14, RFC 2119, 567 DOI 10.17487/RFC2119, March 1997, 568 . 570 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 571 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 572 . 574 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 575 Object Description Exchange Format", RFC 5070, 576 DOI 10.17487/RFC5070, December 2007, 577 . 579 Appendix A. Non-Normative Examples 581 The following provide examples of some potential use cases of the 582 CSIRT ROLIE extension, and provides a showcase for some of its 583 benefits over traditional solutions. 585 The general non-normative examples provided in the core ROLIE 586 document remain an excellent reference resource for typical ROLIE 587 usage. 589 A.1. Use of Link Relations 591 A key benefit of using the RESTful architectural style is the ability 592 to enable the client to navigate to related resources through the use 593 of hypermedia links. In the Atom Syndication Format, the type of the 594 related resource identified in a element is indicated via the 595 "rel" attribute, where the value of this attribute identifies the 596 kind of related resource available at the corresponding "href" 597 attribute. Thus, in lieu of a well-known URI template the URI itself 598 is effectively opaque to the client, and therefore the client must 599 understand the semantic meaning of the "rel" attribute in order to 600 successfully navigate. Broad interoperability may be based upon a 601 sharing consortium defining a well-known set of Atom Link Relation 602 types. These Link Relation types may either be registered with IANA, 603 or held in a private registry. 605 Individual CSIRTs may always define their own link relation types in 606 order to support specific use cases, however support for a core set 607 of well-known link relation types is encouraged as this will maximize 608 interoperability. 610 In addition, it may be beneficial to define use case profiles that 611 correspond to specific groupings of supported link relationship 612 types. In this way, a CSIRT may unambiguously specify the classes of 613 use cases for which a client can expect to find support. 615 The following sections provide non-normative examples of link 616 relation usage. Three distinct cyber security information sharing 617 use case scenarios are described. In each use case, the unique 618 benefits of adopting a resource-oriented approach to information 619 sharing are illustrated. It is important to note that these use 620 cases are intended to be a small representative set and is by no 621 means meant to be an exhaustive list. The intent is to illustrate 622 how the use of link relationship types will enable this resource- 623 oriented approach to cyber security information sharing to 624 successfully support the complete range of existing use cases, and 625 also to motivate an initial list of well-defined link relationship 626 types. 628 A.1.1. Use Case: Incident Sharing 630 This section provides a non-normative example of an incident sharing 631 use case. 633 In this use case, a member CSIRT shares incident information with 634 another member CSIRT in the same consortium. The client CSIRT 635 retrieves a feed of incidents, and is able to identify one particular 636 entry of interest. The client then does an HTTP GET on that entry, 637 and the representation of that resource contains link relationships 638 for both the associated "indicators" and the incident "history", and 639 so on. The client CSIRT recognizes that some of the indicator and 640 history may be relevant within her local environment, and can respond 641 proactively. 643 Example HTTP GET response for an incident entry: 645 646 648 http://www.example.org/csirt/private/incidents/123456 649 Sample Incident 650 652 654 2012-08-04T18:13:51.0Z 655 2012-08-05T18:13:51.0Z 657 660 662 664 666 669 671 672 673 674 676 678 679 123456 681 682 683 685 686 688 As can be seen in the example response, the Atom elements 689 enable the client to navigate to the related indicator resources, 690 and/or the history entries associated with this incident. 692 A.1.2. Use Case: Collaborative Investigation 694 This section provides a non-normative example of a collaborative 695 investigation use case. 697 In this use case, two member CSIRTs that belong to a closed sharing 698 consortium are collaborating on an incident investigation. The 699 initiating CSIRT performs an HTTP GET to retrieve the service 700 document of the peer CSIRT, and determines the collection name to be 701 used for creating a new investigation request. The initiating CSIRT 702 then POSTs a new incident entry to the appropriate collection URL. 703 The target CSIRT acknowledges the request by responding with an HTTP 704 status code 201 Created. 706 Example HTTP GET response for the service document: 708 HTTP/1.1 200 OK 709 Date: Fri, 24 Aug 2012 17:09:11 GMT 710 Content-Length: 934 711 Content-Type: application/atomsvc+xml;charset="utf-8" 713 714 716 718 RID Use Case Requests 719 721 Investigation Requests 722 application/atom+xml; type=entry 723 724 725 Trace Requests 726 application/atom+xml; type=entry 727 728 729 730 732 As can be seen in the example response, the Atom 733 elements enable the client to determine the appropriate collection 734 URL to request an investigation or a trace. 736 The client CSIRT then POSTs a new entry to the appropriate feed 737 collection. Note that the element of the new entry may 738 contain a RID message of type "InvestigationRequest" if desired, 739 however this would NOT be required. The entry content itself need 740 only be an IODEF document, with the choice of the target collection 741 resource URL indicating the callers intent. A CSIRT would be free to 742 use any URI template to accept investigationRequests. 744 POST /csirt/RID/InvestigationRequests HTTP/1.1 745 Host: www.example.org 746 Content-Type: application/atom+xml;type=entry 747 Content-Length: 852 749 750 752 New Investigation Request 753 http://www.example2.org/csirt/private/incidents/123456 754 755 756 2012-08-12T11:08:22Z 757 Name of peer CSIRT 758 759 760 762 763 123 765 766 767 768 769 771 The receiving CSIRT acknowledges the request with HTTP return code 772 201 Created. 774 HTTP/1.1 201 Created 775 Date: Fri, 24 Aug 2012 19:17:11 GMT 776 Content-Length: 906 777 Content-Type: application/atom+xml;type=entry 778 Location: http://www.example.org/csirt/RID/InvestigationRequests/823 779 ETag: "8a9h9he4qphqh" 781 782 784 New Investigation Request 785 http://www.example.org/csirt/RID/InvestigationRequests/823 786 787 788 2012-08-12T11:08:30Z 789 2012-08-12T11:08:30Z 790 Name of peer CSIRT 791 792 793 795 796 123 798 799 800 801 802 804 Consistent with HTTP/1.1 RFC, the location header indicates the URL 805 of the newly created InvestigationRequest. If for some reason the 806 request were not authorized, the client would receive an HTTP status 807 code 403 Unauthorized. In this case the HTTP response body may 808 contain additional details, if an as appropriate. 810 A.1.3. Use Case: Cyber Data Repository 812 This section provides a non-normative example of a cyber security 813 data repository use case. 815 In this use case a client accesses a persistent repository of cyber 816 security data via a RESTful usage model. Retrieving a feed 817 collection is analogous to an SQL SELECT statement producing a result 818 set. Retrieving an individual Atom Entry is analogous to a SQL 819 SELECT statement based upon a primary key producing a unique record. 820 The cyber security data contained in the repository may include 821 different data types, including indicators, incidents, benchmarks, or 822 any other related resources. In this use case, the repository is 823 queried via HTTP GET, and the results that are returned to the client 824 may optionally contain URL references to other cyber security 825 resources that are known to be related. These related resources may 826 also be persisted locally, or they may exist at another (remote) 827 cyber data respository. 829 Example HTTP GET request to a persistent repository for any resources 830 representing Distributed Denial of Service (DDOS) attacks: 832 GET /csirt/repository/ddos 833 Host: www.example.org 834 Accept: application/atom+xml 836 The corresponding HTTP response would be an XML document containing 837 the DDOS feed. 839 Example HTTP GET response for a DDOS feed: 841 HTTP/1.1 200 OK 842 Date: Fri, 24 Aug 2012 17:20:11 GMT 843 Content-Length: nnnn 844 Content-Type: application/atom+xml;type=feed;charset="utf-8" 846 847 856 857 emc-csirt-iodef-feed-service 858 http://www.example.org/csirt/repository/ddos 859 860 Atom formatted representation of a feed of known ddos resources. 861 862 2012-05-04T18:13:51.0Z 863 864 csirt@example.org 865 EMC CSIRT 866 868 869 872 873 http://www.example.org/csirt/repository/ddos/123456 874 Sample DDOS Incident 875 877 879 882 884 885 2012-08-04T18:13:51.0Z 886 2012-08-05T18:13:51.0Z 887 889 890 892 894 A short description of this DDOS attack, extracted 895 from the IODEF Incident class, element. 896 897 898 900 901 902 904 906 This feed document has two atom entries, one of which has been 907 elided. The completed entry illustrates an Atom element that 908 provides a summary of essential details about one particular DDOS 909 incident. Based upon this summary information and the provided 910 category information, a client may choose to do an HTTP GET operation 911 to retrieve the full details of the DDOS incident. This example 912 shows how a persistent repository may provide links to additional 913 resources, both local and remote. 915 Note that the provider of a persistent repostory is not obligated to 916 follow any particular URL template scheme. The repository available 917 at the hypothetical provider "www.example.com" uses a different URL 918 pattern than the hypothetical repository available at "www.cyber- 919 agency.gov". When a client de-references a link to resource that is 920 located in a remote repository the client may be challenged for 921 authentication credentials acceptable to that provider. If the two 922 repository providers choose to support a federated identity scheme or 923 some other form of single-sign-on technology, then the user 924 experience can be improved for interactive clients (e.g., a human 925 user at a browser). However, this is not required and is an 926 implementation choice that is out of scope for this specification. 928 Authors' Addresses 930 John P. Field 931 Pivotal Software, Inc. 932 625 Avenue of the Americas 933 New York, New York 934 USA 936 Phone: (646)792-5770 937 Email: jfield@pivotal.io 939 Stephen A. Banghart 940 National Institute of Standards and Technology 941 100 Bureau Drive 942 Gaithersburg, Maryland 943 USA 945 Phone: (301)975-4288 946 Email: sab3@nist.gov