From 497e4e241f22db344344063c9800a83c2cd2079d Mon Sep 17 00:00:00 2001 From: Tanmay Jain Date: Tue, 14 Jul 2026 18:03:30 +0530 Subject: [PATCH] Added docs for Provenance PostProcessor --- post-processor/provenance/post-processor.go | 92 ++++++++++++++++----- 1 file changed, 70 insertions(+), 22 deletions(-) diff --git a/post-processor/provenance/post-processor.go b/post-processor/provenance/post-processor.go index c6f96add0..eb9439b2b 100644 --- a/post-processor/provenance/post-processor.go +++ b/post-processor/provenance/post-processor.go @@ -2,6 +2,7 @@ // SPDX-License-Identifier: BUSL-1.1 //go:generate packer-sdc mapstructure-to-hcl2 -type Config +//go:generate packer-sdc struct-markdown package provenance @@ -32,28 +33,75 @@ var buildSigstoreBundleForSigner = internalattestation.BuildBundleForSigner type Config struct { common.PackerConfig `mapstructure:",squash"` - Provenance config.Trilean `mapstructure:"provenance"` - BuildType string `mapstructure:"build_type"` - OutputDir string `mapstructure:"output_dir"` - TemplatePath string `mapstructure:"template"` - OnlyBuilds []string `mapstructure:"only_builds"` - UserVariables map[string]string `mapstructure:"user_variables"` - SourceURI string `mapstructure:"source_uri"` - SBOM bool `mapstructure:"sbom"` - SBOMFormat string `mapstructure:"sbom_format"` - SBOMScanPath string `mapstructure:"sbom_scan_path"` - SBOMScope string `mapstructure:"sbom_scope"` - SBOMExclude []string `mapstructure:"sbom_exclude"` - SigningMode string `mapstructure:"signing_mode"` - Signer string `mapstructure:"signer"` - Key string `mapstructure:"key"` - Verifier string `mapstructure:"verifier"` - FulcioURL string `mapstructure:"fulcio_url"` - RekorURL string `mapstructure:"rekor_url"` - UploadTlog bool `mapstructure:"upload_tlog"` - TrustedRootPath string `mapstructure:"trusted_root_path"` - KeylessIdentity string `mapstructure:"keyless_identity"` - KeylessOIDCIssuer string `mapstructure:"keyless_oidc_issuer"` + // Whether to emit provenance attestations. Enabled by default; set to + // `false` to skip the post-processor and pass the artifact through unchanged. + Provenance config.Trilean `mapstructure:"provenance"` + // The SLSA `buildType` URI recorded in the provenance predicate. Defaults to + // `https://packer.io/buildtypes/hcl2/v1`. + BuildType string `mapstructure:"build_type"` + // Directory where attestation sidecar files are written. Defaults to the + // directory containing the artifact's first file, or the current directory + // for artifacts without local files. + OutputDir string `mapstructure:"output_dir"` + // Path to the Packer template that produced the artifact. Recorded as an + // external parameter in the provenance predicate. + TemplatePath string `mapstructure:"template"` + // The list of builds this artifact came from. Recorded as an external + // parameter in the provenance predicate. + OnlyBuilds []string `mapstructure:"only_builds"` + // Additional user variables to record as external parameters in the + // provenance predicate. Values for variables named in + // `packer_sensitive_variables` are redacted. + UserVariables map[string]string `mapstructure:"user_variables"` + // Overrides the auto-detected source repository URI recorded as a resolved + // dependency. By default the source is detected from the Git repository + // containing the current working directory or from CI environment variables. + SourceURI string `mapstructure:"source_uri"` + // Whether to also generate a software bill of materials (SBOM) and a + // corresponding SBOM attestation alongside the provenance statement. + SBOM bool `mapstructure:"sbom"` + // The SBOM output format, either `cyclonedx` (default) or `spdx`. + SBOMFormat string `mapstructure:"sbom_format"` + // The path to scan when generating the SBOM. Defaults to the artifact's + // files or their common parent directory. Required when the artifact files + // span multiple directories. + SBOMScanPath string `mapstructure:"sbom_scan_path"` + // The SBOM scan scope, either `squashed` (default) or `all-layers`. + SBOMScope string `mapstructure:"sbom_scope"` + // Glob patterns of paths to exclude from the SBOM scan. + SBOMExclude []string `mapstructure:"sbom_exclude"` + // The signing mode for attestations: `none` (default, unsigned JSON), + // `key` (local PEM key), `kms` (KMS or Vault URI), or `keyless` (Sigstore + // Fulcio). + SigningMode string `mapstructure:"signing_mode"` + // The signer reference. A PEM private key path for `key` mode, or a KMS or + // Vault URI such as `awskms://...`, `gcpkms://...`, `azurekms://...`, or + // `hashivault://...` for `kms` mode. + Signer string `mapstructure:"signer"` + // An alias for `signer`. When both are set they must be equal. + Key string `mapstructure:"key"` + // The PEM verifier path used to verify the signature in `key` and `kms` + // modes. Defaults to the signer's derived public key. + Verifier string `mapstructure:"verifier"` + // The Fulcio certificate authority URL used for `keyless` signing. Defaults + // to `https://fulcio.sigstore.dev`. + FulcioURL string `mapstructure:"fulcio_url"` + // The Rekor transparency log URL used when `upload_tlog` is enabled. + // Defaults to `https://rekor.sigstore.dev`. + RekorURL string `mapstructure:"rekor_url"` + // Whether to upload the `keyless` signature to the Rekor transparency log + // and emit a Sigstore bundle carrying the transparency evidence. + UploadTlog bool `mapstructure:"upload_tlog"` + // An optional path to a Sigstore trusted-root JSON file used to pin keyless + // verification. When unset, the public Sigstore trusted root is fetched. + TrustedRootPath string `mapstructure:"trusted_root_path"` + // The expected signing identity for `keyless` mode, such as the workflow + // ref `https://github.com/OWNER/REPO/.github/workflows/build.yml@refs/heads/main`. + // Required for keyless signing. + KeylessIdentity string `mapstructure:"keyless_identity"` + // The expected OIDC issuer for `keyless` mode, such as + // `https://token.actions.githubusercontent.com`. Required for keyless signing. + KeylessOIDCIssuer string `mapstructure:"keyless_oidc_issuer"` ctx interpolate.Context }