-
Notifications
You must be signed in to change notification settings - Fork 21
Proposal: Implement Report Object
- Status: Accepted
- Closed: March 23, 2015
- Issue: #223
Per previous conversations on the mailing list and in-person calls, the FS-ISAC Report Object Proposal has been accepted for version 1.2 of STIX. There was general (though not overwhelming) consensus that the implications were acceptable and that it should be added as part of a minor release.
During that decision making process, however, in order to focus on the big picture of whether or not to include the report construct at all certain decisions had to be made but the specifics of those decisions were not discussed by the community. This proposal presents in detail those decision points and requests specific comments on them. Two of the decision points are more extensive and therefore captured in separate proposals:
The rest will be described below and specific decisions will be called out for comment.
In STIX 1.1.1 the STIX_Package element is used to convey a set of STIX component content (Indicators, Campaigns, etc.) but may also optionally include a characterization of any context associating that content together (e.g. what type of content is it, is it related to a particular campaign, threat actor, TTP, etc.). As such, the common STIX_Package structure supports:
- a role as an "envelope" to contain content (Indicators, Campaigns, etc.)
- a role as a "report" to give context to some set of content (which may be defined elsewhere)
- a role as both the set of content (envelope) and the context for it ("report").
The addition of the Report construct means that in STIX 1.2 STIX_Package will only be used as an envelope, no longer as a report. The Report construct will be added to take over that role.
Functionally, this means that STIX_Package would continue to be the root element used to convey STIX content as it is today. Unlike today, however, the descriptive fields inside (Title, Package_Intent, Description, etc.) would be deprecated (and scheduled for removal in a later release) and therefore the default top-level STIX_Package could not be used to give a common title, package intent, etc. to a group of content. Instead, in order to convey that context the producer would include one or more explicit Report constructs that reference the content that was already conveyed and add the context that STIX_Package previously conveyed. This change explicitly separates the usage of STIX_Package as an envelope from the Report as a conveyer of shared context.
Note that this proposal does not expand the reporting capabilities currently in STIX. The new Report object will contain the same fields as the STIX 1.1.1 STIX_Package contains. Future versions of STIX do aim to improve these capabilities but that is not currently slated to be addressed in STIX 1.2.
With the addition of the Report construct, the old usage of STIXType to convey context will be deprecated. STIXType will become a context-less wrapper that simply holds content.
Aligned with that, the following fields are to be deprecated from STIXType or STIXHeaderType:
| Field | Reason for Deprecation |
|---|---|
@idref |
Deprecated because it does not make sense to reference a simple envelope |
@timestamp |
Deprecated because @timestamp is used only for versioning and it does not make sense to version a simple envelope |
STIX_Header/Title |
Used to convey shared context, so not necessary. Use a Report/Title
|
STIX_Header/Description |
Used to convey shared context, so not necessary. Use a Report/Description
|
STIX_Header/Short_Description |
Used to convey shared context, so not necessary. Use a Report/Short_Description
|
STIX_Header/Package_Intent |
Used to convey shared context, so not necessary. Use a Report/Intent
|
STIX_Header/Related_Packages |
This will be discussed in Proposal: Packages Cannot Contain other Packages |
Decision: Is this list of fields to be deprecated from STIXType correct?
The following fields will remain in STIXType with the described new usage (in some cases identical to previous usage):
| Field | New Usage |
|---|---|
@id |
Used for tracking and correlation but no longer for references |
@version |
Used to denote the STIX version that the content complies with |
STIX_Header/Profiles |
Profiles apply across a set of content which may or may not be related and therefore it still makes sense to assert them at the package level |
STIX_Header/Information_Source |
The Information_Source will describe the information source of the included bundle of content. Additionally, per the existing documentation for information source, the header-level information source is intended to be propagated to all content contained in the package, as an optimization to avoid having to repeat it individually for each piece of content. |
STIX_Header/Handling |
Handling is applied to content irrespective of shared context and therefore it still makes sense to provide this ability at the package level |
The add-report-object diff for stix_core.xsd contains the changes.
Decision: Is this list of fields to remain on STIXType correct?
The definition of the report object is taken by essentially cloning the current version of STIXType and removing fields that do not apply to reports but did apply to packages containing content. As explained above the reporting capabilities in the report object will be identical to those provided by STIX_Package in 1.1.1, there are no current plans (though that can be revisited) to extend them with the addition of the report construct.
The Report definition will include the following fields (fields with an asterisk* have different meanings than when they were present on STIX_Package):
| Field | Description |
|---|---|
@id |
Reports would have an ID field like all other major constructs to identify them, support versioning, and support references |
@idref |
Reports would have an IDREF field like all other major constructs to support references |
@timestamp |
Reports would have a timestamp field like all other major constructs to support versioning |
@version* |
Describes the version of the report object that is being conveyed (i.e. 1.0) |
Header |
The report header would contain much the same information as the current STIX_Package/STIX_Header. |
Header/Title |
Title of the report |
Header/Description |
Description of the report |
Header/Short_Description |
A short description of the report |
Header/Intent |
One or more intents behind the report |
Header/Handling* |
Would allow you to mark direct report content (but not top-level constructs referenced from the report) |
Header/Information_Source* |
Information source of the report itself (NOT any content referenced by the report) |
Header/Related_Reports |
Describes relationships between this report and others |
Observables, Indicators, Campaigns, etc.* |
Proposal: Reports Cannot Embed Content discusses how the content for a report could be conveyed |
The following fields were not carried over from STIX_Package:
| Field | Description |
|---|---|
@Profiles |
STIX profiles operate at the same level as schema validation (to entire bundles of content) and therefore will remain at the STIX_Package level |
The add-report-object diff for report.xsd contains the changes. (It's a new addition because 1.1.1 didn't have a report object).
Decision: Is the set of fields on the new Report object correct?
Currently, most top-level STIX constructs (everything except Observable) can reference a STIX_Package via Associated_Packages. That element would be deprecated and reports would always reference out to content. This is in line with current practices in STIX of minimizing double-sided relationships.
Decision: Should the Associated_Packages element be replaced with Associated_Reports or should it simply be deprecated?
- Is this list of fields to be deprecated from STIXType correct?
- Is the set of fields on the new Report object correct?
- Should the
Associated_Packageselement be replaced withAssociated_Reportsor should it simply be deprecated? - Should Reports be able to embed content?
- Should Packages be able to contain other Packages?
Feedback can be sent to the public STIX discussion list (make sure to join first), as a public comment on the github issue for the report object or sent privately to the core STIX team at [email protected].