Comments on Incident Core Extension document (rev 10/10/23)

[rpiazza]

• type names, literals, etc seem to be in a smaller font
• incident-investigation-ov is referred to as an enumeration in the investigation_status property. Maybe it should be, but if it isn't the MUST should be a SHOULD
• impacted_entity_counts can be at the incident level and at the impact level. These numbers may be inconsistent. Maybe it should say something about the property in incident is not a roll-up....
• incident_types really come from event-type-ov???
• Relationship sections should contain the boilerplate from the STIX spec saying "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." Maybe the whole boilerplate (i.e., the first paragraph in all Relationship sections of the STIX spec.)
• impacts vs. targets - maybe something like "targeting does not imply impact".
• identity ---contact-for---> incident - I think the text needs to be more explicit. Something like: "This relationship is different from the created_by_ref property, which is the creator of the STIX Incident object"
• Section 2.2 should have some text about what the Event object is used to represent. Also, maybe some boilerplate about it being an sdo extension so it must contain all of the common properties.
• Section 2.3 should have some text about what the Impact object is used to represent. Also, maybe some boilerplate about it being an sdo extension so it must contain all of the common properties.
• I think listing the various impact extension types in the impact_category property would be a good idea.
• All of the extensions except Integrity has a "Type Name". This type name should property correspond the the impact_category value - but in the examples you use just xxx, not xxx-impact. Or maybe -ext??
• It should be explicit that only one extension type per impact SDO - which I assume is what you had in mind.
• Should the impacted_entity_counts property mention that 0 should be used for no impact of that type?
• I wonder if we need a SHOULD to say that the end time of a superseded object should be before the start time of the next object
• "Producers SHOULD use one of these extensions" - I assume the option would be to use some other custom extension. Does it make sense for there to be no extension at all?
• Section 2.3 should have some text about what the Task object is used to represent. Also, maybe some boilerplate about it being an sdo extension so it must contain all of the common properties.
• Section 3 could use examples. The examples in the repo need updating too.
• Section 3.2 could use some intro text
• number is not a STIX data type. Perhaps use float?
• I suggest quotes around [Tool Name] Automated Exposure Score.
• Section 3.5 could use some intro text
• Section 3.6 could use some intro text
• In asset-type - what about a computer owned by an individual
• "human review" seems to be a superset of "human threat hunting".
• Entity Type and Asset Type are almost the same - do we really need both?
• On the other hand, Event Type seems to have two purposes. One is "what" it is, and other is metadata (e.g., blocked, deferred...)
• Let's talk about activity conditions...
• "The event took and is no longer ongoing" - what are you trying to say here? Maybe "took place"?
• Section 5.11 still has the wrong title - it should be Traceability Enumeration

Not recommended

• Should there be a relationship from event to threat-actor? (see 2 below)
• Maybe not changeable now, but any reason why "variety" is used in monetary_impact, instead of impact_type? (see 5 below)
• conversion_rate's normative language needs improvement. Everything is optional so I can have a min_amount but NOT a currency_actual - so is conversion_rate necessary or not? (normative text already captures this case)

[dc3-tsd]

Thank you for catching these. We believe most of these are errors, but a few of these were intended:

1. incident_types does come from event-type-ov to allow for consistency with other systems and avoiding creating duplicate open vocabularies. If another term can be created for this which is neutral it can certainly be renamed.
2. It may be useful for there to be a link between an Event and a Threat Actor, but this could also cause confusion since performing attribution would imply work was done which would be tracked as a Task within the Incident. So we avoided making this relationship for the time being. If future use cases require it then it could certainly be added as a recommended relationship.
3. Thank you for catching the lack of -ext within the impact extensions. These should be added and the documents should be revised as appropriate. Our only concern with implementing this now is it may break existing code as it is backwards breaking. That said since this is an extension proposal it would be better to fix this now, but we might need to officially flag a new version such as 2.0.1 or 2.1 for the incident extension.
4. We have to keep the impact_category open in order to allow for the expansion of impact in the future. We also cannot forbid additional extensions within it since the STIX specification does not permit this in general. We may be able to state that it MUST only have one category style extension however while still allowing additional extensions in case implementers require additional internal data to be passed along with existing impacts.
5. The use of "variety" from monetary impact was pulled from VERIS and kept for consistency.
6. Agreed on conditions / sequences. While this was based off of CACAO several implementers have complained about this structure. One has begun to put forward a proposal for separate SDOs for capturing sequence information. That is outside the scope of this issue, but it may be worth considering for an additional revision as there isn't much code that requires the current sequence structure and STIX would benefit from a more generic way to pass sequence data outside of just the components of the Incident, Task, and Event objects.

