Provenance: clarify `parameters` can point to the source of the parameter

[samwhite-gl]

Background

Many builds require secrets to be fed into the build job as parameters. Exposing the values of these parameters directly in the attestation could create a security risk.

Currently the wording of the Includes all build parameters SLSA requirement does not make it clear whether it is necessary to include the value of the parameters themselves in the attestation or whether a pointer to the source where the parameter is stored would be adequate to meet the requirement.

Proposal

This issue proposes the following:

1. Add language to clarify that the Includes all build parameters requirement can be met by pointing to a location where the parameters are stored rather than by including the parameters in the attestation directly. Including a pointer to the location of the parameter should be recommended for any parameters that contain secrets.
2. The SLSA schema should also be updated to set the value of predicate.invocation.parameters as an array of objects as follows. This will give the flexibility to allow for attestations that include parameters that both directly describe the value of the parameter as well as attestations that indirectly point to the source location for the parameter.

Example

"parameters": [
  {
    "key": "default_username",
    "value": "admin"
  },
  {
    "key": "default_password",
    "location": "<URI>" // Could point to a git project, a CI file, or a secret management tool
  }
],

Note: This was discussed in the 2022-06-09 SLSA Working Group Call.

[samwhite-gl]

@mlieberman85 would you mind reviewing this proposal?

[joshuagl]

Note: invocation.parameters is "an arbitrary JSON object with a schema defined by buildType.", therefore it's perfectly reasonable for a build service to define a schema which makes sense for them here. I raised an issue suggesting we provide more guidance for buildType specific schemas and general extensibility of the provenance schema: https://github.com/slsa-framework/slsa/issues/396