diff --git a/guides/sbom/relationships.md b/guides/sbom/relationships.md index 8ebd9a3..32f0be4 100644 --- a/guides/sbom/relationships.md +++ b/guides/sbom/relationships.md @@ -25,24 +25,26 @@ page_nav: --- # Establishing Relationships in CycloneDX + CycloneDX has a rich set of relationships that provide additional context and information about the objects in the BOM's inventory. All relationships in CycloneDX are expressed explicitly. Some relationships are declared through the natural use of the CycloneDX format. These include assemblies, dependencies, and pedigree. Other relationships are formed via -references to the object's identity in the BOM, referred to as `bom-ref`. The combination of these two approaches -dramatically simplifies the specification, providing necessary guardrails to prevent deviation of its usage and providing +references to the object's identity in the BOM, referred to as `bom-ref`. The combination of these two approaches +dramatically simplifies the specification, providing necessary guardrails to prevent deviation of its usage and providing an easy path to supporting enveloped signing and other advanced usages. ## Component Assemblies -Components in a BOM can be nested to form an assembly. An assembly is a collection of components that are included in a -parent component. As an analogy, an automotive dashboard contains an instrument panel component. And the instrument panel -component contains a speedometer component. This nested relationship is called an assembly in CycloneDX. -Software assemblies that can be represented in CycloneDX can range from large enterprise solutions comprising multiple -systems, to cloud-native deployments containing extensive collections of related micro-services. +Components in a BOM can be nested to form an assembly. An assembly is a collection of components that are included in a +parent component. As an analogy, an automotive dashboard contains an instrument panel component. And the instrument panel +component contains a speedometer component. This nested relationship is called an assembly in CycloneDX. + +Software assemblies that can be represented in CycloneDX can range from large enterprise solutions comprising multiple +systems, to cloud-native deployments containing extensive collections of related micro-services. Assemblies can also describe simpler inclusions, such as software packages that contain supporting files. -> Assemblies, or leaves within an assembly, can independently be signed. BOMs comprising component assemblies from -> multiple suppliers can benefit from this capability. Each supplier can sign their respective assembly. The creator of +> Assemblies, or leaves within an assembly, can independently be signed. BOMs comprising component assemblies from +> multiple suppliers can benefit from this capability. Each supplier can sign their respective assembly. The creator of > final goods can then sign the BOM as a whole. The following example illustrates a simple component assembly. In this case, Acme Commerce Suite includes two other @@ -82,18 +84,19 @@ Component D and E. If Component C depends on either D or E, dependency relations ![Assemblies](../../../theme/assets/images/guides/SBOM/assemblies.svg) ## Service Assemblies + Services also have assemblies and work identically to those of components. While component assemblies describe a component -that _includes_ another component, service assemblies describe a service with other services _behind_ it. A common cloud -pattern is the use of API gateways which proxy and orchestrate connections to relevant microservices. The microservices -themselves may not be directly accessible; rather, they are accessed exclusively through the API gateway. For this +that _includes_ another component, service assemblies describe a service with other services _behind_ it. A common cloud +pattern is the use of API gateways which proxy and orchestrate connections to relevant microservices. The microservices +themselves may not be directly accessible; rather, they are accessed exclusively through the API gateway. For this scenario, the API gateway service may contain an assembly of microservices behind it. ## Dependencies -CycloneDX provides the ability to describe components and their dependency on other components. This relies on a -component's `bom-ref` to associate the component with the dependency element in the graph. The only requirement for bom-ref -is that it is unique within the BOM. Package URL (PURL) is an ideal choice for bom-ref as it will be both unique and -readable. If PURL is not an option or not all components represented in the BOM contain a PURL, then UUID is recommended. -A dependency graph is typically one node deep and capable of representing both direct and transitive relationships. + +CycloneDX provides the ability to describe components and their dependency on other components. +This relies on a component's `bom-ref` to associate the component with the dependency element in the graph. The only requirement for `bom-ref` +is that it is unique within the BOM. Package URL (PURL) is an ideal choice for `bom-ref` as it will be both unique and readable. If PURL is not an option or not all components represented in the BOM contain a PURL, then UUID is recommended. +A general dependency graph is unspecified deep and capable of representing both direct and transitive relationships. In CycloneDX representation `dependencies`, a dependency graph SHOULD be codified to be one node deep, meaning no nested child-graphs but all relations on the same level. ![Sample Dependency Graph](../../../theme/assets/images/guides/SBOM/dependency-graph.svg) @@ -130,8 +133,8 @@ The dependency graph above can be codified with the following: ] ``` -> Components that do not have dependencies MUST be declared as empty elements within the graph. Components not -> represented in the dependency graph MAY have unknown dependencies. It is RECOMMENDED that implementations assume this +> Components that do not have dependencies MUST be declared as empty elements within the graph. Components not +> represented in the dependency graph MAY have unknown dependencies. It is RECOMMENDED that implementations assume this > to be opaque and not an indicator of a component being dependency-free.