Guidelines and Template for Defining Extensions to IODEF
draft-ietf-mile-template-05.txt

Abstract

This document provides guidelines for extensions to the Incident Object Description Exchange Format (IODEF) [RFC5070] for exchange of incident management data, and contains a template for Internet-Drafts describing those extensions, in order to ease the work and improve the quality of extension descriptions.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on December 08, 2012.

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 of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to 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 are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Applicability of Extensions to IODEF
• 3. Selecting a Mechanism for IODEF Extension
• 4. Security Considerations
• 5. IANA Considerations
• 6. Acknowledgments
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Appendix A. Document Template
• Appendix A.1. Introduction
• Appendix A.2. Terminology
• Appendix A.3. Applicability
• Appendix A.4. Extension Definition
• Appendix A.5. Security Considerations
• Appendix A.6. IANA Considerations
• Appendix A.7. Manageability Considerations
• Appendix A.8. Appendix A: XML Schema Definition for Extension
• Appendix A.9. Appendix B: Examples
• Appendix B. Example Enumerated Type Extension Definition: Presentation Action
• Appendix C. Example Element Definition: Test
• Author's Address

1. Introduction

In the five years since the specification of IODEF [RFC5070], the threat environment has evolved, as has the practice of cooperative network defense. These trends, along with experience gained through implementation and deployment, have indicated the need to extend IODEF. This document provides guidelines for defining these extensions. It starts by describing the applicability of IODEF extensions, and the IODEF extension mechanisms, before providing a section (Appendix Appendix A) that is itself designed to be copied out and filled in as the starting point for an Internet-Draft about an IODEF extension.

This document is designed to give guidance on the extension of IODEF, especially for those extension authors who may be new to the IETF process. Nothing in this document should be construed as defining policies for the definition of these extensions.

At publication time, the Managed Incident Lightweight Exchange (MILE) working group of the IETF provides a home for work on IODEF extensions that do not otherwise have a natural home. IODEF extensions that require the expertise of other IETF working groups or other standards development organizations may be done within those groups with consultation of IODEF experts, such as those appointed for review as in [I-D.ietf-mile-iodef-xmlreg].

2. Applicability of Extensions to IODEF

Before deciding to extend IODEF, the first step is to determine whether an IODEF extension is a good fit for a given problem. There are two sides to this question:

1. Does the problem involve the reporting or sharing of observations, indications, or other information about an incident, whether in progress or completed, 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 of a group thereof. If the answer to this question is unequivocally "No", then IODEF is probably not a good choice as a base technology for the application area.
2. Can IODEF adequately represent information about the incident without extension? IODEF has a rich set of incident-relevant classes. If, after detailed examination of the problem area and the IODEF specification, and consultation with IODEF experts, the answer to this question is "Yes", then extension is not necessary.

Examples of such extensions to IODEF might include:

• Leveraging existing work in describing aspects of incidents to make IODEF more expressive, by 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:

1. extending the enumerated values of Attributes, as per section 5.1 of [RFC5070];
2. class extension through AdditionalData or RecordItem elements, as per section 5.2 of [RFC5070]; and/or
3. containment of the IODEF-Document element within an external XML Document, itself containing extension data, as done by RID [RFC6545].

Note that in this final case, the extension will not be directly interoperable with IODEF implementations, and must "unwrap" the IODEF document from its container; nevertheless, this may be appropriate for certain use cases involving integration of IODEF within external schemas. Extensions using containment of an IODEF-Document are not further treated in this document, though the document template in Appendix Appendix A may be of some use in defining them.

Certain attributes containing enumerated values within certain IODEF elements may be extended. For an attribute named "foo", this is achieved by giving the value of "foo" as "ext-value", and adding a new attribute named "ext-foo" containing the extended value. The attributes which can be extended this way are limited to the following, denoted in 'Element@attribute' format, referencing the section in which they are defined in [RFC5070]:

• 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.3

Note that this list is current as of publication time; the set of IODEF Data Types may be extended by future specifications which update [RFC5070].

An example definition of an attribute extension is given in Appendix Appendix B.

IODEF documents can contain 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 the data type to reference one of the IODEF data types as enumerated inin section 2 of [RFC5070], and should use the "meaning" and "formatid" attributes to explain the content of the element.

XML extensions within an AdditionalData or RecordItem element use a dtype of "xml", and should define a schema for the topmost containing element within the AdditionalData or RecordItem element. An example definition of an element definition is given in Appendix Appendix C.

When adding elements to the AdditionalData section of an IODEF document, an extension's namespace and schema should be registered with IANA; see Appendix Appendix A.6 for details.

4. Security Considerations

This document raises no security issues itself. Extensions defined using the template in Appendix A need to provide an analysis of security issues they may raise. See Appendix Appendix A.5 for details.

5. IANA Considerations

This document contains no considerations for IANA.

6. Acknowledgments

Thanks to David Black, Benoit Claise, Martin Dürst, Eran Hammer, Tom Millar, Kathleen Moriarty, Peter Saint-Andre, Robert Sparks, Takeshi Takahashi, Sean Turner, Samuel Weiler, and Peter Yee, for their reviews and comments. This work is materially supported by the European Union Seventh Framework Program under grant agreement 257315 (DEMONS).

7. References

7.1. Normative References

7.2. Informative References

Appendix A. Document Template

