From d021501662a19ac4558dd0b37ec8efa77538c9fd Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 23 Dec 2025 03:22:45 -0800 Subject: [PATCH 1/2] need new file for real-world stuff --- docs/spec/draft/real-world-examples.md | 207 +++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/spec/draft/real-world-examples.md diff --git a/docs/spec/draft/real-world-examples.md b/docs/spec/draft/real-world-examples.md new file mode 100644 index 000000000..0771f468a --- /dev/null +++ b/docs/spec/draft/real-world-examples.md @@ -0,0 +1,207 @@ +## Mapping to real-world ecosystems + +Most real-world ecosystems fit the package model above but use different terms. +The table below attempts to document how various ecosystems map to the SLSA +Package model. There are likely mistakes and omissions; corrections and +additions are welcome! + + + + + + + + + + + + + + + + + + + + + + + + + + +
Package ecosystem + Package registry + Package name + Package artifact +
Languages +
Cargo (Rust) + Registry + Crate name + Artifact +
CPAN (Perl) + PAUSE + Distribution + Release (or Distribution) +
Go + Module proxy + Module path + Module +
Maven (Java) + Repository + Group ID + Artifact ID + Artifact +
npm (JavaScript) + Registry + Package Name + Package +
NuGet (C#) + Host + Project + Package +
PyPA (Python) + Index + Project Name + Distribution +
Operating systems +
Dpkg (e.g. Debian) + ? + Package name + Package +
Flatpak + Repository + Application + Bundle +
Homebrew (e.g. Mac) + Repository (Tap) + Package name (Formula) + Binary package (Bottle) +
Pacman (e.g. Arch) + Repository + Package name + Package +
RPM (e.g. Red Hat) + Repository + Package name + Package +
Nix (e.g. NixOS) + Repository (e.g. Nixpkgs) or binary cache + Derivation name + Derivation or store object +
Storage systems +
GCS + n/a + Object name + Object +
OCI/Docker + Registry + Repository + Object +
Meta +
deps.dev: System + Packaging authority + Package + n/a +
purl: type + Namespace + Name + n/a +
+ +Notes: + +- [Go](https://go.dev) (golang) uses a significantly different distribution model than other ecosystems. + In Go, the package name is a source repository URL. While clients can fetch + directly from that URL---in which case there is no "package" or + "registry"---they usually fetch a zip file from a *module proxy*. The module + proxy acts as both a builder (by constructing the package artifact from + source) and a registry (by mapping package name to package artifact). People + trust the module proxy because builds are independently reproducible, and a + *checksum database* guarantees that all clients receive the same artifact + for a given URL. + +### Real-world supply chain examples + +Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: + + + + + + + + + + + + + + + +
+Threats from +Known example +How SLSA could help +
A +Producer +SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. +SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. +For closed source software SLSA does not provide any solutions for malicious producers. +
B +Authoring & reviewing +SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. +Two-person review could have caught the unauthorized change. +
C +Source code management +PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. +A better-protected source code system would have been a much harder target for the attackers. +
D +External build parameters +The Great Suspender: Attacker published software that was not built from the purported sources. +A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. +
E +Build process +SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. +Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. +
F +Artifact publication +CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. +Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. +
G +Distribution channel +Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. +Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. +
H +Package selection +Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. +SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. +
I +Usage +Default credentials: Attacker could leverage default credentials to access sensitive data. +SLSA does not address this threat. +
N/A +Dependency threats (i.e. A-H, recursively) +event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. +Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. +
+ + + + + + +
+Availability threat +Known example +How SLSA could help +
N/A +Dependency becomes unavailable +Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. +SLSA does not directly address this threat. +
+ +A SLSA level helps give consumers confidence that software has not been tampered +with and can be securely traced back to source—something that is difficult, if +not impossible, to do with most software today. + + \ No newline at end of file From 1b5f76b2d7b9da93f5c20d4bdfa71afaf2a0a474 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Mon, 26 Jan 2026 01:45:19 -0800 Subject: [PATCH 2/2] dependency track ready for pr --- docs/spec/draft/depend-track-assessment.md | 24 ++++ docs/spec/draft/depend-track-basics.md | 140 +++++++++++++++++++ docs/spec/draft/depend-track-provenance.md | 25 ++++ docs/spec/draft/depend-track-requirements.md | 39 ++++++ docs/spec/draft/depend-track-verification.md | 24 ++++ 5 files changed, 252 insertions(+) create mode 100644 docs/spec/draft/depend-track-assessment.md create mode 100644 docs/spec/draft/depend-track-basics.md create mode 100644 docs/spec/draft/depend-track-provenance.md create mode 100644 docs/spec/draft/depend-track-requirements.md create mode 100644 docs/spec/draft/depend-track-verification.md diff --git a/docs/spec/draft/depend-track-assessment.md b/docs/spec/draft/depend-track-assessment.md new file mode 100644 index 000000000..d87fb5cbb --- /dev/null +++ b/docs/spec/draft/depend-track-assessment.md @@ -0,0 +1,24 @@ +--- +title: Dependency Track Assessment +description: This page describes the parts of the underlying platform of the dependency track that consumers should access with relevant questions. +--- + +# {Dependency Track: Assessment} + +**About this page:** the *Dependency Track: Assessment* page describes the parts of the underlying platform of the dependency track that consumers should assess with relevant questions. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** {expand topic list when contributors add content} + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +**For more information, see:** {optional} + +## Overview of Dependency Track Assessment + +This information will be supplied when development is completed. \ No newline at end of file diff --git a/docs/spec/draft/depend-track-basics.md b/docs/spec/draft/depend-track-basics.md new file mode 100644 index 000000000..e769c5722 --- /dev/null +++ b/docs/spec/draft/depend-track-basics.md @@ -0,0 +1,140 @@ +--- +title: Dependency Track: Basics +description: This page shows how the SLSA Dependency track enables a software producer to measure, control, and reduce risk introduced from third party dependencies. +--- + +# {Dependency Track: Basics} + +**About this page:** the *Dependency Track: Basics* page shows how this track enables a software producer to measure, control, and reduce risk introduced from third party dependencies. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** dependency track terminology, track level summaries and specifics + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +**For more information, see:** {optional} + +## Overview + +The Dependency track is primarily aimed at enterprises/organizations, with medium to large-sized organizations benefiting the most from adoption of the dependency track levels. Organizations include enterprises, but also large open source projects that want to manage third party dependency risk. + +The scope of the SLSA Dependency Track is to properly manage and securely consume build dependencies into the developer workflow to mitigate against supply chain threats targeting the open source ecosystem. + +## Dependency Track Terminology + +These terms apply to the Dependency track. See the general terminology [list](terms-generic.md) for terms used throughout the SLSA specification. + +| Term | Description | +| --- | --- | +| Artifact repository manager | A storage solution that manages your artifact lifecycle and supports different software package management systems while providing consistency to your CI/CD workflow. | +| Build dependencies | Software artifacts fetched or otherwise made available to the build environment during the build of the artifact. This includes open and closed source binary dependencies. | +| Dependency security metadata feed | A metadata feed that provides security or risk information about each dependency to assist consumers in making judgements about the safety of their dependencies. | +| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. | +| Package source files | A language-specific config file in a source code repo that identifies the package registry feeds or artifact repository manager feeds to consume dependencies from. | + +## Dependency Track Level Summary + +| Level | Requirements +| --- | --- +| Dependency L0 | (none) +| Dependency L1 | Inventory of dependencies exists +| Dependency L2 | Known vulnerabilities have been triaged +| Dependency L3 | Dependencies consumed from sources under producer's control +| Dependency L4 | Proactive defence against upstream attacks + +## Dependency Track Level Specifics + +### Level 0: No mitigations to dependency threats + +**Summary:** + +L0 represents the lack of any SLSA dependency track claims. + +**Threats:** + +N/A + +**Outcome:** + +N/A + +### Level 1: Inventory of dependencies exists + +**Summary:** + +An inventory of all build dependencies within the artifact exists. + +**Threat:** + +Inability to respond to incidents or remediate vulnerabilities. + +**Outcome:** + +All third party build dependencies (including transitive) are identified. + +- A comprehensive picture of all third party dependencies enables understanding of the risk exposure. +- An inventory is a prerequisite to identify and manage known vulnerabilities. +- Implementing a centralized inventory can enable efficient incident response and risk exposure measurement. + +### Level 2: Known vulnerabilities have been triaged + +**Summary:** + +All known vulnerabilities in the artifact have been triaged. + +**Threat:** + +Introducing vulnerable dependencies into artifact. + +**Outcome:** + +Artifacts are released with no unknown 'known' vulnerabilities. Outcomes of the triage could result in the decision to: + +- Remediate vulnerabilities, prior to release +- Proceed with the release and remediate vulnerabilities in the next release, following normal release cycle +- Proceed with the release and remediate vulnerabilities by expediting the next patch release. + +**Note:** This does NOT mean the artifact is free of vulnerabilities, but at the time of release all known vulnerabilities are triaged. Also covers race conditions: new vulnerability can, theoretically, be published on the same day as the release. + +### Level 3: Dependencies consumed from locations under producer's control + +**Summary:** + +All third-party build dependencies are consumed from locations under the producer’s control. + +**Threat:** + +Availability risks of upstream sources being removed or taken down (e.g. left-pad incident). + +**Outcome:** + +The build process consumes all third party build dependencies only from artifact producer-controlled locations, allowing for control of how dependencies enter the supply chain, reducing the attackable surface. This also enables developers to continue to build even if upstream resources are unavailable. + +**Note:** Compliance with this level enables the ability to achieve Level 4 compliance. + +### Level 4: Proactive defence against upstream attack + +**Summary:** + +Artifact producer is able to enforce a secure ingestion policy over third-party build dependencies in order to prevent the consumption of compromised upstream artifacts. + +**Threat:** + +Malicious attacks on upstream sources such as package managers, compromised packages, and dependency confusion. Attacks include: + +- A dependency adds a new transitive dependency that is malicious (e.g. Event-Stream incident) +- Typosquatting +- Dependency Confusion +- Intentional vulnerabilities/backdoors/protestware added to a code base (e.g. Colors v1.4.1 incident, node-ipc incident) + +**Outcome:** + +Reduced likelihood of a released artifact including a malicious or compromised third-party dependency. + +**Note:** This capability builds upon Level 3. + diff --git a/docs/spec/draft/depend-track-provenance.md b/docs/spec/draft/depend-track-provenance.md new file mode 100644 index 000000000..906084d00 --- /dev/null +++ b/docs/spec/draft/depend-track-provenance.md @@ -0,0 +1,25 @@ +--- +title: Dependency track provenance +description: This page covers the SLSA Dependency track provenance +--- + +# {Dependency Track: Provenance} + +**About this page:** the *Dependency Track: Provenance* page defines how the distribution and verification of provenance metadata should be done using the SLSA attastation format. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** {expand topic list when contributors add content} + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +**For more information, see:** {optional} + +## Overview of Dependency track provenance + +This information will be supplied when development is completed. + diff --git a/docs/spec/draft/depend-track-requirements.md b/docs/spec/draft/depend-track-requirements.md new file mode 100644 index 000000000..70058a3c1 --- /dev/null +++ b/docs/spec/draft/depend-track-requirements.md @@ -0,0 +1,39 @@ +--- +title: Dependency Track Requirements +description: This page covers the SLSA Dependency track requirements. +--- + +# {Dependency Track: Requirements} + +**About this page:** the *Dependency Track: Requirements* page explains the security requirements for the dependency track. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** dependency track requirements + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +**For more information, see:** {optional} + +## Overview of the Dependency Track requirements + +| Requirement | Description | Example | L1 | L2 | L3 | L4 +| --- | --- | --- | --- | --- | --- | --- +| Inventory of dependencies exists | An organization producing artifacts MUST implement tooling that inventories dependencies for every version they release | Build-time SBOM generated by the build tool, capturing direct and transitive dependencies for the artifact being released. For language ecosystem dependencies, dependency pinning can serve as a starting point for many ecosystems as it provides identification for all transitive dependencies (e.g. `package-lock.json`, `pip –require-hashes`, `go.sum`, Gradle lock). Software Composition Analysis (SCA) tools can serve as another starting point to produce an SBOM, capturing an artifact’s dependencies Metadata associated with vendored source code, identifying the dependency (e.g. by specifying CPE or ecosystem, name and version or a package URL) | ✓ | ✓ | ✓ | ✓ +| Scan dependencies for known vulnerabilities | An organization MUST proactively identify 3rd party dependency in their build that have known vulnerabilities | Leverage SBOMs or SCA tools to scan for CVEs in public vulnerability databases - e.g, NVD. | | ✓ | ✓ | ✓ +| Triage all vulnerable dependencies before release | An organization MUST triage all known vulnerabilities and either remediate the vulnerability, or not remediate in the given release. For example, an organization may make the decision for unremediated vulnerabilities to be recorded in a VEX attestation due to not being exploitable in the manner the dependency was integrated into their artifact | Third party build dependencies of the artifact being released as represented by an SBOM, lockfile, metadata files or other means are scanned for known vulnerabilities. Reported vulnerabilities are triaged and either remediated or not remediated in the given release. Triage decisions for unremediated vulnerabilities can be recorded in a VEX attestation for internal policy enforcement (i.e. VEX is not required to be published to comply with this level).Regular updates outside of the artifact release cycle driven by new dependency releases or discovery of new known vulnerabilities using freely available tools like Dependabot/Renovatebot/OSV-Scanner can simplify the compliance process. | | ✓ | ✓ | ✓ +| The build process consumes all third party build dependencies only from producer-controlled locations | An organization MUST consume dependencies through an artifact producer-controlled location, instead of directly from upstream. | Use of artifact management solutions to internally mirror third party dependencies in packaged form. Source code vendoring, e.g. by mirroring a copy of the upstream code in a local VCS or using ecosystems tools like `go mod vendor` or `cargo vendor`. Republishing third-party Docker base image under producer’s project. | | | ✓ | ✓ +| Enforce secure ingestion policy | An organization MUST consume dependencies that have been determined to have acceptable risk. For example, an organization may implement a malware scanning solution to determine if a dependency is safe, or implement a quantine period before consumption of newest versions are allowed, or leverage a dependency security metadata feed to inform policy decisions. | - Managed ingestion of artifacts into producer’s systems is one place to enforce the above requirements, e.g.: By only ingesting packages that were released 72 hours ago, by checking all packages and versions against known malicious packages databases (e.g. OpenSSF Malicious Packages). Many artifact management solutions support virtual repositories that enable mitigation of dependency confusion. Leverage dependency security metadata feeds to inform policy decisions on dependencies you consume. | | | | ✓ + +--- + +## Future Considerations + +- Ability to apply private patches in response to zero-day vulnerabilities +- All dependencies are verifiably built by a trusted builder +- Ability to detect and address dependencies that are End of Life (EOL) + diff --git a/docs/spec/draft/depend-track-verification.md b/docs/spec/draft/depend-track-verification.md new file mode 100644 index 000000000..81fbe04cb --- /dev/null +++ b/docs/spec/draft/depend-track-verification.md @@ -0,0 +1,24 @@ +--- +title: Dependency track verification +description: This page covers the SLSA Dependency track verificatation +--- + +# {Dependency Track: Verification} + +**About this page:** the *Dependency Track: Verification* page lists recommendations on how human inspectors should verify artifacts and their SLSA provenance. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** {expand topic list when contributors add content} + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +**For more information, see:** {optional} + +## Overview of Dependency track verification + +This information will be supplied when development is completed. \ No newline at end of file