diff --git a/docs/spec/draft/intro-to-tracks.md b/docs/spec/draft/intro-to-tracks.md new file mode 100644 index 000000000..3b6ef0871 --- /dev/null +++ b/docs/spec/draft/intro-to-tracks.md @@ -0,0 +1,101 @@ +--- +title: Introduction to Tracks +description: This page provides an overview of the four SLSA tracks. +--- + +# {Introduction to Tracks} + +## Tracks overview + +The SLSA Specification is composed of four tracks that have multiple levels of security. These tracks address different types of threats to the supply chain and each has their own set of requirements and patterns of use. The tracks are introduced below and the individual sections of this specification will explain their standards and requirements in greater detail. + +## Build Track + +The SLSA build track describes increasing levels of trustworthiness and +completeness in a package artifact's provenance. Provenance describes +what entity built the artifact, what process they used, and what the inputs +were. The lowest track level only requires the provenance to exist, while higher +levels provide increasing protection against tampering of the build, the +provenance, or the artifact. + +The primary purpose of the build track is to enable +verification that the artifact was built as expected. +Consumers have a way of knowing what the expected provenance should look like +for a given package. They then can compare each package artifact's actual provenance +to those expectations. This comparison provides certainty of the package contents, preventing several classes of supply chain threats. + +Each software supply chain ecosystem (for open source) or organization (for closed source) defines +exactly how this is implemented. The implementation includes: a means of defining expectations, what +provenance format is accepted, whether reproducible builds are used, how +provenance is distributed, when verification happens, and what happens on +failure. + +Guidelines for implementers can be found in the +requirements page of the build track. The build track will cover these five topics: + +- Basics +- Requirements +- Provenance +- Verification +- Assessment + +## Build Environment track + +The build environment track +describes the increasing levels of integrity for different components of the +build platform and its underlying compute platform. +The goal of this track is to enable the detection of tampering +with core components of the compute environment executing builds. + +Implementers of this track will: generate SLSA Build +Provenance for build images, validate the integrity of a build's environment +at boot time against good known values, and at level 3 (L3) deploy the build system on +compute that supports system state measurement and attestation capabilities at +the hardware level. + +This track will cover the same five topics as the build track: + +- Basics +- Requirements +- Provenance +- Verification +- Assessment + +**Note:** The build environment track is currently being developed. Some of the topics are not complete at this time. + +## Dependency Track + +The goal of the Dependency Track is to enable a software producer to measure, control and reduce risk introduced from third party dependencies. This track is primarily aimed at enterprises/organizations, with medium- to large-sized organizations benefiting the most from adoption of the dependency track levels. Organizations can include business enterprises, but also large open source projects that want to manage third party dependency risk. + +This track will cover the same five topics as the build track: + +- Basics +- Requirements +- Provenance +- Verification +- Assessment + +**Note:** The dependency track is also still being developed. Some of the topics are not complete at this time. + +## Source Track + +The SLSA source track provides producers and consumers with levels of +trust in the source code they produce and consume. It describes increasing +levels of trustworthiness and completeness of how a source revision was created. + +The expected process for creating a new revision is determined solely by the +repository's owner. The owner also determines the intent of the +software in the repository and administers technical controls to enforce the +process. Consumers can review attestations to verify whether a particular revision meets +their standards. + +This track will cover the same five topics as the build track, but it has one additional topic for example controls: + +- Basics +- Requirements +- Provenance +- Verification +- Assessment +- Example controls + + 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