[rpiazza]

We also cannot forbid additional extensions within it since the STIX specification does not permit this in general.

Not sure what you are trying to say here. Multiple extensions are allowed by the spec (or should be). File is an example where you might want to use more than one extension (that comes directly from Ivan who worked on SCOs with Trey).

I think we want to restrict mutliple Impact extensions - I don't see why that can't be normative language.

BTW - i defined the term "subtype extensions" in the extension policy document to describe the "predefined extensions" we have in the spec and that would be a good term to use for the Impact ones.

[rpiazza]

Some changes still pending

[dzbeck]

////////- [ ] Update Draft date from 10 October 2023

Vocabs/enums

• All vocabs and enums should be checked to make sure they are defined consistently (parallel definitions) - see examples below.
• task-type-ov
  • values should be of the same form, e.g., "investigation" (noun) vs "detected" (verb). Recommend change to nouns: "administration," "detection," "escalation," "declaration," etc.
  • (J) should there be a value to specify a stage (e.g., "stage" or "incident-lifecycle-stage," to be used in combination with other values) OR explicit stage values (e.g., "analysis-stage," "identification-detection-stage," etc.)?
  • (J) add "identification-detection" for use in the I/D stage OR add "identification" (to be used along with "detection")
• event-type-ov
  • (J) should values include additional incident types (e.g., account-access-removal, defacement) (see f.28.A-T)
  • (J) given that this vocab pertains to both incidents and events, how about calling it occurrence-type-ov? With descriptions saying “The incident or event...”?
• incident-investigation-ov
  • the vocab is about the status of the Incident investigation so descriptions should address status. For example, “new” could be “Defender work on this incident has not begun…” and “open” would be “Defender work is in underway for this Incident.”
  • the definition for “closed” seems fine in this respect. However, the meaning of the other sentences for “closed” is confusing. What does “make child Incidents of a closed Incident” mean? Does it mean that smaller Incidents should be defined instead of a giant Incident? Wouldn’t an Incident be closed only after the smaller child Incidents are defined. Maybe just remove “of a closed Incident” in the second sentence.
• recoverability-enum
  • (J) values could be better chosen (e.g., regular —> predictable, extended —> unpredictable-need-resources, supplemented —> predictable-need-resources).
  • (J) should there be a value “unpredictable” with definition “Time to recovery is unpredictable with existing resources” (i.e., resources are fine but recovery time just isn’t known yet).

Section 1

• “The Incident object should have sufficient properties” - not clear whether a user should use sufficient properties or whether the object was designed to have sufficient properties.

This reads fine for me.

• Would be helpful to give a high-level definition of the new SDOs.

We have to assume that anyone looking at extension specification has some familiarity with the STIX spec.

////
just the NEW objects, not the existing STIX objects (Event, Task, Impact). The third paragraph of the abstract is helpful, but I think three bullets in Section 1 would help make it clear how the three new SDOs relate to an incident and to each other.
////

Section 2.1

• Should there be an explanation before the Incident extension property table about why “entry” types are defined for Events and Tasks instead of using them directly (as is done for Impacts)? Also, in the definitions, mention other content that is captured in the sub-object types.

I hope this will be re-worked when Jeff discusses the other Incident proposal - https://github.com/os-threat/cti-stix-common-objects

• Properties are listed by required/optional and alphabetical within each section. They would be more easily digested if grouped more logically - for example, by type (e.g., references to other objects together) and/or role (e.g., start_time, start_time_fidelity, end_time, end_time_fidelity). In STIX, the tables are ordered logically, not by required/optional or alphabet. Another example - “determination" should come after “investigation_status.”

