SCITT Usage Examples

README.md

@@ -41,4 +41,4 @@ A SCITT instance will persist verifiable claims to its ledger. Any optional evid
 
 While a SCITT instance should provide a default storage, there's no limit on what storage services are used. For package managers that support breadths of content types, the evidence may be stored alongside the artifact by which the claim is being made. For package managers that limit the content types to the specific package type, a SCITT instance should provide default storage persistence.
 
-For more info, see: [Supply Chains]({% link supply-chain.md %})
+For more info, see: [Supply Chains](./supply-chain.md)

examples/README.md

@@ -0,0 +1,13 @@
+---
+layout: page
+title:  "SCITT Use Case Examples"
+nav_order: 110
+---
+# Examples
+
+To support the [SCITT Use Cases][use-cases], the following examples are illustrated.
+
+- [Binary Use Case: Multi-Version Product Support, With Third Party Statements of Quality](./feed-binary-usecase.md)
+
+[use-cases]:       https://datatracker.ietf.org/doc/draft-ietf-scitt-software-use-cases/
+

examples/feed-basic-example.md

@@ -0,0 +1,117 @@
+---
+layout: page
+title:  # Feed Basic Example
+parent: Examples
+nav_order: 20
+---
+
+# Feed Basic Example
+
+SCITT provides the registration, persistance and querying of a series of Transparent Statements over the life of the Artifact.
+
+Producers and Third Parties create and register Signed Statements on one or more SCITT Services. And Consumers query one or more SCITT Services for information about software they wish to evaluate.
+
+To demonstrate how SCITT Implements this workflow, a collection of scenarios and examples are provided using the [SCITT Community API Emulator](https://github.com/scitt-community/scitt-api-emulator) and [SCITT.xyz](https://scitt.xyz)
+
+## Scenario: Series of Transparent Statements Over the Life of an Artifact
+
+As a producer publishes a software artifact, they make a SCITT Feed available to provide a series of statements about the Artifact.
+
+For this example, we'll use the [Wabbit Networks](./fictitious-companies.md#wabbit-networks) Network Monitor Software.
+Using SCITT Terminology, the Artifact is a specific versioned release of the net-monitor binary.
+And a Feed is created to provide the series of Statements about the Artifact.
+
+Put simply, a Feed represents a specific Artifact, with a series of statements placed on the Feed.
+
+**Note:** _For the examples below, the contents of statements are opaque to the SCITT Service.
+The SCITT Service doesn't parse or understand what an SBOM, VEX, Patch, New Version is.
+The Transparent Statements have a `contentType` that enables clients to parse the specific content types._
+
+1. On January 1, 2023 Wabbit Networks publishes V1 of their Net-Monitor software, targeting Linux environments
+2. At the time of release, Wabbit Networks publishes SBOMs in both SPDX and Cyclone DX Formats, as well as a Security Scan Result from [Cosmic Security](./fictitious-companies.md#cosmic-security)
+3. As time progresses, and new issues are discovered about components used within the build and release of the net-monitor binary, Wabbit Networks releases updated Scan Reports and updated VEX reports
+4. As new patches are released, Wabbit Networks updates the Feed with information that informs of the new patched version, which is likely a new Feed
+5. As new versions are released, Wabbit Networks updates the relevant Feeds of the new versions, which are likely new Feeds
+6. As versions become out of support, Wabbit Networks publishes statements to the feed, indicating End of Support, (also known as EOL)
+7. As Wabbit Networks as third parties provide security reviews each Feed, the third party may submit their Signed Statement (the security review) to each Feed
+
+## Overview of the Steps
+
+Ultimately, a Feed is the identifier used to query a series of statements about an Artifact.
+
+A few constructs are assumed:
+
+- A Feed should is defined by the issuer of the artifact
+- Other parties can reference the same Feed, making additional statements, signed with their identity
+  - Other parties, if permitted by the registration policy of the publishers SCITT instance, can publish Signed Statements to the same Feed
+  - To enable autonomy, other parties can publish Signed Statements to a different SCITT instance, about the same Feed
+- From a SCITT perspective, the Feed ID is a string as trying to solve the one global unique identifier for software, hardware, content and other types is beyond the scope of SCITT
+- Consumers need to be able to find the Feed ID, based on nothing more than having reference to the artifact they wish to discover information
+- As SCITT supports Signed Statements, issued by an Identity, the following proposal uses the Identity of the Signed Statement as the Identity associated with the Feed
+
+This does leave open the question, what is the content of Signed Statement that defines the Feed?
+
+1. It could be the binary the Feed is based upon
+1. It could be an empty Statement that is simply used as the anchor for the feed, where the binary is subsequently added as one of the many contents associated with the Feed
+
+### Binary in the Feed Identifier
+
+In this scenario, the net-monitor binary is the content of the Statement used to initiate the Feed ID.
+
+The benefits include a bit of simplicity as there's less abstraction as the binary=the feed.
+
+1. Create a Signed Statement that identifies the Feed Id
+
+    ```sh
+    --content-type application/octet-stream
+    --payload "@net-monitor"
+    --identity <Wabbit Networks Key Material>
+    --Feed <nil>
+    --Reg_Info content-hash: <hash of the net-monitor binary> # used for subsequent querying
+    ```
+
+2. Register the signed statement to the SCITT Instance
+3. Capture the Entry ID as the Feed ID
+
+As a result, there is one Transparent Statement on the append-only ledger representing the binary and the Feed.
+
+Subsequent statements, such as the SBOMs, VEX and Scan Reports use the above Feed ID
+
+### Empty Statement as the Feed Identifier
+
+In this scenario, a statement is created that effectively has no content.
+While content could be created, it infers the SCITT Service would need to understand the `contentType` of the Statement.
+
+The benefits of this approach is the Feed isn't tied to a specific binary or file.
+This supports additional scenarios where someone is either tracking physical goods, or a document, (contract), which may change over time.
+
+**Note:** _By abstracting the Feed ID from a specific file, the application layer can query for specific content types, allowing a document to evolve over time.
+The consumer could ask if `<file hash>` is the latest version, and the service could provide the version history of that `contentType` (to elaborate in the document scenario)._
+
+1. Create a Signed Statement that identifies the Feed Id
+
+    ```sh
+    --contentType application/scitt/feed # maybe
+    --payload <nil>
+    --identity <Wabbit Networks Key Material>
+    --Feed <nil>
+    --Reg_Info name: <arbitrary name> # used for subsequent querying
+    ```
+
+1. Register the signed statement to the SCITT Instance, representing the Feed ID
+1. Capture the Entry ID as the Feed ID
+1. Create a Signed Statement for the root artifact: the `net-monitor` v1 binary _(similar to step 1 of above [Binary in the Feed Identifier](#binary-in-the-feed-identifier) )_
+
+    ```sh
+    --content-type application/octet-stream
+    --payload "@net-monitor"
+    --identity <Wabbit Networks Key Material>
+    --Feed <Entry ID from the above statement>
+    --Reg_Info content-hash: <hash of the net-monitor binary> # used for subsequent querying
+    ```
+
+1. Register the Signed Statement, with the Feed Id
+
+As a result, there are Two Transparent Statements on the append-only ledger representing the Feed, and the first entry representing a file on the Feed.
+
+Subsequent statements, such as modifications to the file (contract updates, scans of human wet/digital signatures), redirects to newer versions, updated contractual submission dates, use the above Feed ID

examples/feed-binary-usecase.md

@@ -0,0 +1,83 @@
+---
+layout: page
+title:  # Binary Use Case
+parent: Examples
+nav_order: 10
+---
+
+# Binary Use Case
+
+## Software Producer
+
+[Wabbit Networks](fictitious-companies.md#wabbit-networks) frequently releases their **Net Monitor** software.
+Their software is distributed as container images and loose binaries for Linux and Windows servers.
+They maintain multiple versions of their software, while releasing patched versions.
+
+Wabbit Networks provides SBOMs, VEX Reports with a Vendor Response File (VRF) for each of their releases.
+They occasionally need to issue new versions of the VRF, as well as updated VEX reports, because even while the software may remain unmodified the vulnerability landscape and Wabbit Networks' understanding of it is constantly evolving.
+
+### The Net Monitor Release Page
+
+Due to the complexity of different versions, platforms, architectures and product lines, companies and projects typically use marketing based navigation to assist users with their download choices.
+The below matrix is meant to visually represent a common matrix, that would be provided through marketing links.
+
+Versions and Patched Releases:
+
+- For each major release (`1.0.0`, `2.0.0`, `3.0.0`), there are a set of minor feature releases (`1.1.0`, `1.2.0`) with potential patches (`1.0.1`, `1.0.2`).  
+  <Note:> Vendors and projects use various forms of versioning, including [SemVer](https://semver.org/), [CalVer](https://calver.org/) and other forms.
+  SCITT must support any versioning scheme a producer wishes to support.
+- In the below examples, not all platforms have patches for a specific major or minor release.
+
+| Version | Linux Container | Linux Binary | Windows Container | Windows Installer |
+| - | - | - | - | - |
+| v1.0.0 | [net-monitor:v1.0.0-linux-amd64]() | [net-monitor-v1_0_0.gzip]() | [net-monitor:v1.0.0-win-amd64]() | [net-monitor-v1_0_0.msi]() |
+| -- v1.0.1 | [net-monitor:v1.0.1-linux-amd64]() | [net-monitor-v1_0_1.gzip]() | [net-monitor:v1.0.1-win-amd64]() | [net-monitor-v1_0_1.msi]() |
+| -- v1.0.2 | [net-monitor:v1.0.2-linux-amd64]() | [net-monitor-v1_0_2.gzip]() |  |  |
+| - v1.1.0 | [net-monitor:v1.1.0-linux-amd64]() | [net-monitor-v1_1_0.gzip]() | [net-monitor:v1.1.0-win-amd64]() | [net-monitor-v1_1_0.msi]() |
+| -- v1.1.1 |  |  | [net-monitor:v1.1.1-win-amd64]() | [net-monitor-v1_1_1.msi]() |
+| -- v1.1.2 |  |  | [net-monitor:v1.1.2-win-amd64]() | [net-monitor-v1_1_2.msi]() |
+| - v1.2.0 | [net-monitor:v1.2.0-linux-amd64]() | [net-monitor-v1_2_0.gzip]() | [net-monitor:v1.2.0-win-amd64]() | [net-monitor-v1_2_0.msi]() |
+| v2.0.0 | [net-monitor:v2.0.0-linux-amd64]() | [net-monitor-v2_0_0.gzip]() | [net-monitor:v2.0.0-win-amd64]() | [net-monitor-v2_0_0.msi]() |
+| - v2.1.0 | [net-monitor:v2.1.0-linux-amd64]() | [net-monitor-v2_1_0.gzip]() | [net-monitor:v2.1.0-win-amd64]() | [net-monitor-v2_1_0.msi]() |
+| - v2.1.1 | [net-monitor:v2.1.1-linux-amd64]() | [net-monitor-v2_1_1.gzip]() | | |
+| - v2.1.2 | [net-monitor:v2.1.2-linux-amd64]() | [net-monitor-v2_1_2.gzip]() | | |
+| - v3-alpha | [net-monitor:v3-alpha-linux-amd64]() | [net-monitor-v3-alpha.gzip]() | [net-monitor:v3-alpha-win-amd64]() | [net-monitor-v3-alpha.msi]() |
+
+### Questions for Producers
+
+When software producers wish to publish additional information for their products, how can they:
+
+- Let consumers know the most recently patched version for a specific platform/architecture release?
+- Let consumers know a new version is available?
+- Let consumers know an SBOM, VEX, VRF was verifiably published by the publisher?
+- Let consumers know a newer version of the SBOM, VEX, VRF was released, _and_ verifiably published by the publisher?
+
+> _[IETF SCITT Use Cases](https://www.ietf.org/archive/id/draft-ietf-scitt-software-use-cases-01.html#name-identify-statements-and-upd)_
+
+## Software Consumer
+
+[ACME Rockets](./fictitious-companies.md#acme-rockets) consumes the Net Monitor software from Wabbit Networks.
+They are currently using their version 1 release, and need to get notified of updates when they're available.
+
+## Third Party Security Vendor
+
+[Cosmic Security](./fictitious-companies.md#cosmic-security) evaluates the security posture of its customers, providing 3rd party analysis and validation.
+
+ACME Rockets subscribes to Cosmic Security to monitor the software they use within their environment.
+
+## End to End Integration
+
+ACME Rockets deploys the Cosmic Security products to monitor the software in their environment.
+Wabbit Networks publishes their security information through a public SCITT Service.
+For each product ACME Rockets consumes, a SCITT Feed Identifier is used to get the latest information about the products.
+
+Cosmic Security also publishes their perspective of the ACME Rockets software, as well as other vendors and projects.
+Cosmic Security publishes the information using a a SCITT Service that provides a series of statements associated with the Feeds of each of their products they consume.
+
+## References
+
+Examples of Product Download Pages
+- [OpenSCAD](http://openscad.org/downloads.html)
+  - [Images are currently available for platforms linux/amd64 and linux/arm64](https://hub.docker.com/r/openscad/openscad)
+- [Unity](https://unity.com/releases/editor/whats-new/2023.1.10)
+  - A collection of releases for Windows (`.exe`), Mac (`.pkg`), Linux (.`tar.xz`)

examples/feed-requirements.md

@@ -0,0 +1,25 @@
+---
+layout: page
+title:  # Feed Requirements
+parent: Examples
+nav_order: 5
+---
+
+# Feed Requirements
+
+1. Ability to associate a collection of statements to a root artifact
+   -. When submitting an SBOM, Vex, Statement of Quality, Recommendation for a new version, all need a simple id to associate them to a common artifact.
+1. To know a specific identity created the unique Feed ID
+   - If **Wabbit Networks** creates a feed ID of `abc-123`, other parties should know they're making additional statements to that unique ID
+   - **BadCo** shouldn't be able to create an alternate version of `abc-123` that fools other parties to submitting statements
+   - The determination that **Wabbit Networks** is a good entity and **BadCo** is a bad entity is outside the scope of SCITT
+   - SCITT should prohibit the creation of Feed IDs that can be duped by another entity
+1. Feeds produce a lineage of statements about a root artifact. The root artifact is arbitrary and may not be a specific file or asset
+   - A binary may be versioned over time, and the producer may decide to store different platform/architecture based versions on different feeds
+   - A document that is edited over time, may be kept on the same feed to see it's changes over time
+1. Feeds are not unique to a location. **Wabbit Networks** may host a feed for their net-monitor software
+   - Cosmic Security independently evaluates software, providing a rating  
+     They offer a SCITT Service with statements of quality to other products and projects. On the Cosmic Security scitt instance, the have a Feed-ID from **Wabbit Networks**
+   - The SCITT Transparent Statements are signed by Cosmic Security
+   - ACME Rockets can consume the software from Wabbit Networks, and statements of quality from Cosmic Security. They associate them by the Feed-Id
+   - ACME Rockets chooses to trust statements from Cosmic Security

examples/fictitious-companies.md

@@ -0,0 +1,43 @@
+---
+layout: page
+title:  # Fictitious Companies
+parent: Examples
+nav_order: 100
+---
+
+# Fictitious Companies
+
+To minimize context switching when reading through SCITT scenarios, Use Cases and Examples, a set of fictitious companies and personas are used.
+The companies and personas aim to represent sets of end-to-end scenarios.
+
+## Software Producers
+
+A set of software producers.
+
+### Wabbit Networks
+Wabbit Networks is a software company, specializing in network monitoring software.
+They distribute their software as container images and loose binaries for Linux and Windows servers.
+As consumers purchase different versions, Wabbit Networks maintain multiple versions of their software, while releasing patched versions.
+Over time, some versions become "End of Life" (EOL), where support is no longer provided.
+For each version that's marked EOL, a new supported version is provided.
+
+## Software Consumers
+
+Various consumers of software from various vendors and open source projects.
+
+### ACME Rockets
+
+ACME Rockets consumes the Net Monitor software from Wabbit Networks.
+ACME Rockets has multiple environments ranging from common software the use for Human Resources, services from cloud providers and specialized software for their launch systems.
+In addition, ACME Rockets manages a set of Satellite services, where they maintain and update the software deployed within the satellites.
+
+## Third Party Security Vendors
+
+A set of vendors that provide security perspectives and audits of software products and services.
+
+### Cosmic Security
+
+Cosmic Security evaluates software security, providing their customers 3rd party validation.
+They specialize in the unique requirements of aerospace companies that have unique challenges, such as how they secure launch systems, manufacturing and the software running in satellite deployments.
+The aerospace industry has a network of suppliers and vendors for CAD/CAM, 3D printing, materials and transport services.
+In addition to assuring the software runs across planetary and orbital environments are secure, they must also assure the documents shared across parties are also genuine.