Merge pull request #83 from MarkLodato/mdlint

Reformat using markdownlint and set up GH Action.

.github/dependabot.yml

+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily

.github/workflows/lint.yml

+name: Lint
+on: [pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Markdown Lint
+      uses: nosborn/github-action-markdown-cli@6e34c67b8bd3406dd8ee6eeba353ca4c66793501 # v2.0.0
+      with:
+        files: .
+        config_file: ".markdownlint.yaml"

.markdownlint.yaml

+# MD004/ul-style - Unordered list style
+MD004:
+  style: "dash"
+
+# MD007/ul-indent - Unordered list indentation
+MD007:
+  indent: 4
+
+# MD013/line-length - Line length
+MD013: false
+
+# MD029/ol-prefix - Ordered list item prefix
+MD029:
+  # List style
+  style: "ordered"
+
+# MD030/list-marker-space - Spaces after list markers
+MD030:
+  # Spaces for single-line unordered list items
+  ul_single: 3
+  # Spaces for single-line ordered list items
+  ol_single: 2
+  # Spaces for multi-line unordered list items
+  ul_multi: 3
+  # Spaces for multi-line ordered list items
+  ol_multi: 2
+
+# MD033/no-inline-html - Inline HTML
+MD033: false
+
+# MD034/no-bare-urls - Bare URL used
+MD034: false
+
+# MD046/code-block-style - Code block style
+MD046:
+  style: "fenced"
+
+# MD047/single-trailing-newline - Files should end with a single newline character
+MD047: true
+
+# MD048/code-fence-style - Code fence style
+MD048:
+  style: "backtick"

README.md

@@ -42,11 +42,11 @@ software developers and consumers.
 
 SLSA addresses three issues:
 
--  Software producers want to secure their supply chains but don't know
+-   Software producers want to secure their supply chains but don't know
    exactly how;
--  Software consumers want to understand and limit their exposure to supply
+-   Software consumers want to understand and limit their exposure to supply
    chain attacks but have no means of doing so;
--  Artifact signatures alone prevent only a subset of the attacks we care about.
+-   Artifact signatures alone prevent only a subset of the attacks we care about.
 
 ### Supply Chain Threats
 
@@ -225,7 +225,7 @@ dependencies' supply chains plus its own sources and builds.
 
 Special cases:
 
-*   A ZIP file is containing source code is a package, not a source, because it
+-   A ZIP file is containing source code is a package, not a source, because it
     is built from some other source, such as a git commit.
 
 ### SLSA Levels
@@ -297,6 +297,7 @@ Common - [Security]                  |        |        |        | ✓
 Common - [Access]                    |        |        |        | ✓
 Common - [Superusers]                |        |        |        | ✓
 
+<!-- markdownlint-disable-next-line MD036 -->
 _○ = required unless there is a justification_
 
 [Access]: requirements.md#access
@@ -366,15 +367,15 @@ 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
+-   Reproducible builds do not address source, dependency, or distribution
     threats.
-*   Reproducers must truly be independent, lest they all be susceptible to the
+-   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
+-   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.
@@ -396,38 +397,38 @@ data models. Currently this is joint work between
 [Binary Authorization](https://cloud.google.com/binary-authorization) and
 [in-toto](https://in-toto.io/) but we invite wider participation.
 
-*   [Standard attestation format](https://github.com/in-toto/attestation#in-toto-attestations)
+-   [Standard attestation format](https://github.com/in-toto/attestation#in-toto-attestations)
     to express provenance and other attributes. This will allow sources and
     builders to express properties in a standard way that can be consumed by
     anyone. Also includes reference implementations for generating these
     attestations.
-*   Policy data model and reference implementation.
+-   Policy data model and reference implementation.
 
 For a broader view of the software supply chain problem:
 
-*   [Know, Prevent, Fix: A framework for shifting the discussion around
+-   [Know, Prevent, Fix: A framework for shifting the discussion around
     vulnerabilities in open
     source](https://security.googleblog.com/2021/02/know-prevent-fix-framework-for-shifting.html)
-*   [Threats, Risks, and Mitigations in the Open Source Ecosystem]
+-   [Threats, Risks, and Mitigations in the Open Source Ecosystem]
 
 Prior iterations of the ideas presented here:
 
-*   [Building Secure and Reliable Systems, Chapter 14: Deploying Code](https://sre.google/static/pdf/building_secure_and_reliable_systems.pdf#page=339)
-*   [Binary Authorization for Borg] - This is how Google implements the SLSA
+-   [Building Secure and Reliable Systems, Chapter 14: Deploying Code](https://sre.google/static/pdf/building_secure_and_reliable_systems.pdf#page=339)
+-   [Binary Authorization for Borg] - This is how Google implements the SLSA
     idea internally.
 
 Other related work:
 
-*   [CII Best Practices Badge](https://bestpractices.coreinfrastructure.org/en)
-*   [Security Scorecards](https://github.com/ossf/scorecard) - Perhaps SLSA
+-   [CII Best Practices Badge](https://bestpractices.coreinfrastructure.org/en)
+-   [Security Scorecards](https://github.com/ossf/scorecard) - Perhaps SLSA
     could be implemented as an aggregation of scorecard entries, for at least
     the checks that can be automated.
-*   [Trustmarks](https://trustmark.gtri.gatech.edu/)
+-   [Trustmarks](https://trustmark.gtri.gatech.edu/)
 
 Other takes on provenance and CI/CD:
 
-*   [The Path to Code Provenance](https://medium.com/uber-security-privacy/code-provenance-application-security-77ebfa4b6bc5)
-*   [How to Build a Compromise-Resilient CI/CD](https://www.youtube.com/watch?v=9hCiHr1f0zM)
+-   [The Path to Code Provenance](https://medium.com/uber-security-privacy/code-provenance-application-security-77ebfa4b6bc5)
+-   [How to Build a Compromise-Resilient CI/CD](https://www.youtube.com/watch?v=9hCiHr1f0zM)
 
 <!-- Links -->
 

controls/README.md

@@ -7,11 +7,11 @@ NOTE: This is still a work in progress.
 
 ## Contents
 
-*   [Software Attestations](attestations.md): How to represent software artifact
+-   [Software Attestations](attestations.md): How to represent software artifact
     metadata.
-*   [Policies](policy.md): Conventions for how to express security policies
+-   [Policies](policy.md): Conventions for how to express security policies
     based on attestations.
-*   [Survey](survey.md): Survey of existing and in-development controls that
+-   [Survey](survey.md): Survey of existing and in-development controls that
     relate to the framework.
 
 ## Project Goals
@@ -19,11 +19,11 @@ NOTE: This is still a work in progress.
 (1) Build an ecosystem around software attestations and policies, applicable to
 use cases beyond SLSA and supply chain integrity:
 
-*   Establish clear and consistent terminology and data models.
-*   Define simple interfaces between layers/components, to allow
+-   Establish clear and consistent terminology and data models.
+-   Define simple interfaces between layers/components, to allow
     compatibility between implementations and to encourage discrete,
     composable technologies.
-*   Recommend a cohesive suite of formats, conventions, and tools that are
+-   Recommend a cohesive suite of formats, conventions, and tools that are
     known to work well together.
 
 Currently, there are various projects in this space with overlapping missions
@@ -34,8 +34,8 @@ desire.
 
 (2) Provide recipes for achieving SLSA, built on the ecosystem above:
 
-*   Identify base technologies that meet the SLSA requirements, which serves as
+-   Identify base technologies that meet the SLSA requirements, which serves as
     guidance to system implementers on how to build SLSA-compl8iant services.
     Example: "CI/CD systems should produce provenance attestations in format X."
-*   Recommend simple end-to-end solutions for end users (software developers) to
+-   Recommend simple end-to-end solutions for end users (software developers) to
     achieve SLSA. Example: "Configure GitHub this way to reach SLSA 3."

controls/attestations.md

@@ -21,14 +21,14 @@ in the trusted computing world.)
 An attestation is the generalization of raw artifact/code signing, where the
 signature is directly over the artifact or a hash of artifact:
 
-*   With raw signing, a signature *implies* a single bit of metadata about the
+-   With raw signing, a signature *implies* a single bit of metadata about the
     artifact, based on the public key. The exact meaning must be negotiated
     between signer and verifier, and a new keyset must be provisioned for each
     bit of information. For example, a signature might denote who produced an
     artifact, or it might denote fitness for some purpose, or something else
     entirely.
 
-*   With an attestation, the metadata is *explicit* and the signature only
+-   With an attestation, the metadata is *explicit* and the signature only
     denotes who created the attestation. A single keyset can express an
     arbitrary amount of information, including things that are not possible with
     raw signing. For example, an attestation might state exactly how an artifact
@@ -101,17 +101,17 @@ recognize that other choices may be necessary in various cases.
 
 Summary: Generate [in-toto](https://in-toto.io) attestations.
 
-*   Envelope: **[DSSE](https://github.com/secure-systems-lab/dsse/)** (TODO:
+-   Envelope: **[DSSE](https://github.com/secure-systems-lab/dsse/)** (TODO:
     Recommend Crypto/PKI)
-*   Statement:
+-   Statement:
     **[in-toto/attestation](https://github.com/in-toto/attestation/)**
-*   Predicate: Choose as appropriate.
-    *   [Provenance](https://github.com/in-toto/attestation/tree/main/spec/provenance.md)
-    *   [SPDX](https://github.com/in-toto/attestation/tree/main/spec/spdx.md)
-    *   If none are a good fit, invent a new one.
-*   Bundle and Storage/Lookup:
-    *   Local Filesystem: TODO
-    *   Docker/OCI Registry:
+-   Predicate: Choose as appropriate.
+    -   [Provenance](https://github.com/in-toto/attestation/tree/main/spec/provenance.md)
+    -   [SPDX](https://github.com/in-toto/attestation/tree/main/spec/spdx.md)
+    -   If none are a good fit, invent a new one.
+-   Bundle and Storage/Lookup:
+    -   Local Filesystem: TODO
+    -   Docker/OCI Registry:
         **[sigstore/cosign](https://github.com/sigstore/cosign)**
 
 See [survey](survey.md) for other options.

controls/survey.md

@@ -48,21 +48,21 @@ Raw signing            | ✓        | ✓         | ✗         |         |
 
 Legend:
 
-*   ✓ Defines this layer
-*   ✗ Does not support this layer
-*   ~ Imposes requirements on this layer
-*   (blank) No opinion on this layer
+-   ✓ Defines this layer
+-   ✗ Does not support this layer
+-   ~ Imposes requirements on this layer
+-   (blank) No opinion on this layer
 
 Columns:
 
-*   Envelope: Defines the envelope layer of the attestation.
-*   Statement: Defines the statement layer of the attestation.
-*   Predicate: Defines the predicate layer of the attestation.
-*   Storage: Provides a mechanism for attestation storage and retrieval.
-*   Generation: Provides a mechanism for generating attestations.
-*   Policy: Provides a mechanism for consuming attestations and rendering policy
+-   Envelope: Defines the envelope layer of the attestation.
+-   Statement: Defines the statement layer of the attestation.
+-   Predicate: Defines the predicate layer of the attestation.
+-   Storage: Provides a mechanism for attestation storage and retrieval.
+-   Generation: Provides a mechanism for generating attestations.
+-   Policy: Provides a mechanism for consuming attestations and rendering policy
     decisions.
-*   Status: Is it available now?
+-   Status: Is it available now?
 
 ## Envelope Layer (not specific to Attestations)
 

requirements.md

@@ -2,11 +2,11 @@
 
 Table of Contents:
 
-*   [Definitions](#definitions)
-*   [Source Requirements](#source-requirements)
-*   [Build Requirements](#build-requirements)
-*   [Provenance Requirements](#provenance-requirements)
-*   [Common Requirements](#common-requirements)
+-   [Definitions](#definitions)
+-   [Source Requirements](#source-requirements)
+-   [Build Requirements](#build-requirements)
+-   [Provenance Requirements](#provenance-requirements)
+-   [Common Requirements](#common-requirements)
 
 _Reminder: The definitions below are not yet finalized and subject to change,
 particularly SLSA 3-4._
@@ -167,8 +167,8 @@ only manual command, if any, was to invoke the build script.
 
 Examples:
 
-*   Build script is Makefile, invoked via `make all`.
-*   Build script is .github/workflows/build.yaml, invoked by GitHub Actions.
+-   Build script is Makefile, invoked via `make all`.
+-   Build script is .github/workflows/build.yaml, invoked by GitHub Actions.
 
 <td>✓<td>✓<td>✓<td>✓
 <tr id="build-service">
@@ -197,13 +197,13 @@ from a prior build.
 The build service ensured that the build steps ran in an isolated environment
 free of influence from other build instances, whether prior or concurrent.
 
-*   It MUST NOT be possible for a build to access any secrets of the build
+-   It MUST NOT be possible for a build to access any secrets of the build
     service, such as the provenance signing key.
-*   It MUST NOT be possible for two builds that overlap in time to
+-   It MUST NOT be possible for two builds that overlap in time to
     influence one another.
-*   It MUST NOT be possible for one build to persist or influence the
+-   It MUST NOT be possible for one build to persist or influence the
     build environment of a subsequent build.
-*   Build caches, if used, MUST be purely content-addressable to prevent
+-   Build caches, if used, MUST be purely content-addressable to prevent
     tampering.
 
 <td> <td> <td>✓<td>✓
@@ -217,9 +217,9 @@ fully defined through the build script and nothing else.
 
 Examples:
 
-*   GitHub Actions
+-   GitHub Actions
     [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) `inputs` MUST be empty.
-*   Google Cloud Build
+-   Google Cloud Build
     [user-defined substitutions](https://cloud.google.com/build/docs/configuring-builds/substitute-variable-values)
     MUST be empty. (Default substitutions, whose values are defined by the
     server, are acceptable.)
@@ -235,20 +235,20 @@ access.
 
 The user-defined build script:
 
-*   MUST declare all dependencies, including sources and other build steps,
+-   MUST declare all dependencies, including sources and other build steps,
     using [immutable references] in a format that the build service understands.
 
   The build service:
 
-*   MUST fetch all artifacts in a trusted control plane.
-*   MUST disallow mutable references.
-*   MUST verify the integrity of each artifact.
-    *   If the [immutable reference] includes a cryptographic hash, the service
+-   MUST fetch all artifacts in a trusted control plane.
+-   MUST disallow mutable references.
+-   MUST verify the integrity of each artifact.
+    -   If the [immutable reference] includes a cryptographic hash, the service
         MUST verify the hash and reject the fetch if the verification fails.
-    *   Otherwise, the service MUST fetch the artifact over a channel that
+    -   Otherwise, the service MUST fetch the artifact over a channel that
         ensures transport integrity, such as TLS or code signing.
-*   MUST prevent network access while running the build steps.
-    *   This requirement is "best effort." It SHOULD deter a reasonable team
+-   MUST prevent network access while running the build steps.
+    -   This requirement is "best effort." It SHOULD deter a reasonable team
         from having a non-hermetic build, but it need not stop a determined
         adversary. For example, using a container to prevent network access is
         sufficient.
@@ -304,18 +304,18 @@ the service generating the provenance.
 The data in the provenance MUST be obtained from the build service (either because
 the generator _is_ the build service or because the provenance generator reads the
 data directly from the build service).
-    
+
 Regular users of the service MUST NOT be
 able to inject or alter the contents, except as noted below.
 
 The following provenance fields MAY be generated by the user-controlled build
 steps:
 
-*   The output artifact hash from [Identifies Artifact](#identifies-artifact).
-    *   Reasoning: This only allows a "bad" build to falsely claim that it
+-   The output artifact hash from [Identifies Artifact](#identifies-artifact).
+    -   Reasoning: This only allows a "bad" build to falsely claim that it
         produced a "good" artifact. This is not a security problem because the
         consumer MUST accept only "good" builds and reject "bad" builds.
-*   The "reproducible" boolean and justification from
+-   The "reproducible" boolean and justification from
     [Reproducible](#reproducible).
 
 <td> <td>✓<td>✓<td>✓
@@ -326,26 +326,25 @@ steps:
 Provenance cannot be falsified by the build service's users.
 
 NOTE: This requirement is a stricter version of [Service Generated](#service-generated).
-    
-*   The provenance signing key MUST be stored in a secure key management system
+
+-   The provenance signing key MUST be stored in a secure key management system
     accessible only to the build service account.
-*   The provenance signing key MUST NOT be accessible to the environment running
+-   The provenance signing key MUST NOT be accessible to the environment running
     the user-defined build steps.
-*   Every field in the provenance MUST be generated or verified by the build
+-   Every field in the provenance MUST be generated or verified by the build
     service in a trusted control plane. The user-controlled build steps MUST
     NOT be able to inject or alter the contents, except as noted below.
 
 The following provenance fields MAY be generated by the user-controlled build
 steps without the build service verifying their correctness:
 
-*   The output artifact hash from [Identifies Artifact](#identifies-artifact).
-    *   Reasoning: This only allows a "bad" build to falsely claim that it
+-   The output artifact hash from [Identifies Artifact](#identifies-artifact).
+    -   Reasoning: This only allows a "bad" build to falsely claim that it
         produced a "good" artifact. This is not a security problem because the
         consumer MUST accept only "good" builds and reject "bad" builds.
-*   The "reproducible" boolean and justification from
+-   The "reproducible" boolean and justification from
     [Reproducible](#reproducible).
 
-
 <td> <td> <td>✓<td>✓
 <tr id="dependencies-complete">
 <td>Dependencies Complete
@@ -355,8 +354,8 @@ Provenance records all build dependencies that were available while running the
 build steps. This includes the initial state of the machine, VM, or container of
 the build worker.
 
-*   MUST include all user-specified build steps, sources, dependencies.
-*   SHOULD include all service-provided artifacts.
+-   MUST include all user-specified build steps, sources, dependencies.
+-   SHOULD include all service-provided artifacts.
 
 <td> <td> <td> <td>✓
 </table>

walkthrough.md

@@ -10,36 +10,36 @@ open-source package, not to single it out.)
 The first problem is figuring out the actual supply chain. This requires
 significant manual effort, guesswork, and blind trust. Working backwards:
 
-*   The "latest" tag in Docker Hub points to
+-   The "latest" tag in Docker Hub points to
     [7.72.0](https://hub.docker.com/layers/curlimages/curl/7.72.0/images/sha256-3c3ff0c379abb1150bb586c7d55848ed4dcde4a6486b6f37d6815aed569332fe?context=explore).
-*   It claims to have come from a Dockerfile in the
+-   It claims to have come from a Dockerfile in the
     [curl/curl-docker](https://github.com/curl/curl-docker/blob/d6525c840a62b398424a78d792f457477135d0cf/alpine/latest/Dockerfile)
     GitHub repository.
-*   That Dockerfile reads the following artifacts, assuming there are no further
+-   That Dockerfile reads the following artifacts, assuming there are no further
     fetches during build time:
-    *   Docker Hub image:
+    -   Docker Hub image:
         [registry.hub.docker.com/library/alpine:3.11.5](https://hub.docker.com/layers/alpine/library/alpine/3.11.5/images/sha256-cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221?context=explore)
-    *   Alpine packages: libssh2 libssh2-dev libssh2-static autoconf automake
+    -   Alpine packages: libssh2 libssh2-dev libssh2-static autoconf automake
         build-base groff openssl curl-dev python3 python3-dev libtool curl
         stunnel perl nghttp2
-    *   File at URL: https://curl.haxx.se/ca/cacert.pem
-*   Each of the dependencies has its own supply chain, but let's look at
+    -   File at URL: https://curl.haxx.se/ca/cacert.pem
+-   Each of the dependencies has its own supply chain, but let's look at
     [curl-dev], which contains the actual "curl" source code.
-*   The package, like all Alpine packages, has its build script defined in an
+-   The package, like all Alpine packages, has its build script defined in an
     [APKBUILD](https://git.alpinelinux.org/aports/tree/main/curl/APKBUILD?id=166f72b36f3b5635be0d237642a63f39697c848a)
     in the Alpine git repo. There are several build dependencies:
-    *   File at URL: https://curl.haxx.se/download/curl-7.72.0.tar.xz.
-        *   The APKBUILD includes a sha256 hash of this file. It is not clear
+    -   File at URL: https://curl.haxx.se/download/curl-7.72.0.tar.xz.
+        -   The APKBUILD includes a sha256 hash of this file. It is not clear
             where that hash came from.
-    *   Alpine packages: openssl-dev nghttp2-dev zlib-dev brotli-dev autoconf
+    -   Alpine packages: openssl-dev nghttp2-dev zlib-dev brotli-dev autoconf
         automake groff libtool perl
-*   The source tarball was _presumably_ built from the actual upstream GitHub
+-   The source tarball was _presumably_ built from the actual upstream GitHub
     repository
     [curl/curl@curl-7_72_0](https://github.com/curl/curl/tree/curl-7_72_0), by
     running the commands `./buildconf && ./configure && make && ./maketgz
     7.72.0`. That command has a set of dependencies, but those are not well
     documented.
-*   Finally, there are the systems that actually ran the builds above. We have
+-   Finally, there are the systems that actually ran the builds above. We have
     no indication about their software, configuration, or runtime state
     whatsoever.
 
@@ -47,21 +47,21 @@ Suppose some developer's machine is compromised. What attacks could potentially
 be performed unilaterally with only that developer's credentials? (None of these
 are confirmed.)
 
-*   Directly upload a malicious image to Docker Hub.
-*   Point the CI/CD system to build from an unofficial Dockerfile.
-*   Upload a malicious Dockerfile (or other file) in the
+-   Directly upload a malicious image to Docker Hub.
+-   Point the CI/CD system to build from an unofficial Dockerfile.
+-   Upload a malicious Dockerfile (or other file) in the
     [curl/curl-docker](https://github.com/curl/curl-docker/blob/d6525c840a62b398424a78d792f457477135d0cf/alpine/latest/Dockerfile)
     git repo.
-*   Upload a malicious https://curl.haxx.se/ca/cacert.pem.
-*   Upload a malicious APKBUILD in Alpine's git repo.
-*   Upload a malicious [curl-dev] Alpine package to the Alpine repository. (Not
+-   Upload a malicious https://curl.haxx.se/ca/cacert.pem.
+-   Upload a malicious APKBUILD in Alpine's git repo.
+-   Upload a malicious [curl-dev] Alpine package to the Alpine repository. (Not
     sure if this is possible.)
-*   Upload a malicious https://curl.haxx.se/download/curl-7.72.0.tar.xz. (Won't
+-   Upload a malicious https://curl.haxx.se/download/curl-7.72.0.tar.xz. (Won't
     be detected by APKBUILD's hash if the upload happens before the hash is
     computed.)
-*   Upload a malicious change to the [curl/curl](https://github.com/curl/curl/)
+-   Upload a malicious change to the [curl/curl](https://github.com/curl/curl/)
     git repo.
-*   Attack any of the systems involved in the supply chain, as in the
+-   Attack any of the systems involved in the supply chain, as in the
     [SolarWinds attack](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/).
 
 SLSA intends to cover all of these threats. When all artifacts in the supply