The document template given in this section is provided as a starting point for writing an Internet-Draft describing an IODEF extension. RFCs are subject to additional formatting requirements and must contain additional sections not described in this template; consult the RFC Editor style guide (http://www.rfc-editor.org/styleguide.html) for more information.

This template is informational in nature; in case of any future conflict with RFC Editor requirements for Internet-Drafts, those requirements take precedence.

Appendix A.1. Introduction

The introduction section introduces the problem being solved by the extension, and motivates the development and deployment of the extension.

Appendix A.2. Terminology

The terminology section introduces and defines terms specific to the document. Terminology from [RFC5070] or [RFC6545] should be referenced in this section, but not redefined or copied. If [RFC2119] terms are used in the document, this should be noted in the terminology section.

Appendix A.3. Applicability

The applicability section defines the use cases to which the extension is applicable, and details any requirements analysis done during the development of the extension. The primary goal of this section is to allow readers to see if an extension is indeed intended to solve a given problem. This section should also define and restrict the scope of the extension, as appropriate, by pointing out any non-obvious situations to which it is not intended to apply.

In addition to defining the applicability, this section may also present example situations, which should then be detailed in the examples section, below.

Appendix A.4. Extension Definition

This section defines the extension.

Extensions to enumerated types are defined in one subsection for each attribute to be extended, enumerating the new values with an explanation of the meaning of each new value. An example enumeration extension is shown in Appendix Appendix B, below.

Element extensions are defined in one subsection for each element, in top-down order, from the element contained within AdditionalData or RecordItem; an example element extension is shown in Appendix Appendix C, below. Each element should be described by a UML diagram as in Figure 1, followed by a description of each of the attributes, and a short description of each of the child elements. Child elements should then be defined in a subsequent subsection, if not 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]
+---------------------+

Elements containing child elements should indicate the multiplicity of those child elements, as shown in the figure above. Allowable TYPEs are are enumerated in section 2 of [RFC5070].

Appendix A.5. Security Considerations

[SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a Security Considerations section, rather a template Security Considerations section for future extension documents to be built from this template. See Section 4 for Security Considerations for this document.]

Any security considerations [RFC3552] raised by this extension or its deployment should be detailed in this section. Guidance should focus on ensuring the users of this extension do so in a secure fashion, with special attention to non-obvious implications of the transmission of the information represented by this extension. [RFC3552] may be a useful reference in determining what to cover in this section. This section is required by the RFC Editor.

It should also be noted in this section that the security considerations for IODEF [RFC5070] apply to the extension as well.

Appendix A.6. IANA Considerations

[IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an IANA Considerations section, rather a template IANA Considerations section for future extension documents to be built from this template. See Section 5 for IANA Considerations for this document.]

Any IANA considerations [RFC5226] for the document should be detailed in this section. Note that IODEF extension documents will generally register new namespaces and schemas. In addition, this section is required by the RFC Editor, so if there are no IANA considerations, the section should exist and contain the text "this document has no actions for IANA".

IODEF Extensions which 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 by which additions may be made to the registry.

IODEF Extensions adding elements to the AdditionalData section of an IODEF document should register their own namespaces and schemas for extensions with IANA; therefore, this section should contain at least a registration request for the namespace and the schema, as follows, modified as appropriate 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.

Appendix 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 no such considerations apply, this section can be omitted.

Appendix A.8. Appendix A: XML Schema Definition for Extension

The XML Schema describing the elements defined in the Extension Defintion section is given here. Each of the examples in Appendix Appendix A.9 will be verified to validate against this schema by automated tools.

Appendix A.9. Appendix B: Examples

This section contains example IODEF-Documents illustrating the extension. If example situations are outlined in the applicability section, documents for those examples should be provided in the same order as in the applicability section. Example documents will be tested to validate against the schema given in the appendix.

Appendix B. Example Enumerated Type Extension Definition: Presentation Action

This example extends the IODEF Expectation element to represent the expectation that a slide deck be derived from the IODEF Incident, and that a presentation be given by the recipient's organization thereon.

Attribute: Expectation@action

Extended value(s): give-a-presentation

Value meaning: generate a slide deck from the provided incident information and give a presentation thereon.

Additional considerations: the format of the slide deck is left to the recipient to determine in accordance with its established practices for the presentation of incident reports.

Appendix C. Example Element Definition: Test

This example defines the Test class for labeling IODEF test data.

The Test class is intended to be included within an AdditionalData element in an IODEF Document. If a Test element is present, it indicates that an IODEF Document contains test data, not a information about a real incident.

The Test class contains information about how the test data was generated.

+---------------------+
| Test                |
+---------------------+
| ENUM category       |
| STRING generator    |
|                     |
|                     |
+---------------------+

The Test class has two attributes:

category:

Required. ENUM. The type of test data. The permitted values for this attribute are shown below. The default value is "unspecified".

1. unspecified. The document contains test data, but no further information is available.
2. internal. The test data is intended for the internal use of an implementor, and should not be distributed or used outside the context in which it was generated.
3. unit. The test data is intended for unit testing of an implementation, and may be included with the implementation to support this as part of the build and deployment process.
4. interoperability. The test data is intended for interoperability testing of an implementation, and may be freely shared to support this purpose.

generator:

Optional. STRING. A free-form string identifying the person, entity, or program which generated the test data.

Author's Address