slsa.dev 2.0 (PR 1/x): Content and structure updates

README.md

@@ -1,19 +1,48 @@
-# SLSA: Supply-chain Levels for Software Artifacts
+# SLSA ("salsa") is Supply-chain Levels for Software Artifacts
 
-SLSA (pronunced "salsa") is an open source security framework to describe and
-verify what integrity looks like, giving anyone working with software a common
-language and a way to work at scale.
+SLSA (pronounced ["salsa"](https://www.google.com/search?q=how+to+pronounce+salsa)) is security framework from source to service, giving anyone working with software a common language for increasing levels of software security and supply chain integrity.
 
 **The best way to read about SLSA is to visit [slsa.dev].**
 
 ## What's in this repo?
 
-The primary content of this repo is the [docs/](docs/) directory, containing the
-sources to the [slsa.dev] website. This directory includes the core SLSA
-specification.
+The primary content of this repo is the [docs/](docs/) directory, which contains the core SLSA
+specification and sources to the [slsa.dev] website.
 
-Other files are auxiliary documents that may be useful for the development of
-SLSA.
+You can read SLSA's documentation here:
+
+-   [Levels](docs/levels.md) (Defining the framework)
+-   [Requirements](docs/requirements.md) (How to attain compliance)
+-   [Example of use](docs/example.md)
+-   Our [roadmap](docs/roadmap.md)
+
+## Project status
+
+SLSA is currently in alpha. The framework is constantly being improved. We encourage the community to try adopting SLSA levels incrementally and to share your experiences back to us.
+
+## Contributors
+
+-   [Kim Lewandowski](https://github.com/kimsterv)
+-   [Mark Lodato](https://github.com/MarkLodato)
+-   [Tom Hennen](https://github.com/TomHennen)
+-   [Joshua Lock](https://github.com/joshuagl)
+-   [Jacques Chester](https://github.com/jchestershopify)
+-   And [many others](https://github.com/slsa-framework/slsa/graphs/contributors)
+
+## Get involved
+
+We rely on feedback from other organisations to evolve SLSA and be more useful to more people. We’d love to hear your experiences using it.
+
+**Are the levels achievable in your project? Would you add or remove anything from the framework? What else is needed before you can adopt it?**
+
+-   If you want to discuss the framework, [github issues](https://github.com/slsa-framework/slsa/issues) are [the way](https://i.redd.it/yj67b76hxwd61.jpg).
+-   If you want to contribute to the framework take a look at our [contribution guidelines](CONTRIBUTING.md).
+
+### Joining the working group
+
+-   We meet bi-monthly on Wednesdays at 9am PT. Anyone is welcome to join, whether to listen or to contribute. [Here's the invite](https://calendar.google.com/calendar/u/0/r/week/2021/8/11?eid=NjIycXNoOHBtbDhuNTJiNjlmaWk5ZjU5ZWVfMjAyMTA4MTFUMTYwMDAwWiBzNjN2b2VmaHA1aTlwZmx0YjVxNjduZ3Blc0Bn&sf=true).
+-   We're part of the OpenSSF [Digital Identity Attestation Working Group](https://github.com/ossf/wg-digital-identity-attestation). The OpenSSF community calendar is [here](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ).
+-   Our [Google Group is here](https://groups.google.com/g/ossf-wg-developer-identity), where you can participate in discussion or join the mailing list.
 
 <!-- Links -->
 

docs/_config.yml

@@ -3,8 +3,11 @@ description: Supply-chain Levels for Software Artifacts
 copyright_html: Copyright 2021 The Linux Foundation<br>under the terms of the <a href="https://github.com/slsa-framework/slsa/blob/main/LICENSE">Apache License 2.0</a>
 repository: slsa-framework/slsa
 header_pages:
+  - levels.md
   - requirements.md
-  - walkthrough.md
+  - example.md
+  - roadmap.md
+  - getinvolved.md
 exclude:
   - README.md
 

docs/faq.md

@@ -0,0 +1,68 @@
+# Frequently Asked Questions
+
+<!-- NOTE: This page is currently not currently listed in the navbar because it is light on content. We will add a link once we have more questions. -->
+
+## Q: Why is SLSA not transitive?
+
+SLSA is not transitive in order to make the problem tractable. If SLSA 4
+required dependencies to be SLSA 4, then reaching SLSA 4 would require starting
+at the very beginning of the supply chain and working forward. This is
+backwards, forcing us to work on the least risky component first and blocking
+any progress further downstream. By making each artifact's SLSA rating
+independent from one another, it allows parallel progress and prioritization
+based on risk. (This is a lesson we learned when deploying other security
+controls at scale throughout Google.) We expect SLSA ratings to be composed to
+describe a supply chain's overall security stance, as described in the case
+study [vision](walkthrough.md#vision-case-study).
+
+## Q: What about reproducible builds?
+
+When talking about [reproducible builds](https://reproducible-builds.org), there
+are two related but distinct concepts: "reproducible" and "verified
+reproducible."
+
+"Reproducible" means that repeating the build with the same inputs results in
+bit-for-bit identical output. This property
+[provides](https://reproducible-builds.org/docs/buy-in/)
+[many](https://wiki.debian.org/ReproducibleBuilds/About)
+[benefits](https://static.googleusercontent.com/media/sre.google/en//static/pdf/building_secure_and_reliable_systems.pdf#page=357),
+including easier debugging, more confident cherry-pick releases, better build
+caching and storage efficiency, and accurate dependency tracking.
+
+For these reasons, SLSA 4 [requires](#level-requirements) reproducible builds
+unless there is a justification why the build cannot be made reproducible.
+[Example](https://lists.reproducible-builds.org/pipermail/rb-general/2021-January/002177.html)
+justifications include profile-guided optimizations or code signing that
+invalidates hashes. Note that there is no actual reproduction, just a claim that
+reproduction is possible.
+
+"Verified reproducible" means using two or more independent build systems to
+corroborate the provenance of a build. In this way, one can create an overall
+system that is more trustworthy than any of the individual components. This is
+often
+[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/)
+as a solution to supply chain integrity. Indeed, this is one option to secure
+build steps of a supply chain. When designed correctly, such a system can
+satisfy all of the SLSA build requirements.
+
+That said, verified reproducible builds are not a complete solution to supply
+chain integrity, nor are they practical in all cases:
+
+-   Reproducible builds do not address source, dependency, or distribution
+    threats.
+-   Reproducers must truly be independent, lest they all be susceptible to the
+    same attack. For example, if all rebuilders run the same pipeline software,
+    and that software has a vulnerability that can be triggered by sending a
+    build request, then an attacker can compromise all rebuilders, violating the
+    assumption above.
+-   Some builds cannot easily be made reproducible, as noted above.
+-   Closed-source reproducible builds require the code owner to either grant
+    source access to multiple independent rebuilders, which is unacceptable in
+    many cases, or develop multiple, independent in-house rebuilders, which is
+    likely prohibitively expensive.
+
+Therefore, SLSA does not require verified reproducible builds directly. Instead,
+verified reproducible builds are one option for implementing the requirements.
+
+For more on reproducibility, see
+[Hermetic, Reproducible, or Verifiable?](https://sre.google/static/pdf/building_secure_and_reliable_systems.pdf#page=357)

docs/getinvolved.md

@@ -0,0 +1,26 @@
+# Get involved
+
+**We rely on feedback from other organisations to evolve SLSA and be more useful to more people. We’d love to hear your experiences using it!**
+
+## Feedback
+
+**Are the levels achievable in your project? Would you add or remove anything from the framework? What’s preventing you from adopting it today?**
+
+-   If you want to discuss the framework, [github issues](https://github.com/slsa-framework/slsa/issues) are [the way](https://i.redd.it/yj67b76hxwd61.jpg).
+-   If you want to contribute to the framework take a look at our [contribution guidelines](https://github.com/slsa-framework/slsa/blob/main/CONTRIBUTING.md).
+-   We’re keen to hear your thoughts on how to improve this website. **Take our 5 minute survey [by visiting this link](https://www.smartsurvey.co.uk/s/FM3W4B/).**
+
+## Community
+
+-   We meet bi-monthly on Wednesdays at 9am PT. Anyone is welcome to join, whether to listen or to contribute. [Here's the invite](https://calendar.google.com/calendar/u/0/r/week/2021/8/11?eid=NjIycXNoOHBtbDhuNTJiNjlmaWk5ZjU5ZWVfMjAyMTA4MTFUMTYwMDAwWiBzNjN2b2VmaHA1aTlwZmx0YjVxNjduZ3Blc0Bn&sf=true).
+-   We're part of the OpenSSF [Digital Identity Attestation Working Group](https://github.com/ossf/wg-digital-identity-attestation). The OpenSSF community calendar is [here](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ).
+-   Our [Google Group is here](https://groups.google.com/g/ossf-wg-developer-identity), where you can participate in discussion or join the mailing list.
+
+## We are
+
+-   [Kim Lewandowski](https://github.com/kimsterv)
+-   [Mark Lodato](https://github.com/MarkLodato)
+-   [Tom Hennen](https://github.com/TomHennen)
+-   [Joshua Lock](https://github.com/joshuagl)
+-   [Jacques Chester](https://github.com/jchestershopify)
+-   And [many others](https://github.com/slsa-framework/slsa/graphs/contributors)