RFC 6684
Guidelines and Template for Defining Extensions to the Incident Object Description Exchange Format (IODEF)
Guidelines and Template for Defining Extensions to the Incident Object Description Exchange Format (IODEF) 💖
RFC 6684 (part 1 of 2) 🦋
- Organization: Internet Engineering Task Force (IETF) 🌸
- Request for Comments: 6684
- Author: B. Trammell, ETH Zurich ✨
- Category: Informational
- Date: July 2012
- ISSN: 2070-1721
- Obsoletes / Updates: the header has no Obsoletes or Updates line, so this doc doesn't replace or change any earlier RFC 🙈
Abstract ✨
okay so this doc gives you guidelines for extending IODEF (the Incident Object Description Exchange Format from RFC 5070), which is the format for swapping incident management data 🔥. It also includes a template for Internet-Drafts describing those extensions, so writing them is way easier and the descriptions come out way better 💅.
Status of This Memo 🌈
This document is not an Internet Standards Track specification. It's published for informational purposes 🧚.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, received public review, and was approved for publication by the Internet Engineering Steering Group (IESG). Not every document the IESG approves is a candidate for any level of Internet Standard. See Section 2 of RFC 5741 for that 💀.
For info on the current status of this document, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6684 🎀.
Copyright Notice 🫶
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License 📜.
Table of Contents 🍓
1. Introduction ....................................................2
2. Applicability of Extensions to IODEF ............................3
3. Selecting a Mechanism for IODEF Extension .......................3
4. Security Considerations .........................................5
5. Acknowledgments .................................................5
6. References ......................................................5
6.1. Normative References .......................................5
6.2. Informative References .....................................5
Appendix A. Document Template ......................................7
A.1. Introduction ................................................7
A.2. Terminology .................................................7
A.3. Applicability ...............................................7
A.4. Extension Definition ........................................8
A.5. Security Considerations .....................................8
A.6. IANA Considerations .........................................9
A.7. Manageability Considerations ...............................10
A.8. Appendix A: XML Schema Definition for Extension ............10
A.9. Appendix B: Examples .......................................10
Appendix B. Example Enumerated Type Extension Definition:
Presentation Action ...................................10
Appendix C. Example Element Definition: Test ......................101. Introduction ✨
In the five years since IODEF was specified [RFC5070], the threat environment has changed, and so has the way people do cooperative network defense 🛡️. Those trends, plus what people learned from building and deploying it, showed that IODEF needs to be extended 💜. This document gives you guidelines for defining those extensions. It starts by covering where IODEF extensions fit, then explains the IODEF extension mechanisms, and then gives you Appendix A, a template to start from for any future Internet-Draft about an IODEF extension 📝.
This doc is meant to guide anyone extending IODEF, especially extension authors who are new to the IETF process 🧚♀️. Nothing in it should be read as setting policy for how these extensions get defined 🙅♀️.
At publication time, the Managed Incident Lightweight Exchange (MILE) working group of the IETF is the home for IODEF extension work that doesn't have a natural home anywhere else 🏡. IODEF extensions that need expertise from other IETF working groups, or from other standards development organizations, can be done inside those groups, with help from IODEF experts like the ones appointed for review as in [RFC6685] 🤝.
2. Applicability of Extensions to IODEF 🌸
Before you decide to extend IODEF, figure out whether an IODEF extension is actually a good fit for your problem. There are two sides to this question 👀:
- Does the problem involve reporting or sharing observations, indications, or other information about an incident, whether it's in progress or finished, hypothetical or real? "Incident" is defined in the terminology for the original IODEF requirements [RFC3067]: an event that involves a security violation, whether a single attack or a group of them. If the answer to this question is unequivocally "No", then IODEF is probably not a good base technology for that application area 🙅♀️.
- Can IODEF represent the incident information adequately without an extension? IODEF has a rich set of incident-relevant classes 💅. If, after a detailed look at the problem area and the IODEF specification, plus some consultation with IODEF experts, the answer is "Yes", then you don't need an extension 🎉.
Examples of extensions to IODEF might include the following 🍬:
- Leveraging existing work that describes aspects of incidents, to make IODEF more expressive, through standardized reference to external information bases about incidents and incident-related information 📚
- Allowing the description of new types of entities (e.g., related actors), or new types of characteristics of entities (e.g., information related to financial services), involved in an IODEF incident report 💼
- Allowing the representation of new types of indicators, observables, or incidents in an IODEF incident report 🔍
- Allowing additional semantic or metadata labeling of IODEF Documents (e.g., for handling or disposition instructions, or compliance with data protection and data retention regulations) 🏷️
3. Selecting a Mechanism for IODEF Extension 🎀
IODEF was designed to be extended through any combination of the following 🧩:
- extending the enumerated values of Attributes, per Section 5.1 of [RFC5070];
- class extension through AdditionalData or RecordItem elements, per Section 5.2 of [RFC5070]; and/or
- containment of the IODEF Document element within an external XML Document, itself containing extension data, as done by Real-time Inter-network Defense (RID) [RFC6545].
Heads up, bestie: with that last option, the extension won't be directly interoperable with IODEF implementations, and it must "unwrap" the IODEF document from its container 😬. It can still be the right call for some use cases that involve integrating IODEF into external schemas 💖. Extensions that use containment of an IODEF Document aren't covered any further in this document, though the document template in Appendix A may be useful for defining them ✨.
Certain attributes that hold enumerated values inside certain IODEF elements can be extended. For an attribute named "foo", you do this by setting the value of "foo" to "ext-value" and adding a new attribute named "ext-foo" that holds the extended value 🦋. The attributes you can extend this way are limited to the ones below, written in 'Element@attribute' format, with a pointer to the section where [RFC5070] defines them 📍:
Incident@purpose, Section 3.2
AdditionalData@dtype, Section 3.6
Contact@role, Section 3.7
Contact@type, Section 3.7
RegistryHandle@registry, Section 3.7.1
Impact@type, Section 3.10.1
TimeImpact@metric, Section 3.10.2
TimeImpact@duration, Section 3.10.2
HistoryItem@action, Section 3.11.1
Expectation@action, Section 3.13
System@category, Section 3.15
Counter@type, Section 3.16.1
Counter@duration, Section 3.16.1
Address@category, Section 3.16.2
NodeRole@category, Section 3.16.3
RecordPattern@type, Section 3.19.2
RecordPattern@offsetunit, Section 3.19.2
RecordItem@dtype, Section 3.19.3Keep in mind that this list is only current as of publication time. Future specifications that update [RFC5070] may extend the set of IODEF data types 🔮.
There's an example definition of an attribute extension in Appendix B 💡.
IODEF Documents can hold extended scalar or XML data using an AdditionalData element or a RecordItem element 📦. Scalar data extensions must set the "dtype" attribute of the containing element to one of the IODEF data types enumerated in Section 2 of [RFC5070], and they should use the "meaning" and "formatid" attributes to explain what the element's content is ✍️.
XML extensions inside an AdditionalData or RecordItem element use a dtype of "xml", and they should define a schema for the topmost containing element within that AdditionalData or RecordItem element 🧑💻. There's an example element definition in Appendix C 🌈.
When you add elements to the AdditionalData section of an IODEF document, the extension's namespace and schema should be registered with IANA. See Appendix A.6 for the details 🫶.
That's the first half, babes. The rest (Security Considerations, Acknowledgments, References, and the appendices) is coming in part 2 🧚✨
6.2. Informative References 🎀
okay so these are the background reads, the ones that give the context for the rest of the doc 📚✨ here they are, bestie:
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3067] Arvidsson, J., Cormack, A., Demchenko, Y., and J. Meijer,
"TERENA'S Incident Object Description and Exchange Format
Requirements", RFC 3067, February 2001.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552,
July 2003.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5706] Harrington, D., "Guidelines for Considering Operations and
Management of New Protocols and Protocol Extensions",
RFC 5706, November 2009.
[RFC6545] Moriarty, K., "Real-time Inter-network Defense (RID)",
RFC 6545, April 2012.
[RFC6685] Trammell, B., "Expert Review for Incident Object
Description Exchange Format (IODEF) Extensions in IANA XML
Registry", RFC 6685, July 2012.Appendix A. Document Template 🧚
this template is giving starter kit energy 💖 it's here to help you write an Internet-Draft describing an IODEF extension. RFCs have extra formatting rules and need extra sections that this template doesn't cover, so check the RFC Editor style guide at http://www.rfc-editor.org/styleguide.html for the full scoop 🔍
this template is informational, so if RFC Editor requirements for Internet-Drafts ever conflict with it in the future, those requirements win. no debate 💅
A.1. Introduction 🌸
the Introduction section lays out the problem the extension solves and explains why it's worth building and deploying. main character reason to exist 👑
A.2. Terminology 📖
the Terminology section introduces and defines terms that are specific to your document. if you're using terms from [RFC5070] or [RFC6545], reference them here, but don't redefine or copy them 🙅♀️ and if [RFC2119] terms show up in the document, make a note of that in this section too 💜
A.3. Applicability 🦋
the Applicability section defines the use cases the extension is meant for, and it details any requirements analysis you did while developing it. the big goal here is letting readers quickly check whether the extension is actually meant to solve their problem 👀 this section should also define and limit the scope of the extension where needed, by pointing out any non-obvious situations it doesn't apply to ✨
you may also use this section to present example situations, and those should then be detailed in the examples section, below 🫶
A.4. Extension Definition 💅
this section defines the extension itself, bestie 🎀
enumerated type extensions get their own subsection for each attribute being extended. list out the new values there and explain what each one means 🌈 an example enumeration extension lives in Appendix B, below 💖
element extensions get one subsection per element, going top-down, starting with the element contained within AdditionalData or RecordItem. an example element extension is in Appendix C, below 🧚 every element should come with a Unified Modeling Language (UML) diagram like Figure 1, followed by a description of each attribute and a short description of each child element. child elements then get defined in a following subsection, unless they're already defined in the IODEF Document itself or in another referenced IODEF extension document 🔥
+---------------------+
| Element |
+---------------------+
| TYPE attribute0 |<>----------[ChildExactlyOne]
| TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne]
| |<>--{0..*}--[ChildZeroOrMore]
| |<>--{1..*}--[ChildOneOrMore]
+---------------------+
Figure 1: Example UML Element Diagramelements with child elements should show how many of each child they can have, just like the figure above 🔢 allowable TYPEs are enumerated in Section 2 of [RFC5070] 📋
A.5. Security Considerations 🔐
any security considerations [RFC3552] raised by the extension or its deployment should be detailed in this section. the guidance should focus on making sure users of the extension use it securely, paying special attention to non-obvious implications of transmitting the information the extension represents 😭 [RFC3552] may be a useful reference for deciding what to cover here. this section is required by the RFC Editor, so don't skip it 💀
it should also be noted in this section that the security considerations for IODEF [RFC5070] apply to the extension as well 🛡️
A.6. IANA Considerations 📝
any IANA considerations [RFC5226] for the document should be detailed in this section. heads up: IODEF extension documents will generally register new namespaces and schemas 🧾 this section is required by the RFC Editor, so even if there are no IANA considerations, the section should exist and contain the text "this document has no actions for IANA" 🙈
IODEF Extensions that represent an enumeration should reference an existing IANA registry or subregistry for the values of that enumeration. if no such registry exists, this section should define a new registry to hold the enumeration's values, and define the policies for how additions may be made to it 🌸
IODEF Extensions that add elements to the AdditionalData section of an IODEF Document should register their own namespaces and schemas with IANA. so this section should contain at least a registration request for the namespace and the schema, formatted like the examples below, modified as needed for the extension 💜
Registration request for the IODEF My-Extension namespace:
URI: urn:ietf:params:xml:ns:iodef-myextension-1.0
Registrant Contact: Refer here to the Authors' Addresses section of
the document, or to an organizational contact in the case of an
extension supported by an external organization.
XML: None
Registration request for the IODEF My-Extension XML schema:
URI: urn:ietf:params:xml:schema:iodef-myextension-1.0
Registrant Contact: Refer here to the Authors' Addresses section of
the document, or to an organizational contact in the case of an
extension supported by an external organization.
XML: Refer here to the XML Schema in Appendix A of the document, or
to a well-known external reference in the case of an extension with
an externally defined schema.A.7. Manageability Considerations 🛠️
if any of the operational and/or management considerations listed in Appendix A of [RFC5706] apply to the extension, address them in this section. if none of them apply, this section can be omitted 🦋
A.8. Appendix A: XML Schema Definition for Extension 🧩
the XML Schema describing the elements defined in the Extension Definition section goes here. automated tools will check that each of the examples in Appendix A.9 validates against this schema ✅
A.9. Appendix B: Examples 🍓
this section holds example IODEF Documents that illustrate the extension. if the Applicability section outlines example situations, the documents for those examples should be provided in the same order as they appear in the Applicability section 📋 example documents will be tested to validate against the schema in the appendix 🫶
Appendix B. Example Enumerated Type Extension Definition: Presentation Action 🎤
okay this one's so fun 😭 it extends the IODEF Expectation element to represent the expectation that a slide deck gets made from the IODEF Incident, and that the recipient's organization gives a presentation on it 🌈
Attribute: Expectation@action
Extended value(s): give-a-presentation
Value meaning: generate a slide deck from the provided incident information and give a presentation on it ✨
Additional considerations: the format of the slide deck is up to the recipient, following their established practices for presenting incident reports 💅
Appendix C. Example Element Definition: Test 🧪
this example defines the Test class for labeling IODEF test data 🧚
the Test class is meant to be included within an AdditionalData element in an IODEF Document. if a Test element is present, it means the IODEF Document contains test data, not information about a real incident 🙈 the Test class also holds info about how the test data was generated 🔧
+---------------------+
| Test |
+---------------------+
| ENUM category |
| STRING generator |
| |
| |
+---------------------+
Figure 2: The Test Classthe Test class has two attributes:
category: Required. ENUM. The type of test data. The permitted values for this attribute are listed below. The default value isunspecified. 🌟unspecified. The document contains test data, but no further information is available.internal. The test data is intended for the internal use of an implementor, and it should not be distributed or used outside the context in which it was generated. 🔒unit. The test data is intended for unit testing of an implementation, and it may be included with the implementation to support this as part of the build and deployment process. 🛠️interoperability. The test data is intended for interoperability testing of an implementation, and it may be freely shared to support this purpose. 🤝
generator: Optional. STRING. A free-form string identifying the person, entity, or program that generated the test data. 🎀
Author's Address 🖊️
Brian Trammell
Swiss Federal Institute of Technology Zurich
Gloriastrasse 35
8092 Zurich
Switzerland
Phone: +41 44 632 70 13
EMail: trammell@tik.ee.ethz.ch📦 where this page comes from
- ietf: rfc6684 2012-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms