Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7970

The Incident Object Description Exchange Format Version 2

Pages: 172
Proposed Standard
Errata
Obsoletes:  50706685
Part 6 of 9 – Pages 96 to 121
First   Prev   Next

Top   ToC   RFC7970 - Page 96   prevText

3.29. Indicator Class

The Indicator class describes an indicator. An indicator consists of observable features and phenomenon that aid in the forensic or proactive detection of malicious activity and associated metadata. An indicator can be described outright by referencing or composing previously defined indicators or by referencing observables described in the incident report found in this document.
Top   ToC   RFC7970 - Page 97
   +------------------------+
   | Indicator              |
   +------------------------+
   | ENUM restriction       |<>----------[ IndicatorID            ]
   | STRING ext-restriction |<>--{0..*}--[ AlternativeIndicatorID ]
   |                        |<>--{0..*}--[ Description            ]
   |                        |<>--{0..1}--[ StartTime              ]
   |                        |<>--{0..1}--[ EndTime                ]
   |                        |<>--{0..1}--[ Confidence             ]
   |                        |<>--{0..*}--[ Contact                ]
   |                        |<>--{0..1}--[ Observable             ]
   |                        |<>--{0..1}--[ ObservableReference    ]
   |                        |<>--{0..1}--[ IndicatorExpression    ]
   |                        |<>--{0..1}--[ IndicatorReference     ]
   |                        |<>--{0..*}--[ NodeRole               ]
   |                        |<>--{0..*}--[ AttackPhase            ]
   |                        |<>--{0..*}--[ Reference              ]
   |                        |<>--{0..*}--[ AdditionalData         ]
   +------------------------+

                      Figure 59: The Indicator Class

   The aggregate classes of the Indicator class are:

   IndicatorID
      One.  An identifier for this indicator.  See Section 3.29.1.

   AlternativeIndicatorID
      Zero or more.  An alternative identifier for this indicator.  See
      Section 3.29.2.

   Description
      Zero or more.  ML_STRING.  A free-form text description of the
      indicator.

   StartTime
      Zero or one.  DATETIME.  A timestamp of the start of the time
      period during which this indicator is valid.

   EndTime
      Zero or one.  DATETIME.  A timestamp of the end of the time period
      during which this indicator is valid.

   Confidence
      Zero or one.  An estimate of the confidence in the quality of the
      indicator.  See Section 3.12.5.
Top   ToC   RFC7970 - Page 98
   Contact
      Zero or more.  Contact information for this indicator.  See
      Section 3.9.

   Observable
      Zero or one.  An observable feature or phenomenon of this
      indicator.  See Section 3.29.3.

   ObservableReference
      Zero or one.  A reference to an observable feature or phenomenon
      defined elsewhere in the document.  See Section 3.29.6.

   IndicatorExpression
      Zero or one.  A composition of observables.  See Section 3.29.4.

   IndicatorReference
      Zero or one.  A reference to an indicator.  See Section 3.29.7.

   NodeRole
      Zero or more.  The role of the system in the attack should this
      indicator be matched to it.  See Section 3.18.2.

   AttackPhase
      Zero or more.  The phase in an attack life cycle during which this
      indicator might be seen.  See Section 3.29.8.

   Reference
      Zero or more.  A reference to additional information relevant to
      this indicator.  See Section 3.11.1.

   AdditionalData
      Zero or more.  EXTENSION.  Mechanism by which to extend the data
      model.

   The Indicator class MUST have exactly one instance of an Observable,
   IndicatorExpression, ObservableReference, or IndicatorReference
   class.

   The StartTime and EndTime classes can be used to define an interval
   during which the indicator is valid.  If both classes are present,
   the indicator is consider valid only during the described interval.
   If neither class is provided, the indicator is considered valid
   during any time interval.  If only a StartTime is provided, the
   indicator is valid anytime after this timestamp.  If only an EndTime
   is provided, the indicator is valid anytime prior to this timestamp.
Top   ToC   RFC7970 - Page 99
   The attributes of the Indicator class are:

   restriction
      Optional.  ENUM.  See Section 3.3.1.

   ext-restriction
      Optional.  STRING.  A means by which to extend the restriction
      attribute.  See Section 5.1.1.

3.29.1. IndicatorID Class

The IndicatorID class identifies an indicator with a globally unique identifier. The combination of the name and version attributes and the element content form this identifier. Indicators generated by given CSIRT MUST NOT reuse the same value unless they are referencing the same indicator. +------------------+ | IndicatorID | +------------------+ | ID | | | | STRING name | | STRING version | +------------------+ Figure 60: The IndicatorID Class The content of the class is of type ID and specifies an identifier for an indicator. The attributes of the IndicatorID class are: name Required. STRING. An identifier describing the CSIRT that created the indicator. In order to have a globally unique CSIRT name, the fully qualified domain name associated with the CSIRT MUST be used. This format is identical to the IncidentID@name attribute in Section 3.4. version Required. STRING. A version number of an indicator.
Top   ToC   RFC7970 - Page 100

