Merge pull request #30 from MarkLodato/controls

Merge slsa-controls into slsa

README.md

@@ -24,8 +24,8 @@ standards, inspired by what Google does
     aspects of security.
 2.  **Accreditation:** Process for organizations to certify compliance with
     these standards.
-3.  **[Technical controls][slsa-controls]:** To record provenance and detect or
-    prevent non-compliance.
+3.  **[Technical controls](controls/README.md):** To record provenance and
+    detect or prevent non-compliance.
 
 Ultimately, the software consumer decides whom to trust and what standards to
 enforce. In this light, accreditation is a means to transfer trust across
@@ -38,8 +38,6 @@ an accreditation process and technical controls over time. In the interim, these
 levels can provide value as guidelines for how to secure a software supply
 chain.
 
-[slsa-controls]: https://github.com/slsa-framework/slsa-controls
-
 ## Principles
 
 We suggest initially focusing on the following two main principles:

controls/README.md

+# SLSA: Technical Controls
+
+This repository contains an index of technical controls that fit into the
+[SLSA Framework](../README.md).
+
+NOTE: This is still a work in progress.
+
+## Contents
+
+*   [Software Attestations](attestations.md): How to represent software artifact
+    metadata.
+*   [Policies](policy.md): Conventions for how to express security policies
+    based on attestations.
+*   [Survey](survey.md): Survey of existing and in-development controls that
+    relate to the framework.
+
+## Project Goals
+
+(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
+    compatibility between implementations and to encourage discrete,
+    composable technologies.
+*   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
+and incompatible interfaces. No one project solves all problems and it is
+confusing to understand how the pieces fit together. Our goal is to define a
+"well-lit path" to make it easier for users to achieve the guarantees they
+desire.
+
+(2) Provide recipes for achieving SLSA, built on the ecosystem above:
+
+*   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
+    achieve SLSA. Example: "Configure GitHub this way to reach SLSA 3."

controls/attestations.md

+# Software Attestations
+
+Author: lodato@google.com \
+Date: March 2021 \
+Status: IN REVIEW
+
+## Objective
+
+Standardize the terminology, data model, layers, and conventions for software
+artifact metadata.
+
+## Overview
+
+A software attestation is a signed statement (metadata) about a software
+artifact or collection of software artifacts. (Sometimes called a
+"[software bill of materials](https://en.wikipedia.org/wiki/Software_bill_of_materials)"
+or SBoM. Not to be confused with
+[remote attestation](https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation)
+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
+    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
+    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
+    was produced, including the build command that was run and all of its
+    dependencies.
+
+## Intended Use Case
+
+The primary intended use case is to feed into an
+[automated policy framework](policy.md). See that doc for more info.
+
+Other use cases are "nice-to-haves", including ad-hoc analysis.
+
+## Model and Terminology
+
+We define the following model to represent any software attestations, regardless
+of format. Not all formats will have all fields or all layers, but to be called
+an "attestation" it must fit this general model.
+
+The key words MUST, SHOULD, and MAY are to be interpreted as described in
+[RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+<p align="center"><img width="100%" src="images/attestation_layers.svg"></p>
+
+Example in English:
+
+<p align="center"><img width="80%" src="images/attestation_example_english.svg"></p>
+
+Summary:
+
+-   **Artifact:** Immutable blob of data, usually identified by cryptographic
+    content hash. Examples: file content, git commit, Docker image. May also
+    include a mutable locator, such as a package name or URI.
+-   **Attestation:** Authenticated, machine-readable metadata about one or more
+    software artifacts. MUST contain at least:
+    -   **Envelope:** Authenticates the message. At a minimum, it contains:
+        -   **Message:** Content (statement) of the attestation. The message
+            type SHOULD be authenticated and unambiguous to avoid confusion
+            attacks.
+        -   **Signature:** Denotes the **attester** who created the attestation.
+    -   **Statement:** Binds the attestation to a particular set of artifacts.
+        This is a separate layer is to allow for predicate-agnostic processing
+        and storage/lookup. MUST contain at least:
+        -   **Subject:** Identifies which artifacts the predicate applies to.
+        -   **Predicate:** Metadata about the subject. The predicate type SHOULD
+            be explicit to avoid misinterpretation.
+    -   **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY
+        contain:
+        -   **Link:** *(repeated)* Reference to a related artifact, such as
+            build dependency. Effectively forms a
+            [hypergraph](https://en.wikipedia.org/wiki/Hypergraph) where the
+            nodes are artifacts and the hyperedges are attestations. It is
+            helpful for the link to be standardized to allow predicate-agnostic
+            graph processing.
+-   **Bundle:** A collection of Attestations, which are usually but not
+    necessarily related.
+    -   Note: The bundle itself is unauthenticated. Authenticating multiple
+        attestations as a unit is [TBD](#compound-statement).
+-   **Storage/Lookup:** Convention for where attesters place attestations and
+    how verifiers find attestations for a given artifact.
+
+See [Survey](survey.md) for examples.
+
+## Recommended Suite
+
+We recommend a single suite of formats and conventions that work well together
+and have desirable security properties. Our hope is to align the industry around
+this particular suite because it makes everything easier. That said, we
+recognize that other choices may be necessary in various cases.
+
+Summary: Generate [in-toto](https://in-toto.io) attestations.
+
+*   Envelope:
+    **[secure-systems-lab/signing-spec](https://github.com/secure-systems-lab/signing-spec/)**
+    (TODO: Recommend Crypto/PKI)
+*   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:
+        **[sigstore/cosign](https://github.com/sigstore/cosign)**
+
+See [survey](survey.md) for other options.
+
+## Future Extensions
+
+### Expanded artifact definition
+
+TODO: Can a subject of an attestation be something like "GCP project at time T"?
+That is logically immutable since the "at time T" cannot change.
+
+### Compound predicate
+
+TODO: One subject but multiple predicates. Should we offer an opinion on whether
+this is represented at the Statement layer (repeated predicate) or Predicate
+layer (a "compound" type predicate)?
+
+### Compound statement
+
+TODO: One envelope has multiple statements (separate subject+predicate pairs)
+signed as a unit, which are not valid individually. Is this one attestation or
+multiple?
+
+TODO: Should we represent this as multiple messages within the envelope (i.e. a
+shim) or as a new type of Statement that refers to the other Statements (perhaps
+too complicated).
+
+### Attestation as an artifact
+
+TODO: If you have separate signed attestations and want to refer to the
+collection (e.g. a signed bundle), you can create a statement referring to all
+of them as the subject.
+
+TODO: Figure out serialization. Previously I had been thinking envelopes didn't
+have to be serialized deterministically, but now if they are an Artifact it does
+have to be deterministic/immutable.
+
+## Appendix: Naming
+
+TODO(lodato) Provide a survey of possible names we considered, along with
+pros/cons: Attestation, Testimony, Testament, Claim, Voucher, Statement,
+Predicate, Message, Finding.

controls/policy.md

+# Attestation-based Policies
+
+Author: lodato@google.com \
+Date: March 2021 \
+Status: EARLY DRAFT
+
+## Objective
+
+Standardize the terminology, data model, and interfaces for admission control
+policy based on [software attestations](attestations.md).
+
+## Model and Terminology
+
+*TODO: Define what an attestation-based admission control policy is.*
+
+<p align="center"><img width="50%" src="images/policy_model.svg"></p>
+
+To make the decision, a policy engine combines the following:
+
+-   The artifact identifier, usually a cryptographic content hash.
+-   One or more attestations about the artifact or related artifacts.
+-   A policy describing the requirements as a function of the attestations.
+
+The decision is usually "allow" or "deny". It may be preventative
+("enforcement") or detective ("auditing").
+
+*TODO: Better define the policy model, including the notion of attester, subject
+verification, logging, etc.*
+
+*TODO: Note that a policy decision may itself be an attestation that can be fed
+into further policy decisions down the line.*
+
+*TODO: Two modes: (a) only allow if a "good" attestation exists,
+even if there also exists some "bad" attestation; (b) block if some "bad"
+attestation exists, even if there also exists some "good" attestation. Talk
+about threat model and whether the attestation storage is trusted. (a) is better
+for enforcement in the critical path, while (b) is useful for vulnerability
+remediation.*

controls/survey.md

+# Survey of Known Technologies
+
+Author: lodato@google.com \
+Date: March 2021 \
+Status: IN REVIEW
+
+## Objective
+
+Document all known technologies that relate to SLSA, how they map to our model,
+and a (hopefully not too biased) assessment of various properties of each.
+
+See [Attestations](attestations.md) and [Policy](policy.md) for the
+corresponding models and terminology.
+
+## Overview
+
+The following table provides an overview of how various technologies map to our
+model. Subsequent sections analyze each layer.
+
+[Binary Authorization]: https://cloud.google.com/binary-authorization
+[JSS]: https://jsonenc.info/jss/1.0/
+[JWS]: https://tools.ietf.org/html/rfc7515
+[JWT]: https://tools.ietf.org/html/rfc7519
+[Notary v2]: https://github.com/notaryproject/nv2
+[OpenPGP]: https://tools.ietf.org/html/rfc4880
+[PASETO]: https://paseto.io
+[SPDX]: https://github.com/spdx/spdx-spec
+[Simple Signing]: https://github.com/containers/image/blob/master/docs/containers-signature.5.md
+[in-toto v1]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md
+[in-toto v2]: https://github.com/in-toto/attestations
+[signing-spec]: https://github.com/secure-systems-lab/signing-spec/
+
+Project                | Envelope | Statement | Predicate | Storage | Generation | Policy | Status
+---------------------- | -------- | --------- | --------- | ------- | ---------- | ------ | ------
+Raw signing            | ✓        | ✓         | ✗         |         |            |        | (varies)
+[JSS]                  | ✓        |           |           |         |            |        | Abandoned
+[JWS]                  | ✓        |           |           |         |            |        | IETF Standard
+[JWT]                  | ✓        |           |           |         |            |        | IETF Standard
+[OpenPGP]              | ✓        |           |           |         |            |        | IETF Standard
+[PASETO]               | ✓        |           |           |         |            |        | Stable
+[signing-spec]         | ✓        |           |           |         |            |        | In development
+[in-toto v1]           | ✓        | ✓         | ✓         |         | ✓          | ✓      | Stable
+[Notary v2]            | ~        | ✓         | ✗         | ✓       |            | ✓      | In development
+[Simple Signing]       | ~        | ✓         |           |         |            |        | Stable
+[in-toto v2]           | ~        | ✓         |           |         |            |        | In development
+[SPDX]                 |          |           | ✓         |         |            |        | Stable
+[Binary Authorization] | ~        | ~         | ✗         | ~       |            | ✓      | Stable
+
+Legend:
+
+*   ✓ 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
+    decisions.
+*   Status: Is it available now?
+
+## Envelope Layer (not specific to Attestations)
+
+Property                | [signing-spec] | [OpenPGP] | [JWS] | [JWT] | [PASETO] | [in-toto v1] | [JSS]
+----------------------- | -------------- | --------- | ----- | ----- | -------- | ------------ | -----
+Authenticated Purpose   | ✓              | ✗         | ✓     | ✓     | ✗        | ✓            | ✗
+Arbitrary Message Type  | ✓              | ✓         | ✓     | ✗     | ✗        | ✗            | ✗
+Simple                  | ✓              | ✗         | ✗     | ✗     | ✓        | ✓            | ✓
+Avoids Canonicalization | ✓              | ✓         | ✓     | ✓     | ✓        | ✗            | ✓
+Pluggable Crypto        | ✓              | ✗         | ✓     | ✓     | ✗        | ✓            | ✓
+Efficient Encoding      | ✓              | ✗         | ✗     | ✗     | ✗        | ✓            | ✗
+Widely Adopted          | ✗ (not yet!)   | ✓         | ✓     | ✓     | ✗        | ✗            | ✗
+
+Properties:
+
+-   **Authenticated Purpose:** Does the envelope authenticate how the verifier
+    should interpret the message in order to prevent confusion attacks?
+    -   ✓ signing-spec: `payloadType`, JWS: `typ`, JWT: `aud`, in-toto v1:
+        `_type`
+-   **Arbitrary Message Type:** Does the envelope support arbitrary message
+    types / encodings?
+    -   ✗ PASETO, JWT, in-toto v1, JSS: only supports JSON messages
+-   **Simple:** Is the standard simple, easy to understand, and unlikely to be
+    implemented incorrectly?
+    -   ✗ PGP: Enformous RFC.
+    -   ✗ JWS, JWT: Enormous RFC, many vulnerabilities in the past.
+-   **Avoids Canonicalization:** Does the protocol avoid relying on
+    canonicalization for security, in order to reduce attack surface?
+    -   ✗ in-toto v1: Relies on Canonical JSON
+-   **Pluggable Crypto:** If desired, can the cryptographic algorithm and key
+    management be swapped out if desired? (Not always desirable.)
+    -   ✗ OpenPGP: Uses PGP
+    -   ✗ PASETO: Mandates very specific algorithms, e.g. ed25519
+-   **Efficient Encoding:** Does the standard avoid base64, or can the envelope
+    be re-encoded in a more efficient format, such as protobuf or CBOR, without
+    invalidating the signature?
+-   **Widely Adopted:** Is the standard widely adopted?
+    -   ✗ signing-spec: Not yet used, though in-toto and TUF plan to.
+    -   ✗ PASETO: Not common.
+    -   ✗ in-toto v1: Only by in-toto and TUF.
+    -   ✗ JSS: Abandoned, never used.
+
+## Statement Layer
+
+Property              | [in-toto v2] | [in-toto v1] | [Simple Signing] | [Notary v2] | Raw Signing
+--------------------- | ------------ | ------------ | ---------------- | ----------- | -----------
+Recommended Envelope  | signing-spec | in-toto v1   | OpenPGP          | JWT         | (various)
+Subject: Clear        | ✓            | ✗            | ✓                | ✓           | ✓
+Subject: Any Type     | ✓            | ✓            | ✗                | ✓           | (depends)
+Subject: Multi-Digest | ✓            | ✓            | ✗                | ✗           | (depends)
+Predicate: Supported  | ✓            | ✓            | ✓                | ✗           | ✗
+Predicate: Flexible   | ✓            | ✗ (*)        | ✓                | (n/a)       | (n/a)
+Predicate: Typed      | ✓            | ✗            | ✗                | (n/a)       | (n/a)
+Layered               | ✓            | ✗            | ✓                | (n/a)       | (n/a)
+Evolvable             | ✓            | ✓            | ✗                | ✓           | ✗
+
+Properties:
+
+-   **Recommended Envelope:** Which envelope is recommended (or possibly
+    required)?
+-   **Subject: Clear:** Is the Attestation clearly about a particular
+    attestation?
+    -   ✗ in-toto v1: Subject is ambiguous between `materials` and `products`.
+-   **Subject: Any Type:** Does Subject support arbitrary Artifact types?
+    -   ✗ Simple Signing: `critical.image` only supports Docker/OCI image
+        manifests (and because it's `critical`, that field is required.) Also,
+        `critical.identity` is required but not applicable to all use cases
+        (e.g. build provenance, where the identity is not yet known).
+-   **Subject: Multi-Digest:** Does Subject support specifying multiple digest
+    algorithms for crypto agility?
+    -   ✗ Simple Signing, Notary v2: Only one digest supported. (The `multihash`
+        algorithm mentioned in the OCI image-spec is not defined or implemented
+        anywhere.)
+-   **Predicate: Supported:** Can a predicate be supplied?
+    -   ✗ Notary v2: Does not officially support a predicate. Undefined what
+        happens if extra predicate fields are added to the JWT.
+-   **Predicate: Flexible:** Can a user-defined predicate be used?
+    -   ✗ in-toto v1: Several fixed, required predicate fields. Technically
+        arbitrary data can be added to `environment` but that is not well
+        documented or standardized.
+    -   ✓ Simple Signing: Can use `optional` field.
+-   **Predicate: Typed:** Is there a well-established convention of indicating
+    the meaning of the Attestation and/or the schema of the user-defined
+    predicate unambiguous?
+-   **Layered:** Does the schema clearly match the layers of our
+    [model](#model-and-terminology)?
+    -   ✗ in-toto v1: Statement and Predicate fields are mixed together.
+-   **Evolvable:** Can the spec be modified to support required features?
+    -   ✗ Simple Signing: The `critical` field can effectively never change
+        because the producer and consumer must agree in lock step.
+
+## Bundle + Storage/Lookup
+
+-   Local filesystem
+    -   (none yet)
+-   OCI/Docker Registry:
+    -   [sigstore/cosign](https://github.com/sigstore/cosign) **(recommended)**
+    -   [Notary v2]
+
+## Raw artifact signing
+
+For reference, we list examples of raw artifact signing, where the statement
+only contains the subject.
+
+-   [Node.js](https://github.com/nodejs/node#verifying-binaries)
+    ([example](https://nodejs.org/dist/v14.16.0/SHASUMS256.txt.asc))
+    -   Envelope: PGP Signed Message.
+    -   Statement: List of (sha256, filename) pairs.
+
+## TODO
+
+Show how the following are related:
+
+-   Cosign / SigStore
+-   Kritis
+-   Grafeas / Container Analysis
+-   Docker Content Trust
+-   Notary v1
+-   "attached" signatures. RPMs, Maven artifacts, Windows drivers, OSX app store
+    apps
+-   Android APK signatures
+-   (Public) transparency ledger?