diff --git a/docs/spec/draft/threats.md b/docs/spec/draft/threats.md index db6e5bfe7..8e14b0800 100644 --- a/docs/spec/draft/threats.md +++ b/docs/spec/draft/threats.md @@ -15,9 +15,6 @@ The examples on this page are meant to: - Help implementers better understand what they are protecting against so that they can better design and implement controls. -**TODO:** Update the ordering to match the diagram. We're currently in the -middle of refactoring, with a jumble of new and old. - **TODO:** Expand this threat model to also cover "unknowns". Not sure if that is a "threat" or a "risk". Example: If libFoo is compromised, how do you know if you are compromised? At a first level, if you don't even know whether you @@ -27,12 +24,6 @@ that somehow. This isn't specific to dependencies - it applies to the entire diagram. ([discussion](https://github.com/slsa-framework/slsa/pull/1046/files/ebf34a8f9e874b219f152bad62673eae0b3ba2c3#r1585440922)) -**TODO:** Revisit and possibly update any item that says "out of scope", since -we want to really expand SLSA's scope to include all of these threats. A more -nuanced answer would be that the current version does not define a specific -mitigation, but it's in scope for the project overall. We can also list specific -mitigations even if they're not listed as a level requirement. -
## Overview @@ -264,8 +255,8 @@ does not accept this because the version X is not considered reviewed. *Threat:* Two trusted persons collude to author and approve a bad change. -*Mitigation:* **Outside the scope of SLSA.** We use "two trusted persons" as a -proxy for "intent of the software producer". +*Mitigation:* This threat is not currently addressed by SLSA. We use "two +trusted persons" as a proxy for "intent of the software producer".
Trick reviewer into approving bad code @@ -273,7 +264,7 @@ proxy for "intent of the software producer". *Threat:* Construct a change that looks benign but is actually malicious, a.k.a. "bugdoor." -*Mitigation:* **Outside the scope of SLSA.** +*Mitigation:* This threat is not currently addressed by SLSA.
Reviewer blindly approves changes @@ -281,7 +272,7 @@ proxy for "intent of the software producer". *Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber stamping." -*Mitigation:* **Outside the scope of SLSA.** +*Mitigation:* This threat is not currently addressed by SLSA.
@@ -339,13 +330,22 @@ change to MyPackage without review. *Threat:* Exploit a vulnerability in the implementation of the source code management system to bypass controls. -*Mitigation:* **Outside the scope of SLSA.** +*Mitigation:* This threat is not currently addressed by SLSA. -### (D) External build parameters +## Build threats -**TODO:** Move under "Build threats". +A build integrity threat is a potential for an adversary to introduce behavior +to an artifact without changing its source code, or to build from a +source, dependency, and/or process that is not intended by the software +producer. + +The SLSA Build track mitigates these threats when the consumer +[verifies artifacts](verifying-artifacts.md) against expectations, confirming +that the artifact they received was built in the expected manner. + +### (D) External build parameters An adversary builds from a version of the source code that does not match the official source control repository, or changes the build parameters to inject @@ -433,141 +433,6 @@ the source repo does not match the expected value. -## Dependency threats - -**TODO:** Move after Usage Threats. - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - -- **TODO:** Should we distinguish 1P vs 3P boundaries in the diagram, or - otherwise visualize 1P/3P? -- **TODO:** Expand to cover typosquatting, dependency confusion, and other - "dependency" threats. -- **TODO:** The word "compromised" is a bit too restrictive. If the publisher - intends to do harm, either because they tricked you into using a dependency - (typosquatting or dependency confusion), or because they were good and now - do something bad, that's not really "compromised" per se. -- **TODO:** Should we expand this to cover "transitive SLSA verification"? -- **TODO:** Update the Terminology page to show "build time" vs "runtime", - since the latter term results in confusion. Also consider the term "deploy - time" as an alternative. - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* **TODO** - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. - -*Mitigation:* **TODO** - -
- -Reminder: dependencies that look like [runtime dependencies](#runtime-dep) -actually become build dependencies if they get loaded at build time. - -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - This threat is out of scope of SLSA. SLSA's threat model -does not explicitly model runtime dependencies. Instead, each runtime dependency -is considered a distinct artifact with its own threats. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - ### (E) Build process An adversary introduces an unauthorized change to a build output through @@ -808,9 +673,10 @@ from the public registry instead of the internal one. *Threat:* Register a package name that is similar looking to a popular package and get users to use your malicious package instead of the benign one. -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. +*Mitigation:* This threat is not currently addressed by SLSA. That said, the +requirement to make the source available can be a mild deterrent, can aid +investigation or ad-hoc analysis, and can complement source-based typosquatting +solutions. @@ -818,6 +684,128 @@ ad-hoc analysis, and can complement source-based typosquatting solutions. **TODO:** What should we put here? +## Dependency threats + +A dependency threat is a potential for an adversary to introduce unintended +behavior in one artifact by compromising some other artifact that the former +depends on at build time. (Runtime dependencies are excluded from the model, as +[noted below](#runtime-dep).) + +Unlike other threat categories, dependency threats develop recursively through +the supply chain and can only be exploited indirectly. For example, if +application *A* includes library *B* as part of its build process, then a build +or source threat to *B* is also a dependency threat to *A*. Furthermore, if +library *B* uses build tool *C*, then a source or build threat to *C* is also a +dependency threat to both *A* and *B*. + +This version of SLSA does not explicitly address dependency threats, but we +expect that a future version will. In the meantime, you can [apply SLSA +recursively] to your dependencies in order to reduce the risk of dependency +threats. + +- **TODO:** Should we distinguish 1P vs 3P boundaries in the diagram, or + otherwise visualize 1P/3P? +- **TODO:** Expand to cover typosquatting, dependency confusion, and other + "dependency" threats. +- **TODO:** The word "compromised" is a bit too restrictive. If the publisher + intends to do harm, either because they tricked you into using a dependency + (typosquatting or dependency confusion), or because they were good and now + do something bad, that's not really "compromised" per se. +- **TODO:** Should we expand this to cover "transitive SLSA verification"? +- **TODO:** Update the Terminology page to show "build time" vs "runtime", + since the latter term results in confusion. Also consider the term "deploy + time" as an alternative. + +[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively + +### Build dependency + +An adversary compromises the target artifact through one of its build +dependencies. Any artifact that is present in the build environment and has the +ability to influence the output is considered a build dependency. + +
Include a vulnerable dependency (library, base image, bundled file, etc.) + +*Threat:* Statically link, bundle, or otherwise include an artifact that is +compromised or has some vulnerability, causing the output artifact to have the +same vulnerability. + +*Example:* The C++ program MyPackage statically links libDep at build time. A +contributor accidentally introduces a security vulnerability into libDep. The +next time MyPackage is built, it picks up and includes the vulnerable version of +libDep, resulting in MyPackage also having the security vulnerability. + +*Mitigation:* **TODO** + +
+
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) + +*Threat:* Use a compromised tool or other software artifact during the build +process, which alters the build process and injects unintended behavior into the +output artifact. + +*Example:* MyPackage is a tarball containing an ELF executable, created by +running `/usr/bin/tar` during its build process. An adversary compromises the +`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF +executable it writes. The next time MyPackage is built, the build picks up the +vulnerable `tar` package, which injects the backdoor into the resulting +MyPackage artifact. + +*Mitigation:* **TODO** + +
+ +Reminder: dependencies that look like [runtime dependencies](#runtime-dep) +actually become build dependencies if they get loaded at build time. + +
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) + +*Threat:* During the build process, use a compromised runtime dependency (such +as during testing or dynamic linking), which alters the build process and +injects unwanted behavior into the output. + +**NOTE:** This is technically the same case as [Use a compromised build +tool](#build-tool). We call it out to remind the reader that +[runtime dependencies](#runtime-dep) can become build dependencies if they are +loaded during the build. + +*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep +is not included in MyPackage but required to be installed on the user's machine +at the time MyPackage is run. However, Dep is also loaded during the build +process of MyPackage as part of a test. An adversary compromises Dep such that, +when run during a build, it injects a backdoor into the output artifact. The +next time MyPackage is built, it picks up and loads Dep during the build +process. The malicious code then injects the backdoor into the new MyPackage +artifact. + +*Mitigation:* In addition to all the mitigations for build tools, you can often +avoid runtime dependencies becoming build dependencies by isolating tests to a +separate environment that does not have write access to the output artifact. + +
+ +### Related threats + +The following threats are related to "dependencies" but are not modeled as +"dependency threats". + +
Use a compromised dependency at runtime (modeled separately) + +*Threat:* Load a compromised artifact at runtime, thereby compromising the user +or environment where the software ran. + +*Example:* MyPackage lists package Dep as a runtime dependency. Adversary +publishes a compromised version of Dep that runs malicious code on the user's +machine when Dep is loaded at runtime. An end user installs MyPackage, which in +turn installs the compromised version of Dep. When the user runs MyPackage, it +loads and executes the malicious code from Dep. + +*Mitigation:* N/A - This threat is not currently addressed by SLSA. SLSA's +threat model does not explicitly model runtime dependencies. Instead, each +runtime dependency is considered a distinct artifact with its own threats. + +
+ ## Availability threats **TODO:** Merge into the list above rather than having a separate section. @@ -849,23 +837,23 @@ retention and availability of the source code. *Threat:* Unable to perform a build with the intended dependencies. -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to -support hermetic and reproducible builds may also reduce the impact of this -threat. +*Mitigation:* This threat is not currently addressed by SLSA. That said, some +solutions to support hermetic and reproducible builds may also reduce the +impact of this threat.
De-list artifact *Threat:* The package registry stops serving the artifact. -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. +*Mitigation:* N/A - This threat is not currently addressed by SLSA.
De-list provenance *Threat:* The package registry stops serving the provenance. -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. +*Mitigation:* N/A - This threat is not currently addressed by SLSA.