Provenance v1.0: initial draft

.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