idnits 2.17.1 draft-banghart-mile-rolie-csirt-01.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 (May 3, 2017) is 2548 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) == Outdated reference: A later version (-16) exists of draft-ietf-mile-rolie-03 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: November 4, 2017 NIST 6 May 3, 2017 8 Definition of ROLIE CSIRT Extension 9 draft-banghart-mile-rolie-csirt-01 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 Contributing to this document 24 The source for this draft is being maintained in GitHub. Suggested 25 changes should be submitted as pull requests at 26 . Instructions are on that page 27 as well. Editorial changes can be managed in GitHub, but any 28 substantial issues need to be discussed on the MILE mailing list. 30 Status of This Memo 32 This Internet-Draft is submitted to IETF in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on November 4, 2017. 47 Copyright Notice 49 Copyright (c) 2017 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. New information-types . . . . . . . . . . . . . . . . . . . . 4 64 3.1. The "incident" information type . . . . . . . . . . . . . 4 65 3.2. The "indicator" information type . . . . . . . . . . . . 5 66 4. Usage of CSIRT Information Types in the Atom Publishing 67 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 4.1. / (forward slash) Resource URL . . . . . . . . . . . . . 5 69 5. Usage of CSIRT Information Types in the atom:feed element . . 5 70 6. Usage of CSIRT Information Types in an atom:entry . . . . . . 6 71 6.1. Use of the atom:link element . . . . . . . . . . . . . . 6 72 6.1.1. Link relations for the 'incident' 73 information-type . . . . . . . . . . . . . . . . . . 6 74 6.1.2. Link relations for the 'indicator' 75 information-type . . . . . . . . . . . . . . . . . . 6 76 6.1.3. Link relations for both information-types . . . . . . 7 77 6.2. Use of the rolie:format element . . . . . . . . . . . . . 7 78 6.2.1. IODEF Format . . . . . . . . . . . . . . . . . . . . 8 79 6.2.2. STIX Format . . . . . . . . . . . . . . . . . . . . . 8 80 6.3. Use of the rolie:property element . . . . . . . . . . . . 8 81 6.3.1. urn:ietf:params:rolie:property:csirt:ID . . . . . . . 8 82 6.4. Additional requirements for use of IODEF . . . . . . . . 9 83 6.4.1. The IODEF Document . . . . . . . . . . . . . . . . . 9 84 6.4.2. Category Element . . . . . . . . . . . . . . . . . . 9 85 6.4.3. Entry Elements . . . . . . . . . . . . . . . . . . . 9 86 6.4.4. User Authorization . . . . . . . . . . . . . . . . . 10 87 6.4.5. Expectation and Impact Classes . . . . . . . . . . . 10 88 6.4.6. Search . . . . . . . . . . . . . . . . . . . . . . . 10 89 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 90 7.1. information-type registrations . . . . . . . . . . . . . 11 91 7.1.1. incident information-type . . . . . . . . . . . . . . 11 92 7.1.2. indicator information-type . . . . . . . . . . . . . 11 93 7.2. atom:category scheme registrations . . . . . . . . . . . 11 94 7.2.1. category:csirt:iodef:purpose . . . . . . . . . . . . 11 95 7.2.2. category:csirt:iodef:restriction . . . . . . . . . . 12 96 7.3. rolie:property name registrations . . . . . . . . . . . . 12 97 7.3.1. property:csirt:id . . . . . . . . . . . . . . . . . . 12 98 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 99 9. Normative References . . . . . . . . . . . . . . . . . . . . 13 100 Appendix A. Non-Normative Examples . . . . . . . . . . . . . . . 13 101 A.1. Use of Link Relations . . . . . . . . . . . . . . . . . . 13 102 A.1.1. Use Case: Incident Sharing . . . . . . . . . . . . . 14 103 A.1.2. Use Case: Collaborative Investigation . . . . . . . . 16 104 A.1.3. Use Case: Cyber Data Repository . . . . . . . . . . 18 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 107 1. Introduction 109 Threats to computer security are evolving ever more rapidly as time 110 goes on. As software increases in complexity, the number of 111 vulnerabilities in systems and networks can increase exponentially. 112 Threat actors looking to exploit these vulnerabilities are making 113 more frequent and more widely distributed attacks across a large 114 variety of systems. The adoption of liberal information sharing 115 amongst attackers allows a discovered vulnerability to be shared and 116 used to attack a vulnerable system within a narrow window of time. 117 As the skills and knowledge required to identify and combat these 118 attacks become more and more specialized, even a well established and 119 secure system may find itself unable to quickly respond to an 120 incident. Effective identification of and response to a 121 sophisticated attack requires open cooperation and collaboration 122 between defending operators, software vendors, and end-users. To 123 improve the timeliness of responses, automation must be used to 124 acquire, contextualize, and put to use shared computer security 125 information. 127 CSIRTS share two primary forms of information: incidents and 128 indicators. Using these forms of information, analysts are able to 129 perform a wide range of activities both proactive and reactive to 130 ensure the security of their systems. 132 Incident information describes a cyber security incident. Such 133 information may include attack characteristics, information about the 134 attacker, and attack vector data. Sharing this information helps 135 analysts within the sharing community to inoculate their systems 136 against similar attacks, providing proactive protection. 138 Indicator information describes the symptoms or necessary pre- 139 conditions of an attack. Everything from system vulnerabilities to 140 unexpected network traffic can help analysts secure systems and 141 prepare for an attack. Making this information available for sharing 142 aids in the proactive defense of systems both within an operating 143 unit but also for any CSIRTs that are part of a sharing consortium. 145 As a means to bring automation of content discovery and dissemination 146 into the CSIRT domain, this specification provides an extension to 147 the Resource-Oriented Lightweight Information Exchange (ROLIE) core 148 [I-D.ietf-mile-rolie] designed to address CSIRT use cases. The 149 primary purpose of this extension is to define two new information 150 types: incident, and indicator, along with formats and link relations 151 that support these information-types. 153 2. Terminology 155 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 156 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 157 document are to be interpreted as described in [RFC2119]. 159 Definitions for some of the common computer security-related 160 terminology used in this document can be found in Section 2 of 161 [RFC5070]. 163 3. New information-types 165 This document defines the following two information types: 167 3.1. The "incident" information type 169 The "incident" information type represents any information describing 170 or pertaining to a computer security incident. This document uses 171 the definition of incident provided by [RFC4949]. Provided below is 172 a non-exhaustive list of information that may be considered to be an 173 incident information type. 175 o Timing information: start and end times for the incident and/or 176 the response. 178 o Descriptive information: plain text or machine readable data that 179 provides some degree of description of the incident itself. 181 o Response information: the methods and results of a response to the 182 incident. 184 o Meta and contact information: data about the CSIRT that recorded 185 the information, or the operator that enacted the response. 187 o Effect and result information: data that describes the effects of 188 an incident, or what the final results of the incident are. 190 Note again that this list is not exhaustive, any information that in 191 is the abstract realm of an incident should be classified under this 192 information-type. 194 3.2. The "indicator" information type 196 The "indicator" information type represents computer security 197 indicators or any information surrounding them. This document uses 198 the definition of indicator provided by [RFC4949]. Some examples of 199 indicator information is provided below, but note that indicator is 200 defined in an abstract sense, to be understood as a flexible and 201 widely-applicable definition. 203 o Specific vulnerabilities that indicate a vector for attack. 205 o Signs of malicious reconnaissance. 207 o Definitions of patterns of other indicators. 209 o Events that may indicate an attack and information regarding those 210 events. 212 o Meta information about the collecting agent. 214 This list is intended to provide examples of the indicator 215 information-type, not to define it. 217 4. Usage of CSIRT Information Types in the Atom Publishing Protocol 219 These requirements apply when a ROLIE repository contains any 220 Collections with categories with scheme attributes of either CSIRT 221 information type, or if the CSIRT information types appear in the 222 Categories document. 224 4.1. / (forward slash) Resource URL 226 The forward slash resource URL MUST be supported as defined in 227 Section 5.5 [I-D.ietf-mile-rolie]. Note that this is a stricter 228 requirement than the core document. 230 5. Usage of CSIRT Information Types in the atom:feed element 232 This document does not define any additional requirements for Feeds. 234 6. Usage of CSIRT Information Types in an atom:entry 236 This document defines the following requirements for any Entries that 237 are of the CSIRT information type categories. 239 6.1. Use of the atom:link element 241 These sections define requirements for atom:link elements in Entries. 242 Note that the requirements are determined by the information type 243 that appears in either the Entry or in the parent Feed. 245 6.1.1. Link relations for the 'incident' information-type 247 If the category of an Entry is the incident information type, then 248 the following requirements MUST be followed for inclusion of 249 atom:link elements. 251 +------------+----------------------------------------+-------------+ 252 | Name | Description | Conformance | 253 +------------+----------------------------------------+-------------+ 254 | indicators | Provides a link to a collection of | SHOULD | 255 | | zero or more instances of cyber | | 256 | | security indicators that are | | 257 | | associated with the resource. | | 258 | evidence | Provides a link to a collection of | SHOULD | 259 | | zero or more resources that provides | | 260 | | some proof of attribution for an | | 261 | | incident. The evidence may or may not | | 262 | | have any identified chain of custody. | | 263 | attacker | Provides a link to a collection of | SHOULD | 264 | | zero or more resources that provides a | | 265 | | representation of the attacker. | | 266 | vector | Provides a link to a collection of | SHOULD | 267 | | zero or more resources that provides a | | 268 | | representation of the method used by | | 269 | | the attacker. | | 270 +------------+----------------------------------------+-------------+ 272 Table 1: Link Relations for Resource-Oriented Lightweight Indicator 273 Exchange 275 6.1.2. Link relations for the 'indicator' information-type 277 If the category of an Entry is the indicator information type, then 278 the following requirements MUST be followed for inclusion of 279 atom:link elements. 281 +-----------+-----------------------------------------+-------------+ 282 | Name | Description | Conformance | 283 +-----------+-----------------------------------------+-------------+ 284 | incidents | Provides a link to a collection of zero | SHOULD | 285 | | or more instances of incident | | 286 | | representations associated with the | | 287 | | resource. | | 288 +-----------+-----------------------------------------+-------------+ 290 Table 2: Link Relations for Resource-Oriented Lightweight Indicator 291 Exchange 293 6.1.3. Link relations for both information-types 295 If the category of an Entry is either information-type, the following 296 requirements MUST be followed for inclusion of atom:link elements. 298 +-----------------------+-----------------------------+-------------+ 299 | Name | Description | Conformance | 300 +-----------------------+-----------------------------+-------------+ 301 | assessments | Provides a link to a | MAY | 302 | | collection of zero or more | | 303 | | resources that represent | | 304 | | the results of executing a | | 305 | | benchmark. | | 306 | reports | Provides a link to a | MAY | 307 | | collection of zero or more | | 308 | | resources that represent | | 309 | | RID reports. | | 310 | traceRequests | Provides a link to a | MAY | 311 | | collection of zero or more | | 312 | | resources that represent | | 313 | | RID traceRequests. | | 314 | investigationRequests | Provides a link to a | MAY | 315 | | collection of zero or more | | 316 | | resources that represent | | 317 | | RID investigationRequests. | | 318 +-----------------------+-----------------------------+-------------+ 320 Table 3: Link Relations for Resource-Oriented Lightweight Indicator 321 Exchange 323 6.2. Use of the rolie:format element 325 This document does not contain any additional requirements for the 326 rolie:format element; the formats that follow are provided as 327 examples of formats that describe the incident and indicator 328 information type. The formats are in no particular order, and are 329 not requirements, nor suggestions by the authors. 331 6.2.1. IODEF Format 333 The Incident Object Description Exchange Format (IODEF) is a format 334 for representing computer security information commonly exchanged 335 between Computer Security Incident Response Teams (CSIRTs) or other 336 operational security teams. 338 IODEF conveys indicators, incident reports, response activities, and 339 related meta-data in an XML serialization. This information is 340 formally structured in order to support and encourage automated 341 machine-to-machine security communication, as well as enhanced 342 processing at the endpoint. 344 The full IODEF specification provides further high-level discussion 345 and technical details. 347 The use of the IODEF format imposes additional requirements on the 348 server. See Section 6.4. 350 6.2.2. STIX Format 352 STIX is a structured language for describing a wide range of security 353 resources. STIX approaches the problem with a focus on flexibility, 354 automation, readability, and extensibility. 356 The use of STIX as the content of an Entry does not impose any 357 additional requirements on ROLIE implementations. 359 6.3. Use of the rolie:property element 361 This document provides new registrations for valid rolie:property 362 names. These properties provide optional exposure point for valuable 363 information in the linked content document. Exposing this 364 information in a rolie:property element means that clients do not 365 need to download the linked document to determine if it contains the 366 information they are looking for. 368 6.3.1. urn:ietf:params:rolie:property:csirt:ID 370 Provides an exposure point for an identifier from the indicator or 371 incident document. This value SHOULD be a uniquely identifying value 372 for the document linked to in this entry's atom:content element. 374 6.4. Additional requirements for use of IODEF 376 This section provides the normative requirements for usage of the 377 IODEF format. These requirements SHOULD apply when an atom:entry has 378 an IODEF format entity linked to by its atom:content element. 380 6.4.1. The IODEF Document 382 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 383 a element. Instead, the related activity SHOULD be 384 available via a link rel=related. 386 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 387 a element. Instead, the related history SHOULD be 388 available via a atom:link rel="history". The associated href MAY 389 leverage OpenSearch to specify the required query. 391 6.4.2. Category Element 393 A collection or entry containing IODEF incident content MUST contain 394 at least two additional elements. One category 395 element MUST have the name attribute be equal to 396 'urn:ietf:params:rolie:category:csirt:iodef:purpose' and the other 397 'urn:ietf:params:rolie:category:csirt:iodef:restriction'. This 398 metadata provides valuable metadata for searching and organization 399 IODEF documents. 401 When the name attribute of this element is 402 'urn:ietf:params:rolie:category:csirt:iodef:purpose', the value 403 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 404 traceback, mitigation, reporting, or other. 406 When the name attribute of this element is 407 'urn:ietf:params:rolie:category:csirt:iodef:restriction', the value 408 attribute MUST be constrained as per section 3.2 of IODEF, e.g. 409 public, need-to-know, private, default. 411 6.4.3. Entry Elements 413 An entry containing an IODEF payload MUST contain a 414 element with the following requirements: 416 The "name" attribute is urn:ietf:params:rolie:property:csirt:id. 418 The "value" attribute SHOULD be established via the concatenation of 419 the value of the name attribute from the IODEF element 420 and the corresponding value of the element. This 421 requirement ensures a simple and direct one-to-one relationship 422 between an IODEF incident ID and a corresponding Feed entry ID and 423 avoids the need for any system to maintain a persistent store of 424 these identity mappings. 426 6.4.4. User Authorization 428 When the content model for the Atom element of an Atom 429 Entry contains an , then authorization MUST be 430 adjudicated based upon the Atom element(s), whose values 431 have been mapped as per Section 6.4.2. 433 6.4.5. Expectation and Impact Classes 435 It is frequently the case that an organization will need to triage 436 their investigation and response activities based upon, e.g., the 437 state of the current threat environment, or simply as a result of 438 having limited resources. 440 In order to enable operators to effectively prioritize their response 441 activity, it is RECOMMENDED that feed implementers provide Atom 442 categories that correspond to the IODEF Expectation and Impact 443 classes. The availability of these feed categories will enable 444 clients to more easily retrieve and prioritize cyber security 445 information that has already been identified as having a specific 446 potential impact, or having a specific expectation. 448 Support for these categories may also enable efficiencies for 449 organizations that already have established (or plan to establish) 450 operational processes and workflows that are based on these IODEF 451 classes. 453 6.4.6. Search 455 Implementers SHOULD support search based upon the IODEF AlternativeID 456 class as a search parameter. 458 Implementers SHOULD support search based upon the four timestamp 459 elements of the IODEF Incident class: , , 460 , and . 462 Implementers MAY support additional search capabilities based upon 463 any of the remaining elements of the IODEF Incident class, including 464 the element. 466 Collections that support use of the RID schema as a content model in 467 the Atom member entry element (e.g. in a report resource 468 representation reachable via the "report" link relationship) MUST 469 support search operations that include the RID MessageType as a 470 search parameter, in addition to the aforementioned IODEF schema 471 elements, as contained within the element. 473 7. IANA Considerations 475 7.1. information-type registrations 477 IANA has added the following entries to the "ROLIE Security Resource 478 Information Type Sub-Registry" registry located at 479 . 481 7.1.1. incident information-type 483 The entry is as follows: 485 name: incident 487 index: TBD 489 reference: This document, Section 3.1 491 7.1.2. indicator information-type 493 The entry is as follows: 495 name: indicator 497 index: TBD 499 reference: This document, Section 3.2 501 7.2. atom:category scheme registrations 503 IANA has added the following entries to the "ROLIE URN Parameters" 504 registry located in . 506 7.2.1. category:csirt:iodef:purpose 508 The entry is as follows: 510 name: category:csirt:iodef:purpose 512 Extension IRI: urn:ietf:params:rolie:category:csirt:iodef:purpose 514 Reference: This document, Section 6.4.2 516 Subregistry: None 518 7.2.2. category:csirt:iodef:restriction 520 The entry is as follows: 522 name: category:csirt:iodef:restriction 524 Extension IRI: 525 urn:ietf:params:rolie:category:csirt:iodef:restriction 527 Reference: This document, Section 6.4.2 529 Subregistry: None 531 7.3. rolie:property name registrations 533 IANA has added the following entries to the "ROLIE URN Parameters" 534 registry located in . 536 7.3.1. property:csirt:id 538 The entry is as follows: 540 name: property:csirt:id 542 Extension IRI: urn:ietf:params:rolie:property:csirt:id 544 Reference: This document, section 6.3.1 546 Subregistry: None 548 8. Security Considerations 550 This document implies the use of ROLIE in high-security use cases, as 551 such, added care should be taken to fortify and secure ROLIE 552 repositories and clients using this extension. The guidance in the 553 ROLIE core specification is strongly recommended, and implementers 554 should consider adding additional security measures as they see fit. 556 When providing a private workspace for closed sharing, it is 557 recommended that the ROLIE repository checks user authorization when 558 the user sends a GET request to the service document. If the user is 559 not authorized to send any requests to a given workspace or 560 collection, that workspace or collection should be truncated from the 561 service document in the response. In this way the existence of 562 unauthorized content remains unknown to potential attackers, 563 hopefully reducing attack surface. 565 9. Normative References 567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 568 Requirement Levels", BCP 14, RFC 2119, 569 DOI 10.17487/RFC2119, March 1997, 570 . 572 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 573 Object Description Exchange Format", RFC 5070, 574 DOI 10.17487/RFC5070, December 2007, 575 . 577 [I-D.ietf-mile-rolie] 578 Field, J., Banghart, S., and D. Waltermire, "Resource- 579 Oriented Lightweight Information Exchange", draft-ietf- 580 mile-rolie-03 (work in progress), July 2016. 582 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 583 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 584 . 586 Appendix A. Non-Normative Examples 588 The following provide examples of some potential use cases of the 589 CSIRT ROLIE extension, and provides a showcase for some of its 590 benefits over traditional solutions. 592 The general non-normative examples provided in the core ROLIE 593 document remain an excellent reference resource for typical ROLIE 594 usage. 596 A.1. Use of Link Relations 598 A key benefit of using the RESTful architectural style is the ability 599 to enable the client to navigate to related resources through the use 600 of hypermedia links. In the Atom Syndication Format, the type of the 601 related resource identified in a element is indicated via the 602 "rel" attribute, where the value of this attribute identifies the 603 kind of related resource available at the corresponding "href" 604 attribute. Thus, in lieu of a well-known URI template the URI itself 605 is effectively opaque to the client, and therefore the client must 606 understand the semantic meaning of the "rel" attribute in order to 607 successfully navigate. Broad interoperability may be based upon a 608 sharing consortium defining a well-known set of Atom Link Relation 609 types. These Link Relation types may either be registered with IANA, 610 or held in a private registry. 612 Individual CSIRTs may always define their own link relation types in 613 order to support specific use cases, however support for a core set 614 of well-known link relation types is encouraged as this will maximize 615 interoperability. 617 In addition, it may be beneficial to define use case profiles that 618 correspond to specific groupings of supported link relationship 619 types. In this way, a CSIRT may unambiguously specify the classes of 620 use cases for which a client can expect to find support. 622 The following sections provide non-normative examples of link 623 relation usage. Three distinct cyber security information sharing 624 use case scenarios are described. In each use case, the unique 625 benefits of adopting a resource-oriented approach to information 626 sharing are illustrated. It is important to note that these use 627 cases are intended to be a small representative set and is by no 628 means meant to be an exhaustive list. The intent is to illustrate 629 how the use of link relationship types will enable this resource- 630 oriented approach to cyber security information sharing to 631 successfully support the complete range of existing use cases, and 632 also to motivate an initial list of well-defined link relationship 633 types. 635 A.1.1. Use Case: Incident Sharing 637 This section provides a non-normative example of an incident sharing 638 use case. 640 In this use case, a member CSIRT shares incident information with 641 another member CSIRT in the same consortium. The client CSIRT 642 retrieves a feed of incidents, and is able to identify one particular 643 entry of interest. The client then does an HTTP GET on that entry, 644 and the representation of that resource contains link relationships 645 for both the associated "indicators" and the incident "history", and 646 so on. The client CSIRT recognizes that some of the indicator and 647 history may be relevant within her local environment, and can respond 648 proactively. 650 Example HTTP GET response for an incident entry: 652 653 655 http://www.example.org/csirt/private/incidents/123456 656 Sample Incident 657 659 661 2012-08-04T18:13:51.0Z 662 2012-08-05T18:13:51.0Z 664 667 669 671 673 676 678 679 680 681 683 685 686 123456 688 689 690 692 693 695 As can be seen in the example response, the Atom elements 696 enable the client to navigate to the related indicator resources, 697 and/or the history entries associated with this incident. 699 A.1.2. Use Case: Collaborative Investigation 701 This section provides a non-normative example of a collaborative 702 investigation use case. 704 In this use case, two member CSIRTs that belong to a closed sharing 705 consortium are collaborating on an incident investigation. The 706 initiating CSIRT performs an HTTP GET to retrieve the service 707 document of the peer CSIRT, and determines the collection name to be 708 used for creating a new investigation request. The initiating CSIRT 709 then POSTs a new incident entry to the appropriate collection URL. 710 The target CSIRT acknowledges the request by responding with an HTTP 711 status code 201 Created. 713 Example HTTP GET response for the service document: 715 HTTP/1.1 200 OK 716 Date: Fri, 24 Aug 2012 17:09:11 GMT 717 Content-Length: 934 718 Content-Type: application/atomsvc+xml;charset="utf-8" 720 721 723 725 RID Use Case Requests 726 728 Investigation Requests 729 application/atom+xml; type=entry 730 731 732 Trace Requests 733 application/atom+xml; type=entry 734 735 736 737 739 As can be seen in the example response, the Atom 740 elements enable the client to determine the appropriate collection 741 URL to request an investigation or a trace. 743 The client CSIRT then POSTs a new entry to the appropriate feed 744 collection. Note that the element of the new entry may 745 contain a RID message of type "InvestigationRequest" if desired, 746 however this would NOT be required. The entry content itself need 747 only be an IODEF document, with the choice of the target collection 748 resource URL indicating the callers intent. A CSIRT would be free to 749 use any URI template to accept investigationRequests. 751 POST /csirt/RID/InvestigationRequests HTTP/1.1 752 Host: www.example.org 753 Content-Type: application/atom+xml;type=entry 754 Content-Length: 852 756 757 759 New Investigation Request 760 http://www.example2.org/csirt/private/incidents/123456 761 762 763 2012-08-12T11:08:22Z 764 Name of peer CSIRT 765 766 767 769 770 123 772 773 774 775 776 778 The receiving CSIRT acknowledges the request with HTTP return code 779 201 Created. 781 HTTP/1.1 201 Created 782 Date: Fri, 24 Aug 2012 19:17:11 GMT 783 Content-Length: 906 784 Content-Type: application/atom+xml;type=entry 785 Location: http://www.example.org/csirt/RID/InvestigationRequests/823 786 ETag: "8a9h9he4qphqh" 788 789 791 New Investigation Request 792 http://www.example.org/csirt/RID/InvestigationRequests/823 793 794 795 2012-08-12T11:08:30Z 796 2012-08-12T11:08:30Z 797 Name of peer CSIRT 798 799 800 802 803 123 805 806 807 808 809 811 Consistent with HTTP/1.1 RFC, the location header indicates the URL 812 of the newly created InvestigationRequest. If for some reason the 813 request were not authorized, the client would receive an HTTP status 814 code 403 Unauthorized. In this case the HTTP response body may 815 contain additional details, if an as appropriate. 817 A.1.3. Use Case: Cyber Data Repository 819 This section provides a non-normative example of a cyber security 820 data repository use case. 822 In this use case a client accesses a persistent repository of cyber 823 security data via a RESTful usage model. Retrieving a feed 824 collection is analogous to an SQL SELECT statement producing a result 825 set. Retrieving an individual Atom Entry is analogous to a SQL 826 SELECT statement based upon a primary key producing a unique record. 827 The cyber security data contained in the repository may include 828 different data types, including indicators, incidents, benchmarks, or 829 any other related resources. In this use case, the repository is 830 queried via HTTP GET, and the results that are returned to the client 831 may optionally contain URL references to other cyber security 832 resources that are known to be related. These related resources may 833 also be persisted locally, or they may exist at another (remote) 834 cyber data respository. 836 Example HTTP GET request to a persistent repository for any resources 837 representing Distributed Denial of Service (DDOS) attacks: 839 GET /csirt/repository/ddos 840 Host: www.example.org 841 Accept: application/atom+xml 843 The corresponding HTTP response would be an XML document containing 844 the DDOS feed. 846 Example HTTP GET response for a DDOS feed: 848 HTTP/1.1 200 OK 849 Date: Fri, 24 Aug 2012 17:20:11 GMT 850 Content-Length: nnnn 851 Content-Type: application/atom+xml;type=feed;charset="utf-8" 853 854 863 864 emc-csirt-iodef-feed-service 865 http://www.example.org/csirt/repository/ddos 866 867 Atom formatted representation of a feed of known ddos resources. 868 869 2012-05-04T18:13:51.0Z 870 871 csirt@example.org 872 EMC CSIRT 873 875 876 879 880 http://www.example.org/csirt/repository/ddos/123456 881 Sample DDOS Incident 882 884 886 889 891 892 2012-08-04T18:13:51.0Z 893 2012-08-05T18:13:51.0Z 894 896 897 899 901 A short description of this DDOS attack, extracted 902 from the IODEF Incident class, element. 903 904 905 907 908 909 911 913 This feed document has two atom entries, one of which has been 914 elided. The completed entry illustrates an Atom element that 915 provides a summary of essential details about one particular DDOS 916 incident. Based upon this summary information and the provided 917 category information, a client may choose to do an HTTP GET operation 918 to retrieve the full details of the DDOS incident. This example 919 shows how a persistent repository may provide links to additional 920 resources, both local and remote. 922 Note that the provider of a persistent repostory is not obligated to 923 follow any particular URL template scheme. The repository available 924 at the hypothetical provider "www.example.com" uses a different URL 925 pattern than the hypothetical repository available at "www.cyber- 926 agency.gov". When a client de-references a link to resource that is 927 located in a remote repository the client may be challenged for 928 authentication credentials acceptable to that provider. If the two 929 repository providers choose to support a federated identity scheme or 930 some other form of single-sign-on technology, then the user 931 experience can be improved for interactive clients (e.g., a human 932 user at a browser). However, this is not required and is an 933 implementation choice that is out of scope for this specification. 935 Authors' Addresses 937 John P. Field 938 Pivotal Software, Inc. 939 625 Avenue of the Americas 940 New York, New York 941 USA 943 Phone: (646)792-5770 944 Email: jfield@pivotal.io 946 Stephen A. Banghart 947 National Institute of Standards and Technology 948 100 Bureau Drive 949 Gaithersburg, Maryland 950 USA 952 Phone: (301)975-4288 953 Email: sab3@nist.gov