Build Security

About Build Security

Xygeni helps you to protect the integrity of your artifacts and build (CI/CD) processes. This is known as Build Security.

The Xygeni platform provides a component for an important part of Build Security: the creation, storage and verification of attestations on the software.

The following sections describe Xygeni SALT (Software Attestations Layer for Trust), the component for generating, registering and verifying software attestations.

Quick Start

Install the SALT command-line tool. The following commands work under Linux/macOS.

  # download zipfile
  curl -sLO https://get.xygeni.io/latest/salt/salt.zip
  # unzip in current directory
  unzip salt.zip -d PATH_TO_DIR
  # add alias
  alias salt="PATH_TO_DIR/xygeni_salt/salt"

where PATH_TO_DIR stands for the directory where the SALT tool will be uncompressed (proceed to Installing Salt CLI for detailed instructions or on a different operating system).

Now you can generate sample attestations for your software product: Go to a product repository directory (cd <YOUR_REPO_DIR>), and run commands for creating an one-shot SLSA attestation (attestation slsa):

cd <YOUR_REPO_DIR>
salt at provenance -p my_pipeline -d . \
     --image my_org/my_image:latest \
     --keyless \
     -o slsa.json --output-unsigned slsa.unsigned.json \
     --no-upload --no-result-upload

The SLSA Provenance attestation is written in slsa.unsigned.json file, and the signed envelope (signed with an ephemeral keypair, certified with an ephemeral certificate) is stored in the slsa.json file.

Now verify the attestation:

salt verify \
     --attestation=provenance.signed.json \
     --public-key=cert2.pem --image=xygeni/xygeni_scanner:latest

Concepts

A software attestation is an assertion made about a piece of software. A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts.

Software attestations are a generalization of raw artifact/code signing. The attestation is a signed document (in a given format, typically based on JSON) that associates metadata with an artifact. They represent evidence linking inputs (materials) and outputs (artifacts produced) at each build step.

Attestations provide a verifiable record of the steps done for building the final software artifacts, including input materials for each step and the build commands run.

For more information about what software attestations are, what they are used for, the structure of a software attestation and which standards are in place, please refer to Concepts in Build Security section.

How SALT works

SALT (acronym for Software Attestation Layer for Trust) is the feature in the Xygeni platform for build security. SALT is the infrastructure for creating and verifying software attestations, aiming at different use-cases.

A command-line interface (salt command) is provided for generating attestations in CI/CD pipelines, or for verification of the integrity of the attestations with regard to the software artifacts the attestation refers to. Additional integrations, like plugins, are provided for the most popular CI/CD systems. See command-line reference for further details.

Xygeni provides an attestation registry based on the combination of the in-toto Archivista as storage and sigstore Rekor as a transparency log. The public server for the Xygeni-provided attestation registry is at https://salt.xygeni.io.

Result upload: The results for the attestation generation are uploaded to Xygeni, so any error or integrity failure is reported and could be notified to DevOps engineers and security management teams.

For further information, see how SALT works.

Architecture

The Salt model contains most of the in-toto specification types for software attestations, as shown in the Attestations supported.

The following image depicts the main components of SALT:

For further information, see SALT Architecture.

Command-Line

Salt provides a command-line interface (Salt CLI) with commands for creating the attestation document from the inputs, interacting with the attestations registry, and verifying an attestation with respect to the referenced software product.

salt CMD, with CMD = attestation | keygen | registry | contract | verify.

The Salt CLI has two levels (command + subcommand), and -h | --help will show the help at the command or subcommand level.

The main commands are:

• salt keygen: Generate key pairs for signing

• salt attestation init|add|run|status|commit|reset: Incremental attestation build

• salt attestation provenance: Provenance for pipeline, in a single shot

• salt registry search | get | put: Operations with Attestation Registry

• salt verify: Verify contract / attestation for SW artifact

• salt contract create | from-build | upload | download: Contract handling

Software attestations are typically created in the same pipeline that builds and/or deploys the software. One or more steps can run Salt CLI commands to either build the attestation either in one shot (salt attestation provenance) or incrementally at different steps along the pipeline (salt attestation init|add|run|commit).

See Salt Command-Line Interface Reference for further details.

Attestation Format

SALT follows the in-toto Attestation Framework (IAF). The IAF provides a specification for generating verifiable claims about any aspect of how a piece of software is produced. Consumers or users of software can then validate the origins of the software, and establish trust in its supply chain, using in-toto attestations.

Attestations in the IAF are serialized as JSON.

See the Attestation Format for details about the general format of signed attestations and their components. For further details on the predicate types, read Available Predicate Types.

How to…​

You may need to work with special features or build attestations and handle key materials in a non-standard way. The following are tips & tricks that you may find helpful:

• Store attestations in my registry of choice
• Use keyless signatures
• Add SBOM and other reports to attestations
• Set command autocompletion