Add more documentation around components[].scope

[noqcks]

The CycloneDX standard includes a scope attribute for each component:

I am confused about when one should use required, optional or excluded when generating an entry for a component. Are there any examples? Could the description be altered to make this more clear?

[prabhu]

This attribute can be deprecated in favor of evidence. The presence of an occurrence or a call stack evidence is proof that the component is definitely required. All other components could be treated as unknown to keep it safe.

Example:

consider CVE-2023-4910. Typically unit test files would be treated as a dev dependency and therefore as scope optional. However, there is direct occurrence evidence (even with an SBOM with a post-build lifecycle) so this component must be considered as required. However, the evidence alone is enough instead of setting another redundant attribute.

https://www.malwarebytes.com/blog/news/2023/11/owncloud-vulnerability-can-be-used-to-extract-admin-passwords

[stevespringett]

scope is a way to include a component but not assert that that component is delivered or included in the inventory. For example, you may want to include Windows XP Embedded as a component, mark the scope as excluded, as a way to indicate that the entire stack will include the OS, but that the supplier does not provide it with the software. There is ongoing discussions within CISA on how to specify runtime requirements. Expect this capability to expand in the future.

[stevespringett]

With that said, we will expand the documentation for v1.6. Thanks for the suggestion.

[jkowalleck]

JSON was fixed via d92e58e

XML and ProtoBuf already had the needed docs,
see

specification/schema/bom-1.5.xsd

Lines 857 to 880 in 46ff114

	<xs:simpleType name="scope">
	<xs:restriction base="xs:string">
	<xs:enumeration value="required">
	<xs:annotation>
	<xs:documentation>The component is required for runtime</xs:documentation>
	</xs:annotation>
	</xs:enumeration>
	<xs:enumeration value="optional">
	<xs:annotation>
	<xs:documentation>The component is optional at runtime. Optional components are components that
	are not capable of being called due to them not be installed or otherwise accessible by any means.
	Components that are installed but due to configuration or other restrictions are prohibited from
	being called must be scoped as 'required'.</xs:documentation>
	</xs:annotation>
	</xs:enumeration>
	<xs:enumeration value="excluded">
	<xs:annotation>
	<xs:documentation>Components that are excluded provide the ability to document component usage
	for test and other non-runtime purposes. Excluded components are not reachable within a call
	graph at runtime.</xs:documentation>
	</xs:annotation>
	</xs:enumeration>
	</xs:restriction>
	</xs:simpleType>