Provenance v1.0: initial draft (#525)

This is an initial draft v1.0 for the provenance format. It attempts to address
the major sources of confusion with v0.2, particularly the separation of
concerns between top-level external inputs, resolved dependencies, and per-run
details.

There are still many outstanding TODOs and unresolved design decisions. The idea
is to submit this now so that we can more easily get feedback on the schema and
substance, then send further PRs to address the remaining TODOs and RFCs.

Signed-off-by: Mark Lodato <[email protected]>

.markdownlint.yaml

@@ -14,6 +14,9 @@ MD025:
   # Disable checking of YAML frontmatter.
   front_matter_title: ""
 
+# MD028/no-blanks-blockquote - Blank line inside blockquote
+MD028: false
+
 # MD029/ol-prefix - Ordered list item prefix
 MD029:
   # List style

docs/_data/versions.yml

@@ -34,6 +34,10 @@ provenance:
     v0.2:
       name: Version 0.2
       status: Stable
+    v1:
+      name: Version 1.0 (DRAFT)
+      draft: true
+      status: Working Draft
   current: v0.2
 
 verification_summary:
@@ -45,3 +49,11 @@ verification_summary:
       name: Version 0.2
       status: Stable
   current: v0.2
+
+github-actions-workflow:
+  versions:
+    v0.1:
+      name: Version 0.1 (DRAFT)
+      draft: true
+      status: Working Draft
+  current: v0.1

docs/github-actions-workflow/v0.1/example.json

@@ -0,0 +1,59 @@
+{
+    "predicateType": "https://slsa.dev/provenance/v1?draft",
+    "predicate": {
+        "buildDefinition": {
+            "buildType": "https://slsa.dev/github-actions-workflow/v0.1?draft",
+            "externalParameters": {
+                "inputs": {
+                    "mapValue": {
+                        "build_id": "123456768",
+                        "deploy_target": "deployment_sys_1a",
+                        "perform_deploy": "true"
+                    }
+                },
+                "source": {
+                    "artifactRef": {
+                        "uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
+                        "digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" }
+                    }
+                },
+                "inputs": {
+                    "mapValue": {
+                        "mascot": "Mona"
+                    }
+                },
+                "workflowPath": {
+                    "scalarValue": ".github/workflow/release.yml"
+                }
+            },
+            "systemParameters": {
+                "github": {
+                    "mapValue": {
+                        "actor": "MarkLodato",
+                        "event_name": "workflow_dispatch"
+                    }
+                }
+            },
+            "resolvedDependencies": [
+                {
+                    "uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1"
+                }
+            ]
+        },
+        "runDetails": {
+            "builder": {
+                "id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1"
+            },
+            "metadata": {
+                "invocationId": "https://github.com/octocat/hello-world/actions/runs/1536140711/attempts/1",
+                "startedOn": "2023-01-01T12:34:56Z"
+            }
+        }
+    },
+    "subject": [
+        {
+            "name": "_",
+            "digest": { "sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4" }
+        }
+    ]
+}

docs/github-actions-workflow/v0.1/index.md

@@ -0,0 +1,115 @@
+---
+title: "Build Type: GitHub Actions Workflow"
+layout: standard
+hero_text: |
+    A [SLSA Provenance](../../provenance/v1) `buildType` that describes the
+    execution of a GitHub Actions workflow.
+---
+
+## Description
+
+This `buildType` describes the execution of a top-level [GitHub Actions]
+workflow (as a whole).
+
+Note: This type is not meant to describe execution of subsets of the top-level
+workflow, such as an action, a job, or a reusable workflow.
+
+[GitHub Actions]: https://docs.github.com/en/actions
+
+## Build Definition
+
+### External parameters
+
+All external parameters are REQUIRED unless empty.
+
+<table>
+<tr><th>Parameter<th>Type<th>Description
+
+<tr id="inputs"><td><code>inputs</code><td>mapValue<td>
+
+The [inputs context], with each value converted to string. Every non-empty input
+value MUST be recorded. Empty values SHOULD be omitted.
+
+Note: Only `workflow_dispatch` events and reusable workflows have inputs.
+
+<tr id="source"><td><code>source</code><td>artifact<td>
+
+The git repository containing the top-level workflow YAML file.
+
+This can be computed from the [github context] using
+`"git+" + github.server_url + "/" + github.repository + "@" + github.ref`.
+
+<tr id="vars"><td><code>vars</code><td>vars<td>
+
+The [vars context], with each value converted to string. Every non-empty input
+value MUST be recorded. Empty values SHOULD be omitted.
+
+<tr id="workflowPath"><td><code>workflowPath</code><td>string<td>
+
+The path to the workflow YAML file within `source`.
+
+Note: this cannot be computed directly from the [github context]: the
+`github.workflow` context field only provides the *name* of the workflow, not
+the path. See [getEntryPoint] for one possible implementation.
+
+[getEntryPoint]: https://github.com/slsa-framework/slsa-github-generator/blob/ae7e58c315b65aa92b9440d5ce25d795845b3b2a/slsa/buildtype.go#L94-L135
+
+</table>
+
+[github context]: https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
+[inputs context]: https://docs.github.com/en/actions/learn-github-actions/contexts#inputs-context
+[vars context]: https://docs.github.com/en/actions/learn-github-actions/contexts#vars-context
+
+### System parameters
+
+All system parameters are OPTIONAL.
+
+| Parameter            | Type     | Description |
+| -------------------- | -------- | ----------- |
+| `github`       | mapValue   | A subset of the [github context] as described below. Only includes parameters that are likely to have an effect on the build and that are not already captured elsewhere. |
+
+The `github` map SHOULD contains the following elements:
+
+| GitHub Context Parameter        | Description |
+| ------------------------------- | ----------- |
+| `github.mapValue["actor"]`      | The username of the user that triggered the initial workflow run. |
+| `github.mapValue["event_name"]` | The name of the event that triggered the workflow run. |
+
+> TODO: What about `actor_id`, `repository_id`, and `repository_owner_id`? Those
+> are not part of the context so they're harder to describe, and the repository
+> ones should arguably go on the `source` paramater rather than be here.
+>
+> Also `base_ref` and `head_ref` are similar in that they are annotations about
+> `source` rather than a proper parameter.
+
+> TODO: None of these are really "parameters", per se, but rather metadata
+> about the build. Perhaps they should go in `runDetails` instead? The problem
+> is that we don't have an appropriate field for it currently.
+
+### Resolved dependencies
+
+The resolved dependencies MAY contain any artifacts known to be input to the
+workflow, such as the specific versions of the virtual environments used.
+
+## Run details
+
+### Metadata
+
+The `invocationId` SHOULD be set to `github.server_url + "/actions/runs/" +
+github.run_id + "/attempts/" + github.run_attempt`.
+
+## Example
+
+```json
+{% include_relative example.json %}
+```
+
+Note: The `builder.id` in the example assumes that the build runs under
+[slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator).
+If GitHub itself generated the provenance, the `id` would be different.
+
+## Version history
+
+### v0.1
+
+Initial version