SALT How To…​

The following sections review common needs related to software attestations and how they could be met with SALT.

Store attestations in my registry of choice

Storing the attestation documents in the central Attestation Registry is optional: organizations might prefer to store attestations (which physically are JSON files) co-located with the software artifacts referenced. For example, attestations related to an image may be stored in the same OCI registry where the container images are stored.

There is a project named ORAS (OCI Registry As Storage) that looks for using OCI Registries for arbitrary artifacts, including attestations. You may use its command-line tool to upload attestations to any compatible OCI registry.

Other alternatives are to push the attestation as an artifact in your CI/CD, co-located with the product artifact it references, or embedded as metadata in the packaged software artifact itself. The location of the attestation depends on your use-case and how consumers of the software will perform verifications downstream.

To disable automatic upload to the configured central attestation registry, use the --no-upload and --output options in the attestation commit | attestation provenance commands to not upload the attestation to the central registry and instead store it in a local file that could later be published in your registry of choice.

Xygeni provides a distribution of the Attestation Registry, so organizations may use their own instance, instead of using the public one. Please contact your Xygeni representative for further information.

Use keyless signatures

To use keyless signing, the --keyless option could be passed to the attestation commit | provenance commands. This will fetch an OpenID Connect (OIDC) from specific issuers, using an OAuth flow (standard or device).

Jobs running in CI/CD runners use an OIDC provider that authenticates the job and generates an OIDC ID token. The token will be stored either in an environment variable or in a CI/CD file.The variable and the path are configured in the conf/salt.yaml file:

# Configuration for identity-based ("keyless") certification authority,
# to use for certifying ephemeral public keys.
keylessConfig:
  # The environment variable which may contain a valid OIDC id_token,
  # typically obtained from an OIDC provider in CI/CD systems.
  tokenVar: SIGSTORE_ID_TOKEN
  # The filesystem path where the OIDC token will be loaded
  tokenPath: /var/run/sigstore/cosign/oidc-token
  # ...

For interactive usage (e.g. when NOT in a CI/CD pipeline), the end-user is authenticated using the browser against one of the supported OIDC providers (Google, GitHub or Azure), when the token cannot be found in the configured env-var or file:

Example: For GitLab, ID tokens could be declared in the GitLab pipeline using the id_tokens entry. GitLab will authenticate the running job with the OIDC provider, and place the OIDC ID token in the specified environment variable. For the default environment variable with the token, you may use the default SIGSTORE_ID_TOKEN, and set aud: sigstore so the JWT token is recognized by Fulcio.

generate_attestation_job:
  # GitLab puts the OIDC token in SIGSTORE_ID_TOKEN env-var
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore

  script:
     # salt will fetch from $SIGSTORE_ID_TOKEN
     - salt at slsa --keyless ... rest of command here ...

See OIDC Authentication in GitLab for further details.

See Keyless Signing for details about how OpenID Connect and OAuth authentication can be used for creating ephemeral keys and certificates that could be trusted for attestation verification.

Add SBOM and other reports to attestations

The attestation add allows you to pass an item to be included in the attestation as the predicate (or part of the compound predicate). There are predicates designed to convey SBOM and reports from security tools as part of an attestation, for example for SBOM formats like CycloneDX and SPDX, or for vulnerability reports from security scanners.

Please read Available Predicate Types for further information.

Set command autocompletion

The salt command may export command-line completion (for Bash or ZSH shells only).To install completion, simply run:

source <(salt generate-completion)

Autocompletion helps with writing complex commands, and the -h |--help flag makes it easier to build and test the commands for adding software attestations to your pipelines.