Content updates

Author: stevespringett

CBOM/en/0x02-Preface.md

@@ -1,12 +1,26 @@
 # Preface
 
-Secure supply chains are the foundational building block of modern cyber security. Without being able to describe a system’s components in a machine-consumable way, organizations and software consumers are in the dark if they are at risk of exploitation of known defects or vulnerabilities.
+Welcome to the Authoritative Guide series by the OWASP Foundation and OWASP CycloneDX. In this series, we aim to
+provide comprehensive insights and practical guidance, ensuring that security professionals, developers, and
+organizations alike have access to the latest best practices and methodologies.
 
-Software authors, from hobbyists to software vendors, can quickly adopt CycloneDX in their tooling, producing artifacts that will help consumers understand and manage the risk of the multitude of software that most organizations rely on daily.
+At the heart of the OWASP Foundation lies a commitment to inclusivity and openness. We firmly believe that everyone
+deserves a seat at the table when it comes to shaping the future of cybersecurity standards. Our collaborative
+model fosters an environment where diverse perspectives converge to drive innovation and excellence.
 
-A few years ago, I was involved in a project to review 1700 business-critical applications in 90 days for known software vulnerabilities. If the organization had access to CycloneDX SBOMs, this would have been a trivial task, time that could have been more usefully spent on remediation rather than discovery. Sadly, most of the time was spent working out what software had old faulty components rather than addressing the very real risk of known software vulnerabilities. We were plagued with false positives from the tooling we used simply because scanning software without SBOMs is a heuristic-driven discovery process that is inefficient and wastes a great deal of time we didn’t have. SBOMs resolve these issues, reduce costs, and reduce risk to all involved.
+In line with this ethos, the OWASP Foundation has partnered with Ecma International to create an inclusive,
+community-driven ecosystem for security standards development. This collaboration empowers individuals to contribute
+their expertise and insights, ensuring that standards like CycloneDX reflect the collective wisdom of the global
+cybersecurity community.
 
-I commend the CycloneDX team for a highly polished revision of their standard, one that evolves the state of the art.
+One standout example of this model is OWASP CycloneDX, which is on track to becoming an Ecma International
+standard through Technical Committee 54 (TC54). By leveraging the strengths of both organizations, CycloneDX is poised
+to become a cornerstone of security best practices, providing organizations with a universal standard for software and
+system transparency.
+
+As you embark on your journey through this Authoritative Guide, we encourage you to engage actively with the content
+and join us in shaping the future of cybersecurity standards. Together, we can build a safer and more resilient digital
+world for all.
 
 ---
 

CBOM/en/0x40-Practical-Examples.md

@@ -51,11 +51,7 @@ AES-128-GCM and SHA512withRSA.
   }
 ]
 ```
-A complete example can be found at [https://cyclonedx.org/shortcut/example/algorithm](https://cyclonedx.org/shortcut/example/algorithm)
-
-<div style="page-break-after: always; visibility: hidden">
-\newpage
-</div>
+A complete example can be found at [https://cyclonedx.org/shortcut/example/algorithm](https://cyclonedx.org/shortcut/example/algorithm)  
 
 An example with the QSC Signature algorithm Dilithium5 is listed below.
 

CBOM/en/0x41-Dependencies.md

@@ -0,0 +1,57 @@
+# 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 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. All
+relations are on the same level.
+
+Refer to the [CycloneDX Authoritative Guide to SBOM](https://cyclonedx.org/guides/) for additional details.
+
+In the context of cryptographic dependencies, CycloneDX provides some additional capabilities. As of CycloneDX v1.6, 
+there are two types of dependencies: `dependsOn` and `provides`.
+
+| Dependency Type | Description |
+| --------------- | ------------|
+| `dependsOn` | The `bom-ref` identifiers of the components or services that are dependencies of this dependency object. |
+| `provides` | The `bom-ref` identifiers of the components or services that define a given specification or standard, which are provided or implemented by this dependency object. For example, a cryptographic library that implements a cryptographic algorithm. A component that implements another component does not imply that the implementation is in use. |
+
+
+The dependency type, dependsOn, is leveraged by classic SBOMs to define a complete graph of direct and transitive 
+dependencies. However, for cryptographic and similar assets, "provides" allows for many additional use cases.
+
+![Dependencies](./images/dependencies.svg)
+
+The example shows an application (nginx) that uses the libssl cryptographic library. This library implements the TLSv1.2
+protocol. The relationship between the application, the library and the protocol can be expressed by using the 
+dependencies properties of the SBOM standard.
+
+Since a TLS protocol supports different cipher suites that include multiple algorithms, there should be a way to 
+represent these relationships as part of the CBOM. Compared to adding the algorithms as "classic" dependencies to the 
+protocol, we defined special property fields that allow referencing the deployment with additional meaning.
+The protocolProperties allows adding an array of algorithms to a cipher suite as part of the cipher suite array. 
+By modeling and then referencing these algorithms, we can still have only one classical component at the SBOM level but 
+a subtree of crypto dependencies within the crypto asset components.
+
+The following example illustrates a simple application with a dependency on a cryptographic library, which, in turn,
+implements AES-128-GCM. The cryptographic library also depends on another library.
+
+```json
+"dependencies": [
+  {
+    "ref": "acme-application",
+    "dependsOn": ["crypto-library"]
+  },
+  {
+    "ref": "crypto-library",
+    "provides": ["aes128gcm"],
+    "dependsOn": ["some-library"]
+  }
+]
+```
+
+<div style="page-break-after: always; visibility: hidden">
+\newpage
+</div>

CBOM/en/0x50-Dependencies.md

@@ -0,0 +1,53 @@
+# Decoupling CBOM From SBOM With BOM-Link
+With CycloneDX, it is possible to reference a BOM, or a component, service, or vulnerability inside a BOM from other 
+systems or other BOMs. This deep-linking capability is referred to as BOM-Link and is a
+[formally registered URN](https://www.iana.org/assignments/urn-formal/cdx), governed by [IANA](https://www.iana.org),
+and compliant with [RFC-8141](https://www.rfc-editor.org/rfc/rfc8141.html). 
+
+**Syntax**:
+```ini
+urn:cdx:serialNumber/version#bom-ref
+```
+
+**Examples**:
+```ini
+urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1
+urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#componentA
+```
+
+| Field        | Description                                                                       |
+| ------------ | --------------------------------------------------------------------------------- |
+| serialNumber | The unique serial number of the BOM. The serial number MUST conform to RFC-4122.  |
+| version      | The version of the BOM. The default version is `1`.                               |
+| bom-ref      | The unique identifier of the component, service, or vulnerability within the BOM. |
+
+There are many use cases that BOM-Link supports. Two common scenarios are:
+* Reference one BOM from another BOM
+* Reference a specific component or service in one BOM from another BOM
+
+### Linking an SBOM to a CBOM
+In CycloneDX, external references point to resources outside the object they're associated with and may be
+external to the BOM, or may refer to resources within the BOM. External references can be applied to individual
+components, services, or to the BOM itself. 
+
+The following example illustrates how an application in an SBOM can reference an external CBOM:
+
+```json
+"components": [
+  {
+    "type": "application",
+    "name": "Acme Application",
+    "version": "1.0.0",
+    "externalReferences": [
+      {
+        "type": "bom",
+        "url": "https://example.com/bom/acme-application-1.0.0-cbom.cdx.json",
+        "hashes": [ {
+            "alg": "SHA-256",
+            "content": "708f1f53b41f11f02d12a11b1a38d2905d47b099afc71a0f1124ef8582ec7313"
+        } ]
+      }
+    ]
+  }
+]
+```

CBOM/en/0x50-Linking.md

@@ -0,0 +1,20 @@
+# Attestations
+CycloneDX Attestations is a modern standard for security compliance. CycloneDX Attestations enable organizations with a 
+machine-readable format for communication about security standards, claims and evidence about security requirements, and 
+attestations to the veracity and completeness of those claims. You can think of Attestations as a way to manage 
+"compliance as code."
+
+## Cryptography Standards
+Organizations can declare the cryptography standards they follow, such as NIST or FIPS, in a CycloneDX Attestation. 
+This helps ensure that all parties involved in the software development and deployment process are aware of the required
+cryptography standards.
+
+By providing evidence such as test results, code reviews or other documents that prove that their software meets the 
+cryptography requirements, they enable automatic verification of compliance with the requirements. For example, it can be
+verified that only approved cryptography algorithms are used and implemented correctly.
+
+CycloneDX Attestations can also be used to manage compliance with cryptography requirements over time. As new 
+weaknesses are discovered or standards change, organizations can update their applications, and therefore their 
+attestations, to reflect the changes and ensure ongoing compliance.
+
+Refer to the [CycloneDX Authoritative Guide to Attestations](https://cyclonedx.org/guides/) for additional details.

CBOM/en/0x60-Attestations.md

@@ -63,11 +63,13 @@ themselves may not be directly accessible; rather, they are accessed exclusively
 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 
+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.
+A dependency graph is 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. All
+relations are on the same level.
 
 ![Sample Dependency Graph](images/dependency-graph.svg)