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

@@ -29,6 +29,9 @@ provenance:
       name: Version 0.1
     v0.2:
       name: Version 0.2
+    v1.0:
+      name: Version 1.0 (DRAFT)
+      draft: true
   current: v0.2
 
 verification_summary:
@@ -38,3 +41,10 @@ verification_summary:
     v0.2:
       name: Version 0.2
   current: v0.2
+
+github-actions-workflow:
+  versions:
+    v0.1:
+      name: Version 0.1 (DRAFT)
+      draft: true
+  current: v0.1

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

@@ -0,0 +1,44 @@
+{
+    "predicateType": "https://slsa.dev/provenance/v1?draft",
+    "predicate": {
+        "buildDefinition": {
+            "buildType": "https://slsa.dev/github-actions-workflow/v0.1?draft",
+            "externalParameters": {
+                "inputs_build_id": { "value": "123456768" },
+                "inputs_deploy_target": { "value": "deployment_sys_1a" },
+                "inputs_perform_deploy": { "value": "true" },
+                "source": {
+                    "artifact": {
+                        "uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
+                        "digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" }
+                    }
+                },
+                "workflow_path": { "value": ".github/workflow/release.yml" }
+            },
+            "systemParameters": {
+                "github_actor": { "value": "MarkLodato" },
+                "github_event_name": { "value": "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,106 @@
+---
+title: "Build Type: GitHub Actions Workflow"
+layout: standard
+hero_text: |
+    A [SLSA Provenance](../../provenance/v1.0) `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.
+
+<table>
+<tr><th>Parameter<th>Type<th>Description
+
+<tr id="inputs"><td><code>inputs_*</code><td>string<td>
+
+The [inputs context], with each `inputs.<name>` renamed to `inputs_<name>`.
+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="workflow_path"><td><code>workflow_path</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
+
+### System parameters
+
+> 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.
+
+All system parameters are OPTIONAL. Each corresponds to the [github context]
+value of the same name, with `github.<name>` renamed to `github_<name>`. The
+list only includes parameters that are likely to have an effect on the build and
+that are not already captured elsewhere.
+
+| Parameter            | Type     | Description |
+| -------------------- | -------- | ----------- |
+| `github_actor`       | string   | The username of the user that triggered the initial workflow run. |
+| `github_event_name`  | string   | 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.
+
+### 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

docs/provenance/v1.0.cue

@@ -0,0 +1,51 @@
+{
+    // Standard attestation fields:
+    "_type": "https://in-toto.io/Statement/v0.1",
+    "subject": [...],
+
+    // Predicate:
+    "predicateType": "https://slsa.dev/provenance/v1.0?draft",
+    "predicate": {
+        "buildDefinition": {
+            "buildType": string,
+            "externalParameters": { [string]: #ParameterValue },
+            "systemParameters": { [string]: #ParameterValue },
+            "resolvedDependencies": [ ...#ArtifactReference ],
+        },
+        "runDetails": {
+            "builder": {
+                "id": string,
+                "version": string,
+                "builderDependencies": [ ...#ArtifactReference ],
+            },
+            "metadata": {
+                "invocationId": string,
+                "startedOn": #Timestamp,
+                "finishedOn": #Timestamp,
+            },
+            "byproducts": [ ...#ArtifactReference ],
+        }
+    }
+}
+
+#ParameterValue: {
+    "artifact": #ArtifactReference
+} | {
+    "value": string
+}
+
+#ArtifactReference: {
+    "uri": string,
+    "digest": {
+        "sha256": string,
+        "sha512": string,
+        "sha1": string,
+        // TODO: list the other standard algorithms
+        [string]: string,
+    },
+    "localName": string,
+    "downloadLocation": string,
+    "mediaType": string,
+}
+
+#Timestamp: string  // <YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>Z