Supply chain security

Overview#

EJO tracks what is inside the images you build and where they are deployed:

• Automatic SBOM and vulnerability scan: after every image build, a CycloneDX SBOM is generated and the image is scanned with Trivy, even when the pipeline has no such steps.
• Signing: the COSIGN_SIGN step signs images with cosign.
• Environment policy: images that are unsigned, have no SBOM or contain critical vulnerabilities cannot be deployed to an environment.
• Package search: find which images and environments contain a package or a CVE.

Automatic scan#

The Automatic SBOM and vulnerability scan setting on Settings > Supply chain is on by default. The scan runs in the background and never changes the deployment result unless the environment policy requires it. Only admins can change these settings.

An environment can inherit the organization setting (Inherit from organization) or turn the scan on or off for itself. A repository can opt out with supply_chain: {auto_scan: false} in its .ejo file.

The automatic scan is skipped:

• for pull requests from forks;
• when the setting is off for the organization, environment or repository;
• when the pipeline has no step that builds an image, or the image is not pushed to a registry (no registry_id);
• when the pipeline already has explicit SBOM_GENERATE or TRIVY_SCAN steps;
• when the agent does not support it (upgrade the agent).

Note: When the environment requires an SBOM or blocks critical vulnerabilities and a deploy follows the build, the automatic scan runs before the deploy and its result can block it.

Environment policy#

In the Supply-chain policy section of the environment page:

When any of these is on, promotes, rollbacks and deploy steps refuse images that fail the policy. The error reads supply chain policy: <reasons>.

Signing images#

Prerequisites#

• An environment of type Kubernetes. COSIGN_SIGN, SBOM_GENERATE and TRIVY_SCAN run as Kubernetes Jobs in the cluster.
• For TRIVY_SCAN, Install Trivy on the environment page.

Setup#

1. Generate a cosign key pair on your own machine with the command shown in the Key generation section of Settings > Supply chain.
2. On Infrastructure > Variables, create these three variables:

3. Add the signing and SBOM steps to your pipeline. Signing and SBOM need a digest reference; use the build step's {{.ImageDigest}} output.

Warning: Never commit the key files to git.

Ready-made pipeline#

In the Pipeline pack section of Settings > Supply chain, Create K8s supply chain pipeline creates this pipeline in one click: clone → Kaniko build → COSIGN_SIGN → SBOM_GENERATE → TRIVY_SCAN → K8S_DEPLOY. Running it again updates the pipeline with the same name. Assign the pipeline on your repository binding. Developers can create it too.

Example#

- name: Sign
  kind: COSIGN_SIGN
  config:
    image_ref: "{{.ImageDigest}}"
- name: SBOM
  kind: SBOM_GENERATE
  config:
    image_ref: "{{.ImageDigest}}"
- name: Scan
  kind: TRIVY_SCAN
  config:
    image_ref: "{{.ImageDigest}}"
    severity: HIGH,CRITICAL

By default COSIGN_SIGN does not upload the signature to the public transparency log (tlog_upload: false).

Package and CVE search#

The Infrastructure > Images > Packages page searches the SBOM of every recorded image. Enter a package name (or a pkg: purl prefix) or a CVE id; you can add a version constraint such as <2.17.1. The result shows the images that contain the package and the environments they run in.

Step images#

The environment's Step image policy applies the same signature and vulnerability rules to the images of pack steps and SHELL steps with an image. See Step packs.

Next steps#

• Deploy verification and rollback
• Environments
• Pipeline definition