1 package v1 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/v1" 12 ) 13 14 // ProvenancePredicate is the provenance predicate definition. 15 type ProvenancePredicate struct { 16 // The BuildDefinition describes all of the inputs to the build. The 17 // accuracy and completeness are implied by runDetails.builder.id. 18 // 19 // It SHOULD contain all the information necessary and sufficient to 20 // initialize the build and begin execution. 21 BuildDefinition ProvenanceBuildDefinition `json:"buildDefinition"` 22 23 // Details specific to this particular execution of the build. 24 RunDetails ProvenanceRunDetails `json:"runDetails"` 25 } 26 27 // ProvenanceBuildDefinition describes the inputs to the build. 28 type ProvenanceBuildDefinition struct { 29 // Identifies the template for how to perform the build and interpret the 30 // parameters and dependencies. 31 32 // The URI SHOULD resolve to a human-readable specification that includes: 33 // overall description of the build type; schema for externalParameters and 34 // systemParameters; unambiguous instructions for how to initiate the build 35 // given this BuildDefinition, and a complete example. 36 BuildType string `json:"buildType"` 37 38 // The parameters that are under external control, such as those set by a 39 // user or tenant of the build system. They MUST be complete at SLSA Build 40 // L3, meaning that that there is no additional mechanism for an external 41 // party to influence the build. (At lower SLSA Build levels, the 42 // completeness MAY be best effort.) 43 44 // The build system SHOULD be designed to minimize the size and complexity 45 // of externalParameters, in order to reduce fragility and ease 46 // verification. Consumers SHOULD have an expectation of what “good” looks 47 // like; the more information that they need to check, the harder that task 48 // becomes. 49 ExternalParameters interface{} `json:"externalParameters"` 50 51 // The parameters that are under the control of the entity represented by 52 // builder.id. The primary intention of this field is for debugging, 53 // incident response, and vulnerability management. The values here MAY be 54 // necessary for reproducing the build. There is no need to verify these 55 // parameters because the build system is already trusted, and in many cases 56 // it is not practical to do so. 57 InternalParameters interface{} `json:"internalParameters,omitempty"` 58 59 // Unordered collection of artifacts needed at build time. Completeness is 60 // best effort, at least through SLSA Build L3. For example, if the build 61 // script fetches and executes “example.com/foo.sh”, which in turn fetches 62 // “example.com/bar.tar.gz”, then both “foo.sh” and “bar.tar.gz” SHOULD be 63 // listed here. 64 ResolvedDependencies []ResourceDescriptor `json:"resolvedDependencies,omitempty"` 65 } 66 67 // ProvenanceRunDetails includes details specific to a particular execution of a 68 // build. 69 type ProvenanceRunDetails struct { 70 // Identifies the entity that executed the invocation, which is trusted to 71 // have correctly performed the operation and populated this provenance. 72 // 73 // This field is REQUIRED for SLSA Build 1 unless id is implicit from the 74 // attestation envelope. 75 Builder Builder `json:"builder"` 76 77 // Metadata about this particular execution of the build. 78 BuildMetadata BuildMetadata `json:"metadata,omitempty"` 79 80 // Additional artifacts generated during the build that are not considered 81 // the “output” of the build but that might be needed during debugging or 82 // incident response. For example, this might reference logs generated 83 // during the build and/or a digest of the fully evaluated build 84 // configuration. 85 // 86 // In most cases, this SHOULD NOT contain all intermediate files generated 87 // during the build. Instead, this SHOULD only contain files that are 88 // likely to be useful later and that cannot be easily reproduced. 89 Byproducts []ResourceDescriptor `json:"byproducts,omitempty"` 90 } 91 92 // ResourceDescriptor describes a particular software artifact or resource 93 // (mutable or immutable). 94 // See https://github.com/in-toto/attestation/blob/main/spec/v1.0/resource_descriptor.md 95 type ResourceDescriptor struct { 96 // A URI used to identify the resource or artifact globally. This field is 97 // REQUIRED unless either digest or content is set. 98 URI string `json:"uri,omitempty"` 99 100 // A set of cryptographic digests of the contents of the resource or 101 // artifact. This field is REQUIRED unless either uri or content is set. 102 Digest common.DigestSet `json:"digest,omitempty"` 103 104 // TMachine-readable identifier for distinguishing between descriptors. 105 Name string `json:"name,omitempty"` 106 107 // The location of the described resource or artifact, if different from the 108 // uri. 109 DownloadLocation string `json:"downloadLocation,omitempty"` 110 111 // The MIME Type (i.e., media type) of the described resource or artifact. 112 MediaType string `json:"mediaType,omitempty"` 113 114 // The contents of the resource or artifact. This field is REQUIRED unless 115 // either uri or digest is set. 116 Content []byte `json:"content,omitempty"` 117 118 // This field MAY be used to provide additional information or metadata 119 // about the resource or artifact that may be useful to the consumer when 120 // evaluating the attestation against a policy. 121 Annotations map[string]interface{} `json:"annotations,omitempty"` 122 } 123 124 // Builder represents the transitive closure of all the entities that are, by 125 // necessity, trusted to faithfully run the build and record the provenance. 126 type Builder struct { 127 // URI indicating the transitive closure of the trusted builder. 128 ID string `json:"id"` 129 130 // Version numbers of components of the builder. 131 Version map[string]string `json:"version,omitempty"` 132 133 // Dependencies used by the orchestrator that are not run within the 134 // workload and that do not affect the build, but might affect the 135 // provenance generation or security guarantees. 136 BuilderDependencies []ResourceDescriptor `json:"builderDependencies,omitempty"` 137 } 138 139 type BuildMetadata struct { 140 // Identifies this particular build invocation, which can be useful for 141 // finding associated logs or other ad-hoc analysis. The exact meaning and 142 // format is defined by builder.id; by default it is treated as opaque and 143 // case-sensitive. The value SHOULD be globally unique. 144 InvocationID string `json:"invocationID,omitempty"` 145 146 // The timestamp of when the build started. 147 StartedOn *time.Time `json:"startedOn,omitempty"` 148 149 // The timestamp of when the build completed. 150 FinishedOn *time.Time `json:"finishedOn,omitempty"` 151 } 152