diff --git a/docs/spec/draft/threats.md b/docs/spec/draft/threats.md index 76f785e28..247527d2a 100644 --- a/docs/spec/draft/threats.md +++ b/docs/spec/draft/threats.md @@ -662,9 +662,99 @@ cryptographic signature is no longer valid. ### (G) Distribution channel An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure. +administrative interface or through a compromise of the infrastructure +including modification of the package in transit to the consumer. -**TODO:** +The distribution channel threats and mitigations look very similar to the +Artifact Publication (F) threats and mitigations with the main difference +being that these threats are mitigated by having the *consumer* perform +verification. + +The consumer's actions may be simplified if (F) produces a [VSA][vsa]. +In this case the consumer may replace provenance verification with +[VSA verification][vsa_verification]. + +
Build with untrusted CI/CD (expectations) + +*Threat:* Replace the package with one built using an unofficial CI/CD pipeline +that does not build in the correct way. + +*Mitigation:* Verifier requires provenance showing that the builder matched an +expected value or a VSA for corresponding `resourceUri`. + +*Example:* MyPackage is expected to be built on Google Cloud Build, which is +trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only +trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject +malicious behavior. Adversary then replaces the original package within the +repository with the malicious package. Solution: Verifier rejects because +builder is not as expected. + +
+
Issue VSA from untrusted intermediary (expectations) + +*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. + +*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. + +*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary +builds a malicious package and then issues a VSA of their own for the malicious +package. Solution: Verifier rejects because they only accept VSAs from +TheRepository which the adversary cannot issue since they do not have the +corresponding signing key. + +
+
Upload package without provenance or VSA (Build L1) + +*Threat:* Replace the original package with a malicious one without provenance. + +*Mitigation:* Verifier requires provenance or a VSA before accepting the package. + +*Example:* Adversary replaces MyPackage with a malicious version of MyPackage +on the package repository and deletes existing provenance. Solution: Verifier +rejects because provenance is missing. + +
+
Tamper with artifact after upload (Build L1) + +*Threat:* Take a benign version of the package, modify it in some way, then +replace it while retaining the original provenance or VSA. + +*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches +the hash of the package. + +*Example:* Adversary performs a proper build, modifies the artifact, then +replaces the modified version of the package in the repository and retains the +original provenance. Solution: Verifier rejects because the hash of the +artifact does not match the `subject` found within the provenance. + +
+
Tamper with provenance or VSA (Build L2) + +*Threat:* Perform a build that would not meet expectations, then modify the +provenance or VSA to make the expectations checks pass. + +*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic +signature][authentic] or equivalent proving that the provenance came from an +acceptable builder or the VSA came from an expected verifier. + +*Example 1:* MyPackage is expected to be built by GitHub Actions from the +`good/my-package` repo. Adversary builds with GitHub Actions from the +`evil/my-package` repo and then modifies the provenance so that the source looks +like it came from `good/my-package`. Solution: Verifier rejects because the +cryptographic signature is no longer valid. + +*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary +builds a malicious package and then modifies the original VSA's `subject` +field to match the digest of the malicious package. Solution: Verifier rejects +because the cryptographic signature is no longer valid. + +*Example 3:* Adversary uploads a malicious package to `repo/evil-package`, +getting a valid VSA for `repo/evil-package`. Adversary then replaces +`repo/my-package` and its VSA with `repo/evil-package` and its VSA. +Solution: Verifier rejects because the VSA `resourceUri` field lists +`repo/evil-package` and not the expected `repo/my-package`. + +
## Usage threats @@ -938,3 +1028,5 @@ collision resistance. [isolated]: requirements.md#isolated [unforgeable]: requirements.md#provenance-unforgeable [supply chain threats]: threats-overview +[vsa]: verification_summary +[vsa_verification]: verification_summary#how-to-verify