3.29.2. AlternativeIndicatorID Class

The AlternativeIndicatorID class lists alternative identifiers for an indicator. +-------------------------+ | AlternativeIndicatorID | +-------------------------+ | ENUM restriction |<>--{1..*}--[ IndicatorReference ] | STRING ext-restriction | +-------------------------+ Figure 61: The AlternativeIndicatorID Class The aggregate class of the AlternativeIndicatorID class is: IndicatorReference One or more. A reference to an indicator. See Section 3.29.7. The attributes of the AlternativeIndicatorID class are: restriction Optional. ENUM. See Section 3.3.1. ext-restriction Optional. STRING. A means by which to extend the restriction attribute. See Section 5.1.1.
Top   ToC   RFC7970 - Page 101

3.29.3. Observable Class

The Observable class describes a feature and phenomenon that can be observed or measured for the purposes of detecting malicious behavior. +------------------------+ | Observable | +------------------------+ | ENUM restriction |<>--{0..1}--[ System ] | STRING ext-restriction |<>--{0..1}--[ Address ] | |<>--{0..1}--[ DomainData ] | |<>--{0..1}--[ Service ] | |<>--{0..1}--[ EmailData ] | |<>--{0..1}--[ WindowsRegistryKeysModified ] | |<>--{0..1}--[ FileData ] | |<>--{0..1}--[ CertificateData ] | |<>--{0..1]--[ RegistryHandle ] | |<>--{0..1}--[ RecordData ] | |<>--{0..1}--[ EventData ] | |<>--{0..1}--[ Incident ] | |<>--{0..1}--[ Expectation ] | |<>--{0..1}--[ Reference ] | |<>--{0..1}--[ Assessment ] | |<>--{0..1}--[ DetectionPattern ] | |<>--{0..1}--[ HistoryItem ] | |<>--{0..1}--[ BulkObservable ] | |<>--{0..*}--[ AdditionalData ] +------------------------+ Figure 62: The Observable Class The aggregate classes of the Observable class are: System Zero or one. A System observable. See Section 3.17. Address Zero or one. An Address observable. See Section 3.18.1. DomainData Zero or one. A DomainData observable. See Section 3.19. Service Zero or one. A Service observable. See Section 3.20. EmailData Zero or one. An EmailData observable. See Section 3.21.
Top   ToC   RFC7970 - Page 102
   WindowsRegistryKeysModified
      Zero or one.  A WindowsRegistryKeysModified observable.  See
      Section 3.23.

   FileData
      Zero or one.  A FileData observable.  See Section 3.25.

   CertificateData
      Zero or one.  A CertificateData observable.  See Section 3.24.

   RegistryHandle
      Zero or one.  A RegistryHandle observable.  See Section 3.9.1.

   RecordData
      Zero or one.  A RecordData observable.  See Section 3.22.1.

   EventData
      Zero or one.  An EventData observable.  See Section 3.14.

   Incident
      Zero or one.  An Incident observable.  See Section 3.2.

   Expectation
      Zero or one.  An Expectation observable.  See Section 3.15.

   Reference
      Zero or one.  A Reference observable.  See Section 3.11.1.

   Assessment
      Zero or one.  An Assessment observable.  See Section 3.12.

   DetectionPattern
      Zero or one.  A DetectionPattern observable.  See Section 3.10.1.

   HistoryItem
      Zero or one.  A HistoryItem observable.  See Section 3.13.1.

   BulkObservable
      Zero or one.  A bulk list of observables.  See Section 3.29.3.1.

   AdditionalData
      Zero or more.  EXTENSION.  Mechanism by which to extend the data
      model.

   The Observable class MUST have exactly one of the possible child
   classes.
Top   ToC   RFC7970 - Page 103
   The attributes of the Observable class are:

   restriction
      Optional.  ENUM.  See Section 3.3.1.

   ext-restriction
      Optional.  STRING.  A means by which to extend the restriction
      attribute.  See Section 5.1.1.

