NEW Section called Applying SLSA

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
 

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:
+
+<table>
+<thead>
+<tr>
+<th>
+<th>Threats from
+<th>Known example
+<th>How SLSA could help
+<tbody>
+<tr>
+<td>A
+<td>Producer
+<td><a href="https://en.wikipedia.org/wiki/SpySheriff">SpySheriff</a>: Software producer purports to offer anti-spyware software, but that software is actually malicious.
+<td>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.
+<tr>
+<td>B
+<td>Authoring & reviewing
+<td><a href="https://arstechnica.com/information-technology/2021/09/cryptocurrency-launchpad-hit-by-3-million-supply-chain-attack/">SushiSwap</a>: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself.
+<td>Two-person review could have caught the unauthorized change.
+<tr>
+<td>C
+<td>Source code management
+<td><a href="https://news-web.php.net/php.internals/113838">PHP</a>: Attacker compromised PHP's self-hosted git server and injected two malicious commits.
+<td>A better-protected source code system would have been a much harder target for the attackers.
+<tr>
+<td>D
+<td>External build parameters
+<td><a href="https://www.reddit.com/r/HobbyDrama/comments/jouwq7/open_source_development_the_great_suspender_saga/">The Great Suspender</a>: Attacker published software that was not built from the purported sources.
+<td>A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering.
+<tr>
+<td>E
+<td>Build process
+<td><a href="https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/">SolarWinds</a>: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build.
+<td>Higher SLSA Build levels have <a href="requirements#build-platform">stronger security requirements for the build platform</a>, making it more difficult for an attacker to forge the SLSA provenance and gain persistence.
+<tr>
+<td>F
+<td>Artifact publication
+<td><a href="https://about.codecov.io/apr-2021-post-mortem/">CodeCov</a>: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly.
+<td>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.
+<tr>
+<td>G
+<td>Distribution channel
+<td><a href="https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf">Attacks on Package Mirrors</a>: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages.
+<td>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.
+<tr>
+<td>H
+<td>Package selection
+<td><a href="https://blog.sonatype.com/damaging-linux-mac-malware-bundled-within-browserify-npm-brandjack-attempt">Browserify typosquatting</a>: Attacker uploaded a malicious package with a similar name as the original.
+<td>SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions.
+<tr>
+<td>I
+<td>Usage
+<td><a href="https://www.horizon3.ai/attack-research/disclosures/cve-2023-27524-insecure-default-configuration-in-apache-superset-leads-to-remote-code-execution/">Default credentials</a>: Attacker could leverage default credentials to access sensitive data.
+<td>SLSA does not address this threat.
+<tr>
+<td>N/A
+<td>Dependency threats (i.e. A-H, recursively)
+<td><a href="https://web.archive.org/web/20210909051737/https://schneider.dev/blog/event-stream-vulnerability-explained/">event-stream</a>: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code.
+<td>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.
+</table>
+
+<table>
+<thead>
+<tr>
+<th>
+<th>Availability threat
+<th>Known example
+<th>How SLSA could help
+<tbody>
+<tr>
+<td>N/A
+<td>Dependency becomes unavailable
+<td><a href="https://www.techradar.com/news/this-popular-code-library-is-causing-problems-for-hundreds-of-thousands-of-devs">Mimemagic</a>: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily.
+<td>SLSA does not directly address this threat.
+</table>
+
+For a detailed list of Supply Chain Threat Problems and Solutions, go [here](threats.md).

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.
 
 <table>
 <thead>
@@ -114,6 +123,4 @@ For closed source software SLSA does not provide any solutions for malicious pro
 <td>SLSA does not directly address this threat.
 </table>
 
-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.
+

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.
 
 <!--
 **TODO:** Expand this threat model to also cover "unknowns". Not sure if that is
@@ -30,24 +23,19 @@ diagram.
 
 <article class="threats">
 
-## Overview
+## Supply chain threat model
 
 ![Supply Chain Threats](images/supply-chain-threats.svg)
 
-This threat model covers the *software supply chain*, meaning the process by
-which software is produced and consumed. We describe and cluster threats based
-on where in the software development pipeline those threats occur, labeled (A)
-through (I). This is useful because priorities and mitigations mostly cluster
-along those same lines. Keep in mind that dependencies are
-[highly recursive](#dependency-threats), so each dependency has its own threats
-(A) through (I), and the same for *their* dependencies, and so on. For a more
-detailed explanation of the supply chain model, see
-[Terminology](terminology.md).
-
-Importantly, producers and consumers face *aggregate* risk across all of the
-software they produce and consume, respectively. Many organizations produce
-and/or consume thousands of software packages, both first- and third-party, and
-it is not practical to rely on every individual team in the organization to do
+The threat model above that was first shown in the [Introduction to supply chain attacks](threats-overview.md#introduction-to-supply-chain-attacks) page, shows the software supply chain process of how software is produced and consumed, and where threats can occur. This *Threats & Mitigation* page adds additional details that describe cluster threats based
+on where in the software development pipeline those threats occur. The threat locations are labeled (A)
+through (I) in the diagram and all the examples.
+
+This detailed threat information is important because priorities and mitigations mostly cluster
+along those same lines. Dependencies are
+[highly recursive](#dependency-threats), and each dependency in these examples has its own threats
+(A) through (I), and the same for *their* dependencies, and so on. Recursion problems cause producers and consumers to face *aggregate* risk across all of the
+software they produce and consume. Due to the size and scope of software development organizations, it's not practical to rely on every individual team to do
 the right thing. For this reason, SLSA prioritizes mitigations that can be
 broadly adopted in an automated fashion, minimizing the chance of mistakes.