Lesson 5 of 7 in Security basics for DevOps

Software supply chain: pinning, SBOMs and signatures

Advanced11 min

Your software supply chain is everything that ends up in what you ship: base images, libraries, build tools and the pipeline that assembles them. Securing it means knowing exactly which versions you used, being able to list them, and checking that what you deploy is what your pipeline built.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Scanning images and dependencies for known flaws

The problem this solves

A tag such as python:3.13 or a dependency range such as ^1.2.0 is a moving target. The same Dockerfile built on Monday and on Friday can produce different images, and one of those builds may contain a library that someone replaced or a flaw you never reviewed.

When a new flaw is announced, the first question is whether you use the affected library anywhere. Without a list of what is inside each release, you answer by searching repos and guessing. You also need a way to confirm that the image running in production is the one your pipeline built and not something swapped in along the way.

How it works

Where trust can be added along the path to production
Where trust can be added along the path to productionSource and a lockfile feed a build, the image goes to a registry, a scanner and its SBOM read the registry image, and a signature is checked before deploy.1 buildpins versions2 push3 lists contents4 verifiedSourceyour codeBuildpinned inputsRegistryimage by digestDeployverifies before runLockfileexact versionsSBOM and scanwhat is insideSignaturewho built it
  • Other
  • Runs code
  • Data
  • Control
  • Security

Source and a lockfile feed a build, the image goes to a registry, a scanner and its SBOM read the registry image, and a signature is checked before deploy.

  1. Source to Build: 1 build
  2. Lockfile to Build: pins versions
  3. Build to Registry: 2 push
  4. SBOM and scan to Registry: 3 lists contents
  5. Signature to Deploy: 4 verified

There are three separate ideas. Pinning means asking for exact versions so builds repeat. An SBOM (software bill of materials) is a machine readable list of every component inside a build. Signing attaches proof of who produced an artifact so a consumer can check it before running it.

For pinning, a lockfile records exact library versions and a digest records an exact image. A digest is the sha256 fingerprint of the image content, so it cannot silently change the way a tag can. Pin with the digest and keep the readable tag in a comment, and let an update tool propose version bumps so pinning does not freeze you on old software.

An SBOM lets you answer the announcement question in seconds: you search the lists, not the repos. Scanners can also read an SBOM instead of the image, so one build produces a list that many tools reuse.

Signing is concept level here. Tools such as Sigstore's cosign sign an image in the pipeline and let the deploy step check the signature before running it, so an image that did not come from your pipeline is refused. Setting it up is a project of its own, but you should know it exists and what it prevents.

Try it yourself

You need Docker and Trivy. The steps pull and scan a public image and write files into a throwaway folder.

  1. 1
    Find the digest behind a tag
    docker pull alpine:3.22
    docker image inspect --format '{{index .RepoDigests 0}}' alpine:3.22

    The result looks like alpine@sha256:<64-hex-characters>. Using that full string in a Dockerfile FROM line fixes the exact image content, whatever the tag points to later.

  2. 2
    Generate an SBOM
    mkdir -p ~/sbom-demo && cd ~/sbom-demo
    trivy image --format cyclonedx --output sbom.cdx.json alpine:3.22
    ls -lh sbom.cdx.json

    CycloneDX is one standard SBOM format and SPDX is another. Trivy can write either, for example with --format spdx-json. Open the file and look at the list of components.

  3. 3
    Scan the SBOM instead of the image
    trivy sbom sbom.cdx.json

    Trivy matches the components in the list against the flaw database. This is how you can rescan old releases against new flaws without having the images.

  4. 4
    Install exactly what the lockfile says
    cd <your-node-project>
    npm ci

    npm ci installs the versions in package-lock.json and fails if the lockfile and package.json disagree. npm install can update the lockfile instead. Other ecosystems have equivalents. Remove the demo files with rm -r ~/sbom-demo.

What breaks, and where to look

  • A build that passed yesterday fails today, or behaves differently, and nothing in the repo changed.

    WHY IT HAPPENS
    An unpinned tag or version range resolved to something newer at build time.
    CHECK FIRST
    Compare the resolved versions between the two builds, for example the image digest in the build log or git diff on the lockfile. Then pin the one that moved.
  • npm ci stops with a message saying package.json and package-lock.json are not in sync.

    WHY IT HAPPENS
    Someone edited dependencies in package.json without regenerating the lockfile.
    CHECK FIRST
    Run npm install locally to update the lockfile, review the diff, and commit both files together.
  • A digest pinned months ago still builds, and a scan now reports many flaws in it.

    WHY IT HAPPENS
    Pinning makes the build repeatable, and it also freezes the flaws. Nothing updates the pin for you.
    CHECK FIRST
    Add a scheduled rescan and an update tool such as Dependabot or Renovate that opens a pull request for newer digests, so pins move forward through review.

When not to use this

  • For a small hobby app, a lockfile and a regular scan are most of the value. Full signing and provenance checks pay off when many people or teams consume the artifacts.
  • An SBOM is a list, not a verdict. It tells you what is inside, and you still need a scanner and a process to act on what it shows.

Check yourself

Why pin an image by digest instead of a tag?

A tag is a label that can be moved to different content, and a digest is a fingerprint of the exact content, so it cannot change silently.

What does an SBOM let you do when a new flaw is announced?

Search a list of components per release to learn quickly whether you use the affected library, instead of searching repos by hand.

What problem does signing an image solve?

It lets the deploy step verify who produced an image and refuse anything that did not come from your pipeline.

Lesson 90 of 92 in the DevOps path

Search

Search cheat sheets and projects