From e5daec916b359fd3fb2873983dbf0ab590b43a2a Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Thu, 8 Feb 2024 15:25:29 -0500 Subject: [PATCH 01/15] incorporate some of Dez's edits --- .../Incident Extension Suite.adoc | 80 +++++++++++++------ 1 file changed, 56 insertions(+), 24 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 566c3412d9e..c647c36535a 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -40,11 +40,11 @@ :threat_actor_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_k017w16zutw :tool_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_z4voa9ndw8v -= [stixtitle]*Incident Core Extension Version 2.0 for STIX^TM^ Version 2.1* += [stixtitle]*Incident Core Extension Version 2.1 for STIX^TM^ Version 2.1* [.stix-doc-information-heading]#Draft# -[.stix-doc-information-heading]#10 October 2023# +[.stix-doc-information-heading]#10 October 20238 February 2024# [.stix-doc-information-heading] Editors: @@ -95,7 +95,7 @@ The Incident object should have sufficient properties to represent the current s === 2.1. Incident Core -The properties and additional types within the Incident Core Extension are defined below. As this is an extension of a top-level object, fields such as identifier are not present. This extension *MUST* use [stixliteral]#extension-definition--ef765651-680c-498d-9894-99799f2fa126# as its extension ID. +The properties and additional types within the Incident Core Extension are defined below. As this is an extension of a top-level object, common properties such as *id* are not present. This extension *MUST* use [stixliteral]#extension-definition--ef765651-680c-498d-9894-99799f2fa126# as its extension ID. <<< @@ -107,11 +107,11 @@ The properties and additional types within the Incident Core Extension are defin |*determination* (required) |[stixtype]#<># -|A high level determination on the outcome of this incident. +|A high-level determination on the status of this incident. The value of this property *SHOULD* be [stixliteral]#suspected# until enough information is available to provide a well researched result. -Some automated tools may flag results as blocked or low-value automatically depending on the tool type or activity. -A tool that blocks a series of phishing emails may create an incident with a blocked determination automatically. +Some automated tools may flag results as "blocked" or "low-value" automatically depending on the tool type or activity. +For example, a tool that blocks a series of phishing emails may create an incident with a [stixliteral]#blocked# determination automatically. The values of this property *MUST* come from the [stixtype]#<># enumeration. @@ -139,7 +139,7 @@ These values *SHOULD* be selected from the [stixtype]#<># -|A list of events tied to this incident. +|A list of events (as a list of [stixtype]#<>#) tied to this incident. |*impact_refs* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{identifier_url}[identifier]# @@ -148,11 +148,11 @@ All objects referenced in this list *MUST* be of type [stixtype]#<># -|An optional listing of the entity types that were impacted by the incident, and how many of each type were affected. -Individual impacts may also record more detailed counts as appropriate. +|An listing of the entity types that were impacted by the incident, and how many of each type were affected. +Individual impacts objects may also record more detailed counts as appropriate. If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. -To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to [stixliteral]#0#. +To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to 0. |*incident_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# @@ -173,7 +173,41 @@ enumeration. |*tasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of tasks tied to this incident. +|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. + +|*impact_refs* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#{identifier_url}[identifier]# +|A list of impacts of this incident. +All objects referenced in this list *MUST* be of type [stixtype]#<># + +|*impacted_entity_counts* (optional) +|[stixtype]#<># +|An listing of the entity types that were impacted by the incident, and how many of each type were affected. +Individual impacts objects may also record more detailed counts as appropriate. + +If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. +To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to 0. + +|*incident_types* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# +|This property uses an Open Vocabulary that specifies the type of incident that occurred, if applicable. + +The values of this property *SHOULD* come from the [stixtype]#<># open vocabulary. + +|*recoverability* (optional) +|[stixtype]#<># +|The recoverability of this particular Incident with respect to feasibility and required time and resources. + +The value of this property *MUST* come from the [stixtype]#<># +enumeration. + +|*scores* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#<># +|A list of scores from various automated or manual mechanisms along with optional descriptions. + +|*tasks* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#<># +|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. |=== @@ -265,7 +299,7 @@ include::examples/example_2.1.json[] [[event]] === 2.2. Event -An Event is an activity that takes place during an attack attributed to the attacker. +An Event is an activity attributed to the attacker. This new sdo extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. @@ -347,11 +381,11 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. |*event_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# -|High level types for the event in order to enable aggregation and summaries. +|High level types for the event to enable aggregation and summarization. The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. @@ -384,12 +418,11 @@ This property *SHOULD* be populated. |The level of fidelity that the start_time is recorded in. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be -accurate up to the number of decimals it includes. +If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. |*subevents* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of sub-events tied to this event. +|A list of sub-events (as a list of [stixtype]#<>#) tied to this event. |=== <<< @@ -557,6 +590,8 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. +If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. + |*impacted_entity_counts* (optional) |[stixtype]#<># |An optional listing of the entity types that were impacted and how many of each were affected. @@ -585,8 +620,7 @@ This property *SHOULD* be populated. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be -accurate up to the number of decimals it includes. +If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. |*superseded_by_ref* (optional) |[stixtype]#{identifier_url}[identifier]# @@ -893,7 +927,7 @@ include::examples/example_2.3.2.7.1.json[] [[task]] === 2.4. Task -An Task is an activity that is performed by the victim to respond to the attack. +A Task is an activity that is performed by the victim to respond to the attack. This new sdo extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. @@ -982,8 +1016,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be -accurate up to the number of decimals it includes. +If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. |*error* (optional) |[stixtype]#{string_url}[string]# @@ -1017,8 +1050,7 @@ This property *SHOULD* be populated. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be -accurate up to the number of decimals it includes. +If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. |*subtasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># From 10b6a36760e6d35aa232dac57fc6a23bb5a78f26 Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Thu, 8 Feb 2024 15:27:30 -0500 Subject: [PATCH 02/15] Update Incident Extension Suite.adoc fixed date --- .../incident-ef7/Incident Extension Suite.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index c647c36535a..422710979e1 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -44,7 +44,7 @@ [.stix-doc-information-heading]#Draft# -[.stix-doc-information-heading]#10 October 20238 February 2024# +[.stix-doc-information-heading]#8 February 2024# [.stix-doc-information-heading] Editors: From d243b26cf6411dbeec64fb44e0ff986b5997c295 Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Fri, 9 Feb 2024 13:34:33 -0500 Subject: [PATCH 03/15] changes discussed in WG call 2/9 --- .../Incident Extension Suite.adoc | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 422710979e1..417201c0297 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -110,7 +110,7 @@ The properties and additional types within the Incident Core Extension are defin |A high-level determination on the status of this incident. The value of this property *SHOULD* be [stixliteral]#suspected# until enough information is available to provide a well researched result. -Some automated tools may flag results as "blocked" or "low-value" automatically depending on the tool type or activity. +Some automated tools may flag results as [stixliteral]#blocked# or [stixliteral]#low-value# automatically depending on the tool type or activity. For example, a tool that blocks a series of phishing emails may create an incident with a [stixliteral]#blocked# determination automatically. The values of this property *MUST* come from the [stixtype]#<># enumeration. @@ -123,7 +123,7 @@ The values of this property *MUST* come from the [stixtype]#<># open vocabulary. +The values of this property *SHOULD* come from the [stixtype]#<># open vocabulary. |*criticality* (optional) |[stixtype]#{int_url}[integer]# @@ -299,7 +299,7 @@ include::examples/example_2.1.json[] [[event]] === 2.2. Event -An Event is an activity attributed to the attacker. +An Event is an activity that has a harmful effect on the defender/victim. This new sdo extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. @@ -381,7 +381,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*event_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# @@ -418,7 +418,7 @@ This property *SHOULD* be populated. |The level of fidelity that the start_time is recorded in. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*subevents* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># @@ -590,7 +590,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*impacted_entity_counts* (optional) |[stixtype]#<># @@ -620,7 +620,7 @@ This property *SHOULD* be populated. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*superseded_by_ref* (optional) |[stixtype]#{identifier_url}[identifier]# @@ -642,10 +642,10 @@ It also *MUST* reference an [stixtype]#<># of the same as the *im ==== 2.3.2. Extensions The Impact SDO is currently an extension, but as there are many specific types of impacts with their own unique properties it emulates the File SCO through the use of STIX Extensions to provide the granular details of specific categories of impacts. -As such every Impact *MUST* have one and only one extension which has the same value as the *impact_category* property (see this property description above). +As such every Impact *MUST* have the one extension which has the same value as the *impact_category* property (see this property description above). This allows consumers to quickly validate their ability to process this category of impact and then load all of its specific details. -Producers *SHOULD* use one of these extensions. +Because these extensions are used to specify very different types of impacts, producers *SHOULD* use one and only one of these extensions. However, additional extensions might be proposed in the future and might be used in conjunction with one of these. ===== 2.3.2.1. Availability Impact Extension @@ -927,7 +927,7 @@ include::examples/example_2.3.2.7.1.json[] [[task]] === 2.4. Task -A Task is an activity that is performed by the victim to respond to the attack. +A Task is an activity that is performed by the victim/defender to respond to the attack. This new sdo extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. @@ -1016,7 +1016,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *end_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*error* (optional) |[stixtype]#{string_url}[string]# @@ -1050,7 +1050,7 @@ This property *SHOULD* be populated. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided for this property, the *start_time* should be considered to be accurate to the smallest unit specified with a non-zero value in the timestamp. +If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. |*subtasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># From fcb3b3f11456119c33fa573a9a547c718345ac7b Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Fri, 9 Feb 2024 15:23:41 -0500 Subject: [PATCH 04/15] more Dez edits --- .../Incident Extension Suite.adoc | 56 ++++++++++--------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 417201c0297..5b62c2eed72 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -373,7 +373,7 @@ This is typically used to indicate how an event has affected impacts. |[stixtype]#{timestamp_url}[timestamp]# |The date and time the event was last recorded. If this is not present it is assumed to be unknown. -If *start_time* and *end_time* properties are both defined, then *end_time* value *MUST* be later than the *start_time* value. +If *start_time* and *end_time* properties are both defined, then *end_time* value *MUST* be the same or later than the *start_time* value. |*end_time_fidelity* (optional) |[stixtype]#<># @@ -381,7 +381,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*event_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# @@ -396,11 +396,11 @@ Not all events have goals. |*name* (optional) |[stixtype]#{string_url}[string]# -|An optional name for the event. +|A name for the event. |*sighting_refs* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{identifier_url}[identifier]# -|An optional list of [stixtype]#{sighting_url}[sighting]# objects that were related to this event. +|A list of [stixtype]#{sighting_url}[sighting]# objects that were related to this event. Sightings referenced in this *SHOULD* be based on [stixtype]#{attack_pattern_url}[attack-pattern]#, [stixtype]#{indicator_url}[indicator]#, or [stixtype]#{malware_url}[malware]# SDOs. In some cases observed data may be present, but no [stixtype]#{indicator_url}[indicator]# can be created. @@ -418,7 +418,7 @@ This property *SHOULD* be populated. |The level of fidelity that the start_time is recorded in. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*subevents* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># @@ -508,7 +508,7 @@ include::examples/example_2.2.json[] [[impact]] === 2.3. Impact -An Impact is the result of an attack to the victim. Impacts can have many facets: availability of resources, confidentiality of data, integrety of data or resources, monetary, physical damage, damage to others and traceability (auditing). +An Impact is the result of an attack to the victim. Impacts can have many catgories: availability of resources, confidentiality of data, integrity of data or resources, monetary, physical damage, damage to others and traceability (auditing). This new sdo extension *MUST* use [stixliteral]#extension-definition--7cc33dd6-f6a1-489b-98ea-522d351d71b9# as its extension ID. @@ -551,6 +551,7 @@ As a new sdo extension it must follow the requirements as described in section 7 *recoverability*, *start_time*, *start_time_fidelity*, +*superseded_by_ref* |=== |=== @@ -558,7 +559,7 @@ As a new sdo extension it must follow the requirements as described in section 7 |*impact_category* (required) |[stixtype]#{string_url}[string]# -|The category of impact this applies to. +|The category of impact this object applies to. This *MUST* match an extension that provides greater details of a specific type of impact, and *SHOULD* come from the extensions listed in section 2.3.2 of this document. The value can be specified with or without the "-ext" suffix. |*type* (required) @@ -578,11 +579,11 @@ This can be translated into qualitative values as described in <># @@ -590,11 +591,11 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*impacted_entity_counts* (optional) |[stixtype]#<># -|An optional listing of the entity types that were impacted and how many of each were affected. +|A listing of the entity types that were impacted and how many of each were affected. If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. @@ -610,7 +611,7 @@ The value of this property *MUST* come from the [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*superseded_by_ref* (optional) |[stixtype]#{identifier_url}[identifier]# |The referenced [stixtype]#<># supersedes this one at the *end_time* for the current impact. This allows capturing how the severity of this impact changes over time. -When populated the impact *MUST* have an *end_time*. -It also *MUST* reference an [stixtype]#<># of the same as the *impact_category* property. +When populated this impact *MUST* have an *end_time*. +It also *MUST* reference an [stixtype]#<># of the same as the category specified in the *impact_category* property. |=== @@ -637,12 +638,17 @@ It also *MUST* reference an [stixtype]#<># of the same as the *im ==== 2.3.1. Relationships // tag::impact-relationships[] +There are no relationships explicitly defined between the Impact object and other STIX +Objects, other than those defined as common relationships ([stixrelationship]#duplicate-of#, [stixrelationship]#derived-from#, [stixrelationship]#related-to#, and the embedded relationships defined by the common SDO properties. + +Relationships can be created between any objects +using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. // end::impact-relationships[] ==== 2.3.2. Extensions The Impact SDO is currently an extension, but as there are many specific types of impacts with their own unique properties it emulates the File SCO through the use of STIX Extensions to provide the granular details of specific categories of impacts. -As such every Impact *MUST* have the one extension which has the same value as the *impact_category* property (see this property description above). +As such every Impact *MUST* have the one extension which matches the value of the *impact_category* property (see this property description above). This allows consumers to quickly validate their ability to process this category of impact and then load all of its specific details. Because these extensions are used to specify very different types of impacts, producers *SHOULD* use one and only one of these extensions. However, additional extensions might be proposed in the future and might be used in conjunction with one of these. @@ -660,7 +666,7 @@ Because these extensions are used to specify very different types of impacts, pr |*availability_impact* (required) |[stixtype]#{int_url}[integer]# |The availability / functional impact of the incident on the objects referenced in *impacted_refs*. -If no objects are referenced it should be treated as the overall availability impact for the [stixtype]#{incident_url}[incident]# that references it. +If no objects are referenced, the impact should be treated as the overall availability impact for the [stixtype]#{incident_url}[incident]# that references it. This value *MUST* be between 0 to 100. This can be translated into qualitative values as described in <>. @@ -927,7 +933,7 @@ include::examples/example_2.3.2.7.1.json[] [[task]] === 2.4. Task -A Task is an activity that is performed by the victim/defender to respond to the attack. +A Task is an activity that is performed by or for the victim/defender to respond to the attack. This new sdo extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. @@ -1002,7 +1008,7 @@ The values of this property *SHOULD* come from the [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*error* (optional) |[stixtype]#{string_url}[string]# @@ -1024,13 +1030,13 @@ If no value is provided the timestamp should be considered to be accurate up to |*impacted_entity_counts* (optional) |[stixtype]#<># -|An optional listing of the entity types that were impacted and how many of each were affected. +|A listing of the entity types that were impacted and how many of each were affected. This is primarily used when recording victim notifications. |*name* (optional) |[stixtype]#{string_url}[string]# -|An optional name used to identify the task. +|A name used to identify the task. |*priority* (optional) |[stixtype]#{int_url}[integer]# @@ -1050,7 +1056,7 @@ This property *SHOULD* be populated. This value *MUST* come from [stixtype]#<># enumeration. -If no value is provided the timestamp should be considered to be accurate up to the number of decimals it includes. +If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*subtasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># @@ -1319,7 +1325,7 @@ include::examples/example_3.3.json[] |*description* (optional) |[stixtype]#{string_url}[string]# -|An optional description about how this score was calculated for systems that provide this information. +|A description about how this score was calculated for systems that provide this information. |=== <<< From 2e92368d65425e9f049d7da65e4a439cda951a31 Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Mon, 12 Feb 2024 09:15:38 -0500 Subject: [PATCH 05/15] more Dez edits 2 --- .../incident-ef7/Incident Extension Suite.adoc | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 5b62c2eed72..5e88b3f1305 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -73,15 +73,15 @@ toc::[] [.stix-doc-information-heading]*Abstract:* -The current STIX 2.1 Incident object exists as a stub in the hopes that future work would allow STIX Incidents to be more fully fleshed out using extensions, and that in time a set of core features could be defined to be migrated into a future version of the Incident object or the community could arrive at the consensus to continue to use these extensions. +The current STIX 2.1 Incident object was defined as a stub with the expectation that it would be fleshed out using extensions, and that in time either a set of core features would be integrated into a future version of the STIX or that the community would arrive at the consensus to continue to use these extensions. -In the 1.0 version of the core incident extension information on impact, events, and tasks were embedded within the Incident itself, however this was found to have limitations. -As such a 2.0 version of this extension has been created in order to separate these components into independent SDOs for more complex incidents to be accurately modeled. +In the 1.0 version of the core incident extension, information on impact, events, and tasks were embedded within the Incident object itself, however this was found to have limitations. +Therefore, the 2.0 version of this extension has been created in which these components have been separated into independent SDOs for more complex incidents to be accurately modeled. -These extensions allow tracking incidents across their life cycle where Events are first flagged for investigation resulting in [stixtype]#{incident_url}[incidents]# with [stixtype]#<># being worked to resolve these. +These extensions allow incidents to be tracked across their life cycle where [stixtype]#<># are first flagged for investigation resulting in [stixtype]#{incident_url}[incidents]# with [stixtype]#<># being worked to resolve them. Incidents have [stixtype]#<># that change over time. -[stixtype]#<># can cause or influence these [stixtype]#<># which are in turn mitigated and potentially resolved by [stixtype]#<># performed as part of the incident response process. -Both [stixtype]#<># and [stixtype]#<># can exist independent of [stixtype]#{incident_url}[incidents]# and in most workflows will occur prior to an incident being declared. +[stixtype]#<># can cause or influence these [stixtype]#<># which are in turn mitigated and potentially resolved by [stixtype]#<># performed as part of the incident response process. +Both [stixtype]#<># and [stixtype]#<># can exist independently of [stixtype]#{incident_url}[incidents]# and in most workflows will occur prior to an incident being declared. == 1. Incidents in STIX @@ -299,7 +299,7 @@ include::examples/example_2.1.json[] [[event]] === 2.2. Event -An Event is an activity that has a harmful effect on the defender/victim. +An Event is an activity that has a harmful effect or which will be investigated or already has been investigated as potentially having a harmful effect. Events can be used to further enrich and explain Sightings by allowing analysts to indicate if these are part of a potential threat, and if so how it connects to a larger incident. This new sdo extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. @@ -2906,4 +2906,8 @@ Added [stixliteral]#ransom-demand# and [stixliteral]#ransom-payment# to [stixtyp |Richard Piazza and Jeffrey Mates |Multiple editorial fixes, removing copy paste errors and obsolete relationships. +|06 +|2024-02-15 +|Richard Piazza, Jeffrey Mates and Dez Beck +|Additional editorial fixes, a minor changes to normative statements |=== From fa6e69121e3df90679c479df99b0834986ed7ffd Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Mon, 12 Feb 2024 09:17:38 -0500 Subject: [PATCH 06/15] syntax error --- .../incident-ef7/Incident Extension Suite.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 5e88b3f1305..2af9e34b089 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -78,7 +78,7 @@ The current STIX 2.1 Incident object was defined as a stub with the expectation In the 1.0 version of the core incident extension, information on impact, events, and tasks were embedded within the Incident object itself, however this was found to have limitations. Therefore, the 2.0 version of this extension has been created in which these components have been separated into independent SDOs for more complex incidents to be accurately modeled. -These extensions allow incidents to be tracked across their life cycle where [stixtype]#<># are first flagged for investigation resulting in [stixtype]#{incident_url}[incidents]# with [stixtype]#<># being worked to resolve them. +These extensions allow incidents to be tracked across their life cycle where [stixtype]#<>#s are first flagged for investigation resulting in [stixtype]#{incident_url}[incidents]# with [stixtype]#<># being worked to resolve them. Incidents have [stixtype]#<># that change over time. [stixtype]#<># can cause or influence these [stixtype]#<># which are in turn mitigated and potentially resolved by [stixtype]#<># performed as part of the incident response process. Both [stixtype]#<># and [stixtype]#<># can exist independently of [stixtype]#{incident_url}[incidents]# and in most workflows will occur prior to an incident being declared. From 43f9d447d887f2965a9f7004d68a707a7e931677 Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Mon, 12 Feb 2024 09:59:06 -0500 Subject: [PATCH 07/15] add to Event intro paragraph --- .../incident-ef7/Incident Extension Suite.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 2af9e34b089..35f62d5095f 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -299,7 +299,7 @@ include::examples/example_2.1.json[] [[event]] === 2.2. Event -An Event is an activity that has a harmful effect or which will be investigated or already has been investigated as potentially having a harmful effect. Events can be used to further enrich and explain Sightings by allowing analysts to indicate if these are part of a potential threat, and if so how it connects to a larger incident. +An Event is an activity that has a harmful effect or which will be investigated or already has been investigated as potentially having a harmful effect. Events can be used to further enrich and explain Sightings by allowing analysts to indicate if these are part of a potential threat, and if so how it connects to a larger incident. Some activity, described in an Event, will be found to be not harmful when investigated. This new sdo extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. From aad606c676454874d4f26516cb13abb570a36bba Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Tue, 13 Feb 2024 16:25:01 -0500 Subject: [PATCH 08/15] dez edits 3 --- .../Incident Extension Suite.adoc | 146 +++++++----------- 1 file changed, 58 insertions(+), 88 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 35f62d5095f..227962532a7 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -78,7 +78,7 @@ The current STIX 2.1 Incident object was defined as a stub with the expectation In the 1.0 version of the core incident extension, information on impact, events, and tasks were embedded within the Incident object itself, however this was found to have limitations. Therefore, the 2.0 version of this extension has been created in which these components have been separated into independent SDOs for more complex incidents to be accurately modeled. -These extensions allow incidents to be tracked across their life cycle where [stixtype]#<>#s are first flagged for investigation resulting in [stixtype]#{incident_url}[incidents]# with [stixtype]#<># being worked to resolve them. +These extensions allow incidents to be tracked across their life cycle where [stixtype]#<># are first flagged for investigation resulting in [stixtype]#incidents# with [stixtype]#<># being worked to resolve them. Incidents have [stixtype]#<># that change over time. [stixtype]#<># can cause or influence these [stixtype]#<># which are in turn mitigated and potentially resolved by [stixtype]#<># performed as part of the incident response process. Both [stixtype]#<># and [stixtype]#<># can exist independently of [stixtype]#{incident_url}[incidents]# and in most workflows will occur prior to an incident being declared. @@ -129,11 +129,11 @@ The values of this property *SHOULD* come from the [stixtype]#<>. +If present, this value *MUST* be between 0 to 100. This can be translated into qualitative values as described in <>. |*detection_methods* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# -|A list of strings containing what was used to detect the activity, e.g., commercial tool names, techniques associated with proprietary solutions, human review, external sources, or other methods. +|A list of strings corresponding to the methods used to detect the activity, e.g., commercial tool names, techniques associated with proprietary solutions, human review, external sources, or other methods. These values *SHOULD* be selected from the [stixtype]#<># open vocabulary. @@ -144,53 +144,20 @@ These values *SHOULD* be selected from the [stixtype]#<># +All objects referenced in this list *MUST* be an [stixtype]#<># object. |*impacted_entity_counts* (optional) |[stixtype]#<># -|An listing of the entity types that were impacted by the incident, and how many of each type were affected. +|A listing of the entity types that were impacted by the incident, and how many of each type were affected. Individual impacts objects may also record more detailed counts as appropriate. If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. -To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to 0. - -|*incident_types* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# -|This property uses an Open Vocabulary that specifies the type of incident that occurred, if applicable. - -The values of this property *SHOULD* come from the [stixtype]#<># open vocabulary. - -|*recoverability* (optional) -|[stixtype]#<># -|The recoverability of this particular Incident with respect to feasibility and required time and resources. - -The value of this property *MUST* come from the [stixtype]#<># -enumeration. - -|*scores* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of scores from various automated or manual mechanisms along with optional descriptions. -|*tasks* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. - -|*impact_refs* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#{identifier_url}[identifier]# -|A list of impacts of this incident. -All objects referenced in this list *MUST* be of type [stixtype]#<># - -|*impacted_entity_counts* (optional) -|[stixtype]#<># -|An listing of the entity types that were impacted by the incident, and how many of each type were affected. -Individual impacts objects may also record more detailed counts as appropriate. - -If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to 0. |*incident_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# -|This property uses an Open Vocabulary that specifies the type of incident that occurred, if applicable. +|A list of incident types of incident that occurred, if applicable. The values of this property *SHOULD* come from the [stixtype]#<># open vocabulary. @@ -207,7 +174,7 @@ enumeration. |*tasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. +|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. |=== @@ -217,12 +184,14 @@ enumeration. These are the relationships explicitly defined between the Incident object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. For their -definitions, please see the "Source" object. +targeting this object type from another object type. They are included here for convenience. See the +forward relationship for the definition. Relationships are not restricted to those listed below. Relationships can be created between any objects -using the related-to relationship type or, as with open vocabularies, user-defined names. Because of this, some of these -relationships can be used independent of explicitly using this extension. +using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. + +Because of this, +these relationships can be used with the Incident object as defined in the STIX 2.1 specification. [width="100%",cols="24%,23%,20%,33%",options="header",] @@ -246,7 +215,7 @@ relationships can be used independent of explicitly using this extension. |[stixrelationship]#impacts# |[stixtype]#{identity_url}[identity]#, + [stixtype]#{infrastructure_url}[infrastructure]# -|An incident has an impact on the victim or specific infrastructure. +|The incident has an impact on the victim or specific infrastructure. |[stixtype]#{incident_url}[incident]# |[stixrelationship]#attributed-to# @@ -258,24 +227,24 @@ relationships can be used independent of explicitly using this extension. |[stixrelationship]#targets# |[stixtype]#{identity_url}[identity]#, + [stixtype]#{infrastructure_url}[infrastructure]# -|An incident was targeted at the victim or specific infrastructure. +|The incident targets the identity or infrastructure. |[stixtype]#{incident_url}[incident]# |[stixrelationship]#located-at# |[stixtype]#{location_url}[location]# -|The incident occurred at a specific location or locations. +|The incident occurred at a specific location. // relationships:end 4+^|*Reverse Relationships* // relationships:start |[stixtype]#{campaign_url}[campaign]# |[stixrelationship]#associated-with# |[stixtype]#{incident_url}[incident]# -|The incident in question is part of the campaign that is associated with. +|The incident is associated with the campaign. |[stixtype]#{identity_url}[identity]# |[stixrelationship]#contact-for# |[stixtype]#{incident_url}[incident]# -|An identity should be considered a point of contact for an incident. +|The identity should be considered a point of contact for an incident. This relationship is different from the *created_by_ref* property, which is the creator of the STIX Incident object. Additionally, this can be used to supplement the *created_by_ref* property in cases where external authorship would prevent using it for this purpose. @@ -283,12 +252,12 @@ Additionally, this can be used to supplement the *created_by_ref* property in ca |[stixtype]#{indicator_url}[indicator]# |[stixrelationship]#detected# |[stixtype]#{incident_url}[incident]# -|An indicator was responsible for detecting the incident. +|The indicator detected the incident. // relationships:end |=== // end::incident-relationships[] -==== 2.1.1 Example +==== 2.1.2 Example [source,json] ---- @@ -299,11 +268,11 @@ include::examples/example_2.1.json[] [[event]] === 2.2. Event -An Event is an activity that has a harmful effect or which will be investigated or already has been investigated as potentially having a harmful effect. Events can be used to further enrich and explain Sightings by allowing analysts to indicate if these are part of a potential threat, and if so how it connects to a larger incident. Some activity, described in an Event, will be found to be not harmful when investigated. +An Event is an activity that has a harmful effect or which will be investigated or already has been investigated as potentially having a harmful effect. Events can be used to further enrich and explain Sightings by allowing analysts to indicate if these sightings are part of a potential threat, and if so how they connects to a larger incident. Some activity, described in an Event, will be found to be not harmful when investigated. -This new sdo extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. +This new SDO extension *MUST* use [stixliteral]#extension-definition--4ca6de00-5b0d-45ef-a1dc-ea7279ea910e# as its extension ID. -As a new sdo extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. +As a new SDO extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. [width="100%",cols="100%",stripes=odd] |=== @@ -377,7 +346,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu |*end_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the end_time is recorded in. +|The level of fidelity that the *end_time* property is recorded in. This value *MUST* come from [stixtype]#<># enumeration. @@ -415,14 +384,14 @@ This property *SHOULD* be populated. |*start_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the start_time is recorded in. This value +|The level of fidelity that the *start_time* property is recorded in. This value *MUST* come from [stixtype]#<># enumeration. If no value is provided the timestamp should be considered to be accurate up to the number of decimal digits it includes. |*subevents* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of sub-events (as a list of [stixtype]#<>#) tied to this event. +|A list of sub-events (as a list of [stixtype]#<>#) related to this event. |=== <<< @@ -434,11 +403,11 @@ If no value is provided the timestamp should be considered to be accurate up to These are the relationships explicitly defined between the Event object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. For their -definitions, please see the "Source" object. +targeting this object type from another object type. They are included here for convenience. See the +forward relationship for the definition. Relationships are not restricted to those listed below. Relationships can be created between any objects -using the related-to relationship type or, as with open vocabularies, user-defined names. +using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. [width="100%",cols="23%,20%,24%,33%",options="header",] |=== @@ -454,18 +423,18 @@ using the related-to relationship type or, as with open vocabularies, user-defin |[stixtype]#<># |One event led to another. -For example, a dropper running allowed a ransomware tool to be downloaded and run. +For example, a dropper running led to a ransomware tool to be downloaded and run. |[stixtype]#<># |[stixrelationship]#impacts# |[stixtype]#{infrastructure_url}[infrastructure]#, + - -|An event has an impact on specific infrastructure. +[stixtype]#[]# +|An event has an impact on specific infrastructure. While not all SCO types will make sense in this relationship, allowing any type of SCO prevents artificially restricting what could be used. |[stixtype]#<># |[stixrelationship]#located-at# |[stixtype]#{location_url}[location]# -|The event occurred at a specific location or locations. +|The event occurred at a specific location. // relationships:end |=== @@ -508,11 +477,11 @@ include::examples/example_2.2.json[] [[impact]] === 2.3. Impact -An Impact is the result of an attack to the victim. Impacts can have many catgories: availability of resources, confidentiality of data, integrity of data or resources, monetary, physical damage, damage to others and traceability (auditing). +An Impact is the result of the Incident on the victim, captured in the *impact_ref* property of the Incident object. Impacts can have many categories: availability of resources, confidentiality of data, integrity of data or resources, monetary, physical damage, damage to others and traceability (auditing). -This new sdo extension *MUST* use [stixliteral]#extension-definition--7cc33dd6-f6a1-489b-98ea-522d351d71b9# as its extension ID. +This new SDO extension *MUST* use [stixliteral]#extension-definition--7cc33dd6-f6a1-489b-98ea-522d351d71b9# as its extension ID. -As a new sdo extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. +As a new SDO extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. [width="100%",cols="100%",stripes=odd] |=== @@ -559,7 +528,7 @@ As a new sdo extension it must follow the requirements as described in section 7 |*impact_category* (required) |[stixtype]#{string_url}[string]# -|The category of impact this object applies to. +|The category to which the impact belongs. This *MUST* match an extension that provides greater details of a specific type of impact, and *SHOULD* come from the extensions listed in section 2.3.2 of this document. The value can be specified with or without the "-ext" suffix. |*type* (required) @@ -568,7 +537,7 @@ This *MUST* match an extension that provides greater details of a specific type |*criticality* (optional) |[stixtype]#{int_url}[integer]# -|The criticality of this impact. This value *MUST* be between 0 to 100. +|The criticality of this impact. If present, this value *MUST* be between 0 to 100. This can be translated into qualitative values as described in <>. |*description* (optional) @@ -587,7 +556,7 @@ If the *superseded_by_ref* property is included this *MUST* be included. |*end_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the end_time is recorded in. +|The level of fidelity that the *end_time* property is recorded in. This value *MUST* come from [stixtype]#<># enumeration. @@ -599,9 +568,11 @@ If no value is provided the timestamp should be considered to be accurate up to If this property is not present it should be assumed that this information is not being shared, not that there were no impacted entities. +To affirmatively state no entities of a given class were impacted they should be included with the number of entities affected by it set to 0. + |*impacted_refs* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{identifier_url}[identifier]# -|A list of all impacted entities or infrastructure. This can relate directly to Infrastructure, SCOs, and other SDOs. +|A list of all impacted entities or infrastructure. The values of this property MUST be the identifier for a SDO or SCO. |*recoverability* (optional) |[stixtype]#<># @@ -617,7 +588,7 @@ This property *SHOULD* be populated. |*start_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the start_time is recorded in. +|The level of fidelity that the *start_time* property is recorded in. This value *MUST* come from [stixtype]#<># enumeration. @@ -625,11 +596,10 @@ If no value is provided the timestamp should be considered to be accurate up to |*superseded_by_ref* (optional) |[stixtype]#{identifier_url}[identifier]# -|The referenced [stixtype]#<># supersedes this one at the *end_time* for the current impact. +|The referenced [stixtype]#<># supersedes the *end_time* for the current impact. This allows capturing how the severity of this impact changes over time. -When populated this impact *MUST* have an *end_time*. -It also *MUST* reference an [stixtype]#<># of the same as the category specified in the *impact_category* property. +When this property is populated this impact *MUST* have an *end_time* and and the *superseded_by_ref* value *MUST* reference an [stixtype]#<># of the same as the category specified in the *impact_category* property. |=== @@ -639,7 +609,7 @@ It also *MUST* reference an [stixtype]#<># of the same as the cat // tag::impact-relationships[] There are no relationships explicitly defined between the Impact object and other STIX -Objects, other than those defined as common relationships ([stixrelationship]#duplicate-of#, [stixrelationship]#derived-from#, [stixrelationship]#related-to#, and the embedded relationships defined by the common SDO properties. +Objects, other than those defined as common relationships ([stixrelationship]#duplicate-of#, [stixrelationship]#derived-from#, [stixrelationship]#related-to#, and the embedded relationships defined by the common SDO properties.) Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. @@ -647,8 +617,8 @@ using the [stixrelationship]#related-to# relationship type or, as with open voca ==== 2.3.2. Extensions -The Impact SDO is currently an extension, but as there are many specific types of impacts with their own unique properties it emulates the File SCO through the use of STIX Extensions to provide the granular details of specific categories of impacts. -As such every Impact *MUST* have the one extension which matches the value of the *impact_category* property (see this property description above). +There are many types of impacts, each with its own unique properties, therefore the Impact SDO emulates the File SCO through the use of STIX (sub-type) Extensions to provide the granular details of specific categories of impacts. +As such, every Impact *MUST* have the one extension which matches the value of the *impact_category* property (see this property description above). This allows consumers to quickly validate their ability to process this category of impact and then load all of its specific details. Because these extensions are used to specify very different types of impacts, producers *SHOULD* use one and only one of these extensions. However, additional extensions might be proposed in the future and might be used in conjunction with one of these. @@ -666,9 +636,9 @@ Because these extensions are used to specify very different types of impacts, pr |*availability_impact* (required) |[stixtype]#{int_url}[integer]# |The availability / functional impact of the incident on the objects referenced in *impacted_refs*. -If no objects are referenced, the impact should be treated as the overall availability impact for the [stixtype]#{incident_url}[incident]# that references it. +If no objects are referenced, the impact should be treated as the overall availability impact for the related [stixtype]#{incident_url}[incident]#. -This value *MUST* be between 0 to 100. This can be translated into qualitative values as described in <>. +This value *MUST* be an integer between 0 to 100. This can be translated into qualitative values as described in <>. |=== @@ -935,9 +905,9 @@ include::examples/example_2.3.2.7.1.json[] A Task is an activity that is performed by or for the victim/defender to respond to the attack. -This new sdo extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. +This new SDO extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. -As a new sdo extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. +As a new SDO extension it must follow the requirements as described in section 7.3.2.2 of the STIX 2.1 specification. [width="100%",cols="100%",stripes=odd] |=== @@ -1018,7 +988,7 @@ If *start_time* and *end_time* properties are both defined, then *end_time* valu |*end_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the end_time is recorded in. +|The level of fidelity that the *end_time* fidelity is recorded in. This value *MUST* come from [stixtype]#<># enumeration. @@ -1052,7 +1022,7 @@ This property *SHOULD* be populated. |*start_time_fidelity* (optional) |[stixtype]#<># -|The level of fidelity that the start_time is recorded in. +|The level of fidelity that the *start_time* property is recorded in. This value *MUST* come from [stixtype]#<># enumeration. @@ -1072,11 +1042,11 @@ If no value is provided the timestamp should be considered to be accurate up to These are the relationships explicitly defined between the Task object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. For their -definitions, please see the "Source" object. +targeting this object type from another object type. They are included here for convenience. See the +forward relationship for the definition. Relationships are not restricted to those listed below. Relationships can be created between any objects -using the related-to relationship type or, as with open vocabularies, user-defined names. +using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. When creating sequences of [stixtype]#<># these *SHOULD NOT* be shared using relationship objects. Sequences *SHOULD* be shared within an [stixtype]#{incident_url}[incident]# or [stixtype]#<># as part of the list of *tasks* or *subtasks* respectively. @@ -1119,7 +1089,7 @@ Using these embedded relationships ensure that an incomplete sequence cannot be |[stixtype]#<># |[stixrelationship]#impacts# |[stixtype]#{infrastructure_url}[infrastructure]#, + - +[stixtype]#[]# |A task has an impact on specific infrastructure. |[stixtype]#<># From 8082875c3c59fa8778b85736dfefc5f6710cc013 Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Wed, 14 Feb 2024 09:08:29 -0500 Subject: [PATCH 09/15] dez edits 4 --- .../Incident Extension Suite.adoc | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 227962532a7..b7b6adb11e0 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -661,27 +661,31 @@ include::examples/example_2.3.2.1.1.json[] ^|[stixtr]*Type* ^|[stixtr]*Description* +|*loss_type* (required) +|[stixtype]#<># +|The type of loss that occurred to the relevant information + +The values of this property *MUST* come from the [stixtype]#<># enumeration. + |*information_type* (optional) |[stixtype]#{open_vocab_url}[open-vocab]# |The type of information that had its confidentiality compromised. This can include control systems and other processes that can result in virtual or physical impacts. The value of this property *SHOULD* come from the [stixtype]#<> open vocabulary#. -This value *MUST* be included if the loss_type is not none. Including an entry with loss_type of none and no information_type indicates that no information had its confidentiality impacted by this incident. - -|*loss_type* (required) -|[stixtype]#<># -|The type of loss that occurred to the relevant information - -The values of this property *MUST* come from the [stixtype]#<># enumeration. +This value *MUST* be included if the loss_type is not [stixliteral]#none#. Including an entry with loss_type of none and no information_type indicates that no information had its confidentiality impacted by this incident. |*record_count* (optional) |[stixtype]#{int_url}[integer]# -|The number of records of this type that were compromised. The value of this property *MUST NOT* be negative. +|The number of records of this information type that were compromised. + +The value of this property *MUST NOT* be negative. |*record_size* (optional) |[stixtype]#{int_url}[integer]# -|The amount of data that was compromised in bytes. The value of this property *MUST NOT* be negative. +|The amount of data that was compromised in bytes. + +The value of this property *MUST NOT* be negative. |=== ===== 2.3.2.2.1 Confidentiality Impact Example @@ -703,7 +707,7 @@ include::examples/example_2.3.2.2.1.json[] |*impact_type* (required) |[stixtype]#{open_vocab_url}[open-vocab]# -|The type of impact outside of the direct organization. +|The type of impact outside of the targeted organization. The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. |=== @@ -729,7 +733,7 @@ include::examples/example_2.3.2.3.1.json[] |*alteration* (required) |[stixtype]#<># -|The type of alteration performed against the information_type. +|The type of alteration performed against the information that was compromised. The value of this property *MUST* come from the [stixtype]#<># enumeration. @@ -745,11 +749,15 @@ Including an entry that with an alteration of none and no information_type indic |*record_count* (optional) |[stixtype]#{int_url}[integer]# -|The number of records of this type that were compromised. The value of this property *MUST NOT* be negative. +|The number of records of this type that were compromised. + +The value of this property *MUST NOT* be negative. |*record_size* (optional) |[stixtype]#{int_url}[integer]# -|The amount of data that was compromised in bytes. The value of this property *MUST NOT* be negative. +|The amount of data that was compromised in bytes. + +The value of this property *MUST NOT* be negative. |=== @@ -787,6 +795,8 @@ This value *MUST* be greater than zero. This value *MUST* be included if the *min_amount* property is included. +If this property is provided, the *conversion_time* property must also be provided. + |*conversion_time* (optional) |[stixtype]#{timestamp_url}[timestamp]# |The timestamp when the conversion rate was queried. @@ -794,7 +804,7 @@ This *MUST* be included if a *conversion_rate* property is included. |*currency* (optional) |[stixtype]#{string_url}[string]#| -The currency that the max_amount and min_amount fields use. +The currency that the *max_amount* and *min_amount* properties use. This *SHOULD* be an ISO 4217 alpha currency code or the official currency code for the relevant cryptocurrency. This *SHOULD* match an organizations own primary currency, or for government reporting the currency requested by that government for these reports. From d6147823bcd1eeea619bab3f3d38aafda79df31d Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Wed, 14 Feb 2024 11:44:16 -0500 Subject: [PATCH 10/15] dez edits 5 --- .../incident-ef7/Incident Extension Suite.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index b7b6adb11e0..6ba88490553 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -663,7 +663,7 @@ include::examples/example_2.3.2.1.1.json[] |*loss_type* (required) |[stixtype]#<># -|The type of loss that occurred to the relevant information +|The type of loss that occurred with respect to the relevant information. The values of this property *MUST* come from the [stixtype]#<># enumeration. @@ -733,7 +733,7 @@ include::examples/example_2.3.2.3.1.json[] |*alteration* (required) |[stixtype]#<># -|The type of alteration performed against the information that was compromised. +|The type of alteration affecting integrity of the information. The value of this property *MUST* come from the [stixtype]#<># enumeration. @@ -745,7 +745,7 @@ This can include control systems and other processes that can result in virtual The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. This value *MUST* be included if the alternation is not none. -Including an entry that with an alteration of none and no information_type indicates that no information had its integrity impacted by this incident. +Including an entry that with an alteration of [stixliteral]#none# and no information_type provided indicates that no information had its integrity impacted by this incident. |*record_count* (optional) |[stixtype]#{int_url}[integer]# @@ -789,6 +789,7 @@ The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. -This value *MUST* be included if the *impact_type* is not none. +This value *MUST* be included if the *impact_type* is not [stixliteral]#none# . Including an entry with an *impact_type* of none and no asset_type indicates that no physical damage was caused by this incident. |=== From 729fb4f8356ef9b2b49220de3ee749e21753a55e Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Thu, 15 Feb 2024 13:44:09 -0500 Subject: [PATCH 11/15] dez edits 6 --- .../Incident Extension Suite.adoc | 195 ++++++++++-------- 1 file changed, 104 insertions(+), 91 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 6ba88490553..8948913df82 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -174,7 +174,7 @@ enumeration. |*tasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. +|A list of tasks (as a list of [stixtype]#<>#) tied to this incident. |=== @@ -183,7 +183,9 @@ enumeration. These are the relationships explicitly defined between the Incident object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object -type by way of the Relationship object. The reverse relationships section illustrates the relationships +type by way of the Relationship object. + +The reverse relationships section illustrates the relationships targeting this object type from another object type. They are included here for convenience. See the forward relationship for the definition. @@ -402,7 +404,9 @@ If no value is provided the timestamp should be considered to be accurate up to These are the relationships explicitly defined between the Event object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object -type by way of the Relationship object. The reverse relationships section illustrates the relationships +type by way of the Relationship object. + +The reverse relationships section illustrates the relationships targeting this object type from another object type. They are included here for convenience. See the forward relationship for the definition. @@ -915,7 +919,7 @@ include::examples/example_2.3.2.7.1.json[] [[task]] === 2.4. Task -A Task is an activity that is performed by or for the victim/defender to respond to the attack. +A Task is an activity that is performed by or for the victim/defender to respond to the incident. This new SDO extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. @@ -980,7 +984,7 @@ The value of this property *MUST* come from the [stixtype]#<># |A list of changes that this task has caused. -This is typically used to indicate how an task has affected impacts. +This is typically used to indicate how a task has affected impacts. |*task_types* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocabulary]# @@ -1023,7 +1027,7 @@ This is primarily used when recording victim notifications. |*priority* (optional) |[stixtype]#{int_url}[integer]# |The priority or importance of the task. -This value *MUST* be between 0 to 100. This can be translated into qualitative values as described in <>. +This value *MUST* be between an integer 0 to 100. This can be translated into qualitative values as described in <>. |*start_time* (optional) |[stixtype]#{timestamp_url}[timestamp]# @@ -1042,7 +1046,7 @@ If no value is provided the timestamp should be considered to be accurate up to |*subtasks* (optional) |[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of subtasks tied to this task. +|A list of subtasks related to this task. |=== <<< @@ -1053,16 +1057,18 @@ If no value is provided the timestamp should be considered to be accurate up to These are the relationships explicitly defined between the Task object and other STIX Objects. The table identifies the relationships that can be made from this object type to another object -type by way of the Relationship object. The reverse relationships section illustrates the relationships +type by way of the Relationship object. + +The reverse relationships section illustrates the relationships targeting this object type from another object type. They are included here for convenience. See the forward relationship for the definition. Relationships are not restricted to those listed below. Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. -When creating sequences of [stixtype]#<># these *SHOULD NOT* be shared using relationship objects. +Sequences of[stixtype]#<># SHOULD NOT be shared using relationship objects Sequences *SHOULD* be shared within an [stixtype]#{incident_url}[incident]# or [stixtype]#<># as part of the list of *tasks* or *subtasks* respectively. -Using these embedded relationships ensure that an incomplete sequence cannot be shared accidentally to avoid potential confusion or misunderstandings when processing STIX data. +Using these embedded relationships ensures that an incomplete sequence cannot be shared accidentally (avoiding potential confusion or misunderstandings when processing STIX data.) [width="100%",cols="27%,16%,24%,33%",options="header",] |=== @@ -1107,7 +1113,7 @@ Using these embedded relationships ensure that an incomplete sequence cannot be |[stixtype]#<># |[stixrelationship]#located-at# |[stixtype]#{location_url}[location]# -|The task occurred at a specific location or locations. +|The task occurred at a specific location. // relationships:end |=== @@ -1203,10 +1209,14 @@ _0 individuals_ <<< -[[event-entry]] -=== 3.2. Event Entry Object Type +[[event-sequence-entry]] +=== 3.2. Event Sequence Object Type -*Type Name:* [stixtype]#event-entry# +Event sequence entries store references to subsequent steps for an event entry. +As these are always stored in an list of steps within an array of list entries, validation rules for *event_ref* *MUST* be performed against the entire array of event entries. + + +*Type Name:* [stixtype]#event-sequence-entry# [width="100%",cols="37%,23%,40%",options="header",] |=== @@ -1216,21 +1226,23 @@ _0 individuals_ |*event_ref* (required) |[stixtype]#{identifier_url}[identifier]# -|The event that is described by this entry. -This *MUST* reference an [stixtype]#<># object. +|The identifier of the event that is described by this entry. -|*next_steps* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of event sequences that describes the current event flows into the next one. +This reference *MUST* be included as an *event_ref* within the parent array of [stixtype]#<># objects. -|*sequence_start* (optional) -|[stixtype]#{boolean_url}[boolean]# -|If this is a start of a sequence chain. +|*condition_type* (required) +|[stixtype]#<># +|If the referenced step required the current one to be successful. +If it is optional, or if it is unknown. -All sequences of events *MUST* begin with at least one entry where *sequence_start* is set to [stixliteral]#true#. -If a cycle exists with multiple entries with *sequence_start* set to [stixliteral]#true# then all of these are equally valid start points. +The values of this property *MUST* come from the [stixtype]#<># enumeration. -Default value is [stixliteral]#true#. +|*transition_type* (required) +|[stixtype]#<># +|What state the referenced step depends on. +If it is performed upon success, failure, simple completion, or if it is unknown. + +The values of this property *MUST* come from the [stixtype]#<># enumeration. |=== @@ -1238,17 +1250,15 @@ Default value is [stixliteral]#true#. [source,json] ---- -include::examples/example_3.2.json[] +include::examples/example_3.3.json[] ---- -[[event-sequence-entry]] -=== 3.3. Event Sequence Object Type - -Event sequence entries store references to subsequent steps for an event entry. -As these are always stored in an array of steps within an array of event entries validation rules for *event_ref* *MUST* be performed against the entire array of event entries. +<<< +[[event-entry]] +=== 3.3. Event Entry Object Type -*Type Name:* [stixtype]#event-sequence-entry# +*Type Name:* [stixtype]#event-entry# [width="100%",cols="37%,23%,40%",options="header",] |=== @@ -1258,23 +1268,21 @@ As these are always stored in an array of steps within an array of event entries |*event_ref* (required) |[stixtype]#{identifier_url}[identifier]# -|The identity of the event that is described by this entry. - -This reference *MUST* be included as an *event_ref* within the parent array of [stixtype]#<># objects. +|The event that is described by this entry. +This *MUST* reference an [stixtype]#<># object. -|*condition_type* (required) -|[stixtype]#<># -|If the referenced step required the current one to be successful. -If it is optional, or if it is unknown. +|*next_steps* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#<># +|A list of event sequences that describes the current event flows into the next one. -The values of this property *MUST* come from the [stixtype]#<># enumeration. +|*sequence_start* (optional) +|[stixtype]#{boolean_url}[boolean]# +|If this is a start of a sequence chain. -|*transition_type* (required) -|[stixtype]#<># -|What state the referenced step depends on. -If it is performed upon success, failure, simple completion, or if it is unknown. +All sequences of events *MUST* begin with at least one entry where *sequence_start* is set to [stixliteral]#true#. +If a cycle exists with multiple entries with *sequence_start* set to [stixliteral]#true# then all of these are equally valid start points. -The values of this property *MUST* come from the [stixtype]#<># enumeration. +Default value is [stixliteral]#true#. |=== @@ -1282,10 +1290,9 @@ The values of this property *MUST* come from the [stixtype]#< Automated Exposure Score". |*value* (required) |[stixtype]#{number_url}[number]# @@ -1307,7 +1316,7 @@ include::examples/example_3.3.json[] |*description* (optional) |[stixtype]#{string_url}[string]# -|A description about how this score was calculated for systems that provide this information. +|A description of how this score was calculated by the system, if that information is provided. |=== <<< @@ -1323,7 +1332,7 @@ include::examples/example_3.4.json[] *Type Name:* [stixtype]#state-change# -The *initial_ref* or *result_ref* *MUST* be populated. +The *initial_ref* or *result_ref* property *MUST* be populated. [width="100%",cols="37%,23%,40%",options="header",] |=== @@ -1341,24 +1350,26 @@ The value of this property *SHOULD* come from the [stixtype]#<># +|If the referenced step required the current one to be successful. +If it is optional, or if it is unknown. + +The values of this property *MUST* come from the [stixtype]#<># enumeration. + |*task_ref* (required) |[stixtype]#{identifier_url}[identifier]# -|The identity of the task that is described by this entry. -This *MUST* reference a [stixtype]#<>#. - -|*next_steps* (optional) -|[stixtype]#{list_url}[list]# of type [stixtype]#<># -|A list of task sequences that describes the current task flows into the next one. +|The identity of the event that is described by this entry. -|*sequence_start* (optional) -|[stixtype]#{boolean_url}[boolean]# -|If this is a start of a sequence chain. +This reference *MUST* be included as an *task_ref* within the parent array of [stixtype]#<># objects. -All sequences of tasks *MUST* begin with at least one entry where *sequence_start* is set to [stixliteral]#true#. -If a cycle exists with multiple entries with *sequence_start* set to [stixliteral]#true# then all of these are equally valid start points. +|*transition_type* (required) +|[stixtype]#<># +|What state the referenced step depends on. +If it is performed upon success, failure, simple completion, or if it is unknown. -Default value is [stixliteral]#true#. +The values of this property *MUST* come from the [stixtype]#<># enumeration. |=== @@ -1405,16 +1421,15 @@ Default value is [stixliteral]#true#. [source,json] ---- -include::examples/example_3.6.json[] +include::examples/example_3.7.json[] ---- +<<< -[[task-sequence-entry]] -=== 3.7. Task Sequence Object Type -Task sequence entries store references to subsequent steps for a task entry. -As these are always stored in an array of steps within an array of task entries validation rules for *task_ref* *MUST* be performed against the entire array of task entries. +[[task-entry]] +=== 3.7. Task Entry Object Type -*Type Name:* [stixtype]#task-sequence-entry# +*Type Name:* [stixtype]#task-entry# [width="100%",cols="37%,23%,40%",options="header",] |=== @@ -1422,25 +1437,23 @@ As these are always stored in an array of steps within an array of task entries ^|[stixtr]*Type* ^|[stixtr]*Description* -|*condition_type* (required) -|[stixtype]#<># -|If the referenced step required the current one to be successful. -If it is optional, or if it is unknown. - -The values of this property *MUST* come from the [stixtype]#<># enumeration. - |*task_ref* (required) |[stixtype]#{identifier_url}[identifier]# -|The identity of the event that is described by this entry. +|The identifier of the task that is described by this entry. +This *MUST* reference a [stixtype]#<>#. -This reference *MUST* be included as an *task_ref* within the parent array of [stixtype]#<># objects. +|*next_steps* (optional) +|[stixtype]#{list_url}[list]# of type [stixtype]#<># +|A list of task sequences that describes the current task flows into the next one. -|*transition_type* (required) -|[stixtype]#<># -|What state the referenced step depends on. -If it is performed upon success, failure, simple completion, or if it is unknown. +|*sequence_start* (optional) +|[stixtype]#{boolean_url}[boolean]# +|If this is a start of a sequence chain. -The values of this property *MUST* come from the [stixtype]#<># enumeration. +All sequences of tasks *MUST* begin with at least one entry where *sequence_start* is set to [stixliteral]#true#. +If a cycle exists with multiple entries with *sequence_start* set to [stixliteral]#true# then all of these are equally valid start points. + +Default value is [stixliteral]#true#. |=== @@ -1448,9 +1461,9 @@ The values of this property *MUST* come from the [stixtype]#< Date: Fri, 16 Feb 2024 12:40:00 -0500 Subject: [PATCH 12/15] dez edits 7 --- .../Incident Extension Suite.adoc | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 8948913df82..3cb8af16e52 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -186,8 +186,7 @@ The table identifies the relationships that can be made from this object type to type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. See the -forward relationship for the definition. +targeting this object type from another object type. Relationships are not restricted to those listed below. Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. @@ -358,7 +357,7 @@ If no value is provided the timestamp should be considered to be accurate up to |[stixtype]#{list_url}[list]# of type [stixtype]#{open_vocab_url}[open-vocab]# |High level types for the event to enable aggregation and summarization. -The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. +The values of this property *SHOULD* come from the [stixtype]#<># open vocabulary. |*goal* (optional) |[stixtype]#{string_url}[string]# @@ -407,8 +406,7 @@ The table identifies the relationships that can be made from this object type to type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. See the -forward relationship for the definition. +targeting this object type from another object type. Relationships are not restricted to those listed below. Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. @@ -673,7 +671,7 @@ The values of this property *MUST* come from the [stixtype]#<> open vocabulary#. @@ -744,7 +742,7 @@ The value of this property *MUST* come from the [stixtype]#<># open vocabulary. @@ -1000,7 +998,7 @@ The values of this property *SHOULD* come from the [stixtype]#<># @@ -1060,8 +1058,7 @@ The table identifies the relationships that can be made from this object type to type by way of the Relationship object. The reverse relationships section illustrates the relationships -targeting this object type from another object type. They are included here for convenience. See the -forward relationship for the definition. +targeting this object type from another object type. Relationships are not restricted to those listed below. Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. @@ -2011,15 +2008,16 @@ organizations may choose to not share the details of these impacts. ^|[stixtr]*Description* |[stixliteral]#closed# -|All defender work on this incident has been concluded. -In some cases, blue teams may make child Incidents of a closed Incident. +|All victim/defender work on this incident has been concluded. + +Blue teams may use a closed incident as a starting point for their work, by creating child Incidents of the closed Incident. In these cases, it is appropriate to mark an initial Incident as closed if the related child incidents that track this work are still open. |[stixliteral]#new# -|A new incident that has not begun the formal workflow on the defender's network. +|A new incident which the victim/defender has not begun formal work on. |[stixliteral]#open# -|An open incident that is currently being worked. +|Victim/Defender work is in underway for this Incident. |=== <<< From 113961ce1598fcd23fe1ea3bd7bb606066146ecf Mon Sep 17 00:00:00 2001 From: DC3-DCCI Date: Fri, 16 Feb 2024 13:00:56 -0500 Subject: [PATCH 13/15] Expanding adoc validation python script, adding GitHub job to automatically run it, fixing errors found within adoc files. --- .../extensions-asciidocs-validation.yml | 18 ++++++++ .../STIX-2.1-CUI-marking.adoc | 5 +-- .../Identity-Contact-Information.adoc | 19 +++++---- .../Incident Extension Suite.adoc | 41 ++++++++++--------- .../observed-string-8b1/Observed String.adoc | 5 ++- .../STIX-2.1-PAP-marking-definition.adoc | 2 +- scripts/validate_adoc.py | 9 ++-- 7 files changed, 60 insertions(+), 39 deletions(-) create mode 100644 .github/workflows/extensions-asciidocs-validation.yml diff --git a/.github/workflows/extensions-asciidocs-validation.yml b/.github/workflows/extensions-asciidocs-validation.yml new file mode 100644 index 00000000000..5207593c0db --- /dev/null +++ b/.github/workflows/extensions-asciidocs-validation.yml @@ -0,0 +1,18 @@ +name: AsciiDoc Validation +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set Up Python + uses: actions/setup-python@v2 + with: + python-version: '3.10' + - name: Validate adoc + working-directory: extension-definition-specifications + run: | + for file in */*.adoc; do + python ../scripts/validate_adoc.py -i "$file" + done diff --git a/extension-definition-specifications/cui-marking-definition-dff/STIX-2.1-CUI-marking.adoc b/extension-definition-specifications/cui-marking-definition-dff/STIX-2.1-CUI-marking.adoc index b4ab4cab181..fd046837075 100644 --- a/extension-definition-specifications/cui-marking-definition-dff/STIX-2.1-CUI-marking.adoc +++ b/extension-definition-specifications/cui-marking-definition-dff/STIX-2.1-CUI-marking.adoc @@ -1,6 +1,3 @@ -cui - - :stylesheet: stix.css :stylesdir: ../../asciidoc-shared :toc: macro @@ -72,7 +69,7 @@ The tables below describe the properties of a STIX 2.1 CUI marking definition ex |[stixtype]#{string_url}[string]# |The extension_type property indicates the type of extension is being used. -The value of this property *MUST* be [stixtype]#<># +The value of this property *MUST* be [stixliteral]#property-extension# |*control* (required) |[stixtype]#{string_url}[string]# diff --git a/extension-definition-specifications/identity-66e/Identity-Contact-Information.adoc b/extension-definition-specifications/identity-66e/Identity-Contact-Information.adoc index a498bc811ef..3efac81e279 100644 --- a/extension-definition-specifications/identity-66e/Identity-Contact-Information.adoc +++ b/extension-definition-specifications/identity-66e/Identity-Contact-Information.adoc @@ -10,6 +10,8 @@ :list_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_9w329aiwpu1y :open_vocab_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_bnnxah80y7by :string_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_uxyhzmv0vpyc +:user_account_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_azo70vgj1vm2 +:email_address_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_wmenahkvqmgj = [stixtitle]*Identity Contact Information Extension Version 1.0 for STIX™ Version 2.1* @@ -96,7 +98,7 @@ The properties and additional types within the Identity Contact Information Exte == 2. Additional Sub-Object Types [[contact-number]] -=== 2.1 Contact Number Object Type +=== 2.1. Contact Number Object Type *Type Name:* [stixtype]#contact-number# [width="100%",cols="37%,23%,40%",options="header",] @@ -123,7 +125,7 @@ The properties and additional types within the Identity Contact Information Exte |=== [[email-contact]] -=== 2.2 Email Contact Object Type +=== 2.2. Email Contact Object Type *Type Name:* [stixtype]#email-contact# [width="100%",cols="37%,23%,40%",options="header",] @@ -145,12 +147,12 @@ The properties and additional types within the Identity Contact Information Exte |The type of email that address is used for. This *SHOULD* be drawn from [stixtype]#<>#. |*email_address_ref* (required) -|[stixtype]#{identifier_url}[identifer]# of type [stixtype]#<># +|[stixtype]#{identifier_url}[identifer]# of type [stixtype]#{email_address_url}[email-addr]# |A reference to the email address itself. |=== [[social-media-contact]] -=== 2.3 Social Media Contact Object Type +=== 2.3. Social Media Contact Object Type *Type Name:* [stixtype]#social-media-contact# [width="100%",cols="37%,23%,40%",options="header",] @@ -174,7 +176,7 @@ The properties and additional types within the Identity Contact Information Exte This *SHOULD NOT* be used to capture the social media service used. That *SHOULD* be encoded into the User Account Object that is linked to by the user_account_ref property. |*user_account_ref* (required) -|[stixtype]#{identifier_url}[identifer]# of type [stixtype]#<># +|[stixtype]#{identifier_url}[identifer]# of type [stixtype]#{user_account_url}[user-account]# |A reference to the social media account itself. |=== @@ -206,7 +208,7 @@ This *SHOULD NOT* be used to capture the social media service used. That *SHOUL |=== [[digital-contact-ov]] -=== 3.2 Digital Contact Type Vocabulary +=== 3.2. Digital Contact Type Vocabulary *Type Name:* [stixtype]#digital-contact-ov# [width="100%",cols="37%,63%",options="header",] @@ -226,19 +228,18 @@ This *SHOULD NOT* be used to capture the social media service used. That *SHOUL == 4. Identity Contact Information Examples -=== 4.1 Identitiy Contact Details Example +=== 4.1. Identitiy Contact Details Example [source,json] ---- include::examples/individual_contact_example.json[] ---- -=== 4.2 Organization Contact Details Example +=== 4.2. Organization Contact Details Example [source,json] ---- include::examples/organization_contact_example.json[] ---- -[[appendix-a]] == Appendix A. Acknowledgements *Primary Editor* diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 8948913df82..c7656b186c6 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -39,6 +39,7 @@ :sighting_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_a795guqsap3r :threat_actor_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_k017w16zutw :tool_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_z4voa9ndw8v +:sco_url: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_mlbmudhl16lr = [stixtitle]*Incident Core Extension Version 2.1 for STIX^TM^ Version 2.1* @@ -78,7 +79,7 @@ The current STIX 2.1 Incident object was defined as a stub with the expectation In the 1.0 version of the core incident extension, information on impact, events, and tasks were embedded within the Incident object itself, however this was found to have limitations. Therefore, the 2.0 version of this extension has been created in which these components have been separated into independent SDOs for more complex incidents to be accurately modeled. -These extensions allow incidents to be tracked across their life cycle where [stixtype]#<># are first flagged for investigation resulting in [stixtype]#incidents# with [stixtype]#<># being worked to resolve them. +These extensions allow incidents to be tracked across their life cycle where [stixtype]#<># are first flagged for investigation resulting in [stixtype]#{incident_url}incidents# with [stixtype]#<># being worked to resolve them. Incidents have [stixtype]#<># that change over time. [stixtype]#<># can cause or influence these [stixtype]#<># which are in turn mitigated and potentially resolved by [stixtype]#<># performed as part of the incident response process. Both [stixtype]#<># and [stixtype]#<># can exist independently of [stixtype]#{incident_url}[incidents]# and in most workflows will occur prior to an incident being declared. @@ -259,7 +260,7 @@ Additionally, this can be used to supplement the *created_by_ref* property in ca |=== // end::incident-relationships[] -==== 2.1.2 Example +==== 2.1.2. Example [source,json] ---- @@ -432,7 +433,7 @@ For example, a dropper running led to a ransomware tool to be downloaded and run |[stixtype]#<># |[stixrelationship]#impacts# |[stixtype]#{infrastructure_url}[infrastructure]#, + -[stixtype]#[]# +[stixtype]#{sco_url}[]# |An event has an impact on specific infrastructure. While not all SCO types will make sense in this relationship, allowing any type of SCO prevents artificially restricting what could be used. |[stixtype]#<># @@ -470,7 +471,7 @@ For example, a dropper running led to a ransomware tool to be downloaded and run // end::event-relationships[] -==== 2.2.2 Example +==== 2.2.2. Example [source,json] ---- @@ -646,7 +647,7 @@ This value *MUST* be an integer between 0 to 100. This can be translated into qu |=== -===== 2.3.2.1.1 Availability Impact Example +====== 2.3.2.1.1. Availability Impact Example [source,json] ---- @@ -692,7 +693,7 @@ The value of this property *MUST NOT* be negative. The value of this property *MUST NOT* be negative. |=== -===== 2.3.2.2.1 Confidentiality Impact Example +====== 2.3.2.2.1. Confidentiality Impact Example [source,json] ---- @@ -718,7 +719,7 @@ The value of this property *SHOULD* come from the [stixtype]#<># |[stixrelationship]#impacts# |[stixtype]#{infrastructure_url}[infrastructure]#, + -[stixtype]#[]# +[stixtype]#{sco_url}[]# |A task has an impact on specific infrastructure. |[stixtype]#<># @@ -1155,7 +1156,7 @@ Using these embedded relationships ensures that an incomplete sequence cannot be // end::task-relationships[] -==== 2.4.2 Example +==== 2.4.2. Example [source,json] ---- @@ -1246,7 +1247,7 @@ The values of this property *MUST* come from the [stixtype]#<># +The value of this property *MUST* be [stixliteral]#property-extension# |*pap* (required) |[stixtype]#{string_url}[string]# diff --git a/scripts/validate_adoc.py b/scripts/validate_adoc.py index c08e2ea08c8..34d59cd1da3 100644 --- a/scripts/validate_adoc.py +++ b/scripts/validate_adoc.py @@ -7,7 +7,7 @@ class Validator(): def __init__(self, file_path): self._errors = [] - with open(file_path, "rt") as input_file: + with open(file_path, "rt", encoding="utf-8") as input_file: self._content = input_file.read() def run_jobs(self) -> list: @@ -96,7 +96,9 @@ def section_ids(self, content) -> None: self._errors.append(f"Line {line_number}: {item} should be 1 as the first item") continue - if len(parts) == len(last_parts): + if item[-1] != ".": + self._errors.append(f"Line {line_number}: {item} has no . at the end") + elif len(parts) == len(last_parts): if int(last_parts[-1]) != int(parts[-1]) - 1: self._errors.append(f"Line {line_number}: {item} should be {'.'.join(last_parts[:-1])}.{int(last_parts[-1]) + 1}") elif len(parts) > len(last_parts): @@ -128,9 +130,10 @@ def section_ids(self, content) -> None: errors = validator.run_jobs() if len(errors) > 0: + print(f"Error Validating: {args.input_path}", file=sys.stderr) print("\n".join(errors), file=sys.stderr) exit(1) else: - print("No errors found") + print(f"No errors found: {args.input_path}") exit(0) \ No newline at end of file From 0a73272784f3afd74552070b8e930b879f74be6f Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Tue, 20 Feb 2024 15:57:59 -0500 Subject: [PATCH 14/15] dez edits 8 --- .../Incident Extension Suite.adoc | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index 340b6857d34..d9542074e0e 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -45,7 +45,7 @@ [.stix-doc-information-heading]#Draft# -[.stix-doc-information-heading]#8 February 2024# +[.stix-doc-information-heading]#20 February 2024# [.stix-doc-information-heading] Editors: @@ -620,10 +620,11 @@ using the [stixrelationship]#related-to# relationship type or, as with open voca ==== 2.3.2. Extensions -There are many types of impacts, each with its own unique properties, therefore the Impact SDO emulates the File SCO through the use of STIX (sub-type) Extensions to provide the granular details of specific categories of impacts. +There are many types of impacts, each with its own unique properties, therefore the Impact SDO emulates the File SCO through the use of STIX (sub-type) Extensions to provide the granular details of specific categories of impacts. Seven extensions to [stixtype]#<>#, which further define the impact on a related Incident, are given below. As such, every Impact *MUST* have the one extension which matches the value of the *impact_category* property (see this property description above). This allows consumers to quickly validate their ability to process this category of impact and then load all of its specific details. + Because these extensions are used to specify very different types of impacts, producers *SHOULD* use one and only one of these extensions. However, additional extensions might be proposed in the future and might be used in conjunction with one of these. ===== 2.3.2.1. Availability Impact Extension @@ -638,7 +639,7 @@ Because these extensions are used to specify very different types of impacts, pr |*availability_impact* (required) |[stixtype]#{int_url}[integer]# -|The availability / functional impact of the incident on the objects referenced in *impacted_refs*. +|The availability / functional impact of the related incident on the objects referenced in *impacted_refs*. If no objects are referenced, the impact should be treated as the overall availability impact for the related [stixtype]#{incident_url}[incident]#. This value *MUST* be an integer between 0 to 100. This can be translated into qualitative values as described in <>. @@ -676,7 +677,7 @@ The values of this property *MUST* come from the [stixtype]#<> open vocabulary#. -This value *MUST* be included if the loss_type is not [stixliteral]#none#. Including an entry with loss_type of none and no information_type indicates that no information had its confidentiality impacted by this incident. +This value *MUST* be included if the loss_type is not [stixliteral]#none#. Including an entry with loss_type of none and no information_type indicates that no information had its confidentiality impacted by the related incident. |*record_count* (optional) |[stixtype]#{int_url}[integer]# @@ -748,7 +749,7 @@ This can include information about control systems and other processes that can The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. This value *MUST* be included if the alternation is not none. -Including an entry that with an alteration of [stixliteral]#none# and no information_type provided indicates that no information had its integrity impacted by this incident. +Including an entry that with an alteration of [stixliteral]#none# and no information_type provided indicates that no information had its integrity impacted by the related incident. |*record_count* (optional) |[stixtype]#{int_url}[integer]# @@ -797,21 +798,19 @@ This *MUST NOT* be included if the *currency_actual* property is not included. This *MUST* be included if the *currency_actual* property is included. This value *MUST* be greater than zero. -This value *MUST* be included if the *min_amount* property is included. - If this property is provided, the *conversion_time* property must also be provided. |*conversion_time* (optional) |[stixtype]#{timestamp_url}[timestamp]# -|The timestamp when the conversion rate was queried. +|The timestamp corresponding to the conversion rate from the *currency* property to the *currency_actual* property. This *MUST* be included if a *conversion_rate* property is included. |*currency* (optional) |[stixtype]#{string_url}[string]#| -The currency that the *max_amount* and *min_amount* properties use. +The currency used for reporting which the *max_amount* and *min_amount* properties use. This *SHOULD* be an ISO 4217 alpha currency code or the official currency code for the relevant cryptocurrency. -This *SHOULD* match an organizations own primary currency, or for government reporting the currency requested by that government for these reports. +This *SHOULD* match the currency of the organization or the government producing the report. This value *MUST* be included if the *min_amount* property is included. @@ -827,7 +826,7 @@ This *SHOULD* be an ISO 4217 alpha currency code or the official currency code f |*max_amount* (optional) |[stixtype]#{number_url}[number]# -|The maximum damage estimate of this type in the provided currency. +The maximum monetary amount of the impact using the currency specified in the *currency* property. This value *MUST* be greater than zero. This value *MUST* be included if the *min_amount* property is included. @@ -836,7 +835,7 @@ If *min_amount* and *max_amount* properties are both defined, then *max_amount* |*min_amount* (optional) |[stixtype]#{number_url}[number]# -|The minimum damage estimate of this type in the provided currency. +The maximum monetary amount of the impact using the currency specified in the *currency* property. This value *MUST* be greater than zero. This value *MUST* be included if the *max_amount* property is included. @@ -873,12 +872,12 @@ enumeration. |*asset_type* (optional) |[stixtype]#{open_vocab_url}[open-vocab]# -|The type or property or system that was affected by this impact. +|The type of property or system that was affected by this impact. The value of this property *SHOULD* come from the [stixtype]#<># open vocabulary. This value *MUST* be included if the *impact_type* is not [stixliteral]#none# . -Including an entry with an *impact_type* of none and no asset_type indicates that no physical damage was caused by this incident. +Including an entry with an *impact_type* of none and no asset_type indicates that no physical damage was caused by the related incident. |=== @@ -901,7 +900,7 @@ include::examples/example_2.3.2.6.1.json[] |*traceability_impact* (required) |[stixtype]#<># -|The impact of this incident on a system or organization's ability to perform audits or provide non-repudiation. +|The impact on a system or organization's ability to perform audits or provide non-repudiation. The value of this property *MUST* come from the [stixtype]#<># enumeration. @@ -918,7 +917,7 @@ include::examples/example_2.3.2.7.1.json[] [[task]] === 2.4. Task -A Task is an activity that is performed by or for the victim/defender to respond to the incident. +A Task is an activity that is performed by or for the victim/defender to respond to the related incident. This new SDO extension *MUST* use [stixliteral]#extension-definition--2074a052-8be4-4932-849e-f5e7798e0030# as its extension ID. @@ -1064,8 +1063,8 @@ targeting this object type from another object type. Relationships are not restricted to those listed below. Relationships can be created between any objects using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. -Sequences of[stixtype]#<># SHOULD NOT be shared using relationship objects -Sequences *SHOULD* be shared within an [stixtype]#{incident_url}[incident]# or [stixtype]#<># as part of the list of *tasks* or *subtasks* respectively. +Sequences of [stixtype]#<># *SHOULD NOT* be shared using relationship objects. +Sequences *SHOULD* be shared within an [stixtype]#{incident_url}[incident]# or [stixtype]#<># using the *tasks* or *subtasks* properties, respectively. Using these embedded relationships ensures that an incomplete sequence cannot be shared accidentally (avoiding potential confusion or misunderstandings when processing STIX data.) [width="100%",cols="27%,16%,24%,33%",options="header",] From 479d30150522f6cd6b0be5f69b132a2dc13f68cb Mon Sep 17 00:00:00 2001 From: Rich Piazza Date: Fri, 23 Feb 2024 14:17:13 -0500 Subject: [PATCH 15/15] dez edits 8 --- .../incident-ef7/Incident Extension Suite.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc index d9542074e0e..4b2e2b7b59d 100644 --- a/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc +++ b/extension-definition-specifications/incident-ef7/Incident Extension Suite.adoc @@ -410,7 +410,13 @@ The reverse relationships section illustrates the relationships targeting this object type from another object type. Relationships are not restricted to those listed below. Relationships can be created between any objects -using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. +using the [stixrelationship]#related-to# relationship type or, as with open vocabularies, user-defined names. + +Sequences of [stixtype]#<># *SHOULD NOT* be shared using relationship objects. +Sequences *SHOULD* be shared within an [stixtype]#{incident_url}[incident]# or [stixtype]#<># using the *events* or *subevents* properties, respectively. +Using these embedded relationships ensures that an incomplete sequence cannot be shared accidentally (avoiding potential confusion or misunderstandings when processing STIX data.) + + [width="100%",cols="23%,20%,24%,33%",options="header",] |===