• “As this is an extension of a top-level object, fields such as identifier are not present.” Should this be “common properties such as identifier are not present.”

• “high level” —> “high-level”

• Definition for “determination” property is unclear. “Outcome” makes it seem like it relates to whether or not the adversary was successful. How about changing the property name to “declaration” with a definition something like, “A high-level declaration of the incident status.”

Changed "outcome" to "status"

• "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" —> if “low-value” defines “blocked” put it in parentheses, or if it is a separate value, add it to the enum. Also, “blocked” in the last sentence should be in the special font.
• events property - should definition say “list of event entries” instead of “list of events”?
• impacted_entity_counts definition - remove “optional” (not specified in other property definitions). Remove “also”. The value “0” should not be in special font (see criticality property).
• Definition of scores property mentions description but not values and names. Maybe, “A list of scores from automated or manual mechanisms to include name, value, and optional description.

I think this is ok

• Should embedded relationships be listed in the relationship table in Section 2.1.1? Would be helpful for a fuller overview.

The "style" is to only include new suggested relationships.

Section 2.2

• “During an attack attributed to the attacker” is awkward. How about “An Event is an activity attributed to the attacker.”
• Update end_time_fidelity and start_time_fidelity definitions: “If no value is provided, the timestamp should be considered accurate to the smallest unit specified with a non-zero value”
• Event_types definition: “summaries” —> summarization. Remove “in order”
• Need better definition of subevents property. What is a subevent vs an event?

Waiting on other Incident proposal - https://github.com/os-threat/cti-stix-common-objects

Section 2.4

• first sentence "An Task" --> "A Task
  /

NEW COMMENTS BELOW 2/8/24

