diff --git a/assets/enotary.svg b/assets/enotary.svg new file mode 100644 index 0000000..1060780 --- /dev/null +++ b/assets/enotary.svg @@ -0,0 +1 @@ +eNotaryConceptual FlowLedgerSCITT InstanceStorageeNotaryreceiptClaim_EvidencePolicy123456 \ No newline at end of file diff --git a/assets/oci-consuming-public-content.png b/assets/oci-consuming-public-content.png new file mode 100644 index 0000000..6ecf5e5 Binary files /dev/null and b/assets/oci-consuming-public-content.png differ diff --git a/assets/oci-consuming-public-content.png:Zone.Identifier b/assets/oci-consuming-public-content.png:Zone.Identifier new file mode 100644 index 0000000..e69de29 diff --git a/assets/scitt-promotion.svg b/assets/scitt-promotion.svg new file mode 100644 index 0000000..382dd28 --- /dev/null +++ b/assets/scitt-promotion.svg @@ -0,0 +1 @@ +SCITT Claims PromotionLedgerInternal team ALedgerInternal team BLedgerPublic SCITT Service \ No newline at end of file diff --git a/canonical-customers.md b/canonical-customers.md new file mode 100644 index 0000000..b917a3f --- /dev/null +++ b/canonical-customers.md @@ -0,0 +1,38 @@ +# Canonical Customer Scenarios + +To provide a common reference across the SCITT documents and use cases, we'll use a few fictitious software and hardware companies. + +## Wabbit Networks + +A small software company, producing network monitoring software. Wabbit Networks is likely not known by most customers, and therefore needs some verifiable identity and claims to assure customers can trust their software. + +### Wabbit Networks Products + +Wabbit Networks produces several software products, including: + +- **Network Monitor**: Network monitoring software that customers run on their networks + - **`net-monitor:v1`**: V1 of a container image + - **`net evaluator`**: desktop installed software which evaluates the data generated by the net-monitor software +- **Device Drivers**: which are installed across a customers windows, mac and linux devices + +## ACME Rockets + +A small company that uses software to build and launch mission critical rockets. Like most companies, they consume software from multiple vendors and open source projects, and build internal systems to manage their operations. + +ACME Rockets has development teams, operational software and critical software that operates their launch systems and software on their rockets. + +ACME Rockets operates across multiple clouds and has on-prem software, including software that operates in space, the ultimate in offline, occasionally connected networks. + +## Public Software + +> NOTE: how do we feel about using existing public registries, by name/type, or will this get into details implying how they may/should implement their registry services? Should we use some abstract names, and defer future SCITT implementations. +> +> Assuming we keep with the agnostic names, we'll need some fun examples, across some common theme. + +### Container Base Images + +To enable custom app development, using containers, a set of base images are published on a public registry. Users build atop these base images, assuring the stream of updates meets their requirements. + +### Public Packages + +A set of public OSS packages available for consumption. diff --git a/scenarios/building-dependencies.md b/scenarios/building-dependencies.md new file mode 100644 index 0000000..6db1daf --- /dev/null +++ b/scenarios/building-dependencies.md @@ -0,0 +1,62 @@ +# Building and Consuming Dependencies + +You're starting down the path of securing your supply chain. You want to verify the sources (packages & components) you build from and with (sdks and compilers). +Before focusing on "a secure supply chain", you might simply have performed `npm restore`, `apt get` or select references from public registries. You might pull the base image you'll deploy with, or the sdk images you'll compile with from [docker hub][docker-hub]. + +How do you know those components are secured and reliable? +Is the latest the most secure, or just the latest build that may have pulled in the latest vulnerability or the latest simple human mistake? +Simply receiving signed components may not be enough to ensure complete security and reliability of the components. + +## Taking Ownership of the Artifacts You Depend Upon + +The first step of securing any supply chain is securing your dependencies, to assure you know what you're building upon. If you built against the foo package on monday, do you know you'll get the same result if you build against the same named reference on Wednesday? + +See [Consuming Public Content](https://opencontainers.org/posts/blog/2020-10-30-consuming-public-content/) for a reference to this workflow: +Consuming Public Content + +The workflow to import the artifacts you depend upon into your own managed registry applies to all the components, from the referenced packages, the sdks & compilers, to the container images your multi-stage container build depends upon. + +## Gated Import + +As you import the artifacts you depend upon, you can start to apply various checks, to see if the software meets your requirements. + +Does the dependency: + +- come from an identity you trust? +- have an SBOM that identifies what it was built from? +- have a recent security scan, you can confirm comes from an identity you trust? + +You may want to run additional security scans, or even unit and/or functional tests to assure the latest update functions as expected. + +As the import completes, the artifacts are stored in golden registries. + +### Golden Registry + +A golden registry is an internal instance that contains the approved artifacts a company should consider trusted. +Artifacts in golden registries have been through the gated import process. +However, just because the artifact has been vetted, doesn't mean the artifacts are applicable for all scenarios. +In comparison, although all employees of ACME Rockets have an ACME Rockets badge, are all employees of the company given the same access rights? + +## Stamps of Approval (Claims and Endorsements) + +How do you know the artifacts from the golden registries meet your companies requirements? +How do you know the artifacts approved for building software shouldn't be deployed to production as they may include tools that would be dangerous to run in a production environment? +Likewise, how do you know the artifacts approved for the marketing application aren't deployed to the critical financial environment? + +As you evaluate each artifact, you'll want to be specific for what environments it's approved for. In SCITT, these become claims or endorsements to query and verify against, to assure the specific artifact meets those requirements. + +During the import process, you'll either accept the claims and endorsements that may come with the package you're importing, or you may add a claim and/or endorsement that states it meets your companies requirements. + +When verifying a claim and/or endorsement, you'll want to assure the claims and endorsements originate from an identity you trust. + +## Import Workflow + +> TODO: complete the following steps. +1. + +### Discussion Points: + +- [Querying a SCITT instance for a specific claim](../scitt-components/claim-endorsement-spec.md) + + +[docker-hub]: http://hub.docker.com/ \ No newline at end of file diff --git a/scenarios/building.md b/scenarios/building.md new file mode 100644 index 0000000..e31887d --- /dev/null +++ b/scenarios/building.md @@ -0,0 +1,3 @@ +# Building Apps + +> Building the apps, based on dependencies \ No newline at end of file diff --git a/scenarios/extending-existing-services.md b/scenarios/extending-existing-services.md new file mode 100644 index 0000000..4d505c9 --- /dev/null +++ b/scenarios/extending-existing-services.md @@ -0,0 +1,14 @@ +# Extending Existing Services and Project with SCITT + +The IETF SCITT standards are designed to extend existing projects, products and services with a standards based way to push, discover, pull supply chain claims and evidence. + +## Adding SCITT APIs + +SCITT provides a set of API for pushing, discovering and pulling supply chain claims and evidence. + +By extending existing projects, products and services with SCITT apis, the users of the existing projects will add value to their services without having to configure yet another service, or configure yet more firewall rules. + +> TODO: +> - Image of SCITT APIs added to an existing service that's already in a VNet +> - How SCITT APIs can be added + diff --git a/scenarios/fuel-pump.md b/scenarios/fuel-pump.md new file mode 100644 index 0000000..6691065 --- /dev/null +++ b/scenarios/fuel-pump.md @@ -0,0 +1,6 @@ +# Hardware-Fuel Pump Scenario + +> TODO: +> - Builds on the IETF fuel pump scenario +> - Shows how SCITT supports specific instances of a product, where software has multiple copies that are all exactly the same, while hardware is multiple instances that evolve on their own (fuel pump drift between hot and cold climates) +> \ No newline at end of file diff --git a/scenarios/promoting-dev-test-prod.md b/scenarios/promoting-dev-test-prod.md new file mode 100644 index 0000000..f17b396 --- /dev/null +++ b/scenarios/promoting-dev-test-prod.md @@ -0,0 +1,2 @@ +# Promoting from Dev, Test to Production + diff --git a/scenarios/publishing-updates.md b/scenarios/publishing-updates.md new file mode 100644 index 0000000..57059e9 --- /dev/null +++ b/scenarios/publishing-updates.md @@ -0,0 +1,7 @@ +# Publishing Updates + +> NOTE: +> - What does publishing an update mean? +> - How do you communicate you have an update? +> - Is the update a security or feature update? +> - Is the old version "out of support" diff --git a/scenarios/redirection-revocation.md b/scenarios/redirection-revocation.md new file mode 100644 index 0000000..a7fcdc6 --- /dev/null +++ b/scenarios/redirection-revocation.md @@ -0,0 +1,10 @@ +# SCITT Redirection and Revocation + +> TODO: +> - When should revocation actually be used? +> - How to provide granularity, so revocation doesn't become a global DOS of the software supply chain +> - Identity theft, vs. individual artifact problems +> - H2 handle a new version is available +> - H2 handle an artifact is considered problematic, and for what circumstances is it problematic +> - H2 end of life of support, vs. it's "expired", and what does "expired mean" +> - Tease out elements of the Asbestos scenario from [Roles and Responsibilities of Signing, SBoMs, and Security Scanners](https://stevelasker.blog/2022/01/11/roles-and-responsibilities-of-signing-sboms-and-security-scanners/) \ No newline at end of file diff --git a/scenarios/sbom.md b/scenarios/sbom.md new file mode 100644 index 0000000..f227209 --- /dev/null +++ b/scenarios/sbom.md @@ -0,0 +1,4 @@ +# The SBOM Scenario + +> NOTE: intended to utilize the existing SBOM doc, with pointers to how it leverages the SCITT foundations, enabling us to iterate on the specifics of what SCITT provides and why + diff --git a/scitt-components.md b/scitt-components.md new file mode 100644 index 0000000..63bd323 --- /dev/null +++ b/scitt-components.md @@ -0,0 +1,40 @@ +# SCITT Components + +SCITT provides a set of components enabling Supply Chain, Integrity, Transparency and Trust. +(See [What Is SCITT][WHAT_IS_SCITT]) +But what are the scenarios, projects and products that SCITT enables? +This collection of docs will describe the core components of SCITT, and how it can be enabled and extended to support a breadth of use cases. + +As SCITT is in active design through the [IETF SCITT working group][SCITT_IETF_WG], these documents aim to facilitate various design discussions, based on a set of SCITT primitives and scenarios that benefit from the SCITT primitives. + +## Table of Contents + +The following is a list of documents we'll round out to enable discussions: + +- **Getting Started** + - [What is SCITT][WHAT_IS_SCITT]: a quick overview to get started + - [What are Verifiable Identities](scitt-components/verifiable-identities.md): The importance of every piece of info in a supply chain to be backed by a verifiable identity + - [Extending Existing Projects, Products and Services with SCITT](scenarios/extending-existing-services.md) + - [Types of Claims and Evidence Supported by SCITT](scitt-components/types-claims-evidence.md) + - [Original and Updated Claims & Evidence](scitt-components/categories-of-claims-evidence.md): How SCITT supports a continual stream of updates + - [Importance of Detached Signatures, Claims and Evidence](scitt-components/detached-artifacts.md) + - [eNotary & Policy](assets/enotary.svg): The role of the eNotary and ingestion policy +- **Scenarios SCITT Enables** + - [Canonical Customer Scenarios](canonical-customers.md): Wabbit Networks and ACME Rockets + - **Software Workflow** + - [Building and Consuming Dependencies](scenarios/building-dependencies.md) + - [Building Apps](scenarios/building.md) + - [SBOM](scenarios/sbom.md): Evidence, initiated at creation time + - [Promoting from Dev, Test to Production](scenarios/promoting-dev-test-prod.md) + - [Publishing Updates](scenarios/publishing-updates.md): how to communicate a new version is available, and does it supersede a previous version? + - [Revocation](scenarios/redirection-revocation.md): Claims that are continual updated as info of the product is learned. + - **Hardware Scenarios** + - [Fuel Pump Certification](scenarios/fuel-pump.md): hardware scenario where multiple instances of a product (the serial number) have individual claims and evidence +- **Design Discussions**: Areas for us drill in, to enable the above scenarios + - [Claims and Endorsement Format](scitt-components/claim-endorsement-spec.md): Discussion why SCITT needs a simplified format for the claims, with links to the evidence + - [One or Many Instances of SCITT](./scitt-components/one-or-many-instances.md): design goals and philosophy + - [RBAC](scitt-components/scitt-rbac.md): How SCITT enables limited access + - [Indexing Content Types](scitt-components/scitt-indexing.md): How SCITT is extensible to enable new, evolving content types + +[SCITT_IETF_WG]: https://datatracker.ietf.org/group/scitt/ +[WHAT_IS_SCITT]: https://ietf-scitt.github.io/scitt-web/ \ No newline at end of file diff --git a/scitt-components/categories-of-claims-evidence.md b/scitt-components/categories-of-claims-evidence.md new file mode 100644 index 0000000..ff15af8 --- /dev/null +++ b/scitt-components/categories-of-claims-evidence.md @@ -0,0 +1,13 @@ +# Categories of Claims and Evidence + +There are two main categories of information about any supply chain: + +1. What was known when the product was created? +1. What has been learned, since the product was created? + +## TODO: + +Describe the types of information that is + +- known at creation time. Including information that would be publicly disclosed, what might be kept for auditors, and what is kept in case bad stuff happens, and details are needed to remediate +- \ No newline at end of file diff --git a/scitt-components/claim-endorsement-spec.md b/scitt-components/claim-endorsement-spec.md new file mode 100644 index 0000000..aee33bf --- /dev/null +++ b/scitt-components/claim-endorsement-spec.md @@ -0,0 +1,9 @@ +# Claims & Endorsement Specification + +> TODO: +> - Why a spec for a claim is important, enabling query capabilities +> - Delta of a claim vs. evidence +> - Assumed it's the content of the COSE payload +> - Discussion for known claim values, likely with namespaces, enabling consumers to identify if a product is good for production, vs build, energy vs. gaming, financial vs. government, high security vs. critical security +> - Why simple name/value pairs are too simple +> - Why SBOM/in-toto formats are perfect for evidence types, but too complex to be the format for the claims placed on the ledger \ No newline at end of file diff --git a/scitt-components/detached-artifacts.md b/scitt-components/detached-artifacts.md new file mode 100644 index 0000000..73b11c9 --- /dev/null +++ b/scitt-components/detached-artifacts.md @@ -0,0 +1,8 @@ +# Detached Artifacts + +> TODO: Describe the importance for detached signatures, claims and evidence + +- Protection from Trojan Horse Scenarios +- Ability to continually add information to sealed artifacts and evidence +- Ability to filter what may/should be promoted across an ecosystem +- Ability to link to existing artifacts by unique IDs and hashes (NOTE: to track how we'll establish unique IDs and/or hashes) \ No newline at end of file diff --git a/scitt-components/enotary-policy.md b/scitt-components/enotary-policy.md new file mode 100644 index 0000000..147e735 --- /dev/null +++ b/scitt-components/enotary-policy.md @@ -0,0 +1,34 @@ +# SCITT eNotary + +The ability to configure the types of supported identities, with specific identity allow/deny configurations. + +SCITT provides a means to store information on a ledger. The information on the ledger is only as good as the validity of the identities making the entries. +Similar to a public notary, an eNotary verifies the identity of the incoming requests. +If the identity is verified, the eNotary will provide a notarized endorsement for the entry, issuing a receipt for the completed process. + +Also similar to a public notary, the eNotary process does not attempt to validate the evidence being notarized. +It verifies the identities and makes a ledger entry of the claims, with pointers to any optional evidence. + +## eNotary Conceptual Overview + +The eNotary provides the following conceptual workflow: + +1. A claim, (with optional evidence) is submitted to a SCITT instance +2. On ingress, the SCITT eNotary parses the identity associated with the claim and compares the identity type with those supported in the eNotary policy. +3. If the eNotary policy supports the identity type, the eNotary will attempt to verify the validity of the identity. +4. If the identify is verified, the optional evidence is submitted to an associated storage account. The reference to the persisted evidence is maintained +5. A notarized entry is made to the SCITT registry (ledger), endorsed by the eNotaries key. The optional evidence reference is persisted in the registry as a pointer. +6. A receipt is returned, endorsed by the eNotary + +SCITT eNotary + +## Claims Identity and SCITT Access Control + +To submit information to a SCITT instance, access control would most likely be enforced. +Standard Roles Based Access Control (RBAC) would provide the means to read/write information. +The RBAC type would be determined by the host of the SCITT instance, and likely implements cloud specific identity and authorization capabilities. +Details of RBAC are covered elsewhere. + +The identity associated with access control is often unrelated to the identity of the claims. +The claim identity may be a specific project, a build system, an auditor's report. +While the identity used for access control is captured in the ledger, and likely part of the receipt, the eNotary is validating the identity associated with the claim. diff --git a/scitt-components/one-or-many-instances.md b/scitt-components/one-or-many-instances.md new file mode 100644 index 0000000..e2a0b66 --- /dev/null +++ b/scitt-components/one-or-many-instances.md @@ -0,0 +1,16 @@ +# One or Many Instances of SCITT + +This document frames the design philosophy for multiple instances of SCITT, and how they interoperate with each other. + +## Topics to Cover + +- One global instance for all package types (public and private) + - The simplicity with the pros and cons +- Instances aligned with the distribution of projects & products + - A single instance for each software vendor/oss project? + - Instances of SCITT alongside the existing package managers/distribution points +- Private instances, for companies to manage their internal development +- How SCITT information is promoted across instances, and maintained as a constant stream of updates +- Public anonymous access +- Public authenticated access +- Private authenticated access \ No newline at end of file diff --git a/scitt-components/scitt-indexing.md b/scitt-components/scitt-indexing.md new file mode 100644 index 0000000..d506f81 --- /dev/null +++ b/scitt-components/scitt-indexing.md @@ -0,0 +1,10 @@ +# Indexing Specific Content Types + +> TODO: +> - SCITT must provide some level of indexing to find the most basic information (does artifact _**a**_ have claim _**b**_, but only return claims if it was submitted by identities _**x,y,z**_) +> - How will SCITT support new content types, who's evidence is stored in associated storage? Some SCITT instances will support SPDX, others CycloneDX. What happens when a new format appears (VEX as an example). Can the "vex team" implement a new indexer that any SCITT instance can add? Can SCITT provide an extensibility model enabling this pattern? + +> Assumptions: +> - SCITT doesn't store evidence on the ledger +> - SCITT has associated storage, or at least a PURL to find the evidence on some storage system +> - SCITT should provide query capabilities to query ont he info in the SCITT ledger, with extensibility to AND information that is stored externally. The returned results would provide PURLs (assumed to be a purl) to the location of the storage. This enables various subsystems to store content types, with SCITT adding value as a central indexing system, without owning the content \ No newline at end of file diff --git a/scitt-components/scitt-rbac.md b/scitt-components/scitt-rbac.md new file mode 100644 index 0000000..1be658d --- /dev/null +++ b/scitt-components/scitt-rbac.md @@ -0,0 +1,36 @@ +# SCITT Role Based Access Control + +> TODO: +> - Why we need limited access to information submitted to SCITT +> - Will SCITT support partitioned access within a SCITT instance, or will a SCITT instance be limited and only approved content is promoted to another SCITT instance that has broader access? + +## Promotion Across RBAC Instances + +Whether a SCITT instance supports RBAC partitioning or not, users will configure multiple SCITT instances to support their dev through production workflows, or their internal systems being maintained separate from their public services. Users can promote the content from internal, secured SCITT instances, to SCITT instances with different permissions, or public access. + +SCITT Instance Promotion + +## Design Options + +### RBAC at the SCITT Instance + +Any access to a SCITT instances means access to all content + +#### Pros + +Simpler to implement + +#### Cons + +- Teams that need to limit access within a SCITT instance will need to run multiple SCITT instances +- This may not work well when associating a SCITT instance with a registry/datastore that supports partitioned RBAC + +### RBAC Partitioning a SCITT Instance + +#### Pros + +- Maps to existing registries/storage services that support partitioning + +#### Cons + +- Harder to implement diff --git a/scitt-components/types-claims-evidence.md b/scitt-components/types-claims-evidence.md new file mode 100644 index 0000000..aef8b9a --- /dev/null +++ b/scitt-components/types-claims-evidence.md @@ -0,0 +1,29 @@ +# SCITT: Supported Types of Claims and Evidence + +The security of a supply chain must continue to evolve. +As a result, SCITT adopts a model of minimal fixed formats with full extensibility, enabling an ever evolving ecosystem of scenarios and evidence types. +Users will be able to submit verifiable claims and evidence to a SCITT instance, without concern that new evidence types may be limited. + +## Claims and Queries + +SCITT Claims have a minimal schema to enable stability across SCITT instances, where users can query claims, with links to optional evidence. However, the types of evidence to represent a claim is limitless. + +## Evidence + +The types of evidence we know today will quickly evolve. When we started the projects, SBOMs were just evolving, with two specific formats (SPDX and CycloneDX). +SCITT should not take a bet on any specific format, while specific users may. +New formats quickly evolve, such as VEX. Users must have the ability to adopt new formats, and the community must have a way develop new formats without having to focus on how they distribute or associate those formats with the supply chain projects. +As a result, a SCITT instance will support all types of evidence formats, with the option for how to query into them. + +## Evidence Indexing Extensibility + +All SCITT instances will have the ability to query a basic set of claims. +However, there will be concrete examples where a user will also need to query into specific evidence formats. + +**Example**: What artifacts are currently deployed in production, and have the log4j component? + +In the above example, the user could query the SCITT ledger for the claim `deployed-to-production:prod-a`. If the SCITT ledger simply returned all the software currently deployed, requiring a query of a separate system for their SBOM format of choice, the value quickly diminishes. If the SCITT instances supported index extensibility, someone could write the SPDX or CycloneDX indexer allowing the user to write a query that finds the production deployed projects, AND those that have log4j in their SBOMs. + +## Design Discussions: + +- [SCITT Indexing](scitt-indexing.md) diff --git a/scitt-components/verifiable-identities.md b/scitt-components/verifiable-identities.md new file mode 100644 index 0000000..191c0ad --- /dev/null +++ b/scitt-components/verifiable-identities.md @@ -0,0 +1,4 @@ +# Verifiable Identities + +> TODO: Describe the importance of a verifiable identity, as the base requirement to trust any type of content from the original artifact, claim or evidence. +> \ No newline at end of file