diff --git a/docs/spec/draft/principles.md b/docs/spec/draft/principles.md index 535c75a7f..d04d5f922 100644 --- a/docs/spec/draft/principles.md +++ b/docs/spec/draft/principles.md @@ -1,10 +1,11 @@ --- -title: Guiding principles +title: Guiding principles description: An introduction to the guiding principles behind SLSA's design decisions. --- -This page is an introduction to the guiding principles behind SLSA's design -decisions. +Best practices for implementing the slsa specification are outlined on this page. They include +advice on how to achieve the best outcomes through: +simplicity, trust and verify, minimize platforms, using attestations, anonymous contributors. ## Simple levels with clear outcomes diff --git a/docs/spec/draft/real-world-examples.md b/docs/spec/draft/real-world-examples.md new file mode 100644 index 000000000..9558eb9e8 --- /dev/null +++ b/docs/spec/draft/real-world-examples.md @@ -0,0 +1,98 @@ +--- +title: The Supply Chain Problem +description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page outlines a set of real world supply chain threat situations and explains how SLSA could mitigate each type of problem. +--- + +# {The Supply Chain Problem} + +Attacks can occur at every link in a typical software supply chain, and these +kinds of attacks are increasingly public, disruptive, and costly in today's +environment. + +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. + +The table below outlines a set of real world supply chain threat problems and explains how SLSA can mitigate them. Each threat in this table has a label of (A) through (I). These labels coincide with the red triangle threat locations in the [Supply Chain Threat Model](threats.md#supply-chain-threat-model) diagram. See that [page](threats.md#supply-chain-threat-model) for in-depth details on threat problems and SLSA solutions. + +## Real world examples of Supply Chain threats + +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. +
+ +For a detailed list of Supply Chain Threat Problems and Solutions, go [here](threats.md). diff --git a/docs/spec/draft/threats-overview.md b/docs/spec/draft/threats-overview.md index 8b2d04a25..4564a6ebd 100644 --- a/docs/spec/draft/threats-overview.md +++ b/docs/spec/draft/threats-overview.md @@ -1,42 +1,51 @@ --- -title: Supply chain threats +title: Supply chain threat overview description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. --- -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). +# {The Supply Chain Problem} -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) +## Introduction to Supply Chain Attacks -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. +Attacks can occur at every link in a typical software supply chain, and these +kinds of attacks are increasingly public, disruptive, and costly in today's +environment. This page outlines possible attacks throughout the supply chain and how +SLSA can help. -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized +Threats can be mitigated because SLSA's primary focus is supply chain integrity. Integrity means protection against tampering or unauthorized modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. +integrity into source integrity vs build integrity: -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. +- **Source integrity:** Ensures that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. -**Build integrity:** Ensure that the package is built from the correct, +- **Build integrity:** Ensures that the package is built from the correct, unmodified sources and dependencies according to the build recipe defined by the software producer, and that artifacts are not modified as they pass between development stages. -**Availability:** Ensure that the package can continue to be built and +SLSA can provide additional mitigation because its secondary focus is on availablity: + +- **Availability:** Ensures that the package can continue to be built and maintained in the future, and that all code and change history is available for investigations and incident response. -### Real-world examples +SLSA 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. + +## Supply chain threat model + +![Supply Chain Threats](images/supply-chain-threats.svg) + +This supply chain threat model diagram shows where threats can occur in the supply chain sequence of events. The letters (A) through (I) represent different threats and are explained in the real-world example table [below](real-world-examples). For more technical details on supply chain threats, see [Threats & mitigations](threats.md). + +**Note:** SLSA does not currently address all of the threats presented in the diagram. -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: +## Real-world examples of Supply Chain threats + +Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. + +The table below outlines a set of real world supply chain threat problems and explains how SLSA can mitigate them. Each threat in this table has a label of (A) through (I). These labels coincide with the red triangle threat locations in the diagram above. See the [Threats & Mitigations](threats.md) page for in-depth details on threat problems and SLSA solutions. @@ -114,6 +123,4 @@ For closed source software SLSA does not provide any solutions for malicious pro
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. + diff --git a/docs/spec/draft/threats.md b/docs/spec/draft/threats.md index 80c89581a..e550cac9b 100644 --- a/docs/spec/draft/threats.md +++ b/docs/spec/draft/threats.md @@ -3,19 +3,12 @@ title: Threats & mitigations description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. --- -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. +# {Threats & Mitigations} -The examples on this page are meant to: +This page supplies a comprehensive technical analysis of supply chain threat problems and +their corresponding mitigations with SLSA. It expands on the diagram first presented in the [Introduction to supply chain attacks](threats-overview.md#introduction-to-supply-chain-attacks) page and provides additional examples with detailed descriptions of different types of supply chain threats. They cover threats to the integrity of source, build, usage, dependency, availability, and verification portions of the software supply chain. Each example of a threat problem includes a SLSA mitigation that explains the reasons for the SLSA [build](build-requirements.md) and [source](source-requirements.md) requirements. -- Explain the reasons for each of the SLSA [build](build-requirements.md) and - [source](source-requirements.md) requirements. -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](about#how-slsa-works) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. +Having more information on threats and mitigation can increase confidence that the SLSA requirements are sufficient to achieve the desired [level](about#how-slsa-works) of integrity protection and help implementers understand what they are protecting against so that they can better design and implement controls. -
+The pages in this section provide information on general concepts of how and where to put SLSA into practice. They define SLSA [use cases](use-cases) and [guiding principles](principles.md). -## Applications of SLSA +## Use cases -
+SLSA protects against tampering during the software supply chain, but how? +The answer depends on the use case in which SLSA is applied. This page defines the three most common settings where supply chain problems threaten the security of different types of software producing organizations. They include: first party organizations, +oopen source software producers, and vendor services. -
-
-### First party +## First party organizations @@ -35,7 +31,7 @@ In its simplest form, SLSA can be used entirely within an organization to reduce risk from internal sources. This is the easiest case in which to apply SLSA because there is no need to transfer trust across organizational boundaries. -Example ways an organization might use SLSA internally: +Example of ways an organization might use SLSA internally: - A small company or team uses SLSA to ensure that the code being deployed to production in binary form is the same one that was tested and reviewed in @@ -53,11 +49,11 @@ Example ways an organization might use SLSA internally:
-### Open source +## Open source software producers @@ -70,7 +66,7 @@ dependencies. In this way, consumers need only trust a small number of secure build platforms rather than the many thousands of developers with upload permissions across various packages. -Example ways an open source ecosystem might use SLSA to protect users: +Example of ways an open source ecosystem might use SLSA to protect users: - At upload time, the package registry rejects the package if it was not built from the canonical source repository. @@ -85,23 +81,23 @@ Example ways an open source ecosystem might use SLSA to protect users:
-### Vendors +## Vendor services
-Finally, SLSA can be used to reduce risk for consumers of vendor-provided +SLSA can also be used to reduce risk for consumers of vendor-provided software and services. Unlike open source, there is no canonical source repository to map to, so instead the focus is on the trustworthiness of claims made by the vendor. -Example ways a consumer might use SLSA for vendor-provided software: +Example of ways a consumer might use SLSA for vendor-provided software: - Prefer vendors who make SLSA claims and back them up with credible evidence. - Require a vendor to implement SLSA as part of a contract. @@ -118,7 +114,7 @@ Example ways a consumer might use SLSA for vendor-provided software:
-## Motivating example +## Hypothetical example