• In the STIX spec, "All STIX Cyber-observable Objects" is in the red/pink font (but it isn't in the Event relationship table).

Section 2.3

• Suggest changing the first sentence to, "An Impact is the effect of an attack on the victim."

This has been changed to "An Event is an activity that has a harmful effect on the defender/victim."

• "integrity" spelled "integrety"
• Suggest changing "facets" to "categories" to align with the definition of the impact_category property. i.e., "There are many categories of impacts: availability of resources, ..."
• Description of impact_category property should start, "The category of impact. This MUST..." (don't need "this applies to")

Changed to "The category of impact this object applies to."

• Property definitions should be consistent with "this impact" vs "the impact."
• The "Impact Object Specific Properties" section at the top of the property table is missing "superseded_by_ref."
• Suggest rewording superseded_by_ref definition: "...It also MUST reference an impact in the category specified by the impact_category property."
• First sentence of section 2.3.2 doesn't make sense - maybe two sentences have been merged without a conjunction?
• Suggest rewriting sentence in 2.3.2: "As such every Impact MUST have one and only one extension from the category which matches the value of the impact_category property."
• These two sentences seem to conflict: (1) "every Impact MUST have one and only one extension" and (2) Producers SHOULD use one of these extensions. Who are the Producers and aren't they producing Impacts? Or is this sentence saying they should use one of the defined ones rather than defining their own?

Changed to:
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.
Producers and consumers are terms from the spec's Conformance section

• Definition of "availability_impact": replace "it" with "impact" or remove "that references it."
• Time fidelity (here and other locations): saying, "the number of decimals" doesn't make sense. In STIX, there is text that says, "The minimum precision MUST be milliseconds (three digits after the decimal place in seconds)." Similar terms should be used - for example, "precision" instead of "fidelity" and "digits" instead of "decimals" and "decimal point" when/if needed.

Changed to "decimal digits". I think fidelity is a slightly different concept than precision.

• Check that the definitions for time fidelity properties are as intended - they vary between SDOs.
• [] Should the *_time_fidelity properties be instead *_time_precision?
• Remove the word "optional" from property descriptions because it's redundant (already specified after the property name). e.g., "impacted_entity_counts (optional)."
• Section 2.3.1 Relationships has no text. Should embedded relationships be listed? If there are no relationships to define and embedded relationships will not be listed, then include text such as "No relationships are defined."

Section 2.4

• Should the first sentence be more inclusive, not just activity performed by the victim? could be a variety of performers.

Changed to: A Task is an activity that is performed by or for the victim/defender to respond to the attack.

• If a Task is marking a singular time - for example a "detection" task that corresponds to detecting the Incident, then both the start_time and end_time properties would be defined and they would be identical (by team discussion), but the description for end_time says that if both are defined, end_time must be later than start_time.
• Description of the description property: revise to "A description of the task" (missing "the" and to say it occurred implies it has finished (could be ongoing).

[dzbeck]

/Comments 2/12/24

• Abstract: the formatting looks odd for "event#s" and "[stixtype]incidents#."

Section 2.1 Incident Core

• determination property description: value "suspected" should be in quotes (or special blue-background font) in the first paragraph. Same for "blocked" in the last line of the second paragraph.
• criticality description: suggest, "If present, the value MUST be an integer between 0 and 100."
• detection_methods description: suggest, "A list of strings corresponding to the methods used to detect the activity..."
• impacted_entity_counts description: "A listing..." (not "An") and last sentence, "...it should be included..." (not "they").
• incident_types description: different format than other properties. Suggest removing "This property uses an Open Vocabulary" and use, "A list of incident types that occurred."
• tasks description: should be task-entry, not event-entry.
• impact_refs description: missing period. Suggest test "A list of impacts of the incident. The value of this property MUST be the identifier for an Impact object."
• the properties repeat in the table - after tasks, starts again with impact_refs through tasks.

Section 2.1.1 Relationships

• suggest, "Because of this, some of these relationships can be created without using the relationship types defined in this extension."
• STIX spec puts "related-to" relationship type in the blue background font. If not using special font, use quotes.
• remove "or locations" from located-at description.
• associated-with description: suggest "The campaign is associated with the incident." (if you want to say, "The incident is part of the campaign" then "part-of" is the better relationship type, as a forward, not reverse relationship). Don't need "in question" in any case.
• targets description: should it be "The incident targets the identity or infrastructure."? (or "targeted" - but not "was targeted at") Should "identity" instead of "victim" be used to match the SDO?
• Why do some descriptions use "An X" and others "The X" - suggest they all be "The X."
• detected description: suggest, "The indicator detected the incident."
• In the STIX doc, SDO names are capitalized. Suggest doing the same throughout this document. E.g., "The Incident targets the Identity or Infrastructure."
• Also, STIX uses the phrase, "This Relationship describes that..." Might want to do the same in this doc?? E.g., "This Relationship describes that the Incident targets the Identity or Infrastructure."

Section 2.2

• fix nouns so they match, suggest: "Events can be used to further enrich and explain Sightings by allowing analysts to indicate if THE SIGHTINGS are part of a potential threat, and if so, how THEY CONNECT to a larger incident."
• capitalize "SDO"
• end_time_fidelity description: font of end_time should be bold face.
• (J) event_types description is odd. Suggest, "A list of high-level types for the Event to enable aggregation and summarization." Also, should be "The values of this property..." (plural).
• subevents description: "tied" could be interpreted in different ways - suggest using "related" instead.

Section 2.2.1 Relationships

• says "For their definitions, please see the "Source" object" but the descriptions are given (in the STIX doc, the description for reverse relationships says, "See forward relationship for definition."
• led-to description: suggest using "led to" in the example instead of "allowed."
• impacts description: add "While not all SCO types will make sense as infrastructure, allowing any type of SCO prevents artificially restricting what could be used."
• located-at description: in terms of a single SRO, what would it mean for an event to occur at specific locations (plural)? should it be only "location"?
• (J) Should there be reverse relationships "identity performed event" or "threat-actor performed event"?

Section 2.3 Impact

• first sentence, "category" is missing an "e."
• After reading the property descriptions of the Impact extensions in Section 2.3.2, which refer to "the incident," I think there should be a sentence in the Section 2.3 intro about how Impacts relate to an Incident, e.g., that the relationship is captured via the Incident impact_refs property. Then the incident can be referred to as "the related incident" in the property descriptions of the Impact extensions.
• impact_category description: "The category of impact this object applies to" is confusing - the impact does not apply to a category - rather, the category describes the impact object. How about, "The category of the impact" or "The category to which the impact belongs"?
• criticality description: "If present, the value MUST be an integer between 0 and 100."
• description description: suggest, "A description of the impact."
• impacted_entity_counts description: should it have the additional text like the property under Incident Core?
• impacted_refs description: suggest, "A list of impacted entities, such as infrastructure. The value of this property MUST be the identifier for a SDO or SCO."
• superseded_by_ref description (1/2): suggest, "The referenced impact supersedes this impact at the end_time." (it's unclear whether "this one" and "the current impact" are the same impact).
• superseded_by_ref description (2/2): suggest, "When this property is populated, this impact MUST have an end_time, and the superseded_by_ref value must reference an impact of the same category as specified in the impact_category."

Section 2.3.1

• closing parenthesis missing in first sentence: "(duplicate-of, derived-from, related-to)"

Section 2.3.2

• Not sure on the purpose of the phrase "The Impact SDO is currently an extension" - suggest beginning with, "There are many types of impacts, each with its own unique properties, so the Impact SDO emulates the File SCO and uses STIX Extensions to provide the specific details." Also, instead of "the one extension" suggest "exactly one extension."
• Suggest a simple transition sentence, "Seven extensions to the Impact SDO, which further define the impact on a related Incident, are given below."
• Suggest replacing "the incident" with "the related incident" in property descriptions in Section 2.3.2.1-2.3.2.7 (relates to suggestion above).

Section 2.3.2.1

• availability_impact description: suggest, "The availability / functional impact 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 incident."
• add "an integer", i.e., "This value MUST be an integer between 0 and 100."

[dzbeck]

comments 2/13/24

Section 2.3.2.2

• information_type description: what is "This" in the sentence "This can include control systems and other processes that can result in virtual or physical impacts" - makes it sound like "control system" is an information type.
  Suggest just saying, "The type of information that had its confidentiality compromised."
• Should "virtual" vs "physical" impact be captured in a property? (a virtual impact like there is a physical impact?)
• "none" should be a special font or in quotes
• properties should be in bold face throughout document.
• loss_type description: suggest "The type of loss that occurred." ("to the relevant information" doesn't make sense.) ("to the relevant information" doesn't make sense.) or maybe, "The type of loss that occurred with respect to the relevant information."
• previous tables have required properties listed before optional.
• record_count description: remove "of this type" (assumed).
• record_count description: what is a "record"?

Section 2.3.2.3

• what does "direct organization" mean? Does that mean the targeted organization? or the organization reporting the Incident?

Section 2.3.2.4

• should the property be "alteration_type"? Should "integrity" be part of the description?
• alteration_type description: suggest something like, "...performed against the information that was compromised?" I.e., the information is altered, not the information_type.
• information_type description: see comment from Section 2.3.2.2 about "This"
• put ov and enum values in quotes.

Section 2.3.2.5

• why not call the variety property "monetary_impact_type"?
• (J) currency description: suggest "This SHOULD match an organization's primary currency or the currency of the government reporting the currency request." (not sure this is the intended meaning)
• (J) I don't understand the difference between currency and currency_actual. Is it the currency requested (in which case call it "currency_requested")?
• (J) conversion_time description: should this be when the rate was queried or when the conversion was made? Add "value" - "This value MUST be..."
• property values should be in bold face.
• (J) conversion_rate description (1/2): be more explicit regarding the direction of the conversion rate. I.e., is it currency/currency_actual? or currency_actual/currency? --> should be currency_actual/currency.
• (J) conversion_rate description (2/2): check space between sentences. Maybe combine, e.g., "This MUST be included if the currency_actual property and/or min_amount property is included."
• (J) max_amount and min_amount properties: suggest removing "damage" - monetary impact won't always be damage. Also maybe remove "estimate" - the max and min range is an estimate. Specify what is meant by "currency." Suggest something like, "The maximum monetary amount of the impact using the currency specified in the currency property." Also, last sentence remove "the" before "min_amount" (or add "the" to other properties in the sentence).

Section 2.3.2.6

• (J) asset_type description: "The type OF property..." Suggest using "asset" - for example, "The type of asset (property or system) that was affect by the physical impact."
• use special font or use quotes on vocab/enum values (e.g., "none").

Section 2.3.2.7

• (J) should traceability_impact be just "traceability" (properties of other subtypes don't append "impact," e.g., "alteration").
• (J) the traceability-enum: Is "traceability" the same as "accountability"? suggest changing values of the enum to use "traceability" instead of "accountability." (or vice versa).
• (J) traceability_impact description: suggest removing "of this incident"

[dzbeck]

comments 2/14/24

Section 2.4

• first sentence: should it be "...to respond to the incident" (instead of "attack")?
• changed_objects description: suggest, "A list of changes to objects as a result of the task." should be "a task" (not "an).
• task_types description: “summaries” —> summarization. Remove “in order”
• see previous question about requiring the end_time to be later than the start_time (e.g., detection task).
• priority description: add "an integer" and make "0 and 100"
• subtasks description: "tied" could be interpreted in different ways - suggest using "related" instead.

Section 2.4.1

• says see the forward relationship for the definition, but the descriptions are given below.
• (J) Suggest, "Sequences of tasks SHOULD NOT be shared using relationship objects."
• (J) Suggest, "Sequences SHOULD be shared within an Incident or Task using the tasks or subtasks properties, respectively.
• Back in Section 2.1, the tasks property description should have "as a list of TASK-entry"
• last sentence suggest: "Using these embedded relationships ensures [add s] that an incomplete sequence cannot be shared accidentally (avoiding potential confusion or misunderstandings when processing STIX data).
• various relationship type descriptions: why is "was performed that" added? seems better without - e.g., A task causes an event
• in reverse relationship descriptions: why is "specific" necessary?

Section 3

• The description makes it sound like every dictionary must include all entity types. Should it be something like, "The name of an entity type MUST be specified as a key in the dictionary and the count of the entity type MUST be specified as the corresponding value"?

(J) Section 3.2

• next_steps description: "describes the current event flows into the next one" is unclear.
• Should "sequence chain" be defined? Should it be "event sequence" instead of "sequence chain"?

(J) Section 3.3

• section description unclear. Does a sequence store all subsequent steps or just the next?
• is "stored in an array of steps" an extension/spec thing or an implementation thing?
• event_ref description: "The identity" makes it sound like an identity object. Maybe just "The event described by this entry" or maybe "The identifier of the event described by this entry"?
• all descriptions could use reworking to make the meaning clear.

Section 3.4

• (J) why isn't "value" called "score"?
• name description: confused by the brackets notation. What does "automated exposure score" refer to?
• description description (1/2): suggest, "Description of how the score was calculated."
• description description (1/2): meaning unclear... does "for systems that provide this information" mean that not all systems will provide this info or that the description will be used by some systems?

(J) Section 3.5

• add "property" : "The initial_ref or result_ref property MUST be populated."
• state_change_type description: is "influenced" the correct word?
• initial_ref description: what is an object state? ("The initial object state that this event affected"). Revise to make meaning more clear.
• These descriptions say "MUST reference the same type of SDO" - same as what? same as the event? or maybe this object type doesn't only apply to events?

(J) Section 3.6

• "The identify of the task" - should it be "the identifier" of the task?
• Seems like "This MUST reference a task" is redundant since the first sentence is "The identifier of the task..."
• all descriptions could be refined for clarity.

[dzbeck]

comments 2/15/24

Section 3.6

• just as the Task Sequence object is described, the Task Entry object should be described too, to explain its role in the extension.

(J) Section 3.7

• is "stored in an array of steps" an extension/spec thing or an implementation thing? If an implementation consideration, should make that clear.
• task_ref description: change "identity" to "identifier"
• condition_type and transition_type descriptions are currently sentence fragments. Suggest revising for clarity and readability.

Section 4.4

• should references (here and from other places) be put in a reference section?

Probably :-)