Add summaries for the security models of attestations and trusted publishing (#17242)

* Add summaries for the security models of attestations and trusted publishers

Signed-off-by: Mac Chaffee <[email protected]>

* Apply suggestions from code review

* Switch to non-walled link

* Clarify short/long-lived token risks

* Update docs/user/trusted-publishers/security-model.md

---------

Signed-off-by: Mac Chaffee <[email protected]>
Co-authored-by: Dustin Ingram <[email protected]>

Author: mac-chaffee

docs/user/attestations/security-model.md

@@ -4,6 +4,29 @@ title: Security Model and Considerations
 
 # Security model and considerations
 
+Since attestations are a framework for asserting certain facts about a package,
+the security model of attestations depends on which types of facts are being
+asserted.
+
+The most basic type of attestation (the type enabled by default in
+[`pypa/gh-action-pypi-publish`][gh-action-pypi-publish]) asserts that the
+project was published by an authorized publisher such as a particular CI
+provider in a particular code repository.
+
+This type of attestation has two main purposes:
+
+- It protects against modification of a project *after* it was built,
+  such as while it is stored in a package index or mirror.
+- It allows verifying parties to observe *changes* to the project's Trusted Publisher.
+  For example, a verifying party might observe that a project's new releases
+  are coming from a different Trusted Publisher, indicating that control
+  of the project may have changed hands maliciously.
+
+More advanced types of attestations can assert more things about the package
+such as whether it was tampered with *before* it was built, but these
+attestations require specialized build processes and are rarer as a result. See
+"[What about reproducible builds?]" in the SLSA FAQ.
+
 ## General considerations
 
 PyPI's support for attestations is built on top of a combination
@@ -14,27 +37,27 @@ See below for security considerations for each.
 
 !!! note
 
-    TL;DR: An attestation will tell you **who** produced a
-    PyPI package, but not **whether** you should trust them.
+    TL;DR: An attestation will tell you **where** a PyPI package came from, but
+    not **whether** you should trust it.
 
 Like with all signing schemes, it's tempting to treat the *presence* of
 an attestation as proof of a package's *trustworthiness*.
 
-However, this is **not** what an attestation (or any kind of signature)
-conveys. At its core, a valid signature for some identity conveys a
-proof of **authenticity**: if the signature is verifiable against a key,
-then we know that the identity that controls that key produced the signature
-and is saying *something* about the signed-over data.
+However, this is **not** what an attestation (or any kind of signature) conveys.
+At its core, a valid signature for an identity on a package conveys a proof of
+access to that identity while the package was built.
 
-In other words: a valid signature asserts **authenticity**, but it does **not**
-tell the verifying party (e.g., a user installing packages from PyPI) **whether**
-they should trust the identity that holds the key.
+In other words: a valid signature does **not** tell the verifying party (e.g., a
+user installing packages from PyPI) **whether** they should trust the identity
+that holds the key or whether they should trust that malicious/vulnerable code
+was added before or during the build.
 
 As a concrete example: PyPI serves `sampleproject-4.0.0.tar.gz`, which is
 [attested] by [pypa/sampleproject] on GitHub. This is a proof that
-`sampleproject-4.0.0.tar.gz` is authentic for that identity, but it does **not**
-tell the user **whether** they should trust [pypa/sampleproject]. To determine
-trust, the user *must* make a trust decision about [pypa/sampleproject].
+`sampleproject-4.0.0.tar.gz` came from that identity unmodified, but it does
+**not** tell the user **whether** they should trust [pypa/sampleproject]. To
+determine trust, the user *must* make a trust decision about
+[pypa/sampleproject].
 
 This trust decision can have a time dimension: a user might decide to trust
 [pypa/sampleproject] because it was the first identity seen for the
@@ -116,6 +139,10 @@ PyPI's attestations feature makes full use of these trust-reduction techniques:
 attestations are not considered verified unless they include an inclusion proof
 from Rekor, as well as an inclusion proof from Fulcio's CT log.
 
+[gh-action-pypi-publish]: https://github.com/pypa/gh-action-pypi-publish
+
+[What about reproducible builds?]: https://slsa.dev/spec/v1.0/faq#q-what-about-reproducible-builds
+
 [Trusted Publishing]: /trusted-publishers/
 
 [Sigstore's "keyless signing"]: https://docs.sigstore.dev/cosign/signing/overview/

docs/user/trusted-publishers/security-model.md

@@ -4,23 +4,50 @@ title: Security Model and Considerations
 
 # Security model and considerations
 
-## General considerations
-
-While more secure than passwords and long-lived API tokens, OIDC publishing
-is not a panacea. In particular:
-
-* Short-lived API tokens are still sensitive material, and should not be
-  disclosed (ideally not at all, but certainly not before they expire).
-
-* OIDC tokens themselves are sensitive material, and should not be disclosed.
-  OIDC tokens are also short-lived, but an attacker who successfully intercepts
-  one can mint API tokens against it for as long as it lives.
+Trusted Publishing is primarily designed to be a more secure alternative to
+the long-lived API tokens that have traditionally been used for publishing to
+PyPI.
+
+In recent years, theft of credentials such as API tokens has [played a major
+role in cyber attacks]. The reason for this is the unfortunate reality that
+managing credentials can be complicated and risky. Trusted Publishing reduces
+this risk by using short-lived tokens instead of long-lived tokens. Short-lived
+tokens are less likely to be misplaced, leaked in logs, or stolen by malware
+since they don't have to be stored. Additionally, if short-lived tokens are
+leaked, they only give attackers a narrow time window to exploit the leaked
+token, which minimizes the potential damage.
+
+However, it is important to still be aware of the kinds of risks that
+Trusted Publishing does not cover. You should think of Trusted Publishing as one
+tool in the toolbelt for securing packages.
 
-* Configuring a Trusted Publisher means establishing trust in a particular piece
-  of external state (such as a GitHub Actions workflow); that state **must not**
-  be controllable by untrusted parties.
+## General considerations
 
-In summary: treat your Trusted Publishers *as if* they were API tokens. If you
+* Trusted Publishing uses short-lived API tokens that expire 
+  no more than 15 minutes after the OIDC flow that authorizes them.
+  Just like normal API authentication, Trusted Publishing
+  does not assert the safety of the code or the trustworthiness
+  of its authors.
+ 
+* Trusted Publishing does not address whether the package has been modified
+  before or after it was built. [Attestations] can address those risks.
+
+* Short-lived API tokens are sensitive material that must be protected from
+  getting stolen or leaked.
+
+* OIDC tokens themselves are also sensitive material that must be protected
+  from getting stolen or leaked. OIDC tokens expire quickly, but an attacker who
+  successfully intercepts one can use it to generate API tokens until it
+  expires.
+
+* Configuring a Trusted Publisher means trusting an identity provider (IdP),
+  such as GitHub Actions. Trusted Publishing relies on the integrity of that
+  IdP and the actors that are authorized to use it. In practice, this means
+  that users of Trusted Publishing must protect and secure the CI/CD workflows
+  that they register as Trusted Publishers, as weaknesses in those workflows
+  can be equivalent to credential compromise.
+
+In summary: treat your Trusted Publishers *as if* they are API tokens. If you
 wouldn't let a user or piece of code access your API token, then they shouldn't
 be able to invoke your Trusted Publisher.
 
@@ -147,7 +174,7 @@ own security model and considerations.
     When using Trusted Publishing with Google Cloud, you must trust the service account
     and _any service which uses it as the default ephemeral identity_.
 
-    Specifically, it is not recommened to configure the [default service
+    Specifically, it is not recommended to configure the [default service
     accounts](https://cloud.google.com/iam/docs/service-account-types#default), as
     they are provided by default to every service when they are created.
 
@@ -258,6 +285,10 @@ own security model and considerations.
       access the OIDC token to a bare minimum. This prevents both accidental
       and malicious disclosure.
 
+[played a major role in cyber attacks]: https://therecord.media/cisa-cyberattacks-using-valid-credentials
+
+[Attestations]: /attestations/
+
 [fundamentally dangerous]: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
 
 [Use a dedicated environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment