Unverified Commit 725bae50 authored by Mark Lodato's avatar Mark Lodato Committed by GitHub
Browse files

Merge pull request #83 from MarkLodato/mdlint

Reformat using markdownlint and set up GH Action.
parents 81795370 16a1a47a
version: 2
updates:
- package-ecosystem: github-actions
directory: "/"
schedule:
interval: daily
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"
# 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"
......@@ -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 -->
......
......@@ -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."
......@@ -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.
......
......@@ -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)
......
......@@ -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>
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment