1 package v02 2 3 import ( 4 "time" 5 6 "github.com/in-toto/in-toto-golang/in_toto/slsa_provenance/common" 7 ) 8 9 const ( 10 // PredicateSLSAProvenance represents a build provenance for an artifact. 11 PredicateSLSAProvenance = "https://slsa.dev/provenance/v0.2" 12 ) 13 14 // These are type aliases to common to avoid backwards incompatible changes. 15 type ( 16 DigestSet = common.DigestSet 17 ProvenanceBuilder = common.ProvenanceBuilder 18 ProvenanceMaterial = common.ProvenanceMaterial 19 ) 20 21 // ProvenancePredicate is the provenance predicate definition. 22 type ProvenancePredicate struct { 23 // Builder identifies the entity that executed the invocation, which is trusted to have 24 // correctly performed the operation and populated this provenance. 25 // 26 // The identity MUST reflect the trust base that consumers care about. How detailed to be is a 27 // judgement call. For example, GitHub Actions supports both GitHub-hosted runners and 28 // self-hosted runners. The GitHub-hosted runner might be a single identity because it’s all 29 // GitHub from the consumer’s perspective. Meanwhile, each self-hosted runner might have its 30 // own identity because not all runners are trusted by all consumers. 31 Builder common.ProvenanceBuilder `json:"builder"` 32 33 // BuildType is a URI indicating what type of build was performed. It determines the meaning of 34 // [Invocation], [BuildConfig] and [Materials]. 35 BuildType string `json:"buildType"` 36 37 // Invocation identifies the event that kicked off the build. When combined with materials, 38 // this SHOULD fully describe the build, such that re-running this invocation results in 39 // bit-for-bit identical output (if the build is reproducible). 40 // 41 // MAY be unset/null if unknown, but this is DISCOURAGED. 42 Invocation ProvenanceInvocation `json:"invocation,omitempty"` 43 44 // BuildConfig lists the steps in the build. If [ProvenanceInvocation.ConfigSource] is not 45 // available, BuildConfig can be used to verify information about the build. 46 // 47 // This is an arbitrary JSON object with a schema defined by [BuildType]. 48 BuildConfig interface{} `json:"buildConfig,omitempty"` 49 50 // Metadata contains other properties of the build. 51 Metadata *ProvenanceMetadata `json:"metadata,omitempty"` 52 53 // Materials is the collection of artifacts that influenced the build including sources, 54 // dependencies, build tools, base images, and so on. 55 // 56 // This is considered to be incomplete unless metadata.completeness.materials is true. 57 Materials []common.ProvenanceMaterial `json:"materials,omitempty"` 58 } 59 60 // ProvenanceInvocation identifies the event that kicked off the build. 61 type ProvenanceInvocation struct { 62 // ConfigSource describes where the config file that kicked off the build came from. This is 63 // effectively a pointer to the source where [ProvenancePredicate.BuildConfig] came from. 64 ConfigSource ConfigSource `json:"configSource,omitempty"` 65 66 // Parameters is a collection of all external inputs that influenced the build on top of 67 // ConfigSource. For example, if the invocation type were “make”, then this might be the 68 // flags passed to make aside from the target, which is captured in [ConfigSource.EntryPoint]. 69 // 70 // Consumers SHOULD accept only “safe” Parameters. The simplest and safest way to 71 // achieve this is to disallow any parameters altogether. 72 // 73 // This is an arbitrary JSON object with a schema defined by buildType. 74 Parameters interface{} `json:"parameters,omitempty"` 75 76 // Environment contains any other builder-controlled inputs necessary for correctly evaluating 77 // the build. Usually only needed for reproducing the build but not evaluated as part of 78 // policy. 79 // 80 // This SHOULD be minimized to only include things that are part of the public API, that cannot 81 // be recomputed from other values in the provenance, and that actually affect the evaluation 82 // of the build. For example, this might include variables that are referenced in the workflow 83 // definition, but it SHOULD NOT include a dump of all environment variables or include things 84 // like the hostname (assuming hostname is not part of the public API). 85 Environment interface{} `json:"environment,omitempty"` 86 } 87 88 type ConfigSource struct { 89 // URI indicating the identity of the source of the config. 90 URI string `json:"uri,omitempty"` 91 // Digest is a collection of cryptographic digests for the contents of the artifact specified 92 // by [URI]. 93 Digest common.DigestSet `json:"digest,omitempty"` 94 // EntryPoint identifying the entry point into the build. This is often a path to a 95 // configuration file and/or a target label within that file. The syntax and meaning are 96 // defined by buildType. For example, if the buildType were “make”, then this would reference 97 // the directory in which to run make as well as which target to use. 98 // 99 // Consumers SHOULD accept only specific [ProvenanceInvocation.EntryPoint] values. For example, 100 // a policy might only allow the "release" entry point but not the "debug" entry point. 101 // MAY be omitted if the buildType specifies a default value. 102 EntryPoint string `json:"entryPoint,omitempty"` 103 } 104 105 // ProvenanceMetadata contains metadata for the built artifact. 106 type ProvenanceMetadata struct { 107 // BuildInvocationID identifies this particular build invocation, which can be useful for 108 // finding associated logs or other ad-hoc analysis. The exact meaning and format is defined 109 // by [common.ProvenanceBuilder.ID]; by default it is treated as opaque and case-sensitive. 110 // The value SHOULD be globally unique. 111 BuildInvocationID string `json:"buildInvocationID,omitempty"` 112 113 // BuildStartedOn is the timestamp of when the build started. 114 // 115 // Use pointer to make sure that the abscense of a time is not 116 // encoded as the Epoch time. 117 BuildStartedOn *time.Time `json:"buildStartedOn,omitempty"` 118 // BuildFinishedOn is the timestamp of when the build completed. 119 BuildFinishedOn *time.Time `json:"buildFinishedOn,omitempty"` 120 121 // Completeness indicates that the builder claims certain fields in this message to be 122 // complete. 123 Completeness ProvenanceComplete `json:"completeness"` 124 125 // Reproducible if true, means the builder claims that running invocation on materials will 126 // produce bit-for-bit identical output. 127 Reproducible bool `json:"reproducible"` 128 } 129 130 // ProvenanceComplete indicates wheter the claims in build/recipe are complete. 131 // For in depth information refer to the specifictaion: 132 // https://github.com/in-toto/attestation/blob/v0.1.0/spec/predicates/provenance.md 133 type ProvenanceComplete struct { 134 // Parameters if true, means the builder claims that [ProvenanceInvocation.Parameters] is 135 // complete, meaning that all external inputs are properly captured in 136 // ProvenanceInvocation.Parameters. 137 Parameters bool `json:"parameters"` 138 // Environment if true, means the builder claims that [ProvenanceInvocation.Environment] is 139 // complete. 140 Environment bool `json:"environment"` 141 // Materials if true, means the builder claims that materials is complete, usually through some 142 // controls to prevent network access. Sometimes called “hermetic”. 143 Materials bool `json:"materials"` 144 } 145