Tech-invite3GPPspecsGlossariesIETFRFCsGroupsSIPABNFsWorld Map

RFC 7970

 
 
 

The Incident Object Description Exchange Format Version 2

Part 6 of 9, p. 96 to 121
Prev Section       Next Section

 


prevText      Top      ToC       Page 96 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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