3.29.3.1. BulkObservable Class
The BulkObservable class allows the enumeration of a single type of observable without requiring each one to be encoded individually in multiple instances of the same class. The type attribute describes the type of observable listed in the child BulkObservableList class. The BulkObservableFormat class optionally provides additional metadata. +---------------------------+ | BulkObservable | +---------------------------+ | ENUM type |<>--{0..1}--[ BulkObservableFormat ] | STRING ext-type |<>----------[ BulkObservableList ] | |<>--{0..*}--[ AdditionalData ] +---------------------------+ Figure 63: The BulkObservable Class The aggregate classes of the BulkObservable class are: BulkObservableFormat Zero or one. Provides additional metadata about the observables enumerated in the BulkObservableList class. See Section 3.29.3.1.1. BulkObservableList One. STRING. A list of observables, one per line. Each line is separated with either a LF character or CR and LF characters. The type attribute specifies which observables will be listed. AdditionalData Zero or more. EXTENSION. Mechanism by which to extend the data model.
Top   ToC   RFC7970 - Page 104
   The attributes of the BulkObservable class are:

   type
      Optional.  ENUM.  The type of the observable listed in the child
      ObservableList class.  These values are maintained in the
      "BulkObservable-type" IANA registry per Section 10.2.

      1.   asn.  Autonomous System Number (per the Address@category
           attribute).

      2.   atm.  Asynchronous Transfer Mode (ATM) address (per the
           Address@category attribute).

      3.   e-mail.  Email address (per the Address@category attribute).

      4.   ipv4-addr.  IPv4 host address in dotted-decimal notation,
           e.g., 192.0.2.1 (per the Address@category attribute).

      5.   ipv4-net.  IPv4 network address in dotted-decimal notation,
           slash, significant bits, e.g., 192.0.2.0/24 (per the
           Address@category attribute).

      6.   ipv4-net-mask.  IPv4 network address in dotted-decimal
           notation, slash, network mask in dotted-decimal notation,
           i.e., 192.0.2.0/255.255.255.0 (per the Address@category
           attribute).

      7.   ipv6-addr.  IPv6 host address, e.g., 2001:DB8::3 (per the
           Address@category attribute).

      8.   ipv6-net.  IPv6 network address, slash, significant bits,
           e.g., 2001:DB8::/32 (per the Address@category attribute).

      9.   ipv6-net-mask.  IPv6 network address, slash, network mask
           (per the Address@category attribute).

      10.  mac.  Media Access Control (MAC) address, i.e., a:b:c:d:e:f
           (per the Address@category attribute).

      11.  site-uri.  A URL or URI for a resource (per the
           Address@category attribute).

      12.  domain-name.  A fully qualified domain name or part of a name
           (e.g., fqdn.example.com, example.com).

      13.  domain-to-ipv4.  A mapping of FQDN to IPv4 address specified
           as a comma-separated list (e.g., "fqdn.example.com,
           192.0.2.1").
Top   ToC   RFC7970 - Page 105
      14.  domain-to-ipv6.  A mapping of FQDN to IPv6 address specified
           as a comma-separated list (e.g., "fqdn.example.com,
           2001:DB8::3").

      15.  domain-to-ipv4-timestamp.  Same as domain-to-ipv4 but with a
           timestamp (in the DATETIME format) of the resolution (e.g.,
           "fqdn.example.com, 192.0.2.1, 2015-06-11T00:38:31-06:00").

      16.  domain-to-ipv6-timestamp.  Same as domain-to-ipv6 but with a
           timestamp (in the DATETIME format) of the resolution (e.g.,
           "fqdn.example.com, 2001:DB8::3, 2015-06-11T00:38:31-06:00").

      17.  ipv4-port.  An IPv4 address, port, and protocol tuple (e.g.,
           192.0.2.1, 80, TCP).  The protocol name corresponds to the
           "Keyword" column in the "Assigned Internet Protocol Numbers"
           registry [IANA.Protocols].

      18.  ipv6-port.  An IPv6 address, port, and protocol tuple (e.g.,
           2001:DB8::3, 80, TCP).  The protocol name corresponds to the
           "Keyword" column in the "Assigned Internet Protocol Numbers"
           registry [IANA.Protocols].

      19.  windows-reg-key.  A Microsoft Windows registry key.

      20.  file-hash.  A file hash.  The format of this hash is
           described in the Hash class that MUST be present in a sibling
           BulkObservableFormat class.

      21.  email-x-mailer.  An X-Mailer field from an email.

      22.  email-subject.  An email subject line.

      23.  http-user-agent.  A User Agent field from an HTTP request
           header (e.g., "Mozilla/5.0 (Windows NT 6.3; WOW64; rv:38.0)
           Gecko/20100101 Firefox/38.0").

      24.  http-request-uri.  The Request URI from an HTTP request
           header.

      25.  mutex.  The name of a system mutex (mutual exclusion lock).

      26.  file-path.  A file path (e.g., "/tmp/local/file",
           "c:\windows\system32\file.sys").

      27.  user-name.  A username.
Top   ToC   RFC7970 - Page 106
      28.  ext-value.  A value used to indicate that this attribute is
           extended and the actual value is provided using the
           corresponding ext-* attribute.  See Section 5.1.1.

   ext-type
      Optional.  STRING.  A means by which to extend the type attribute.
      See Section 5.1.1.

3.29.3.1.1. BulkObservableFormat Class
The ObservableFormat class specifies metadata about the format of an observable enumerated in a sibling BulkObservableList class. +---------------------------+ | BulkObservableFormat | +---------------------------+ | |<>--{0..1}--[ Hash ] | |<>--{0..*}--[ AdditionalData ] +---------------------------+ Figure 64: The BulkObservableFormat Class The aggregate classes of the BulkObservableFormat class are: Hash Zero or one. Describes the format of a hash. See Section 3.26.1. AdditionalData Zero or more. EXTENSION. Mechanism by which to extend the data model. The BulkObservableFormat class has no attributes. Either Hash or AdditionalData MUST be present.

3.29.4. IndicatorExpression Class

The IndicatorExpression describes an expression composed of observed phenomenon, features, or indicators. Elements of the expression can be described directly, reference relevant data from other parts of a given IODEF document, or reference previously defined indicators. All child classes of a given instance of IndicatorExpression form a boolean algebraic expression where the operator between them is determined by the operator attribute.
Top   ToC   RFC7970 - Page 107
   +--------------------------+
   | IndicatorExpression      |
   +--------------------------+
   | ENUM operator            |<>--{0..*}--[ IndicatorExpression  ]
   | STRING ext-operator      |<>--{0..*}--[ Observable           ]
   |                          |<>--{0..*}--[ ObservableReference  ]
   |                          |<>--{0..*}--[ IndicatorReference   ]
   |                          |<>--{0..1}--[ Confidence           ]
   |                          |<>--{0..*}--[ AdditionalData       ]
   +--------------------------+

                 Figure 65: The IndicatorExpression Class

   The aggregate classes of the IndicatorExpression class are:

   IndicatorExpression
      Zero or more.  An expression composed of other observables or
      indicators.  See Section 3.29.4.

   Observable
      Zero or more.  A description of an observable.  See
      Section 3.29.3.

   ObservableReference
      Zero or more.  A reference to an observable.  See Section 3.29.6.

   IndicatorReference
      Zero or more.  A reference to an indicator.  See Section 3.29.7.

   Confidence
      Zero or one.  An estimate of the confidence in the quality of the
      terms expressed in the expression.  See Section 3.12.5.

   AdditionalData
      Zero or more.  EXTENSION.  Mechanism by which to extend the data
      model.

   The attributes of the IndicatorExpression class are:

   operator
      Optional.  ENUM.  The operator to be applied between the child
      elements.  See Section 3.29.5 for parsing guidance.  The default
      value is "and".  These values are maintained in the
      "IndicatorExpression-operator" IANA registry per Section 10.2.

      1.  not.  negation operator.

      2.  and.  conjunction operator.
Top   ToC   RFC7970 - Page 108
      3.  or.  disjunction operator.

      4.  xor.  exclusive disjunction operator.

   ext-operator
      Optional.  STRING.  A means by which to extend the operator
      attribute.  See Section 5.1.1.

3.29.5. Expressions with IndicatorExpression

Boolean algebraic expressions can be used to specify relationships between observables and indicators. These expressions are constructed through the use of the operator attribute and parent- child relationships in IndicatorExpressions. These expressions should be parsed as follows: 1. The operator specified by the operator attribute is applied between each of the child elements of the immediate parent IndicatorExpression element. If no operator attribute is specified, it should be assumed to be the conjunction operator (i.e., operator="and"). 2. A nested IndicatorExpression element with a parent IndicatorExpression is the equivalent of a parentheses in the expression. The following examples in Figures 66 through 70 illustrate these parsing rules: 1 : <IndicatorExpression> 2 [O1]: <Observable>..</Observable> 3 [O2]: <Observable>..</Observable> 4 : </IndicatorExpression> Equivalent expression: (O1 AND O2) Figure 66: Nested Elements in an IndicatorExpression without an Operator Attribute Specified 1 : <IndicatorExpression operator="or"> 2 [O1]: <Observable>..</Observable> 3 [O2]: <Observable>..</Observable> 4 : </IndicatorExpression> Equivalent expression: (O1 OR O2) Figure 67: Nested Elements in an IndicatorExpression with an Operator Attribute Specified
Top   ToC   RFC7970 - Page 109
   1     : <IndicatorExpression operator="or">
   2     :    <IndicatorExpression operator="or">
   3 [O1]:      <Observable>..</Observable>
   4 [O2]:      <Observable>..</Observable>
   5     :    </IndicatorExpression>
   6 [O3]:    <Observable>..</Observable>
   7     : </IndicatorExpression>

   Equivalent expression: ((O1 OR O2) OR O3)

   Figure 68: Nested Elements with a Recursive IndicatorExpression with
                      an Operator Attribute Specified

   1     : <IndicatorExpression operator="not">
   2     :    <IndicatorExpression operator="and">
   3 [O1]:      <Observable>..</Observable>
   4 [O2]:      <Observable>..</Observable>
   5     :    </IndicatorExpression>
   6     : </IndicatorExpression>

   Equivalent expression: (NOT (O1 AND O2))

   Figure 69: A Recursive IndicatorExpression with an Operator Attribute
                                 Specified

    1                          :    <IndicatorExpression operator="or">
    2                          :      <IndicatorExpression>
    3 [O1 with low confidence] :        <Observable>..</Observable>
    4                          :        <Confidence rating="low" />
    5                          :      </IndicatorExpression>
    6                          :      <IndicatorExpression>
    7 [O2 with high confidence]:        <Observable>..</Observable>
    8                          :        <Confidence rating="high" />
    9                          :      </IndicatorExpression>
   10                          :    </IndicatorExpression>

   Equivalent expression: ((O1) OR (O2))

          Figure 70: Varying Confidence on Particular Observables

   Invalid algebraic expressions while valid XML MUST NOT be specified.
Top   ToC   RFC7970 - Page 110

3.29.6. ObservableReference Class

The ObservableReference describes a reference to an observable feature or phenomenon described elsewhere in the document. The ObservableReference class has no content. +-------------------------+ | ObservableReference | +-------------------------+ | IDREF uid-ref | +-------------------------+ Figure 71: The ObservableReference Class The ObservableReference class has no content. The attribute of the ObservableReference class is: uid-ref Required. IDREF. An identifier that serves as a reference to a class in the IODEF document. The referenced class will have this identifier set in its observable-id attribute.

3.29.7. IndicatorReference Class

The IndicatorReference describes a reference to an indicator. This reference may be to an indicator described in this IODEF document or in a previously exchanged IODEF document. The IndicatorReference class has no content. +--------------------------+ | IndicatorReference | +--------------------------+ | IDREF uid-ref | | STRING euid-ref | | STRING version | +--------------------------+ Figure 72: The IndicatorReference Class The attributes of the IndicatorReference class are: uid-ref Optional. IDREF. An identifier that references an Indicator class in the IODEF document. The referenced Indicator class will have this identifier set in its IndicatorID class.
Top   ToC   RFC7970 - Page 111
   euid-ref
      Optional.  STRING.  An identifier that references an IndicatorID
      not in this IODEF document.

   version
      Optional.  STRING.  A version number of an indicator.

   Either the uid-ref or the euid-ref attribute MUST be set.

3.29.8. AttackPhase Class

The AttackPhase class describes a particular phase of an attack life cycle. +------------------------+ | AttackPhase | +------------------------+ | |<>--{0..*}--[ AttackPhaseID ] | |<>--{0..*}--[ URL ] | |<>--{0..*}--[ Description ] | |<>--{0..*}--[ AdditionalData ] +------------------------+ Figure 73: The AttackPhase Class The aggregate classes of the AttackPhase class are: AttackPhaseID Zero or more. STRING. An identifier for the phase of the attack. URL Zero or more. URL. A URL to a resource describing this phase of the attack. Description Zero or more. ML_STRING. A free-form text description of this phase of the attack. AdditionalData Zero or more. EXTENSION. A mechanism by which to extend the data model. AttackPhase MUST have at least one instance of a child class. The AttackPhase class has no attributes.
Top   ToC   RFC7970 - Page 112

4. Processing Considerations

This section provides additional requirements and guidance on creating and processing IODEF documents.

4.1. Encoding

Every IODEF document MUST begin with an XML declaration and MUST specify the XML version used. The character encoding MUST also be explicitly specified. UTF-8 [RFC3629] SHOULD be used unless UTF-16 [RFC2781] is necessary. Encodings other than UTF-8 and UTF-16 SHOULD NOT be used. The IODEF conforms to all XML data-encoding conventions and constraints. The XML declaration with UTF-8 character encoding will read as follows: <?xml version="1.0" encoding="UTF-8" ?> Certain characters have special meaning in XML and MUST not appear in literal form. Per Section 2.4 of [W3C.XML], these characters MUST be escaped with a numeric character or entity reference.

4.2. IODEF Namespace

The IODEF schema declares a namespace of "urn:ietf:params:xml:ns:iodef-2.0" and registers it per [W3C.XMLNS]. Each IODEF document MUST include a valid reference to the IODEF schema using the "xsi:schemaLocation" attribute. An example of such a declaration would look as follows: <IODEF-Document version="2.00" lang="en-US" xmlns:iodef="urn:ietf:params:xml:ns:iodef-2.0" xsi:schemaLocation="urn:ietf:params:xmls:schema:iodef-2.0" ...>

4.3. Validation

IODEF documents MUST be well-formed XML. It is RECOMMENDED that recipients validate the document against the schema described in Section 8. However, mere conformance to this schema is not sufficient for a semantically valid IODEF document. The text of Section 3 describes further formatting and constraints, including some that cannot be conveniently encoded in the schema. These MUST also be considered by an IODEF implementation. Furthermore, the enumerated values present in this document are a static list that will be incomplete over time as select attributes can be extended by a corresponding IANA registry per Section 10.2. Therefore, IODEF
Top   ToC   RFC7970 - Page 113
   implementations SHOULD periodically update their schema and MAY need
   to update their parsing algorithms to incorporate newly registered
   values.

4.4. Incompatibilities with v1

The IODEF data model in this document makes a number of changes to [RFC5070]. These changes were largely additive -- classes and enumerated values were added. However, some incompatibilities between [RFC5070] and this new specification were introduced. These incompatibilities are as follows: o The IODEF-Document@version attribute is set to "2.0". o Attributes with enumerated values can now also be extended with IANA registries. o All iodef:MLStringType classes use xml:lang. IODEF-Document also uses xml:lang. o The Service@ip_protocol attribute was renamed to @ip-protocol. o The Node/NodeName class was removed in favor of representing domain names with Node/DomainData/Name class. The Node/DataTime class was also removed, so that the Node/DomainData/ DateDomainWasChecked class can represent the time at which the name-to-address resolution occurred. o The Node/NodeRole class was moved to System/NodeRole. o The Reference class is now defined by [RFC7495]. o The data previously represented in the Impact class is now in the SystemImpact and IncidentCategory classes. The Impact class has been removed. o The semantics of Counter@type are now represented in Counter@unit. o The IODEF-Document@formatid attribute has been renamed to @format- id. o The Incident/ReportTime class is no longer required. However, the GenerationTime class is required. o The Fax class was removed and is now represented by a generic Telephone class.
Top   ToC   RFC7970 - Page 114
   o  The Telephone, Email, and PostalAddress classes were redefined
      from improved internationalization.

   o  The "ipv6-net-mask" value was removed from the category attribute
      of Address.

5. Extending the IODEF

In order to support the dynamic nature of security operations, the IODEF data model will need to continue to evolve. This section discusses how new data elements can be incorporated into the IODEF. There is support to add additional enumerated values and new classes. Adding additional attributes to existing classes is not supported. These extension mechanisms are designed so that adding new data elements is possible without requiring modifications to this document. Extensions can be implemented publicly or privately. With proven value, well-documented extensions can be incorporated into future versions of the specification.

5.1. Extending the Enumerated Values of Attributes

Additional enumerated values can be added to select attributes either through the use of specially marked attributes with the "ext-" prefix or through a set of corresponding IANA registries. The former approach allows for the extension to remain private. The latter approach is public.

5.1.1. Private Extension of Enumerated Values

The data model supports adding new enumerated values to an attribute without public registration. For each attribute that supports this extension technique, there is a corresponding attribute in the same element whose name is identical but with a prefix of "ext-". This special attribute is referred to as the extension attribute. The attribute being extended is referred to as an extensible attribute. For example, an extensible attribute named "foo" will have a corresponding extension attribute named "ext-foo". An element may have many extensible attributes. In addition to a corresponding extension attribute, each extensible attribute has "ext-value" as one its possible enumerated values. Selection of this particular value in an extensible attribute signals that the extension attribute contains data. Otherwise, this "ext-value" value has no meaning.
Top   ToC   RFC7970 - Page 115
   In order to add a new enumerated value to an extensible attribute,
   the value of this attribute MUST be set to "ext-value", and the new
   desired value MUST be set in the corresponding extension attribute.
   For example, extending the type attribute of the SystemImpact class
   would look as follows:

    <SystemImpact type="ext-value" ext-type="new-attack-type">

   A given extension attribute MUST NOT be set unless the corresponding
   extensible attribute has been set to "ext-value".

5.1.2. Public Extension of Enumerated Values

The data model also supports publicly extending select enumerated attributes. A new entry can be added by registering a new entry in the appropriate IANA registry. Section 10.2 provides a mapping between the extensible attributes and their corresponding registry. Section 4.3 discusses the XML validation implications of this type of extension. All extensible attributes that support private extensions also support public extensions.

5.2. Extending Classes

Classes of the EXTENSION (iodef:ExtensionType) type can extend the data model. They provide the ability to have new atomic or XML- encoded data elements in all of the top-level classes of the Incident class and in a few of the complex subordinate classes. As there are multiple instances of the extensible classes in the data model, there is discretion on where to add a new data element. It is RECOMMENDED that the extension be placed in the most closely related class to the new information. Extensions using the atomic data types (i.e., all values of the dtype attributes other than "xml") MUST: 1. Set the element content to the desired value, and 2. Set the dtype attribute to correspond to the data type of the element content.
Top   ToC   RFC7970 - Page 116
   The following guidelines exist for extensions using XML (i.e.,
   dtype="xml"):

   1.  The element content of the extensible class MUST be set to the
       desired value, and the dtype attribute MUST be set to "xml".

   2.  The extension schema MUST declare a separate namespace.  It is
       RECOMMENDED that these extensions have the prefix "iodef-".  This
       recommendation makes readability of the document easier by
       allowing the reader to infer which namespaces relate to IODEF by
       inspection.

   3.  It is RECOMMENDED that extension schemas follow the naming
       convention of the IODEF data model.  This too improves the
       readability of extended IODEF documents.  The names of all
       elements SHOULD be capitalized.  For elements with composed
       names, a capital letter SHOULD be used for each word.  Attribute
       names SHOULD be in lowercase.  Attributes with composed names
       SHOULD be separated by a hyphen.

   4.  Implementations that encounter an unrecognized element,
       attribute, or attribute value in a supported namespace SHOULD
       reject the document as a syntax error.

   5.  There are security and performance implications in requiring
       implementations to dynamically download schemas at runtime.
       Therefore, implementations MUST NOT download schemas at runtime
       unless the appropriate precautions are taken.  Implementations
       also need to contend with the potential of significant network
       and processing issues.

   6.  Some adopters of the IODEF may have private schema definitions
       that are not publicly available.  Thus, implementations may
       encounter IODEF documents with references to private schemas that
       may not be resolvable.  Hence, IODEF document recipients MUST be
       prepared for a schema definition in an IODEF document never to
       resolve.
Top   ToC   RFC7970 - Page 117
   The following schema and XML document excerpt provide a template for
   an extension schema and its use in the IODEF document.

   This example schema defines a namespace of "iodef-extension1" and a
   single element named "newdata".

     <xs:schema
        targetNamespace="iodef-extension1.xsd"
        xmlns:iodef-extension1="iodef-extension1.xsd"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">
        attributeFormDefault="unqualified"
        elementFormDefault="qualified">
      <xs:import
           namespace="urn:ietf:params:xml:ns:iodef-2.0"
           schemaLocation=" urn:ietf:params:xml:schema:iodef-2.0"/>

        <xs:element name="newdata" type="xs:string" />
     </xs:schema>

   The following XML excerpt demonstrates the use of the above schema as
   an extension to the IODEF.

        <IODEF-Document
             version="2.00" lang="en-US"
             xmlns="urn:ietf:params:xml:ns:iodef-2.0"
             xmlns:iodef=" urn:ietf:params:xml:ns:iodef-2.0"
             xmlns:iodef-extension1="iodef-extension1.xsd"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="iodef-extension1.xsd">
            <Incident purpose="reporting">
            ...
              <AdditionalData dtype="xml" meaning="xml">
                <iodef-extension1:newdata>
                 Field that could not be represented elsewhere
                </iodef-extension1:newdata>
              </AdditionalData>
            </Incident>
      </IODEF-Document>

5.3. Deconflicting Private Extensions

To disambiguate which private extension is used in an IODEF document, the data model provides a means to identify the source of an extension. Two attributes in the IODEF-Document class, private-enum-name and private-enum-id, are used to specify this attribution. Only a single private extension can be identified in a given IODEF-Document.
Top   ToC   RFC7970 - Page 118
   If an implementor has a single private extension, then only the
   private-enum-name attribute needs to be specified.  Multiple distinct
   private extensions or versioning of a single extension can be
   attributed by also setting the corresponding private-num-id
   attribute.

   The following XML excerpt demonstrates the specification of a private
   extension from "example.com" with an identifier of "13".

        <IODEF-Document
             version="2.00" lang="en-US"
             private-enum-name="example.com"
             private-enum-id="13" ...>
            ...
      </IODEF-Document>

   If an unrecognized private extension is encountered in processing,
   the recipient MAY reject the entire document as a syntax error.

6. Internationalization Issues

Internationalization and localization is of specific concern to the IODEF as it facilitates operational coordination with a diverse set of partners. The IODEF implements internationalization by relying on XML constructs and through explicit design choices in the data model. Since the IODEF is implemented as an XML schema, it supports different character encodings, such as UTF-8 and UTF-16, that are possible with XML. Additionally, each IODEF document MUST specify the language in which its content is encoded. The language can be specified with the attribute "xml:lang" (per Section 2.12 of [W3C.XML]) in the top-level element (i.e., IODEF-Document) and lets all other elements inherit that definition. All IODEF classes with a free-form text definition (i.e., all those defined with type iodef:MLStringType) can also specify a language different from the rest of the document. The data model supports multiple translations of free-form text. All ML_STRING (iodef:MLStringType) classes have a one-to-many cardinality to their parent. This allows the identical text translated into different languages to be encoded in different instances of the same class with a common parent. This design also enables the creation of a single document containing all the translations. The IODEF implementation SHOULD extract the appropriate language relevant to the recipient.
Top   ToC   RFC7970 - Page 119
   Related instances of a given iodef:MLStringType class that are
   translations of each other are identified by a common identifier set
   in the translation-id attribute.  The example below shows three
   instances of a Description class expressed in three different
   languages.  The relationship between these three instances of the
   Description class is conveyed by the common value of "1" in the
   translation-id attribute.

   <IODEF-Document version="2.00" xml:lang="en" ...>
     <Incident purpose="reporting">
       ...
       <Description translation-id="1"
                    xml:lang="en">English</Description>
       <Description translation-id="1"
                    xml:lang="de">Englisch</Description>
       <Description translation-id="1"
                    xml:lang="fr">Anglais</Description>

   The IODEF balances internationalization support with the need for
   interoperability.  While the IODEF supports different languages, the
   data model also relies heavily on standardized enumerated attributes
   that can crudely approximate the contents of the document.  With this
   approach, a CSIRT should be able to make some sense of an IODEF
   document it receives even if the free-form text data elements are
   written in a language unfamiliar to the recipient.

7. Examples

This section provides examples of IODEF documents. These examples do not represent the full capabilities of the data model or the only way to encode particular information.

7.1. Minimal Example

A document containing only the mandatory elements and attributes. <?xml version="1.0" encoding="UTF-8"?> <!-- Minimum IODEF document --> <IODEF-Document version="2.00" xml:lang="en" xmlns="urn:ietf:params:xml:ns:iodef-2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.iana.org/assignments/xml-registry/schema/ iodef-2.0.xsd"> <Incident purpose="reporting" restriction="private"> <IncidentID name="csirt.example.com">492382</IncidentID> <GenerationTime>2015-07-18T09:00:00-05:00</GenerationTime> <Contact type="organization" role="creator">
Top   ToC   RFC7970 - Page 120
         <Email>
           <EmailTo>contact@csirt.example.com</EmailTo>
         </Email>
       </Contact>
       <!-- Add more fields to make the document useful -->
     </Incident>
   </IODEF-Document>

7.2. Indicators from a Campaign

An example of C2 domains from a given campaign. <?xml version="1.0" encoding="UTF-8"?> <!-- A list of C2 domains associated with a campaign --> <IODEF-Document version="2.00" xml:lang="en" xmlns="urn:ietf:params:xml:ns:iodef-2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.iana.org/assignments/xml-registry/schema/ iodef-2.0.xsd"> <Incident purpose="watch" restriction="green"> <IncidentID name="csirt.example.com">897923</IncidentID> <RelatedActivity> <ThreatActor> <ThreatActorID> TA-12-AGGRESSIVE-BUTTERFLY </ThreatActorID> <Description>Aggressive Butterfly</Description> </ThreatActor> <Campaign> <CampaignID>C-2015-59405</CampaignID> <Description>Orange Giraffe</Description> </Campaign> </RelatedActivity> <GenerationTime>2015-10-02T11:18:00-05:00</GenerationTime> <Description>Summarizes the Indicators of Compromise for the Orange Giraffe campaign of the Aggressive Butterfly crime gang. </Description> <Assessment> <BusinessImpact type="breach-proprietary"/> </Assessment> <Contact type="organization" role="creator"> <ContactName>CSIRT for example.com</ContactName> <Email> <EmailTo>contact@csirt.example.com</EmailTo> </Email> </Contact>
Top   ToC   RFC7970 - Page 121
         <IndicatorData>
           <Indicator>
             <IndicatorID name="csirt.example.com" version="1">
             G90823490
             </IndicatorID>
             <Description>C2 domains</Description>
             <StartTime>2014-12-02T11:18:00-05:00</StartTime>
             <Observable>
               <BulkObservable type="fqdn">
               <BulkObservableList>
                 kj290023j09r34.example.com
                 09ijk23jfj0k8.example.net
                 klknjwfjiowjefr923.example.org
                 oimireik79msd.example.org
               </BulkObservableList>
             </BulkObservable>
           </Observable>
         </Indicator>
       </IndicatorData>
     </Incident>
   </IODEF-Document>



(page 121 continued on part 7)

Next Section