github.com/yogeshkumararora/slsa-github-generator@v1.10.1-0.20240520161934-11278bd5afb4/PROVENANCE_FORMAT.md (about) 1 # Provenance Format 2 3 The provenance format for each workflow conforms to the [SLSA v0.2 provenance 4 format](https://slsa.dev/provenance/v0.2). Each of the projects populates the 5 provenance with the same base information based on GitHub Actions. The common 6 fields of the SLSA provenance predicate attested to are below. 7 8 ## Common Fields 9 10 ### Builder 11 12 `Builder.Id`: The builder ID refers to the fully qualified URI of the trusted builder's workflow and its reference. 13 14 ```json 15 "builder": { 16 "id": "https://github.com/yogeshkumararora/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1" 17 } 18 ``` 19 20 ### Build Type 21 22 `buildType`: This is the URI for the particular provenance builder. For example, this is the `buildType` for the Go builder: 23 24 ```json 25 "buildType": "https://github.com/yogeshkumararora/slsa-github-generator/go@v1" 26 ``` 27 28 In SLSA the [buildType](https://slsa.dev/provenance/v0.2#buildType) defines how 29 many other fields are formatted including all of those below. 30 31 ### Invocation 32 33 `invocation`: Identifies the event that kicked off the build. This describes the workflow run and includes GitHub workflow event information, entrypoint, and parameters from trigger events. 34 35 `invocation.configSource`: This describes the calling workflow's source (`uri` and `digest`) and the `entryPoint` of the build. 36 37 ```json 38 "configSource": { 39 "uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main", 40 "digest": { 41 "sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2" 42 }, 43 "entryPoint": ".github/workflows/release.yml" 44 }, 45 ``` 46 47 `invocation.parameters`: This describes any parameters from trigger events. 48 49 `invocation.environment`: This describes the GitHub workflow builder-controlled environment variables, including the event information, required to reproduce the build. See `github` content [documentation](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) for more information. 50 51 | Name | Value | Description | 52 | ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 53 | `github_event_name` | `workflow_dispatch`, `schedule`, `push`, etc | Name of the [event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#available-events) that initiated the workflow run. | 54 | `github_event_payload` | `"{"inputs": null, "repository": { ... }}"` | The full [event payload](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads), including workflow inputs and repository information. | 55 | `github_ref_type` | `"branch"` | The type of ref that triggered the workflow run. | 56 | `github_ref` | `"refs/heads/main"` | The ref that triggered the workflow run. | 57 | `github_base_ref` | `"feat/feat-branch"` | The ref or source branch of the pull request in a workflow run. Only populated on pull requests. | 58 | `github_head_ref` | `"feat/feat-branch"` | The is ref or source branch of the pull request in a workflow run. | 59 | `github_actor` | `"laurentsimon"` | The username of the user that initiated the workflow run. | 60 | `github_sha1` | `"b54fb2ec8807a93b58d5f298b7e6b785ea7078bb"` | The is the commit SHA that triggered the workflow run. | 61 | `github_repository_owner` | `"slsa-framework"` | The owner of the repository. | 62 | `github_repository_id` | `"8923542"` | The is the unique ID of the repository. | 63 | `github_actor_id` | `"973615"` | The is the unique ID of the actor that triggered the workflow run. | 64 | `github_repository_owner_id` | `"123456"` | The is the unique ID of the owner of the repository. | 65 | `github_run_attempt` | `"1"` | The is run attempt of the workflow run. | 66 | `github_run_id` | `"2436960022"` | The is the run ID for the workflow run. | 67 | `github_run_number` | `"32"` | The is the run number of the workflow run. | 68 69 ```json 70 "environment": { 71 "github_actor": "laurentsimon", 72 "github_base_ref": "", 73 "github_event_name": "workflow_dispatch", 74 "github_event_payload": { 75 "inputs": null, 76 "ref": "refs/heads/main", 77 "repository": { ... } 78 }, 79 "github_head_ref": "add-field-docs", 80 "github_ref": "refs/pull/169/merge", 81 "github_ref_type": "branch", 82 "github_repository_owner": "slsa-framework", 83 "github_run_attempt": "1", 84 "github_run_id": "2436960022", 85 "github_run_number": "32", 86 "github_sha1": "b54fb2ec8807a93b58d5f298b7e6b785ea7078bb", 87 "github_repository_id": "8923542", 88 "github_repository_owner": "ianlewis", 89 "github_repository_owner_id": "123456", 90 } 91 ``` 92 93 ### Build Config 94 95 `buildConfig`: This contains information on the steps of the build. The default is nil, specific builders implement their own. See: 96 97 - [Golang BuildConfig Format](https://github.com/yogeshkumararora/slsa-github-generator/blob/main/internal/builders/go/README.md#buildconfig-format). 98 99 ### Materials 100 101 `materials`: List of materials that influenced the build, including the repository that triggered the GitHub Actions workflow. 102 103 ```json 104 "materials": [ 105 { 106 "uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main", 107 "digest": { 108 "sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2" 109 } 110 }, 111 { 112 "uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1" 113 } 114 ] 115 ``` 116 117 ### Metadata 118 119 `metadata`: Other properties of the build, including `BuildInvocationID`, which is the unique `RunID` and `RunAttempt` separated by a '-'. 120 121 ```json 122 "metadata": { 123 "buildInvocationID": "2387611653-1", 124 "completeness": { 125 "parameters": true, 126 "environment": false, 127 "materials": false 128 }, 129 "reproducible": false 130 }, 131 132 ``` 133 134 Specific implementations of builders may define and customize their own `buildConfig`, `invocation`, `materials`, and `metadata`.