idnits 2.17.1 draft-banghart-mile-rolie-csirt-03.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 (March 5, 2018) is 2245 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MILE Working Group S. Banghart 3 Internet-Draft NIST 4 Intended status: Informational J. Field 5 Expires: September 6, 2018 Pivotal 6 March 5, 2018 8 Definition of ROLIE CSIRT Extension 9 draft-banghart-mile-rolie-csirt-03 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 September 6, 2018. 39 Copyright Notice 41 Copyright (c) 2018 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 4. Additional Requirements for the Atom Syndication Format . . . 4 59 5. Information-type Extensions . . . . . . . . . . . . . . . . . 4 60 5.1. The "incident" information type . . . . . . . . . . . . . 4 61 5.2. The "indicator" information type . . . . . . . . . . . . 5 62 5.3. Use of the rolie:format element . . . . . . . . . . . . . 5 63 5.3.1. IODEF Format . . . . . . . . . . . . . . . . . . . . 6 64 5.3.2. STIX Format . . . . . . . . . . . . . . . . . . . . . 6 65 6. rolie:property Extensions . . . . . . . . . . . . . . . . . . 6 66 6.1. urn:ietf:params:rolie:property:csirt:ID . . . . . . . . . 6 67 7. Use of the atom:link element . . . . . . . . . . . . . . . . 6 68 7.1. Link relations for the 'incident' 69 information-type . . . . . . . . . . . . . . . . . . . . 7 70 7.2. Link relations for the 'indicator' 71 information-type . . . . . . . . . . . . . . . . . . . . 7 72 7.3. Link relations for both information-types . . . . . . . . 8 73 8. Other Extensions . . . . . . . . . . . . . . . . . . . . . . 8 74 8.1. Use of atom:category . . . . . . . . . . . . . . . . . . 8 75 8.1.1. Newly registered category values . . . . . . . . . . 8 76 8.1.2. Expectation and Impact Classes . . . . . . . . . . . 9 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 9.1. information-type registrations . . . . . . . . . . . . . 9 79 9.1.1. incident information-type . . . . . . . . . . . . . . 9 80 9.1.2. indicator information-type . . . . . . . . . . . . . 9 81 9.2. atom:category scheme registrations . . . . . . . . . . . 10 82 9.2.1. category:csirt:iodef:purpose . . . . . . . . . . . . 10 83 9.2.2. category:csirt:iodef:restriction . . . . . . . . . . 10 84 9.3. rolie:property name registrations . . . . . . . . . . . . 10 85 9.3.1. property:csirt:id . . . . . . . . . . . . . . . . . . 10 86 10. Security Considerations . . . . . . . . . . . . . . . . . . . 11 87 11. Normative References . . . . . . . . . . . . . . . . . . . . 11 88 Appendix A. Non-Normative Examples . . . . . . . . . . . . . . . 12 89 A.1. Use of Link Relations . . . . . . . . . . . . . . . . . . 12 90 A.1.1. Use Case: Incident Sharing . . . . . . . . . . . . . 13 91 A.1.2. Use Case: Collaborative Investigation . . . . . . . . 15 92 A.1.3. Use Case: Cyber Data Repository . . . . . . . . . . 17 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 95 1. Introduction 97 Threats to computer security are evolving ever more rapidly as time 98 goes on. As software increases in complexity, the number of 99 vulnerabilities in systems and networks can increase exponentially. 100 Threat actors looking to exploit these vulnerabilities are making 101 more frequent and more widely distributed attacks across a large 102 variety of systems. The adoption of liberal information sharing 103 amongst attackers allows a discovered vulnerability to be shared and 104 used to attack a vulnerable system within a narrow window of time. 105 As the skills and knowledge required to identify and combat these 106 attacks become more and more specialized, even a well established and 107 secure system may find itself unable to quickly respond to an 108 incident. Effective identification of and response to a 109 sophisticated attack requires open cooperation and collaboration 110 between defending operators, software vendors, and end-users. To 111 improve the timeliness of responses, automation must be used to 112 acquire, contextualize, and put to use shared computer security 113 information. 115 CSIRTS share two primary forms of information: incidents and 116 indicators. Using these forms of information, analysts are able to 117 perform a wide range of activities both proactive and reactive to 118 ensure the security of their systems. 120 Incident information describes a cyber security incident. Such 121 information may include attack characteristics, information about the 122 attacker, and attack vector data. Sharing this information helps 123 analysts within the sharing community to inoculate their systems 124 against similar attacks, providing proactive protection. 126 Indicator information describes the symptoms or necessary pre- 127 conditions of an attack. Everything from system vulnerabilities to 128 unexpected network traffic can help analysts secure systems and 129 prepare for an attack. Making this information available for sharing 130 aids in the proactive defense of systems both within an operating 131 unit but also for any CSIRTs that are part of a sharing consortium. 133 As a means to bring automation of content discovery and dissemination 134 into the CSIRT domain, this specification provides an extension to 135 the Resource-Oriented Lightweight Information Exchange (ROLIE) core 136 [RFC8322] designed to address CSIRT use cases. The primary purpose 137 of this extension is to define two new information types: incident, 138 and indicator, along with formats and link relations that support 139 these information-types. 141 2. Terminology 143 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 144 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 145 document are to be interpreted as described in [RFC2119]. 147 Definitions for some of the common computer security-related 148 terminology used in this document can be found in Section 2 of 149 [RFC5070]. 151 3. Additional Requirements for the Atom Publishing Protocol 153 This document specifies the following additional requirements for use 154 of the Atom Publishing Protocol.[RFC5023] 156 3.1. Use of HTTP requests 158 This document defines the following requirements on HTTP request 159 behavior: 161 3.1.1. / (forward slash) Resource URL 163 The forward slash resource URL SHOULD be supported as defined in 164 Section 5.5 [RFC8322]. Note that this is a stricter requirement than 165 [RFC8322]. 167 4. Additional Requirements for the Atom Syndication Format 169 This document does not specify any additional requirements for the 170 Atom Syndication Format. [RFC4287] 172 5. Information-type Extensions 174 5.1. The "incident" information type 176 The "incident" information type represents any information describing 177 or pertaining to a computer security incident. This document uses 178 the definition of incident provided by [RFC4949]. Provided below is 179 a non-exhaustive list of information that may be considered to be an 180 incident information type. 182 o Timing information: start and end times for the incident and/or 183 the response. 185 o Descriptive information: plain text or machine readable data that 186 provides some degree of description of the incident itself. 188 o Response information: the methods and results of a response to the 189 incident. 191 o Meta and contact information: data about the CSIRT that recorded 192 the information, or the operator that enacted the response. 194 o Effect and result information: data that describes the effects of 195 an incident, or what the final results of the incident are. 197 Note again that this list is not exhaustive, any information that in 198 is the abstract realm of an incident should be classified under this 199 information-type. 201 5.2. The "indicator" information type 203 The "indicator" information type represents computer security 204 indicators or any information surrounding them. This document uses 205 the definition of indicator provided by [RFC4949]. Some examples of 206 indicator information is provided below, but note that indicator is 207 defined in an abstract sense, to be understood as a flexible and 208 widely-applicable definition. 210 o Specific vulnerabilities that indicate a vector for attack. 212 o Signs of malicious reconnaissance. 214 o Definitions of patterns of other indicators. 216 o Events that may indicate an attack and information regarding those 217 events. 219 o Meta information about the collecting agent. 221 This list is intended to provide examples of the indicator 222 information-type, not to define it. 224 5.3. Use of the rolie:format element 226 This document does not contain any additional requirements for the 227 rolie:format element; the formats that follow are provided as 228 examples of formats that describe the incident and indicator 229 information type. The formats are in no particular order, and are 230 not requirements, nor suggestions by the authors. 232 5.3.1. IODEF Format 234 The Incident Object Description Exchange Format (IODEF) is a format 235 for representing computer security information commonly exchanged 236 between Computer Security Incident Response Teams (CSIRTs) or other 237 operational security teams. 239 IODEF conveys indicators, incident reports, response activities, and 240 related meta-data in an XML serialization. This information is 241 formally structured in order to support and encourage automated 242 machine-to-machine security communication, as well as enhanced 243 processing at the endpoint. 245 The full IODEF specification provides further high-level discussion 246 and technical details. 248 5.3.2. STIX Format 250 STIX is a structured language for describing a wide range of security 251 resources. STIX approaches the problem with a focus on flexibility, 252 automation, readability, and extensibility. 254 The use of STIX as the content of an Entry does not impose any 255 additional requirements on ROLIE implementations. 257 6. rolie:property Extensions 259 This document provides new registrations for valid rolie:property 260 names. These properties provide optional exposure point for valuable 261 information in the linked content document. Exposing this 262 information in a rolie:property element means that clients do not 263 need to download the linked document to determine if it contains the 264 information they are looking for. 266 6.1. urn:ietf:params:rolie:property:csirt:ID 268 Provides an XML element that can be populated with an identifier from 269 the indicator or incident document linked to by an atom:content 270 element. This value SHOULD be a uniquely identifying value for the 271 document linked to in this entry's atom:content element. 273 7. Use of the atom:link element 275 These sections define requirements for atom:link elements in Entries. 276 Note that the requirements are determined by the information type 277 that appears in either the Entry or in the parent Feed. 279 7.1. Link relations for the 'incident' information-type 281 If the category of an Entry is the incident information type, then 282 the following requirements MUST be followed for inclusion of 283 atom:link elements. 285 +------------+----------------------------------------+-------------+ 286 | Name | Description | Conformance | 287 +------------+----------------------------------------+-------------+ 288 | indicators | Provides a link to a collection of | SHOULD | 289 | | zero or more instances of cyber | | 290 | | security indicators that are | | 291 | | associated with the resource. | | 292 | evidence | Provides a link to a collection of | SHOULD | 293 | | zero or more resources that provides | | 294 | | some proof of attribution for an | | 295 | | incident. The evidence may or may not | | 296 | | have any identified chain of custody. | | 297 | attacker | Provides a link to a collection of | SHOULD | 298 | | zero or more resources that provides a | | 299 | | representation of the attacker. | | 300 | vector | Provides a link to a collection of | SHOULD | 301 | | zero or more resources that provides a | | 302 | | representation of the method used by | | 303 | | the attacker. | | 304 +------------+----------------------------------------+-------------+ 306 Table 1: Link Relations for Resource-Oriented Lightweight Indicator 307 Exchange 309 7.2. Link relations for the 'indicator' information-type 311 If the category of an Entry is the indicator information type, then 312 the following requirements MUST be followed for inclusion of 313 atom:link elements. 315 +-----------+-----------------------------------------+-------------+ 316 | Name | Description | Conformance | 317 +-----------+-----------------------------------------+-------------+ 318 | incidents | Provides a link to a collection of zero | SHOULD | 319 | | or more instances of incident | | 320 | | representations associated with the | | 321 | | resource. | | 322 +-----------+-----------------------------------------+-------------+ 324 Table 2: Link Relations for Resource-Oriented Lightweight Indicator 325 Exchange 327 7.3. Link relations for both information-types 329 If the category of an Entry is either information-type, the following 330 requirements MUST be followed for inclusion of atom:link elements. 332 +-----------------------+-----------------------------+-------------+ 333 | Name | Description | Conformance | 334 +-----------------------+-----------------------------+-------------+ 335 | assessments | Provides a link to a | MAY | 336 | | collection of zero or more | | 337 | | resources that represent | | 338 | | the results of executing a | | 339 | | benchmark. | | 340 | reports | Provides a link to a | MAY | 341 | | collection of zero or more | | 342 | | resources that represent | | 343 | | RID reports. | | 344 | traceRequests | Provides a link to a | MAY | 345 | | collection of zero or more | | 346 | | resources that represent | | 347 | | RID traceRequests. | | 348 | investigationRequests | Provides a link to a | MAY | 349 | | collection of zero or more | | 350 | | resources that represent | | 351 | | RID investigationRequests. | | 352 +-----------------------+-----------------------------+-------------+ 354 Table 3: Link Relations for Resource-Oriented Lightweight Indicator 355 Exchange 357 8. Other Extensions 359 This document defines additional extensions as follows: 361 8.1. Use of atom:category 363 8.1.1. Newly registered category values 365 This document registers two additional registered atom:category 366 names: 'urn:ietf:params:rolie:category:csirt:iodef:purpose' and 367 'urn:ietf:params:rolie:category:csirt:iodef:restriction'. These 368 categories IODEF content exposure provides valuable metadata for the 369 searching and organization of IODEF documents. 371 When the name attribute of the category is 372 'urn:ietf:params:rolie:category:csirt:iodef:purpose', the value 373 attribute SHOULD be constrained as per section 3.2 of IODEF 374 [RFC7970], e.g. traceback, mitigation, reporting, or other. 376 When the name attribute of the category is 377 'urn:ietf:params:rolie:category:csirt:iodef:restriction', the value 378 attribute SHOULD be constrained as per section 3.2 of IODEF 379 [RFC7970], e.g. public, need-to-know, private, default. 381 8.1.2. Expectation and Impact Classes 383 It is frequently the case that an organization will need to triage 384 their investigation and response activities based upon, e.g., the 385 state of the current threat environment, or simply as a result of 386 having limited resources. 388 In order to enable operators to effectively prioritize their response 389 activity, it is RECOMMENDED that feed implementers provide Atom 390 categories that correspond to the IODEF Expectation and Impact 391 classes. The availability of these feed categories will enable 392 clients to more easily retrieve and prioritize cyber security 393 information that has already been identified as having a specific 394 potential impact, or having a specific expectation. 396 Support for these categories may also enable efficiencies for 397 organizations that already have established (or plan to establish) 398 operational processes and workflows that are based on these IODEF 399 classes. 401 9. IANA Considerations 403 9.1. information-type registrations 405 IANA has added the following entries to the "ROLIE Security Resource 406 Information Type Sub-Registry" registry located at 407 . 409 9.1.1. incident information-type 411 The entry is as follows: 413 name: incident 415 index: TBD 417 reference: This document, Section 5.1 419 9.1.2. indicator information-type 421 The entry is as follows: 423 name: indicator 424 index: TBD 426 reference: This document, Section 5.2 428 9.2. atom:category scheme registrations 430 IANA has added the following entries to the "ROLIE URN Parameters" 431 registry located in . 433 9.2.1. category:csirt:iodef:purpose 435 The entry is as follows: 437 name: category:csirt:iodef:purpose 439 Extension IRI: urn:ietf:params:rolie:category:csirt:iodef:purpose 441 Reference: This document, Section 8.1.1 443 Subregistry: None 445 9.2.2. category:csirt:iodef:restriction 447 The entry is as follows: 449 name: category:csirt:iodef:restriction 451 Extension IRI: 452 urn:ietf:params:rolie:category:csirt:iodef:restriction 454 Reference: This document, Section 8.1.1 456 Subregistry: None 458 9.3. rolie:property name registrations 460 IANA has added the following entries to the "ROLIE URN Parameters" 461 registry located in . 463 9.3.1. property:csirt:id 465 The entry is as follows: 467 name: property:csirt:id 469 Extension IRI: urn:ietf:params:rolie:property:csirt:id 471 Reference: This document, section 6.3.1 472 Subregistry: None 474 10. Security Considerations 476 This document implies the use of ROLIE in high-security use cases, as 477 such, added care should be taken to fortify and secure ROLIE 478 repositories and clients using this extension. The guidance in the 479 ROLIE core specification is strongly recommended, and implementers 480 should consider adding additional security measures as they see fit. 482 When providing a private workspace for closed sharing, it is 483 recommended that the ROLIE repository checks user authorization when 484 the user sends a GET request to the service document. If the user is 485 not authorized to send any requests to a given workspace or 486 collection, that workspace or collection should be truncated from the 487 service document in the response. In this way the existence of 488 unauthorized content remains unknown to potential attackers, 489 hopefully reducing attack surface. 491 11. Normative References 493 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 494 Requirement Levels", BCP 14, RFC 2119, 495 DOI 10.17487/RFC2119, March 1997, 496 . 498 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 499 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 500 December 2005, . 502 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 503 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 504 . 506 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 507 Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, 508 October 2007, . 510 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 511 Object Description Exchange Format", RFC 5070, 512 DOI 10.17487/RFC5070, December 2007, 513 . 515 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 516 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 517 November 2016, . 519 [RFC8322] Field, J., Banghart, S., and D. Waltermire, "Resource- 520 Oriented Lightweight Information Exchange (ROLIE)", 521 RFC 8322, DOI 10.17487/RFC8322, February 2018, 522 . 524 Appendix A. Non-Normative Examples 526 The following provide examples of some potential use cases of the 527 CSIRT ROLIE extension, and provides a showcase for some of its 528 benefits over traditional solutions. 530 The general non-normative examples provided in the core ROLIE 531 document remain an excellent reference resource for typical ROLIE 532 usage. 534 A.1. Use of Link Relations 536 A key benefit of using the RESTful architectural style is the ability 537 to enable the client to navigate to related resources through the use 538 of hypermedia links. In the Atom Syndication Format, the type of the 539 related resource identified in a element is indicated via the 540 "rel" attribute, where the value of this attribute identifies the 541 kind of related resource available at the corresponding "href" 542 attribute. Thus, in lieu of a well-known URI template the URI itself 543 is effectively opaque to the client, and therefore the client must 544 understand the semantic meaning of the "rel" attribute in order to 545 successfully navigate. Broad interoperability may be based upon a 546 sharing consortium defining a well-known set of Atom Link Relation 547 types. These Link Relation types may either be registered with IANA, 548 or held in a private registry. 550 Individual CSIRTs may always define their own link relation types in 551 order to support specific use cases, however support for a core set 552 of well-known link relation types is encouraged as this will maximize 553 interoperability. 555 In addition, it may be beneficial to define use case profiles that 556 correspond to specific groupings of supported link relationship 557 types. In this way, a CSIRT may unambiguously specify the classes of 558 use cases for which a client can expect to find support. 560 The following sections provide non-normative examples of link 561 relation usage. Three distinct cyber security information sharing 562 use case scenarios are described. In each use case, the unique 563 benefits of adopting a resource-oriented approach to information 564 sharing are illustrated. It is important to note that these use 565 cases are intended to be a small representative set and is by no 566 means meant to be an exhaustive list. The intent is to illustrate 567 how the use of link relationship types will enable this resource- 568 oriented approach to cyber security information sharing to 569 successfully support the complete range of existing use cases, and 570 also to motivate an initial list of well-defined link relationship 571 types. 573 A.1.1. Use Case: Incident Sharing 575 This section provides a non-normative example of an incident sharing 576 use case. 578 In this use case, a member CSIRT shares incident information with 579 another member CSIRT in the same consortium. The client CSIRT 580 retrieves a feed of incidents, and is able to identify one particular 581 entry of interest. The client then does an HTTP GET on that entry, 582 and the representation of that resource contains link relationships 583 for both the associated "indicators" and the incident "history", and 584 so on. The client CSIRT recognizes that some of the indicator and 585 history may be relevant within her local environment, and can respond 586 proactively. 588 Example HTTP GET response for an incident entry: 590 591 593 http://www.example.org/csirt/private/incidents/123456 594 Sample Incident 595 597 599 2012-08-04T18:13:51.0Z 600 2012-08-05T18:13:51.0Z 602 605 607 609 611 614 616 617 618 619 621 623 624 123456 626 627 628 630 631 633 As can be seen in the example response, the Atom elements 634 enable the client to navigate to the related indicator resources, 635 and/or the history entries associated with this incident. 637 A.1.2. Use Case: Collaborative Investigation 639 This section provides a non-normative example of a collaborative 640 investigation use case. 642 In this use case, two member CSIRTs that belong to a closed sharing 643 consortium are collaborating on an incident investigation. The 644 initiating CSIRT performs an HTTP GET to retrieve the service 645 document of the peer CSIRT, and determines the collection name to be 646 used for creating a new investigation request. The initiating CSIRT 647 then POSTs a new incident entry to the appropriate collection URL. 648 The target CSIRT acknowledges the request by responding with an HTTP 649 status code 201 Created. 651 Example HTTP GET response for the service document: 653 HTTP/1.1 200 OK 654 Date: Fri, 24 Aug 2012 17:09:11 GMT 655 Content-Length: 934 656 Content-Type: application/atomsvc+xml;charset="utf-8" 658 659 661 663 RID Use Case Requests 664 666 Investigation Requests 667 application/atom+xml; type=entry 668 669 670 Trace Requests 671 application/atom+xml; type=entry 672 673 674 675 677 As can be seen in the example response, the Atom 678 elements enable the client to determine the appropriate collection 679 URL to request an investigation or a trace. 681 The client CSIRT then POSTs a new entry to the appropriate feed 682 collection. Note that the element of the new entry may 683 contain a RID message of type "InvestigationRequest" if desired, 684 however this would NOT be required. The entry content itself need 685 only be an IODEF document, with the choice of the target collection 686 resource URL indicating the callers intent. A CSIRT would be free to 687 use any URI template to accept investigationRequests. 689 POST /csirt/RID/InvestigationRequests HTTP/1.1 690 Host: www.example.org 691 Content-Type: application/atom+xml;type=entry 692 Content-Length: 852 694 695 697 New Investigation Request 698 http://www.example2.org/csirt/private/incidents/123456 699 700 701 2012-08-12T11:08:22Z 702 Name of peer CSIRT 703 704 705 707 708 123 710 711 712 713 714 716 The receiving CSIRT acknowledges the request with HTTP return code 717 201 Created. 719 HTTP/1.1 201 Created 720 Date: Fri, 24 Aug 2012 19:17:11 GMT 721 Content-Length: 906 722 Content-Type: application/atom+xml;type=entry 723 Location: http://www.example.org/csirt/RID/InvestigationRequests/823 724 ETag: "8a9h9he4qphqh" 726 727 729 New Investigation Request 730 http://www.example.org/csirt/RID/InvestigationRequests/823 731 732 733 2012-08-12T11:08:30Z 734 2012-08-12T11:08:30Z 735 Name of peer CSIRT 736 737 738 740 741 123 743 744 745 746 747 749 Consistent with HTTP/1.1 RFC, the location header indicates the URL 750 of the newly created InvestigationRequest. If for some reason the 751 request were not authorized, the client would receive an HTTP status 752 code 403 Unauthorized. In this case the HTTP response body may 753 contain additional details, if an as appropriate. 755 A.1.3. Use Case: Cyber Data Repository 757 This section provides a non-normative example of a cyber security 758 data repository use case. 760 In this use case a client accesses a persistent repository of cyber 761 security data via a RESTful usage model. Retrieving a feed 762 collection is analogous to an SQL SELECT statement producing a result 763 set. Retrieving an individual Atom Entry is analogous to a SQL 764 SELECT statement based upon a primary key producing a unique record. 765 The cyber security data contained in the repository may include 766 different data types, including indicators, incidents, benchmarks, or 767 any other related resources. In this use case, the repository is 768 queried via HTTP GET, and the results that are returned to the client 769 may optionally contain URL references to other cyber security 770 resources that are known to be related. These related resources may 771 also be persisted locally, or they may exist at another (remote) 772 cyber data respository. 774 Example HTTP GET request to a persistent repository for any resources 775 representing Distributed Denial of Service (DDOS) attacks: 777 GET /csirt/repository/ddos 778 Host: www.example.org 779 Accept: application/atom+xml 781 The corresponding HTTP response would be an XML document containing 782 the DDOS feed. 784 Example HTTP GET response for a DDOS feed: 786 HTTP/1.1 200 OK 787 Date: Fri, 24 Aug 2012 17:20:11 GMT 788 Content-Length: nnnn 789 Content-Type: application/atom+xml;type=feed;charset="utf-8" 791 792 801 802 emc-csirt-iodef-feed-service 803 http://www.example.org/csirt/repository/ddos 804 805 Atom formatted representation of a feed of known ddos resources. 806 807 2012-05-04T18:13:51.0Z 808 809 csirt@example.org 810 EMC CSIRT 811 813 814 817 818 http://www.example.org/csirt/repository/ddos/123456 819 Sample DDOS Incident 820 822 824 827 829 830 2012-08-04T18:13:51.0Z 831 2012-08-05T18:13:51.0Z 832 834 835 837 839 A short description of this DDOS attack, extracted 840 from the IODEF Incident class, element. 841 842 843 845 846 847 849 851 This feed document has two atom entries, one of which has been 852 elided. The completed entry illustrates an Atom element that 853 provides a summary of essential details about one particular DDOS 854 incident. Based upon this summary information and the provided 855 category information, a client may choose to do an HTTP GET operation 856 to retrieve the full details of the DDOS incident. This example 857 shows how a persistent repository may provide links to additional 858 resources, both local and remote. 860 Note that the provider of a persistent repostory is not obligated to 861 follow any particular URL template scheme. The repository available 862 at the hypothetical provider "www.example.com" uses a different URL 863 pattern than the hypothetical repository available at "www.cyber- 864 agency.gov". When a client de-references a link to resource that is 865 located in a remote repository the client may be challenged for 866 authentication credentials acceptable to that provider. If the two 867 repository providers choose to support a federated identity scheme or 868 some other form of single-sign-on technology, then the user 869 experience can be improved for interactive clients (e.g., a human 870 user at a browser). However, this is not required and is an 871 implementation choice that is out of scope for this specification. 873 Authors' Addresses 875 Stephen A. Banghart 876 National Institute of Standards and Technology 877 100 Bureau Drive 878 Gaithersburg, Maryland 879 USA 881 Phone: (301)975-4288 882 Email: sab3@nist.gov 884 John P. Field 885 Pivotal Software, Inc. 886 625 Avenue of the Americas 887 New York, New York 888 USA 890 Phone: (646)792-5770 891 Email: jfield@pivotal.io