RFC 7970
The Incident Object Description Exchange Format Version 2
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.
+------------------------+ | 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.
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.
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.
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.
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.
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.
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.
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").
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.
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.
+--------------------------+ | 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.
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
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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">
<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>
<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)
