idnits 2.17.1
draft-field-mile-rolie-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 :
----------------------------------------------------------------------------
** There are 109 instances of too long lines in the document, the longest
one being 94 characters in excess of 72.
** The abstract seems to contain references ([RFC6545], [RFC6546],
[RFC5070]), which it shouldn't. Please replace those with straight
textual mentions of the documents in question.
-- The document has examples using IPv4 documentation addresses according
to RFC6890, but does not use any IPv6 documentation addresses. Maybe
there should be IPv6 examples, too?
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 528 has weird spacing: '...lection href=...'
== Line 936 has weird spacing: '...lection href=...'
== Line 940 has weird spacing: '...lection href=...'
== 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 (August 15, 2013) is 3905 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Looks like a reference, but probably isn't: '1' on line 1642
== Unused Reference: 'XMLencrypt' is defined on line 1798, but no explicit
reference was found in the text
== Unused Reference: 'XMLsig' is defined on line 1803, but no explicit
reference was found in the text
== Unused Reference: 'SWID' is defined on line 1816, but no explicit
reference was found in the text
== Unused Reference: 'RFC2396' is defined on line 1822, but no explicit
reference was found in the text
== Unused Reference: 'RFC2822' is defined on line 1826, but no explicit
reference was found in the text
== Unused Reference: 'RFC3339' is defined on line 1829, but no explicit
reference was found in the text
== Unused Reference: 'RFC3552' is defined on line 1832, but no explicit
reference was found in the text
== Unused Reference: 'RFC5226' is defined on line 1836, but no explicit
reference was found in the text
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970)
-- Obsolete informational reference (is this intentional?): RFC 2396
(Obsoleted by RFC 3986)
-- Obsolete informational reference (is this intentional?): RFC 2822
(Obsoleted by RFC 5322)
-- Obsolete informational reference (is this intentional?): RFC 5226
(Obsoleted by RFC 8126)
Summary: 4 errors (**), 0 flaws (~~), 13 warnings (==), 6 comments (--).
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 August 15, 2013
5 Expires: February 16, 2014
7 Resource-Oriented Lightweight Indicator Exchange
8 draft-field-mile-rolie-02.txt
10 Abstract
12 This document defines a resource-oriented approach to cyber security
13 information sharing. Using this approach, a CSIRT or other
14 stakeholder may share and exchange representations of cyber security
15 incidents, indicators, and other related information as Web-
16 addressable resources. The transport protocol binding is specified
17 as HTTP(S) with a MIME media type of Atom+XML. An appropriate set of
18 link relation types specific to cyber security information sharing is
19 defined. The resource representations leverage the existing IODEF
20 [RFC5070] and RID [RFC6545] specifications as appropriate.
21 Coexistence with deployments that conform to existing specifications
22 including RID [RFC6545] and Transport of Real-time Inter-network
23 Defense (RID) Messages over HTTP/TLS [RFC6546] is supported via
24 appropriate use of HTTP status codes.
26 Status of This Memo
28 This Internet-Draft is submitted in full conformance with the
29 provisions of BCP 78 and BCP 79.
31 Internet-Drafts are working documents of the Internet Engineering
32 Task Force (IETF). Note that other groups may also distribute
33 working documents as Internet-Drafts. The list of current Internet-
34 Drafts is at http://datatracker.ietf.org/drafts/current/.
36 Internet-Drafts are draft documents valid for a maximum of six months
37 and may be updated, replaced, or obsoleted by other documents at any
38 time. It is inappropriate to use Internet-Drafts as reference
39 material or to cite them other than as "work in progress."
41 This Internet-Draft will expire on February 16, 2014.
43 Copyright Notice
45 Copyright (c) 2013 IETF Trust and the persons identified as the
46 document authors. All rights reserved.
48 This document is subject to BCP 78 and the IETF Trust's Legal
49 Provisions Relating to IETF Documents
50 (http://trustee.ietf.org/license-info) in effect on the date of
51 publication of this document. Please review these documents
52 carefully, as they describe your rights and restrictions with respect
53 to this document. Code Components extracted from this document must
54 include Simplified BSD License text as described in Section 4.e of
55 the Trust Legal Provisions and are provided without warranty as
56 described in the Simplified BSD License.
58 Table of Contents
60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
62 3. Background and Motivation . . . . . . . . . . . . . . . . . . 4
63 3.1. Message-oriented versus Resource-oriented Architecture . 5
64 3.1.1. Message-oriented Architecture . . . . . . . . . . . . 5
65 3.1.2. Resource-Oriented Architecture . . . . . . . . . . . 5
66 3.2. Authentication of Users . . . . . . . . . . . . . . . . . 7
67 3.3. Authorization Policy Enforcement . . . . . . . . . . . . 7
68 3.3.1. Enforcement at Destination System . . . . . . . . . . 7
69 3.3.2. Enforcement at Source System . . . . . . . . . . . . 8
70 4. RESTful Usage Model . . . . . . . . . . . . . . . . . . . . . 9
71 4.1. Dynamic Service Discovery versus Static URL Template . . 10
72 4.2. Non-Normative Examples . . . . . . . . . . . . . . . . . 11
73 4.2.1. Service Discovery . . . . . . . . . . . . . . . . . . 11
74 4.2.2. Feed Retrieval . . . . . . . . . . . . . . . . . . . 14
75 4.2.3. Entry Retrieval . . . . . . . . . . . . . . . . . . . 16
76 4.2.4. Use of Link Relations . . . . . . . . . . . . . . . . 19
77 5. Requirements for RESTful (Atom+xml) Binding . . . . . . . . 29
78 5.1. Transport Layer Security . . . . . . . . . . . . . . . . 29
79 5.2. User Authentication . . . . . . . . . . . . . . . . . . . 29
80 5.3. User Authorization . . . . . . . . . . . . . . . . . . . 30
81 5.4. Content Model . . . . . . . . . . . . . . . . . . . . . . 30
82 5.5. HTTP methods . . . . . . . . . . . . . . . . . . . . . . 31
83 5.6. Service Discovery . . . . . . . . . . . . . . . . . . . . 31
84 5.6.1. Workspaces . . . . . . . . . . . . . . . . . . . . . 32
85 5.6.2. Collections . . . . . . . . . . . . . . . . . . . . . 32
86 5.6.3. Service Document Security . . . . . . . . . . . . . . 32
87 5.7. Category Mapping . . . . . . . . . . . . . . . . . . . . 32
88 5.7.1. Collection Category . . . . . . . . . . . . . . . . . 32
89 5.7.2. Entry Category . . . . . . . . . . . . . . . . . . . 33
90 5.8. Entry ID . . . . . . . . . . . . . . . . . . . . . . . . 33
91 5.9. Entry Content . . . . . . . . . . . . . . . . . . . . . . 33
92 5.10. Link Relations . . . . . . . . . . . . . . . . . . . . . 33
93 5.10.1. Additional Link Relation Requirements . . . . . . . 35
94 5.11. Member Entry Forward Security . . . . . . . . . . . . . . 36
95 5.12. Date Mapping . . . . . . . . . . . . . . . . . . . . . . 36
96 5.13. Search . . . . . . . . . . . . . . . . . . . . . . . . . 37
97 5.14. / (forward slash) Resource URL . . . . . . . . . . . . . 37
98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38
99 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40
100 8. ToDo and Open Issues . . . . . . . . . . . . . . . . . . . . 40
101 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41
102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 41
103 10.1. Normative References . . . . . . . . . . . . . . . . . . 41
104 10.2. Informative References . . . . . . . . . . . . . . . . . 42
105 Appendix A. Change Tracking . . . . . . . . . . . . . . . . . . 43
106 Appendix B. Resource Authorization Model . . . . . . . . . . . . 43
107 B.1. Example XACML Profile . . . . . . . . . . . . . . . . . . 44
108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44
110 1. Introduction
112 This document defines a resource-oriented approach to cyber security
113 information sharing that follows the REST (Architectural Styles and
114 the Design of Network-based Software Architectures) architectural
115 style. The resource representations leverage the existing IODEF
116 [RFC5070] and RID [RFC6545] specifications as appropriate. The
117 transport protocol binding is specified as HTTP(S) with a media type
118 of Atom+XML. An appropriate set of link relation types specific to
119 cyber security information sharing is defined. Using this approach,
120 a CSIRT or other stakeholder may exchange cyber security incident and
121 /or indicator information as Web-addressable resources.
123 The goal of this specification is to define a loosely-coupled, agile
124 approach to cyber security situational awareness. This approach has
125 architectural advantages for some use case scenarios, such as when a
126 CSIRT or other stakeholder is required to share cyber security
127 information broadly (e.g., at internet scale), or when an information
128 sharing consortium requires support for asymmetric interactions
129 amongst their stakeholders.
131 Coexistence with deployments that conform to existing specifications
132 including RID [RFC6545] and Transport of Real-time Inter-network
133 Defense (RID) Messages over HTTP/TLS [RFC6546] is supported via
134 appropriate use of HTTP status codes.
136 2. Terminology
138 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT,"
139 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this
140 document are to be interpreted as described in [RFC2119].
141 Definitions for some of the common computer security-related
142 terminology used in this document can be found in Section 2 of
143 [RFC5070].
145 3. Background and Motivation
147 It is well known that Internet security threats are evolving ever
148 more rapidly, and are becoming ever more sophisticated than before.
149 The threat actors are frequently distributed and are not constrained
150 to operating within a fixed, closed consortium. The technical skills
151 needed to perform effective analysis of a security incident, or to
152 even recognize an indicator of compromise are already specialized and
153 relatively scarce. As threats continue to evolve, even an
154 established network of CSIRT may find that it does not always have
155 all of the skills and knowledge required to immediately identify and
156 respond to every new incident. Effective identification of and
157 response to a sophisticated, multi-stage attack frequently depends
158 upon cooperation and collaboration, not only amongst the defending
159 CSIRTs, but also amongst other stakeholders, including, potentially,
160 individual end users.
162 Existing approaches to cyber security information sharing are based
163 upon message exchange patterns that are point-to-point, and event-
164 driven. Sometimes, information that may be useful to, and sharable
165 with multiple peers is only made available to peers after they have
166 specifically requested it. Unfortunately, a sharing peer may not
167 know, a priori, what information to request from another peer.
168 Sending unsolicited RID reports does provide a mechanism for
169 alerting, however these reports are again sent point-to-point, and
170 must be reviewed for relevance and then prioritized for action by the
171 recipient. Thus, distribution of some relevant incident and
172 indicator information may exhibit significant latency.
174 In order to appropriately combat the evolving threats, the defending
175 CSIRTs should be enabled to operate in a more agile manner, sharing
176 selected cyber security information proactively, if and as
177 appropriate.
179 For example, a CSIRT analyst would benefit by having the ability to
180 search a comprehensive collection of indicators that has been
181 published by a government agency, or by another member of a sharing
182 consortium. The representation of each indicator may include links
183 to the related resources, enabling an appropriately authenticated and
184 authorized analyst to freely navigate the information space of
185 indicators, incidents, and other cyber security domain concepts, as
186 needed. In general, a more Web-centric sharing approach will enable
187 a more dynamic and agile collaboration amongst a broader, and varying
188 constituency.
190 The following sections discuss additional specific technical issues
191 that motivate the development of an alternative approach.
193 3.1. Message-oriented versus Resource-oriented Architecture
195 The existing approaches to cyber security information sharing are
196 based upon message-oriented interactions. The following paragraphs
197 explore some of the architectural constraints associated with
198 message-oriented interactions and consider the relative merits of an
199 alternative model based on a Resource-oriented architecture for use
200 in some use case scenarios.
202 3.1.1. Message-oriented Architecture
204 In general, message-based integration architectures may be based upon
205 either an RPC-style or a document-style binding. The message types
206 defined by RID represent an example of an RPC-style request. This
207 approach imposes implied requirements for conversational state
208 management on both of the communicating RID endpoint(s). Experience
209 has shown that this state management frequently becomes the limiting
210 factor with respect to the runtime scalability of an RPC-style
211 architecture.
213 In addition, the practical scalability of a peer-to-peer message-
214 based approach will be limited by the administrative procedures
215 required to manage O(N^2) trust relationships and at least O(N)
216 policy groups.
218 As long as the number of CSIRTs participating in an information
219 sharing consortium is limited to a relatively smaller number of nodes
220 (i.e., O(2^N), where N < 5), these scalability constraints may not
221 represent a critical concern. However, when there is a requirement
222 to support a significantly larger number of participating peers, a
223 different architectural approach will be required. One alternative
224 to the message-based approach that has demonstrated scalability is
225 the REST [REST] architectural style.
227 3.1.2. Resource-Oriented Architecture
229 Applying the REST architectural style to the problem domain of cyber
230 security information sharing would take the approach of exposing
231 incidents, indicators, and any other relevant types as simple Web-
232 addressable resources. By using this approach, a CSIRT or other
233 organization can more quickly and easily share relevant incident and
234 indicator information with a much larger and potentially more diverse
235 constituency. A client may leverage virtually any available HTTP
236 user agent in order to make requests of the service provider. This
237 improved ease of use could enable more rapid adoption and broader
238 participation, thereby improving security for everyone.
240 A key interoperability aspect of any RESTful Web service will be the
241 choices regarding the available resource representations. For
242 example, clients may request that a given resource representation be
243 returned as either XML or JSON. In order to enable back-
244 compatibility and interoperability with existing CSIRT
245 implementations, IODEF [RFC5070] is specified for this transport
246 binding as a mandatory to implement (MTI) data representation for
247 incident and indicator resources. In addition to the REQUIRED
248 representation, an implementation MAY support additional
249 representations if and as needed such as IODEF extensions, the RID
250 schema, or other schemas. For example, an implementation may choose
251 to provide support for returning a JSON representation of an incident
252 resource.
254 Finally, an important principle of the REST architectural style is
255 the use of hypertext links as the embodiment of application state
256 (HATEOAS). Rather than the server maintaining conversational state
257 for each client context, the server will instead include a suitable
258 set of hyperlinks in the resource representation that is returned to
259 the client. In this way, the server remains stateless with respect
260 to a series of client requests. The included hyperlinks provide the
261 client with a specific set of permitted state transitions. Using
262 these links the client may perform an operation, such as updating or
263 deleting the resource representation. The client may also be
264 provided with hypertext links that can be used to navigate to any
265 related resource. For example, the resource representation for an
266 incident object may contain links to the related indicator
267 resource(s).
269 This document specifies the use of Atom Syndication Format [RFC4287]
270 and Atom Publishing Protocol [RFC5023] as the mechanism for
271 representing the required hypertext links.
273 3.1.2.1. A Resource-Oriented Use Case: "Mashup"
275 In this section we consider a non-normative example use case scenario
276 for creating a cyber security "mashup".
278 Any CSIRT can enable any authenticated and authorized client that is
279 a member of the sharing community to quickly and easily navigate
280 through any of the cyber security information that that provider is
281 willing to share. An authenticated and authorized analyst may then
282 make HTTP(S) requests to collect incident and indicator information
283 known at one CSIRT with threat actor data being made available from
284 another CSIRT. The resulting correlations may yield new insights
285 that enable a more timely and effective defensive response. Of
286 course, this report may, in turn, be made available to others as a
287 new Web-addressable resource, reachable via another URL. By
288 employing the RESTful Web service approach the effectiveness of the
289 collaboration amongst a consortium of CSIRTs and their stakeholders
290 can be greatly improved.
292 3.2. Authentication of Users
294 In the store-and-forward, message-based model for information sharing
295 client authentication is provided via a Public Key Infrastructure
296 (PKI) -based trust and mutually authenticated TLS between the
297 messaging system endpoints. There is no provision to support
298 authentication of a client by another means. As a result,
299 participation in the sharing community is limited to those
300 organizations that have sufficient resources and capabilities to
301 manage a PKI.
303 A CSIRT may apply XML Security to the content of a message, however
304 the contact information provided within the message body represents a
305 self-asserted identity, and there is no guarantee that the contact
306 information will be recognized by the peer. As a result, the audit
307 trail and the granularity of any authorization policies is limited to
308 the identity of the peer CSIRT organization.
310 A CSIRT implementing this specification MUST implement server-
311 authenticated TLS. The CSIRT may choose to authenticate its client
312 users via any suitable authentication scheme that can be implemented
313 via HTTP(S). A participating CSIRT MAY choose to support more than
314 one authentication method. Support for use of a Federated Identity
315 approach is RECOMMENDED. Establishing a specific end user identity
316 prior to processing a request is RECOMMENDED. Doing so will enable
317 the source system to maintain a more complete audit trail of exactly
318 what cyber security incident and indicator information has been
319 shared, when, and with whom.
321 3.3. Authorization Policy Enforcement
323 A key aspect of any cyber security information sharing arrangement is
324 assigning the responsibility for authorization policy enforcement.
325 The authorization policy must be enforced either at the destination
326 system, or the source system, or both. The following sections
327 discuss these alternatives in greater detail.
329 3.3.1. Enforcement at Destination System
331 The store-and-forward, message-based approach to cyber security
332 information sharing requires that the origin system delegate
333 authorization policy enforcement to the destination system. The
334 origin system may leverage XML Encryption and DigitalSignature to
335 protect the message content. In addition, the origin system assigns
336 a number of policy-related attribute values, including a
337 "restriction" attribute, before the message is sent. These labels
338 indicate the sender's expectation for confidentiality enforcement and
339 appropriate handling at the destination. Section 9.1 of RFC6545
340 provides specific guidance to implementers on use of the XML security
341 standards in order to achieve the required levels of security for the
342 exchange of incident information.
344 Once the message has been received at the destination system, the XML
345 encryption and digital signature protections on the message will be
346 processed, and based upon the pre-established PKI-based trust
347 relationships, the message content is validated and decrypted.
348 Typical implementations will then pass the cleartext data to an
349 internal Incident Handling System (IHS) for further review and/or
350 action by a human operator or analyst. Regardless of where in the
351 deployment architecture the XML message-level security is being
352 handled, eventually the message content will be made available as
353 cleartext for handling by human systems analysts and other
354 operational staff.
356 The authorization policy enforcement of the message contents must
357 then be provided by the destination IHS. It is the responsibility of
358 the destination system to honor the intent of the policy restriction
359 labels assigned by the origin system. Ideally, these policy labels
360 would serve as part of a distributed Mandatory Access Control scheme.
361 However, in practice a typical IHS will employ a Discretionary Access
362 Control (DAC) model rather than a MAC model and so the policy related
363 attributes are defined to represent handling "hints" and provide no
364 guarantee of enforcement at the destination.
366 As a result, ensuring that the destination system or counterparty
367 will in fact correctly enforce the intended authorization policies
368 becomes a key issue when entering into any information sharing
369 agreements. The origin CSIRT must accept a non-zero risk of
370 information leakage, and therefore must rely upon legal recourse as a
371 compensating control. Establishing such legal sharing agreements can
372 be a slow and difficult process, as it assumes a high level of trust
373 in the peer, with respect to both intent and also technical
374 capabilities.
376 3.3.2. Enforcement at Source System
378 In this model, the required authorization policy enforcements are
379 implemented entirely within the source system. Enforcing the
380 required authorization policy controls at the source system
381 eliminates the risk of subsequent information leakage at the
382 destination system due to inadequate or incomplete implementation of
383 the expected controls. The destination system is not expected to
384 perform any additional authorization enforcements. Authorization
385 enforcement at the source system may be based on, e.g. Role-based
386 Access Controls applied in the context of an established user
387 identity. The source system may use any appropriate authentication
388 mechanism in order to determine the user identity of the requestor,
389 including, e.g. federated identity. An analyst or operator at a
390 CSIRT may request specific information on a given incident or
391 indicator from a peer CSIRT, and the source system will return a
392 suitable representation of that resource based upon the specific role
393 of the requestor. A different authenticated user (perhaps from the
394 same destination CSIRT) may receive a different representation of the
395 same resource, based upon the source system applying suitable Role-
396 based Access Control policy enforcements for the second user
397 identity.
399 Consistent with HTTP [RFC2616] a user's request MAY be denied with a
400 resulting HTTP status code value of 4xx such as 401 Unauthorized, 403
401 Forbidden, or 404 Not Found, or 405 Method Not Allowed, if and as
402 appropriate.
404 4. RESTful Usage Model
406 This section describes the basic use of Atom Syndication Format
407 [RFC4287] and Atom Publishing Protocol [RFC5023] as a RESTful
408 transport binding and dynamic discovery protocol, respectively, for
409 cyber security information sharing.
411 As described in Atom Publishing Protocol [RFC5023], an Atom Service
412 Document is an XML-based document format that allows a client to
413 dynamically discover the collections provided by a publisher.
415 As described in Atom Syndication Format [RFC4287], Atom is an XML-
416 based document format that describes lists of related information
417 items known as collections, or "feeds". Each feed document contains
418 a collection of zero or more related information items called "member
419 entries" or "entries".
421 When applied to the problem domain of cyber security information
422 sharing, an Atom feed may be used to represent any meaningful
423 collection of information resources such as a set of incidents, or
424 indicators. Each entry in a feed could then represent an individual
425 incident, or indicator, or some other resource, as appropriate.
426 Additional feeds could be used to represent other meaningful and
427 useful collections of cyber security resources. A feed may be
428 categorized, and any feed may contain information from zero or more
429 categories. The naming scheme and the semantic meaning of the terms
430 used to identify an Atom category are application-defined.
432 4.1. Dynamic Service Discovery versus Static URL Template
434 In order to specify a protocol for cyber security information sharing
435 using the REST architectural style it is necessary to define the set
436 of resources to be modeled, and how these resources are related.
437 Based on this interface contract, clients will then interact with the
438 REST service by navigating the modeled entities, and their
439 relationships. The interface contract between the client and the
440 server may either be statically bound or dynamically bound.
442 In the statically bound case, the clients have a priori knowledge of
443 the resources that are supported. In the REST architectural style
444 this static interface contract takes the form of a URL template.
445 This approach is not appropriate for the cyber security information
446 sharing domain for at least two reasons.
448 First, there is no standard for a cyber security domain model. While
449 information security practitioners can generally agree on some of the
450 basic concepts that are important to modeling the cyber security
451 domain -- such as "indicator," "incident," or "attacker," -- there is
452 no single domain model that can been referenced as the basis for
453 specifying a standardized RESTful URI Template. Second, the use of
454 static URL templates creates a tighter coupling between the client
455 implementation and the server implementation. Security threats on
456 the internet are evolving ever more rapidly, and it will never be
457 possible to establish a statically defined resource model and URL
458 Template. Even if there were an initial agreement on an appropriate
459 URL template, it would eventually need to change. If and when a
460 CSIRT finds that it needs to change the URL template, then any
461 existing deployed clients would need to be upgraded.
463 Thus, rather than attempting to define a fixed set of resources via a
464 URI Template, this document has instead specified an approach based
465 on dynamic discovery of resources via an Atom Publishing Protocol
466 Service Document. By using this approach, it is possible to
467 standardize the RESTful usage model, without needing to standardize
468 on the definitions of specific, strongly-typed resources. A client
469 can dynamically discover what resources are provided by a given
470 CSIRT, and then navigate that domain model accordingly A specific
471 server implementation may still embody a particular URL template,
472 however the client does not need a priori knowledge of the format of
473 the links, and the URL itself is effectively opaque to the client.
474 Clients are not bound to any particular server's interface.
476 The following paragraphs provide a number of non-normative examples
477 to illustrate the use of Atom Publishing Protocol for basic cyber
478 security information sharing service discovery, as well as the use of
479 Atom Syndication Format as a mechanism to publish cyber security
480 information feeds.
482 Normative requirements are defined below, in Section 5.
484 4.2. Non-Normative Examples
486 4.2.1. Service Discovery
488 This section provides a non-normative example of a client doing
489 service discovery.
491 An Atom service document enables a client to dynamically discover
492 what feeds a particular publisher makes available. Thus, a CSIRT may
493 use an Atom service document to enable clients of the CSIRT to
494 determine what specific cyber security information the CSIRT makes
495 available to the community. The service document could be made
496 available at any well known location, such as via a link from the
497 CSIRT's home page. One common technique is to include a link in the
498
section of the organization's home page, as shown below:
500 Example of bootstrapping Service Document discovery:
502
504 A client may then format an HTTP GET request to retrieve the service
505 document:
507 GET /csirt/svcdoc.xml
508 Host: www.example.org
509 Accept: application/atomsvc+xml
511 Notice the use of the HTTP Accept: request header, indicating the
512 MIME type for Atom service discovery. The response to this GET
513 request will be an XML document that contains information on the
514 specific feed collections that are provided by the CSIRT.
516 Example HTTP GET response:
518 HTTP/1.1 200 OK
519 Date: Fri, 24 Aug 2012 17:09:11 GMT
520 Content-Length: 570
521 Content-Type: application/atomsvc+xml;charset="utf-8"
523
524
526
527 Incidents
528
529 Incidents Feed
530 application/atom+xml; type=entry
531
532
533
535 This simple Service Document example shows that this CSIRT provides
536 one workspace, named "Incidents." Within that workspace, the CSIRT
537 makes one feed collection available. When attempting to GET or POST
538 entries to that feed collection, the client must indicate a content
539 type of application/atom+xml.
541 A CSIRT may also offer a number of different feeds, each containing
542 different types of cyber security information. In the following
543 example, the feeds have been categorized. This categorization will
544 help the clients to decide which feeds will meet their needs.
546 HTTP/1.1 200 OK
547 Date: Fri, 24 Aug 2012 17:10:11 GMT
548 Content-Length: 1912
549 Content-Type: application/atomsvc+xml;charset="utf-8"
551
552
554
555 Cyber Security Information Sharing
556
557 Public Indicators
558
559
560
561
562 application/atom+xml; type=entry
563
564
565 Public Incidents
566
567
568
569
570 application/atom+xml; type=entry
571
572
573
574 Private Consortium Sharing
575
576 Incidents
577 application/atom+xml;type=entry
578
579
580
581
582
583
584
586 In this example, the CSIRT is providing a total of three feed
587 collections, organized into two different workspaces. The first
588 workspace contains two feeds, consisting of publicly available
589 indicators and publicly available incidents, respectively. The
590 second workspace provides one additional feed, for use by a sharing
591 consortium. The feed contains incident information containing
592 entries related to three purposes: traceback, mitigation, and
593 reporting. The entries in this feed are categorized with a
594 restriction of either "Need-to-Know" or "private". An appropriately
595 authenticated and authorized client may then proceed to make GET
596 requests for one or more of these feeds. The publicly provided
597 incident information may be accessible with or without
598 authentication. However, users accessing the feed targeted to the
599 private sharing consortium would be expected to authenticate, and
600 appropriate authorization policies would subsequently be enforced by
601 the feed provider.
603 4.2.2. Feed Retrieval
605 This section provides a non-normative example of a client retrieving
606 an incident feed.
608 Having discovered the available cyber security information sharing
609 feeds, an authenticated and authorized client who is a member of the
610 private sharing consortium may be interested in receiving the feed of
611 known incidents. The client may retrieve this feed by performing an
612 HTTP GET operation on the indicated URL.
614 Example HTTP GET request for a Feed:
616 GET /csirt/private/incidents
617 Host: www.example.org
618 Accept: application/atom+xml
620 The corresponding HTTP response would be an XML document containing
621 the incidents feed:
623 Example HTTP GET response for a Feed:
625 HTTP/1.1 200 OK
626 Date: Fri, 24 Aug 2012 17:20:11 GMT
627 Content-Length: 2882
628 Content-Type: application/atom+xml;type=feed;charset="utf-8"
630
631
637 emc-csirt-iodef-feed-service
638 http://www.example.org/csirt/private/incidents
639 Atom formatted representation of a feed of IODEF documents
640 2012-05-04T18:13:51.0Z
641
642 csirt@example.org
643 EMC CSIRT
644
646
647
649
650 http://www.example.org/csirt/private/incidents/123456
651 Sample Incident
652
653
654 2012-08-04T18:13:51.0Z
655 2012-08-05T18:13:51.0Z
656
657
658
659 A short description of this incident, extracted from the IODEF Incident class, element.
660
662
663
664
666
668 This feed document has two atom entries, one of which has been
669 elided. The completed entry illustrates an Atom element that
670 provides a summary of essential details about one particular
671 incident. Based upon this summary information and the provided
672 category information, a client may choose to do an HTTP GET operation
673 to retrieve the full details of the incident. This example provides
674 a RESTful alterntive to the RID investigation request messaage, as
675 described in sections 6.1 and 7.2 of RFC6545.
677 4.2.3. Entry Retrieval
679 This section provides a non-normative example of a client retrieving
680 an incident as an Atom entry.
682 Having retrieved the feed of interest, the client may then decide
683 based on the description and/or category information that one of the
684 entries in the feed is of further interest. The client may retrieve
685 this incident Entry by performing an HTTP GET operation on the
686 indicated URL.
688 Example HTTP GET request for an Entry:
690 GET /csirt/private/incidents/123456
691 Host: www.example.org
692 Accept: application/atom+xml
694 The corresponding HTTP response would be an XML document containing
695 the incident:
697 Example HTTP GET response for an Entry:
699 HTTP/1.1 200 OK
700 Date: Fri, 24 Aug 2012 17:30:11 GMT
701 Content-Length: 4965
702 Content-Type: application/atom+xml;type=entry;charset="utf-8"
704
705
706 http://www.example.org/csirt/private/incidents/123456
707 Sample Incident
708
709
710 2012-08-04T18:13:51.0Z
711 2012-08-05T18:13:51.0Z
712
713
714
715 A short description of this incident, extracted from the IODEF Incident class, element.
717
718
719
721
722
723
725
726
728
729
730
732
733 123456
735 2004-02-02T22:49:24+00:00
736 2004-02-02T22:19:24+00:00
737 2004-02-02T23:20:24+00:00
738
739 Host involved in DoS attack
740
741
742
743
744
745 Constituency-contact for 192.0.2.35
746
747 Constituency-contact@192.0.2.35
748
749
750
751
752
753 192.0.2.35
754
755
756
757 38765
758
759
760
761
762 192.0.2.67
763
764
765
766 80
767
768
769
770
771
772 Rate-limit traffic close to source
773
774
775
776
777
778 The IPv4 packet included was used in the described attack
779
780 450000522ad9
781 0000ff06c41fc0a801020a010102976d0050103e020810d9
782 4a1350021000ad6700005468616e6b20796f7520666f7220
783 6361726566756c6c792072656164696e6720746869732052
784 46432e0a
785
786
787
788
789
790
791
792
794 As can be seen in the example response, above, an IODEF document is
795 contained within the Atom element. The client may now
796 process the IODEF document as needed.
798 Note also that, as described previously, the content of the Atom
799 element is application-defined. In the present context,
800 the Atom categories have been assigned based on a mapping of the
801 and attributes, as defined in the IODEF
802 schema. In addition, the IODEF element has been
803 judiciously chosen so that the associated name attribute, as well as
804 the corresponding incidentID value, can be concatenated in order to
805 easily create the corresponding element for the Atom entry.
806 These and other mappings are normatively defined in Section 5, below.
808 Finally, it should be noted that in order to optimize the client
809 experience, and avoid an additional round trip, a feed provider may
810 choose to include the entry content inline, as part of the feed
811 document. That is, an Atom element within a Feed document
812 may contain an Atom element as a child. In this case, the
813 client will receive the full content of the entries within the feed.
814 The decision of whether to include the entry content inline or to
815 include it as a link is a design choice left to the feed provider
816 (e.g. based upon local environmental factors such as the number of
817 entries contained in a feed, the available network bandwidth, the
818 available server compute cycles, the expected client usage patterns,
819 etc.).
821 4.2.4. Use of Link Relations
823 As noted previously, a key benefit of using the RESTful architectural
824 style is the ability to enable the client to navigate to related
825 resources through the use of hypermedia links. In the Atom
826 Syndication Format, the type of the related resource identified in a
827 element is indicated via the "rel" attribute, where the value
828 of this attribute identifies the kind of related resource available
829 at the corresponding "href" attribute. Thus, in lieu of a well-known
830 URI template the URI itself is effectively opaque to the client, and
831 therefore the client must understand the semantic meaning of the
832 "rel" attribute in order to successfully navigate. Broad
833 interoperability may be based upon a sharing consortium defining a
834 well-known set of Atom Link Relation types. These Link Relation
835 types may either be registered with IANA, or held in a private
836 registry.
838 Individual CSIRTs may always define their own link relation types in
839 order to support specific use cases, however support for a core set
840 of well-known link relation types is encouraged as this will maximize
841 interoperability.
843 In addition, it may be beneficial to define use case profiles that
844 correspond to specific groupings of supported link relationship
845 types. In this way, a CSIRT may unambiguously specify the classes of
846 use cases for which a client can expect to find support.
848 The following sections provide NON-NORMATIVE examples of link
849 relation usage. Four distinct cyber security information sharing use
850 case scenarios are described. In each use case, the unique benefits
851 of adopting a resource-oriented approach to information sharing are
852 illustrated. It is important to note that these use cases are
853 intended to be a small representative set and is by no means meant to
854 be an exhaustive list. The intent is to illustrate how the use of
855 link relationship types will enable this resource-oriented approach
856 to cyber security information sharing to successfully support the
857 complete range of existing use cases, and also to motivate an initial
858 list of well-defined link relationship types.
860 4.2.4.1. Use Case: Incident Sharing
862 This section provides a non-normative example of an incident sharing
863 use case.
865 In this use case, a member CSIRT shares incident information with
866 another member CSIRT in the same consortium. The client CSIRT
867 retreives a feed of incidents, and is able to identify one particular
868 entry of interest. The client then does an HTTP GET on that entry,
869 and the representation of that resource contains link relationships
870 for both the associated "indicators" and the incident "history", and
871 so on. The client CSIRT recognizes that some of the indicator and
872 history may be relevant within her local environment, and can respond
873 proactively.
875 Example HTTP GET response for an incident entry:
877
878
879 http://www.example.org/csirt/private/incidents/123456
880 Sample Incident
881
882
883 2012-08-04T18:13:51.0Z
884 2012-08-05T18:13:51.0Z
886
888
889
890
891
893
894
896
897
898
899 123456
900
901
902
903
904
906 As can be seen in the example response, the Atom elements
907 enable the client to navigate to the related indicator resources, and
908 /or the history entries associated with this incident.
910 4.2.4.2. Use Case: Collaborative Investigation
912 This section provides a non-normative example of a collaborative
913 investigation use case.
915 In this use case, two member CSIRTs that belong to a closed sharing
916 consortium are collaborating on an incident investigation. The
917 initiating CSIRT performs an HTTP GET to retrieve the service
918 document of the peer CSIRT, and determines the collection name to be
919 used for creating a new investigation request. The initiating CSIRT
920 then POSTs a new incident entry to the appropriate collection URL.
921 The target CSIRT acknowledges the request by responding with an HTTP
922 status code 201 Created.
924 Example HTTP GET response for the service document:
926 HTTP/1.1 200 OK
927 Date: Fri, 24 Aug 2012 17:09:11 GMT
928 Content-Length: 934
929 Content-Type: application/atomsvc+xml;charset="utf-8"
931
932
934
935 RID Use Case Requests
936
937 Investigation Requests
938 application/atom+xml; type=entry
939
940
941 Trace Requests
942 application/atom+xml; type=entry
943
944
945
946
948 As can be seen in the example response, the Atom
949 elements enable the client to determine the appropriate collection
950 URL to request an investigation or a trace.
952 The client CSIRT then POSTs a new entry to the appropriate feed
953 collection. Note that the element of the new entry may
954 contain a RID message of type "InvestigationRequest" if desired,
955 however this would NOT be required. The entry content itself need
956 only be an IODEF document, with the choice of the target collection
957 resource URL indicating the callers intent. A CSIRT would be free to
958 use any URI template to accept investigationRequests.
960 POST /csirt/RID/InvestigationRequests HTTP/1.1
961 Host: www.example.org
962 Content-Type: application/atom+xml;type=entry
963 Content-Length: 852
965
966
967 New Investigation Request
968 http://www.example2.org/csirt/private/incidents/123456
969 2012-08-12T11:08:22Z
970 Name of peer CSIRT
971
972
973
974 123
975
976
977
978
979
981 The receiving CSIRT acknowledges the request with HTTP return code
982 201 Created.
984 HTTP/1.1 201 Created
985 Date: Fri, 24 Aug 2012 19:17:11 GMT
986 Content-Length: 906
987 Content-Type: application/atom+xml;type=entry
988 Location: http://www.example.org/csirt/RID/InvestigationRequests/823
989 ETag: "8a9h9he4qphqh"
991
992
993 New Investigation Request
994 http://www.example.org/csirt/RID/InvestigationRequests/823
995 2012-08-12T11:08:30Z
996 2012-08-12T11:08:30Z
997 Name of peer CSIRT
998
999
1000
1001 123
1002
1003
1004
1006
1007
1009 Consistent with HTTP/1.1 RFC, the location header indicates the URL
1010 of the newly created InvestigationRequest. If for some reason the
1011 request were not authorized, the client would receive an HTTP status
1012 code 403 Unauthorized. In this case the HTTP response body may
1013 contain additional details, if an as appropriate.
1015 4.2.4.3. Use Case: Search (Query)
1017 This section provides a non-normative example of a search use case.
1019 The following example provides a RESTful alternative to the RID Query
1020 messaage, as described in sections 6.5 and 7.4 of RFC6545. Note that
1021 in the RESTful approach described herein there is no requirement to
1022 define a query language specific to RID queries. Instead, CSIRTs may
1023 provide support for search operations via existing search facilities,
1024 and advertise these capabilities via an appropriate URL template.
1025 Clients dynamically retrieve the search description document, and
1026 invoke specific searches via an instantiated URL template.
1028 An HTTP response body may include a link relationship of type
1029 "search." This link provides a reference to an OpenSearch
1030 description document.
1032 Example HTTP response that includes a "search" link:
1034 HTTP/1.1 200 OK
1035 Date: Fri, 24 Aug 2012 17:20:11 GMT
1036 Content-Length: nnnn
1037 Content-Type: application/atom+xml;type=feed;charset="utf-8"
1039
1040
1046
1050
1052
1053
1054
1056
1058 The OpenSearch Description document contains the information needed
1059 by a client to request a search. An example of an Open Search
1060 description document is shown below:
1062 Example HTTP response that includes a "search" link:
1064
1065
1066 CSIRT search example
1067 Cyber security information sharing consortium search interface
1068 example csirt indicator search
1069 admin@example.org
1070
1071
1072
1073 www.example.org CSIRT search
1074
1075 en-us
1076 UTF-8
1077 UTF-8
1078
1080 The OpenSearch Description document shown above contains two
1081 elements that contain parameterized URL templates. These templates
1082 provide a representation of how the client should make search
1083 requests. The exact format of the query string, including the
1084 parameterization is specified by the feed provider.
1086 This OpenSearch Description Document also contains an example of a
1087 element. Each element describes a specific search
1088 request that can be made by the client. Note that the parameters of
1089 the element correspond to the URL template parameters. In
1090 this way, a provider may fully describe the search interface
1091 available to the clients. Section 5.12, below, provides specific
1092 NORMATIVE requirements for the use of Open Search.
1094 4.2.4.4. Use Case: Cyber Data Repository
1096 This section provides a non-normative example of a cyber security
1097 data repository use case.
1099 In this use case a client accesses a persistent repository of cyber
1100 security data via a RESTful usage model. Retrieving a feed
1101 collection is analogous to an SQL SELECT statement producing a result
1102 set. Retrieving an individual Atom Entry is analogous to a SQL
1103 SELECT statement based upon a primary key producing a unique record.
1104 The cyber security data contained in the repository may include
1105 different data types, including indicators, incidents, becnmarks, or
1106 any other related resources. In this use case, the repository is
1107 queried via HTTP GET, and the results that are returned to the client
1108 may optionally contain URL references to other cyber security
1109 resources that are known to be related. These related resources may
1110 also be persisted locally, or they may exist at another (remote)
1111 cyber data respository.
1113 Example HTTP GET request to a persistent repository for any resources
1114 representing Distributed Denial of Service (DDOS) attacks:
1116 GET /csirt/repository/ddos
1117 Host: www.example.org
1118 Accept: application/atom+xml
1120 The corresponding HTTP response would be an XML document containing
1121 the DDOS feed.
1123 Example HTTP GET response for a DDOS feed:
1125 HTTP/1.1 200 OK
1126 Date: Fri, 24 Aug 2012 17:20:11 GMT
1127 Content-Length: nnnn
1128 Content-Type: application/atom+xml;type=feed;charset="utf-8"
1130
1131
1137 emc-csirt-iodef-feed-service
1138 http://www.example.org/csirt/repository/ddos
1139 Atom formatted representation of a feed of known ddos resources.
1140 2012-05-04T18:13:51.0Z
1141
1142 csirt@example.org
1143 EMC CSIRT
1144
1146
1147
1149
1150 http://www.example.org/csirt/repository/ddos/123456
1151 Sample DDOS Incident
1152
1153
1154
1155
1156 2012-08-04T18:13:51.0Z
1157 2012-08-05T18:13:51.0Z
1158
1159
1160
1161
1162 A short description of this DDOS attack, extracted from the IODEF Incident class, element.
1163
1165
1166
1167
1169
1171 This feed document has two atom entries, one of which has been
1172 elided. The completed entry illustrates an Atom element that
1173 provides a summary of essential details about one particular DDOS
1174 incident. Based upon this summary information and the provided
1175 category information, a client may choose to do an HTTP GET operation
1176 to retrieve the full details of the DDOS incident. This example
1177 shows how a persistent repository may provide links to additional
1178 resources, both local and remote.
1180 Note that the provider of a persistent repostory is not obligated to
1181 follow any particular URL template scheme. The repository available
1182 at the hypothetical provider "www.example.com" uses a different URL
1183 pattern than the hypothetical repository available at "www.cyber-
1184 agency.gov". When a client de-references a link to resource that is
1185 located in a remote repository the client may be challenged for
1186 authentication credentials acceptable to that provider. If the two
1187 repository providers choose to support a federated identity scheme or
1188 some other form of single-sign-on technology, then the user
1189 experience can be improved for interactive clients (e.g., a human
1190 user at a browser). However, this is not required and is an
1191 implementation choice that is out of scope for this specification.
1193 5. Requirements for RESTful (Atom+xml) Binding
1195 This section provides the NORMATIVE requirements for using Atom
1196 format and Atom Pub as a RESTful binding for cyber security
1197 information sharing.
1199 5.1. Transport Layer Security
1201 Servers implementing this specification MUST support server-
1202 authenticated TLS.
1204 Servers MAY support mutually authenticated TLS.
1206 5.2. User Authentication
1208 Servers MUST require user authentication.
1210 Servers MAY support more than one client authentication method.
1212 Servers participating in an information sharing consotium and
1213 supporting interactive user logins by members of the consortium
1214 SHOULD support client authentication via a federated identity scheme
1215 as per SAML 2.0.
1217 Servers MAY support client authenticated TLS.
1219 5.3. User Authorization
1221 This document does not mandate the use of any specific user
1222 authorization mechanisms. However, service implementers SHOULD
1223 provide appropriate authorization checking for all resource accesses,
1224 including individual Atom Entries, Atom Feeds, and Atom Service
1225 Documents.
1227 Authorization for a resource MAY be adjudicated based on the value(s)
1228 of the associated Atom element(s).
1230 When the content model for the Atom element of an Atom
1231 Entry contains an , then authorization MUST be
1232 adjudicated based upon the Atom element(s), whose values
1233 have been mapped as per Section 5.7.
1235 Any use of the element(s) as an input to an authorization
1236 policy decision MUST include both the "scheme" and "term" attributes
1237 contained therein. As described in Section 5.7 below, the namespace
1238 of the "term" attribute is scoped by the associated "scheme"
1239 attribute.
1241 5.4. Content Model
1243 Member entry resources providing a representation of an incident
1244 resource (e.g., as specified in the link relation type) MUST use the
1245 IODEF schema as the content model for the Atom Entry
1246 element.
1248 Member Entry resources providing a representation of an indicator
1249 resource (e.g., as specified in the link relation type) MUST use the
1250 IODEF schema as the content model for the Atom Entry
1251 element.
1253 The resource representation MAY include an appropriate indicator
1254 schema type within the element of the IODEF Incident
1255 class. Supported indicator schema types SHALL be registered via an
1256 IANA table (todo: IANA registration/review).
1258 Member Entry resources providing a representation of a RID report
1259 resource (e.g., as specified in the link relation type) MUST use the
1260 RID schema as the content model for the Atom Entry element.
1262 Member Entry resources providing representation of other types,
1263 SHOULD use the IODEF schema as the content model for the Atom Entry
1264 element.
1266 If the member entry content model is not IODEF, then the
1267 element of the Atom entry MUST contain an appropriate XML namespace
1268 declaration.
1270 5.5. HTTP methods
1272 The following table defines the HTTP [RFC2616] uniform interface
1273 methods supported by this specification:
1275 +------------+------------------------------------------------------+
1276 | HTTP | Description |
1277 | method | |
1278 +------------+------------------------------------------------------+
1279 | GET | Returns a representation of an individual member |
1280 | | entry resource, or a feed collection. |
1281 | PUT | Replaces the current representation of the specified |
1282 | | member entry resource with the representation |
1283 | | provided in the HTTP request body. |
1284 | POST | Creates a new instance of a member entry resource. |
1285 | | The representation of the new resource is provided |
1286 | | in the HTTP request body. |
1287 | DELETE | Removes the indicated member entry resource, or feed |
1288 | | collection. |
1289 | HEAD | Returns metadata about the member entry resource, or |
1290 | | feed collection, contained in HTTP response headers. |
1291 | PATCH | Support TBD. |
1292 +------------+------------------------------------------------------+
1294 Table 1: Uniform Interface for Resource-Oriented Lightweight
1295 Indicator Exchange
1297 Clients MUST be capable of recognizing and prepared to process any
1298 standard HTTP status code, as defined in [RFC2616]
1300 5.6. Service Discovery
1302 This specification requires that a CSIRT MUST publish an Atom Service
1303 Document that describes the set of cyber security information sharing
1304 feeds that are provided.
1306 The service document SHOULD be discoverable via the CSIRT
1307 organization's Web home page or another well-known public resource.
1309 5.6.1. Workspaces
1311 The service document MAY include multiple workspaces. Any CSIRT
1312 providing both public feeds and private consortium feeds MUST place
1313 these different classes of feeds into different workspaces, and
1314 provide appropriate descriptions and naming conventions to indicate
1315 the intended audience of each workspace.
1317 5.6.2. Collections
1319 A CSIRT MAY provide any number of collections within a given
1320 Workspace. It is RECOMMENDED that each collection appear in only a
1321 single Workspace. It is RECOMMENDED that at least one collection be
1322 provided that accepts new incident reports from users. At least one
1323 collection MUST provide a feed of incident information for which the
1324 content model for the entries uses the IODEF schema. The title of
1325 this collection SHOULD be "Incidents".
1327 5.6.3. Service Document Security
1329 Access to the service document MUST be protected via server-
1330 authenticated TLS and a server-side certificate.
1332 When deploying a service document for use by a closed consortium, the
1333 service document MAY also be digitally signed and/or encrypted, using
1334 XML DigSig and/or XML Encryption, respectively.
1336 5.7. Category Mapping
1338 This section defines normative requirements for mapping IODEF
1339 metadata to corresponding Atom category elements. (todo: decide
1340 between IANA registration of scheme, or use a full URI).
1342 5.7.1. Collection Category
1344 An Atom collection MAY hold entries from one or more categories. The
1345 collection category set MUST contain at least the union of all the
1346 member entry categories. A collection MAY have additional category
1347 metadata that are unique to the collection, and not applicable to any
1348 individual member entry. A collection containing IODEF incident
1349 content MUST contain at least two elements. One category
1350 MUST be specified with the value of the "scheme" attribute as
1351 "restriction". One category MUST be specified with the value of the
1352 "scheme" attribute as "purpose". The value of the "fixed" attribute
1353 for both of these category elements MUST be "yes". When the category
1354 scheme="restriction", the allowable values for the "term" attribute
1355 are constrained as per section 3.2 of IODEF, e.g. public, need-to-
1356 know, private, default. When the category scheme="purpose", the
1357 allowable values for the "term" attribute are constrained as per
1358 section 3.2 of IODEF, e.g. traceback, mitigation, reporting, other.
1360 5.7.2. Entry Category
1362 An Atom entry containing IODEF content MUST contain at least two
1363 elements. One category MUST be specified with the value
1364 of the "scheme" attribute as "restriction". One category MUST be
1365 specified with the value of the "scheme" attribute as "purpose".
1366 When the category scheme="restriction", the value of the "term"
1367 attribute must be exactly one of ( public, need-to-know, private,
1368 default). When the category scheme="purpose", the value of the
1369 "term" attribute must be exactly one of (traceback, mitigation,
1370 reporting, other). When the purpose is "other"....
1372 Any member entry MAY have any number of additional categories.
1374 5.8. Entry ID
1376 The ID element for an Atom entry SHOULD be established via the
1377 concatenation of the value of the name attribute from the IODEF
1378 element and the corresponding value of the
1379 element. This requirement ensures a simple and direct one-to-one
1380 relationship between an IODEF incident ID and a corresponding Feed
1381 entry ID and avoids the need for any system to maintain a persistent
1382 store of these identity mappings.
1384 (todo: Note that this implies a constraint on the IODEF document that
1385 is more restrictive than the current IODEF schema. IODEF section 3.3
1386 requires only that the name be a STRING type. Here we are stating
1387 that name must be an IRI. Possible request to update IODEF to
1388 constrain, or to support a new element or attribute).
1390 5.9. Entry Content
1392 The element of an Atom SHOULD include an IODEF
1393 document. The element SHOULD include an appropriate XML
1394 namespace declaration for the IODEF schema. If the content model of
1395 the element does not follow the IODEF schema, then the
1396 element MUST include an appropriate XML namespace
1397 declaration.
1399 A client MAY ignore content that is not using the IODEF schema.
1401 5.10. Link Relations
1403 In addition to the standard Link Relations defined by the Atom
1404 specification, this specification defines the following additional
1405 Link Relation terms, which are introduced specifically in support of
1406 the Resource-Oriented Lightweight Indicator Exchange protocol.
1408 +-----------------------+----------------------------+--------------+
1409 | Name | Description | Conformance |
1410 +-----------------------+----------------------------+--------------+
1411 | service | Provides a link to an atom | MUST |
1412 | | service document | |
1413 | | associated with the | |
1414 | | collection feed. | |
1415 | search | Provides a link to an | MUST |
1416 | | associated Open Search | |
1417 | | document that describes a | |
1418 | | URL template for search | |
1419 | | queries. | |
1420 | history | Provides a link to a | MUST |
1421 | | collection of zero or more | |
1422 | | historical entries that | |
1423 | | are associated with the | |
1424 | | resource. | |
1425 | incidents | Provides a link to a | MUST |
1426 | | collection of zero or more | |
1427 | | instances of actual cyber | |
1428 | | security event(s) that are | |
1429 | | associated with the | |
1430 | | resource. | |
1431 | indicators | Provides a link to a | MUST |
1432 | | collection of zero or more | |
1433 | | instances of cyber | |
1434 | | security indicators that | |
1435 | | are associated with the | |
1436 | | resource. | |
1437 | evidence | Provides a link to a | SHOULD |
1438 | | collection of zero or more | |
1439 | | resources that provides | |
1440 | | some proof of attribution | |
1441 | | for an incident. The | |
1442 | | evidence may or may not | |
1443 | | have any identified chain | |
1444 | | of custody. | |
1445 | campaign | Provides a link to a | SHOULD |
1446 | | collection of zero or more | |
1447 | | resources that provides a | |
1448 | | representation of the | |
1449 | | associated cyber attack | |
1450 | | campaign. | |
1451 | attacker | Provides a link to a | SHOULD |
1452 | | collection of zero or more | |
1453 | | resources that provides a | |
1454 | | representation of the | |
1455 | | attacker. | |
1456 | vector | Provides a link to a | SHOULD |
1457 | | collection of zero or more | |
1458 | | resources that provides a | |
1459 | | representation of the | |
1460 | | method used by the | |
1461 | | attacker. | |
1462 | assessments | Provides a link to a | SHOULD |
1463 | | collection of zero or more | |
1464 | | resources that represent | |
1465 | | the results of executing a | |
1466 | | benchmark. | |
1467 | reports | Provides a link to a | SHOULD |
1468 | | collection of zero or more | |
1469 | | resources that represent | |
1470 | | RID reports. | |
1471 | traceRequests | Provides a link to a | SHOULD |
1472 | | collection of zero or more | |
1473 | | resources that represent | |
1474 | | RID traceRequests. | |
1475 | investigationRequests | Provides a link to a | SHOULD |
1476 | | collection of zero or more | |
1477 | | resources that represent | |
1478 | | RID investigationRequests. | |
1479 | swid | Provides a link to a | SHOULD |
1480 | | collection of zero or more | |
1481 | | resources that represent | |
1482 | | related Software ID tags. | |
1483 +-----------------------+----------------------------+--------------+
1485 Table 2: Link Relations for Resource-Oriented Lightweight Indicator
1486 Exchange
1488 Unless specifically registered with IANA these short names MUST be
1489 fully qualified via concatenation with a base-uri. An appropriate
1490 base-uri could be established via agreement amongst the members of an
1491 information sharing consortium. For example, the rel="indicators"
1492 relationship would become rel="http://www.example.org/csirt/incidents
1493 /relationships/indicators."
1495 5.10.1. Additional Link Relation Requirements
1497 An IODEF document that is carried in an Atom Entry SHOULD NOT contain
1498 a element. Instead, the related activity SHOULD be
1499 available via a link rel=related.
1501 An IODEF document that is carried in an Atom Entry SHOULD NOT contain
1502 a element. Instead, the related history SHOULD be
1503 available via a link rel="history" (todo: or a fully qualified link
1504 rel name). The associated href MAY leverage OpenSearch to specify
1505 the required query.
1507 An Atom Entry MAY include additional link relationships not specified
1508 here. If a client encounters a link relationship of an unknown type
1509 the client MUST ignore the offending link and continue processing the
1510 remaining resource representation as if the offending link element
1511 did not appear.
1513 The link relationship "swid" may be used for a collection of zero or
1514 more software identification tags that are related to the current
1515 indicator. The representation of the resources available via this
1516 link relationship MAY follow an appropriate standard, such as ISO/IEC
1517 19770-2:2009 Information technology -- Software asset management --
1518 Part 2: Software identification tag.
1520 5.11. Member Entry Forward Security
1522 As described in Authorization Policy Enforcement (Authorization
1523 Policy Enforcement) a RESTful model for cyber security information
1524 sharing requires that all of the required security enforcement for
1525 feeds and entries MUST be enforced at the source system, at the point
1526 the representation of the given resource(s) is created. A CSIRT
1527 provider SHALL NOT return any feed content or member entry content
1528 for which the client identity has not been specifically
1529 authenticated, authorized, and audited.
1531 Sharing communities that have a requirement for forward message
1532 security (such that client systems are required to participate in
1533 providing message level security and/or distributed authorization
1534 policy enforcement), MUST use the RID schema as the content model for
1535 the member entry element.
1537 5.12. Date Mapping
1539 The Atom feed element MUST be populated with the current
1540 time at the instant the feed representation was generated. The Atom
1541 entry element MUST be populated with the same time value
1542 as the element from the IODEF document.
1544 5.13. Search
1546 Implementers MUST support OpenSearch 1.1 [opensearch] as the
1547 mechanism for describing how clients may form search requests.
1549 Implementers MUST provide a link with a relationship type of
1550 "search". This link SHALL return an Open Search Description Document
1551 as defined in OpenSearch 1.1.
1553 Implementers MUST support an OpenSearch 1.1 compliant search URL
1554 template that enables a search query via Atom Category, including the
1555 scheme attribute and terms attribute as search parameters.
1557 Implementers SHOULD support search based upon the IODEF AlternativeID
1558 class as a search parameter.
1560 Implementers SHOULD support search based upon the four timestamp
1561 elements of the IODEF Incident class: , ,
1562 , and .
1564 Implementers MAY support additional search capabilities based upon
1565 any of the remaining elements of the IODEF Incident class, including
1566 the element.
1568 Collections that support use of the RID schema as a content model in
1569 the Atom member entry element (e.g. in a report resource
1570 representation reachable via the "report" link relationship) MUST
1571 support search operations that include the RID MessageType as a
1572 search parameter, in addition to the aforementioned IODEF schema
1573 elements, as contained within the element.
1575 Implementers MUST fully qualify all OpenSearch URL template parameter
1576 names using the defined IODEF or RID XML namespaces, as appropriate.
1578 5.14. / (forward slash) Resource URL
1580 The "/" resource MAY be provided for compatibility with existing
1581 deployments that are using Transport of Real-time Inter-network
1582 Defense (RID) Messages over HTTP/TLS [RFC6546]. Consistent with
1583 RFC6546 errata, a client requesting a GET on "/" MUST receive an HTTP
1584 status code 405 Method Not Allowed. An implementation MAY provide
1585 full support for RFC6546 such that a POST to "/" containing a
1586 recognized RID message type just works. Alternatively, a client
1587 requesting a POST to "/" MAY receive an HTTP status code 307
1588 Temporary Redirect. In this case, the location header in the HTTP
1589 response will provide the URL of the appropriate RID endpoint, and
1590 the client may repeat the POST method at the indicated location.
1591 This resource could also leverage the new draft by reschke that
1592 proposes HTTP status code 308 (cf: draft-reschke-http-
1593 status-308-07.txt).
1595 6. Security Considerations
1597 This document defines a resource-oriented approach to lightweight
1598 indicator exchange using HTTP, TLS, Atom Syndicate Format, and Atom
1599 Publishing Protocol. As such, implementers must understand the
1600 security considerations described in those specifications.
1602 In addition, there are a number of additional security considerations
1603 that are unique to this specification.
1605 As described above in the section Authentication of Users
1606 (Section 3.2), the approach described herein is based upon all policy
1607 enforcements being implemented at the point when a resource
1608 representation is created. As such, CSIRTS sharing cyber security
1609 information using this specification must take care to authenticate
1610 their HTTP clients using a suitably strong user authentication
1611 mechanism. Sharing communities that are exchanging information on
1612 well-known indicators and incidents for purposes of public education
1613 may choose to rely upon, e.g. HTTP Authentication, or similar.
1614 However, sharing communities that are engaged in sensitive
1615 collaborative analysis and/or operational response for indicators and
1616 incidents targeting high value information systems should adopt a
1617 suitably stronger user authentication solution, such as TLS client
1618 certificates, or a risk-based or multi-factor approach. In general,
1619 trust in the sharing consortium will depend upon the members
1620 maintaining adequate user authentication mechanisms.
1622 Collaborating consortiums may benefit from the adoption of a
1623 federated identity solution, such as those based upon SAML-core
1624 [SAML-core] and SAML-bind [SAML-bind] and SAML-prof [SAML-prof] for
1625 Web-based authentication and cross-organizational single sign-on.
1626 Dependency on a trusted third party identity provider implies that
1627 appropriate care must be exercised to sufficiently secure the
1628 Identity provider. Any attacks on the federated identity system
1629 would present a risk to the CISRT, as a relying party. Potential
1630 mitigations include deployment of a federation-aware identity
1631 provider that is under the control of the information sharing
1632 consortium, with suitably stringent technical and management
1633 controls.
1635 As discussed above in the section Authorization Policy Enforcement
1636 (Section 3.3), authorization of resource representations is the
1637 responsibility of the source system, i.e. based on the authenticated
1638 user identity associated with an HTTP(S) request. The required
1639 authorization policies that are to be enforced must therefore be
1640 managed by the security administrators of the source system. Various
1641 authorization architectures would be suitable for this purpose, such
1642 as RBAC [1] and/or ABAC, as embodied in XACML [XACML]. In
1643 particular, implementers adopting XACML may benefit from the
1644 capability to represent their authorization policies in a
1645 standardized, interoperable format.
1647 Additional security requirements such as enforcing message-level
1648 security at the destination system could supplement the security
1649 enforcements performed at the source system, however these
1650 destination-provided policy enforcements are out of scope for this
1651 specification. Implementers requiring this capability should
1652 consider leveraging, e.g. the element in the RID schema.
1653 Refer to RFC6545 section 9 for more information.
1655 When security policies relevant to the source system are to be
1656 enforced at both the source and destination systems, implementers
1657 must take care to avoid unintended interactions of the separately
1658 enforced policies. Potential risks will include unintended denial of
1659 service and/or unintended information leakage. These problems may be
1660 mitigated by avoiding any dependence upon enforcements performed at
1661 the destination system. When distributed enforcement is unavoidable,
1662 the usage of a standard language (e.g. XACML) for the expression of
1663 authorization policies will enable the source and destination systems
1664 to better coordinate and align their respective policy expressions.
1666 Adoption of the information sharing approach described in this
1667 document will enable users to more easily perform correlations across
1668 separate, and potentially unrelated, cyber security information
1669 providers. A client may succeed in assembling a data set that would
1670 not have been permitted within the context of the authorization
1671 policies of either provider when considered individually. Thus,
1672 providers may face a risk of an attacker obtaining an access that
1673 constitutes an undetected separation of duties (SOD) violation. It
1674 is important to note that this risk is not unique to this
1675 specification, and a similar potential for abuse exists with any
1676 other cyber security information sharing protocol. However, the wide
1677 availability of tools for HTTP clients and Atom feed handling implies
1678 that the resources and technical skills required for a successful
1679 exploit may be less than it was previously. This risk can be best
1680 mitigated through appropriate vetting of the client at account
1681 provisioning time. In addition, any increase in the risk of this
1682 type of abuse should be offset by the corresponding increase in
1683 effectiveness that that this specification affords to the defenders.
1685 While it is a goal of this specification to enable more agile cyber
1686 security information sharing across a broader and varying
1687 constituency, there is nothing in this specification that necessarily
1688 requires this type of deployment. A cyber security information
1689 sharing consortium may chose to adopt this specification while
1690 continuing to operate as a gated community with strictly limited
1691 membership.
1693 7. IANA Considerations
1695 If the values of the newly defined link relations are not fully
1696 qualified URIs then we need to register these link types with IANA
1697 (e.g. rel="history") It is possible to adjust this document so that
1698 it has no actions for IANA.
1700 8. ToDo and Open Issues
1702 The following is the "todo" and open issues list:
1704 1. Need to make a decision on whether new IANA link registrations
1705 are required, or whether fully qualified (private) link types are
1706 sufficient.
1708 2. Should we require Atom categories that correspond to IODEF
1709 Expectation class and/or IODEF Impact class?
1711 3. Should we include specific requirements for Archive and Paging?
1712 Perhaps just reference RFC 5005?
1714 4. We need more requirements input on use cases involving RID schema
1715 in the Atom member entry content model for link rel=report.
1717 5. An Atom service document will have categories, but this is still
1718 coarse-grained, and not visible at the transport protocol level.
1719 Should we include a MIME media type parameter to support
1720 negotiation and better document the content model schema
1721 contained in a collection, i.e.:
1723 Accept: application/atom+xml;type=entry;content=iodef
1725 Accept: application/atom+xml;type=entry;content=rid
1727 Accept: application/atom+xml;type=entry;content=iodef+openioc
1729 6. If so, I think these parameters may require media type
1730 registration as per RFC4288?
1732 7. Further work is needed to investigate the use of a link
1733 relationship for SWID tags, as related resources.
1735 8. It has been suggested that a RESTful binding approach similar to
1736 ROLIE may be relevant to certain related use cases being
1737 considered in SACM. This requires further discussion to explore
1738 the requirements in more detail.
1740 9. Acknowledgements
1742 The author gratefully acknowledges the valuable contributions of Tom
1743 Maguire, Kathleen Moriarty, and Vijayanand Bharadwaj. These
1744 individuals provided detailed review comments on earlier drafts, and
1745 many suggestions that have helped to improve this document .
1747 10. References
1749 10.1. Normative References
1751 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1752 Requirement Levels", BCP 14, RFC 2119, March 1997.
1754 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1755 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1756 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1758 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
1759 Syndication Format", RFC 4287, December 2005.
1761 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing
1762 Protocol", RFC 5023, October 2007.
1764 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident
1765 Object Description Exchange Format", RFC 5070, December
1766 2007.
1768 [RFC6545] Moriarty, K., "Real-time Inter-network Defense (RID)", RFC
1769 6545, April 2012.
1771 [opensearch]
1772 Clinton, D., "OpenSearch 1.1 draft 5 specification", 2011,
1773 .
1775 [SAML-core]
1776 Cantor, S., Kemp, J., Philpott, R., and E. Mahler,
1777 "Assertions and Protocols for the OASIS Security Assertion
1778 Markup Language (SAML) V2.0 ", OASIS Standard , March
1779 2005, .
1782 [SAML-prof]
1783 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra,
1784 P., Philpott, R., and E. Mahler, "Profiles for the OASIS
1785 Security Assertion Markup Language (SAML) V2.0", OASIS
1786 Standard , March 2005, .
1789 [SAML-bind]
1790 Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E.
1791 Mahler, "Bindings for the OASIS Security Assertion Markup
1792 Language (SAML) V2.0 ", OASIS Standard , March 2005,
1793 .
1796 10.2. Informative References
1798 [XMLencrypt]
1799 Imaura, T., Dillaway, B., and E. Simon, "XML Encryption
1800 Syntax and Processing", W3C Recommendation , December
1801 2002, .
1803 [XMLsig] Bartel, M., Boyer, J., Fox, B., LaMaccia, B., and E.
1804 Simon, "XML-Signature Syntax and Processing", W3C
1805 Recommendation Second Edition, June 2008,
1806 .
1808 [XACML] Rissanen, E., "eXtensible Access Control Markup Language
1809 (XACML) Version 3.0", August 2010, .
1812 [REST] Fielding, R., "Architectural Styles and the Design of
1813 Network-based Software Architectures", 2000, .
1816 [SWID] Suryn, W., "ISO/IEC 19770-2:2009 Information technology -
1817 Software asset management - Part 2: Software
1818 identification tag", 2009, .
1822 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1823 Resource Identifiers (URI): Generic Syntax", RFC 2396,
1824 August 1998.
1826 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
1827 2001.
1829 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
1830 Internet: Timestamps", RFC 3339, July 2002.
1832 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
1833 Text on Security Considerations", BCP 72, RFC 3552, July
1834 2003.
1836 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
1837 IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1838 May 2008.
1840 [RFC6546] Trammell, B., "Transport of Real-time Inter-network
1841 Defense (RID) Messages over HTTP/TLS", RFC 6546, April
1842 2012.
1844 Appendix A. Change Tracking
1846 Changes since -01 version, Feb 15, 2013:
1848 o Updated author's contact information.
1850 o Added a new link relationship definition to Table 2, for Software
1851 Identification tag (SWID) as another potential related resource.
1853 o Included a non-normative reference to the related ISO/IEC standard
1854 in this section, Additional Link Relation Requirements. See:
1855 Section 5.10.1
1857 o Corrected a small number of spelling errors and/or typos
1858 throughout.
1860 Appendix B. Resource Authorization Model
1862 As described in Section 3.3.2 above, ROLIE assumes that all
1863 authorization policy enforcement is provided at the source server.
1864 The implementation details of the authorization scheme chosen by a
1865 ROLIE-compliant provider are out of scope for this specification.
1866 Implementers are free to choose any suitable authorization mechanism
1867 that is capable of fulfilling the policy enforcement requirements
1868 relevant to their consortium and/or organization.
1870 It is well known that one of the major barriers to information
1871 sharing is ensuring acceptable use of the information shared. In the
1872 case of ROLIE, one way to lower that barrier may be to develop a
1873 XACML profile. Use of XACML would allow a ROLIE-compliant provider
1874 to express their information sharing authorization policies in a
1875 standards-compliant, and machine-readable format.
1877 This improved interoperability may, in turn, enable more agile
1878 interactions in the cyber security sharing community. For example, a
1879 peer CSIRT, or another interested stakeholder such as an auditor,
1880 would be able to review and compare CSIRT sharing policies using
1881 appropriate tooling.
1883 The XACML 3.0 standard is based upon the notion that authorization
1884 policies are defined in terms of predicate logic expressions written
1885 against the attributes associated with one or more of the following
1886 four entities:
1888 o SUBJECT
1890 o ACTION
1892 o RESOURCE
1894 o ENVIRONMENT
1896 Thus, a suitable approach to a XACML 3.0 profile for ROLIE
1897 authorization policies could begin by using the 3-tuple of [SUBJECT,
1898 ACTION, RESOURCE] where:
1900 o SUBJECT is the suitably authenticated identity of the requestor.
1902 o ACTION is the associated HTTP method, GET, PUT, POST, DELETE,
1903 HEAD, (PATCH).
1905 o RESOURCE is an XPath expression that uniquely identifies the
1906 instance or type of the ROLIE resource being requested.
1908 Implementers who have a need may also choose to evaluate based upon
1909 the additional ENVIRONMENT factors, such as current threat level, and
1910 so on. One could also write policy to consider the CVSS score
1911 associated with the resource, or the lifecycle phase of the resource
1912 (vulnerability unverified, confirmed, patch available, etc.), and so
1913 on.
1915 Having these policies expressed in a standards-compliant and machine-
1916 readable format could improve the agility and effectiveness of a
1917 cyber security information sharing group or consortium, and enable
1918 better cyber defenses.
1920 B.1. Example XACML Profile
1922 Work-in-Progress. If this aproach finds support in the community
1923 then this section (or a new draft, as a seperate document) could
1924 provide a more complete XACML 3.0 compliant example.
1926 Author's Address
1927 John P. Field
1928 Pivotal
1929 841 Broadway
1930 8th Floor
1931 New York, New York
1932 USA
1934 Phone: 973-635-0228
1935 Email: jfield@gopivotal.com