GitLab Hardened Builds

This project builds GitLab’s components from source, hermetically, with Nix — and attaches the supply-chain evidence that a secure release needs: a complete SBOM, SLSA provenance, Sigstore signatures, vulnerability scans with VEX exceptions, and (where it applies) FIPS-validated crypto.

You don’t have to be GitLab-the-monorepo to use it. If you have a gitlab-org/* project, you can hand this project a derivation — or just your source tree — and get back a hardened, signed, attested OCI image with a signed SBOM.

What you get

A hardened image. No shell in production images, non-root by default, minimal layers, standard OCI labels — built with the same buildGitlabImage builder GitLab’s own service images use.
A complete SBOM. CycloneDX, covering the Nix runtime closure and the language-ecosystem dependencies (Go modules, Rust crates, Ruby gems, Python wheels, npm/yarn packages) that a closure-only walk misses.
Signatures and provenance. Keyless Sigstore signatures over the artifact, the SBOM, and a SLSA v1.0 provenance statement.
A vulnerability gate. Grype against the SBOM, with OpenVEX exceptions so a known-not-affected CVE doesn’t block your release.
SLSA Level 3 isolation. The from-source build runs on an ephemeral, offline VM with no secrets and no network — the same tier this project builds its own artifacts on.
FIPS, optionally. Build under the FIPS package set and your image carries truthful FIPS labels backed by a validated module.

The two halves

The system splits cleanly, and it’s worth understanding why:

A pure-Nix API you import from this flake (lib.${system}.mkHardenedImage / mkSecureArtifact). It produces the image and the SBOM. It’s deterministic, IFD-free, and needs no secrets — so it runs anywhere your nix build runs.
A reusable CI component you include in your pipeline. It does the parts that can’t be a pure function: signing, attestation, the offline SLSA L3 build, and the scan gate. Those need this project’s signing key, its Sigstore identity, and its offline runners — so they live in CI, not in a Nix function you import.

This split is deliberate. An imported Nix function can’t hold a signing key or run an offline VM, so it doesn’t pretend to. See Signing & provenance and SLSA Level 3 builds for the details.

Where to start

New here? Read the Quickstart.
Need to check a term’s definition? See the Glossary
Integrating a whole project’s pipeline? See Integrate an external project.
Want the function signatures? The API reference is generated from the source doc-comments.
Looking for the live build evidence for a release? When the pipeline has build-matrix results, the Build matrix chapter (listed after the API reference) shows every image’s SBOM, signature, provenance, findings, and applied overrides.

This documentation describes the API defined in ADR-0039 and the requirements FR-091..FR-104 in the implementation spec. Where a capability is still being wired, the relevant page says so plainly rather than implying it’s finished.

Quickstart: request a hardened image

The fastest path is: import this flake, wrap a derivation you already build with mkHardenedImage, nix build it, and then add the CI include to get signing, attestation, and the scan gate.

1. A minimal consumer flake

You need a derivation for whatever you ship. It can be anything — pkgs.hello stands in for your real service below. The public API lives at hardened-builds.lib.${system} and is Linux-only (x86_64-linux, aarch64-linux).

{
  description = "My service, packaged as a hardened image";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hardened-builds.url = "git+https://gitlab.com/gitlab-org/software-supply-chain-security/hardened-builds?ref=main";
    hardened-builds.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs =
    { self, nixpkgs, hardened-builds }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
      hb = hardened-builds.lib.${system};

      # Your real package goes here (buildGoModule / buildRustPackage / …).
      myService = pkgs.hello;
    in
    {
      packages.${system}.my-service-image = hb.mkHardenedImage {
        name = "my-service";
        version = "0.1.0";
        package = myService;
        cmd = [ "/bin/hello" ];
      };
    };
}

Use the git+https URL as shown. Don’t use a gitlab: URL: Nix’s gitlab: fetcher resolves a project in a subgroup to the wrong project, even with the %2F encoding the Nix manual suggests (NixOS/nix#6435).

hardened-builds is currently a private GitLab project, so nix needs your GitLab credentials to fetch it. If you already clone from GitLab over SSH, this makes git fetch this one repository over SSH, without changing the URL in your flake.nix or flake.lock:

$ git config --global \
    url."ssh://git@gitlab.com/gitlab-org/software-supply-chain-security/hardened-builds".insteadOf \
    "https://gitlab.com/gitlab-org/software-supply-chain-security/hardened-builds"

In CI the slsa-l1 component handles this for you; see Fetching hardened-builds in CI.

2. Build it

$ nix build .#my-service-image

That gives you the OCI image. mkHardenedImage also attaches a CycloneDX SBOM by default; it hangs off passthru.sbom:

$ nix build .#my-service-image.passthru.sbom

That is everything the pure-Nix half produces: the image and its SBOM. It does not sign, attest, scan, or run an SLSA L3 build — those need this project’s signing key, Sigstore identity, and offline runners, which a Nix function you import cannot hold. See Signing & provenance and SLSA Level 3 builds.

3. Add the CI component

Drop this into your .gitlab-ci.yml. It builds .#my-service-image, generates its SBOM and scans it on your project’s own runners, with SLSA Build L1 provenance written by GitLab Runner. For signed provenance on the offline SLSA L3 tier, include /ci/components/hardened-artifact-slsa-l3.yml instead:

include:
  - project: "gitlab-org/software-supply-chain-security/hardened-builds"
    ref: main # pin to a release tag in real use
    file: "/ci/components/hardened-artifact-slsa-l1.yml"
    inputs:
      flake-target: "my-service-image"
      artifact-name: "my-service"

flake-target is your flake package output (.#my-service-image). The rest of the inputs (sbom, scan, fips, …) default sensibly; Integrate an external project walks through each one, both build tiers, and which job runs where.

Scaffold instead of hand-writing

If you’d rather start from a working skeleton:

$ nix flake init -t 'git+https://gitlab.com/gitlab-org/software-supply-chain-security/hardened-builds?ref=main#default'

That drops a flake.nix and a starter .gitlab-ci.yml already wired to the component. Adapt the package and the flake-target/artifact-name inputs.

Where to next

Building from a source tree instead of a derivation? Pick your ecosystem: Go, Python, Ruby, Rust.
Unsupported ecosystem or a custom build? Bring your own derivation.
The exact signatures live in the API reference.

Integrate an external project

This is the end-to-end version of the Quickstart: a whole project’s pipeline, from the flake output your team owns to the CI include that turns it into a signed, attested, scanned artifact. It also explains which jobs run where, and why the split matters.

The two things you provide

A flake output that produces a hardened image. You build this with lib.${system}.mkHardenedImage (derivation-first) or mkSecureArtifact (source-first). This is pure Nix — it produces the image and SBOM and nothing else.
A CI include that runs the parts a Nix function cannot: the offline SLSA L3 build, and then signing, attestation, and the vulnerability gate on a networked runner.

The flake output

{
  description = "my-service, packaged and hardened";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hardened-builds.url = "git+https://gitlab.com/gitlab-org/software-supply-chain-security/hardened-builds?ref=main";
    hardened-builds.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs =
    { self, nixpkgs, hardened-builds }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
      hb = hardened-builds.lib.${system};

      myService = pkgs.buildGoModule {
        pname = "my-service";
        version = "1.4.0";
        src = ./.;
        vendorHash = "sha256-…";
      };
    in
    {
      packages.${system}.my-service-image = hb.mkHardenedImage {
        name = "my-service";
        version = "1.4.0";
        package = myService;
        cmd = [ "/bin/my-service" ];
      };
    };
}

The CI component references this output by name, so the output name (my-service-image) and the flake-target input must match.

Use the git+https URL for the hardened-builds input, not a gitlab: one, and while hardened-builds is private, set up your local credentials; the Quickstart explains both.

The `.gitlab-ci.yml` include

The component comes in two files, one per build tier (ADR-0044). Include exactly one.

File	Build tier	Use it when
`/ci/components/hardened-artifact-slsa-l1.yml`	`slsa-l1`	You want the hardened build, SBOM and scan gate, but don’t require SLSA L2 or L3 conformance.
`/ci/components/hardened-artifact-slsa-l3.yml`	`slsa-l3`	Your project has access to this project’s offline SLSA L3 runners and needs signed provenance.

Both run the same build, SBOM and scan steps. slsa-l3 builds on the offline VM and adds signing; slsa-l1 runs on any available GitLab runner, but does not provide signed builds and only meets SLSA L1 build level. Switching tiers means changing file: reference and the tier-specific inputs; your flake and build do not change.

`slsa-l1`

include:
  - project: "gitlab-org/software-supply-chain-security/hardened-builds"
    # Pin to an immutable ref. A commit SHA is the only fully immutable
    # option; a release tag is acceptable where you trust the maintainer.
    # Never track a branch: whatever lands on it executes in your pipeline.
    ref: main # TODO: switch this to a release tag once this project is released
    file: "/ci/components/hardened-artifact-slsa-l1.yml"
    inputs:
      flake-target: "my-service-image"
      artifact-name: "my-service"
      sbom: true
      scan: true
      fips: false
      hardened-builds-via-ci-job-token: true
      artifact-expiry: "1 month"
      nix-image: "nixos/nix:2.35.2"

flake-target - the flake output to build, i.e. .#<flake-target>. Required. Letters, digits and _.+- only.
artifact-name - the name used in output filenames. Required. Letters, digits and _.- only.
sbom (default true) - build the CycloneDX SBOM from the image’s passthru.sbom. See SBOMs.
scan (default true) - Grype-scan the SBOM, then gate on Critical findings. Requires sbom. See VEX & vulnerability scanning.
fips (default false) - before publishing anything, assert the image carries a validated FIPS label. See FIPS.
hardened-builds-via-ci-job-token (default true) - fetch your flake’s hardened-builds input with CI_JOB_TOKEN, since hardened-builds is currently private. See Fetching hardened-builds in CI below.
artifact-expiry (default 1 month) - how long the build job’s artifacts are kept. That includes the SLSA provenance, so keep what you release, for example by attaching it to a GitLab release.
nix-image (default nixos/nix:2.35.2) - the image providing the nix CLI. It needs Nix 2.26 or newer: older Nix refuses to fetch hardened-builds as a flake input, because its flake.lock contains a relative path input.

Job	Runner	What it does
`hardened:build`	untagged	Builds the image, publishes it as a job artifact, and exports its Nix closure to the CI cache. No secrets.
`hardened:sbom`	untagged	Builds the SBOM, substituting from the build’s cached closure where it can.
`hardened:scan`	untagged	Grype gate against the SBOM.

The build job sets RUNNER_GENERATE_ARTIFACTS_METADATA, so GitLab Runner writes SLSA provenance (artifacts-metadata.json) listing the build job’s artifacts, including the image, by digest. The SBOM comes from a separate job, as in slsa-l3, so it is not in that provenance. The provenance is unsigned: SLSA Build L1. The artifacts exist before the scan runs, so release only from pipelines that succeeded.

What the provenance records

artifacts-metadata.json is an in-toto Statement with a SLSA Provenance v1 predicate. See GitLab’s field reference. For the build job it records:

subject - each artifact file (the image JSON and the cache public key) by SHA-256 digest.
externalParameters - the project (source), the job name (entryPoint), and the names of the job’s CI/CD variables. The values are always empty strings, by design, so secrets never reach the provenance.
resolvedDependencies - the project and the commit that was built.
internalParameters and runDetails - the runner, executor, architecture, job ID, and start and finish times.

It does not record the component’s inputs, such as flake-target or fips, or the hardened-builds ref your pipeline included. Recover those from the recorded commit: your .gitlab-ci.yml holds the include: ref and inputs, and your flake.lock pins every Nix input. That only works if the ref is immutable (a commit SHA, or a tag you trust), and if nothing overrides the component’s variables through project, group or pipeline CI/CD variables, whose values are not recorded either.

In both tiers the scan installs Grype with nix profile install --inputs-from . nixpkgs#grype, so its version comes from your flake’s flake.lock. Your flake must have an input named nixpkgs; otherwise Nix falls back to the unpinned global registry.

Fetching `hardened-builds` in CI

hardened-builds is currently a private GitLab project, so CI needs a credential to fetch your flake’s hardened-builds input. With hardened-builds-via-ci-job-token (default true), every job in this component, the scan included (it installs Grype with --inputs-from .), sends the job’s CI_JOB_TOKEN to git when it fetches the hardened-builds repository, and only that repository: other gitlab.com inputs don’t get the token. Your flake.lock is used unchanged, so this also works with a hardened-builds input pointed at a feature branch. A git+ssh input works too: git fetches it over HTTPS instead. Turn the input off only if you’ve already set up your own working credential for this input (e.g. a deploy key).

A job token can read a private project only when both of these hold, so check them before your first pipeline run, or hardened:build fails immediately:

Your project, or a group above it, is on hardened-builds’ CI/CD job token allowlist. Ask the hardened-builds maintainers to add it under their Settings > CI/CD > Job token permissions.
The user the pipeline runs as can read hardened-builds. That includes the owner of a scheduled pipeline and anyone who runs a pipeline on a merge request, so a contributor without access gets a failing pipeline even when your project is on the allowlist.

See GitLab’s job token documentation.

If you add your own job that evaluates your flake (see below), it needs the same credential. Jobs that extend .hardened-nix-store get it. Any other job can add !reference [.hardened-builds-via-ci-job-token, script] to its before_script: or the start of its script:.

This input goes away once hardened-builds is public.

Using the built image in your own jobs

A later job - a registry push, for example - can restore the image’s store paths from the build instead of rebuilding them, by extending .hardened-nix-store:

publish:
  extends: .hardened-nix-store
  image: nixos/nix:2.35.2
  script:
    - nix run .#my-service-image.copyTo -- --dest-creds "$REG_USER:$REG_PASS" docker://registry.example.com/my-service:latest

.hardened-nix-store restores the closure from the pipeline’s CI cache and trusts only store paths signed by the key hardened:build published as a job artifact. It waits for hardened:scan, so an image that failed the gate is not published, and runs in the .post stage by default.

If your job sets its own needs:, keep both hardened:build and hardened:scan (optional) from .hardened-nix-store. If it sets its own before_script:, re-add !reference [.hardened-nix-cache, before_script] and !reference [.hardened-builds-via-ci-job-token, script] (!reference does not follow extends:).
If your pipeline defines its own stages:, that list replaces the component’s, so it must include build, sbom and scan (and sign for slsa-l3).
The cache is shared between runners only when they have a distributed cache configured, as GitLab.com hosted runners do. Otherwise a job on a different runner restores nothing, and Nix builds or fetches the store paths itself.

`slsa-l3`

include:
  - project: "gitlab-org/software-supply-chain-security/hardened-builds"
    ref: main # TODO: switch this to a release tag once this project is released
    file: "/ci/components/hardened-artifact-slsa-l3.yml"
    inputs:
      flake-target: "my-service-image"
      artifact-name: "my-service"
      sbom: true
      sign: true
      attest: true
      scan: true
      fips: false
      slsa-build-tag: "nix-slsa-l3-amd64"
      attic-shared-tag: "nix-attic-shared"
      nix-image: "nixos/nix:2.35.2"

The inputs it shares with slsa-l1 behave the same. slsa-l3 has no hardened-builds-via-ci-job-token input. Its hardened:build runs on the offline SLSA L3 VM, which has no network and no secrets by design. Its hardened:sbom, hardened:scan and hardened:sign evaluate your flake on the shared runner, so while hardened-builds is private they need a credential for the hardened-builds input, which slsa-l3 does not set up yet. In addition:

sign (default true) - keyless Sigstore sign the artifact (and SBOM). See Signing & provenance.
attest (default true) - generate and sign a SLSA v1.0 provenance statement.
slsa-build-tag / attic-shared-tag - the runner tags for the offline build VM and the networked shared runner.

This is a security boundary, not just scheduling (ADR-0035):

Job	Runner	Why
`hardened:build`	offline SLSA L3 VM (`slsa-build-tag`)	Realises the derivation from source under isolation. No secrets, no network, no signing key.
`hardened:sbom`	shared runner (`attic-shared-tag`)	Substitutes the closure the offline build pushed to Attic; does not rebuild.
`hardened:scan`	shared runner	Grype gate against the substituted SBOM.
`hardened:sign`	shared runner	Holds the Sigstore identity and network; signs the artifact + SBOM + provenance.

The build runs offline with no secrets. Every downstream job substitutes the closure with nix build … --max-jobs 0 — a cache miss fails rather than rebuilding off the VM, so the signed thing is provably the thing the offline VM built. Signing never touches the offline job: the VM has no key by construction, so it can’t. That’s the whole point of the split — read SLSA Level 3 builds for the isolation model.

Building from source instead

If your team would rather hand the pipeline a source tree and let hardened-builds detect the ecosystem and build it, swap mkHardenedImage for mkSecureArtifact. Start from the per-ecosystem guide: Go, Python, Ruby, Rust.

Go

mkSecureArtifact detects a Go project by the presence of a go.mod file at the root of src. It then builds the module with buildGoModule and hands the result to mkHardenedImage.

The marker

Detection is file-presence based: a go.mod at the top of src means “go”. If a .goreleaser.yml / .goreleaser.yaml is also present, detect records it as the buildConfigFile, but it does not act on it automatically — you opt into the goreleaser path explicitly (below).

Required and optional `ecosystemArgs`

vendorHash (required) — the buildGoModule vendor hash. There is no way around this; a missing vendorHash throws at eval time.
subPackages (optional) — which packages to build (default [ "." ]).
goreleaser (optional) — a parsed goreleaser config; when present, the build args (subPackages, ldflags, CGO_ENABLED) come from it instead of subPackages.
goVersion, buildId (optional) — only meaningful on the goreleaser path.

Plain `buildGoModule` (subPackages)

hb.mkSecureArtifact {
  name = "my-tool";
  version = "1.2.0";
  src = ./.;
  ecosystemArgs = {
    vendorHash = "sha256-…";
    subPackages = [ "cmd/my-tool" ];
  };
  image.cmd = [ "/bin/my-tool" ];
}

Anything under image.* is forwarded to mkHardenedImage — that is how you set cmd, entrypoint, env, and so on.

The goreleaser path

Many gitlab-org/* Go tools drive their release builds with goreleaser. Parse the config and pass it through so the resulting binary carries goreleaser’s ldflags (version stamping, CGO_ENABLED, the right main package):

let
  gorel = hardened-builds.lib.${system}.parseGoreleaser ./.goreleaser.yml; # see note
in
hb.mkSecureArtifact {
  name = "glab";
  version = "1.40.0";
  src = ./.;
  rev = self.rev or "0000000000000000000000000000000000000000";
  ecosystemArgs = {
    vendorHash = "sha256-…";
    goreleaser = gorel;
    goVersion = "1.22.3";
  };
}

The emitter resolves goreleaser’s {{.Version}}, {{.ShortCommit}}, and {{.Env.GO_VERSION}} template placeholders by plain string substitution against version, rev, and goVersion. rev must be the real full commit SHA — {{.ShortCommit}} is the first 7 characters of it — even if you fetch the source by tag elsewhere. Any other unresolved {{…}} placeholder throws at eval time rather than baking a literal template string into your binary.

Note: the goreleaser parser lives in lib/ecosystem/goreleaser.nix. Wire it into your consumer flake the same way you wire the rest of the API; the exact attribute name is in the API reference.

Derivation-first alternative

If the source-first dispatch doesn’t fit — a monorepo with several binaries, an unusual build, or you already have a package — build the buildGoModule derivation yourself and pass it straight to mkHardenedImage:

let
  myTool = pkgs.buildGoModule {
    pname = "my-tool";
    version = "1.2.0";
    src = ./.;
    vendorHash = "sha256-…";
    subPackages = [ "cmd/my-tool" ];
  };
in
hb.mkHardenedImage {
  name = "my-tool";
  version = "1.2.0";
  package = myTool;
  cmd = [ "/bin/my-tool" ];
}

You get the same image and SBOM either way; mkSecureArtifact is just the convenience wrapper around detect-then-build-then-image.

SBOM

The Go module set and the Go stdlib are folded into the CycloneDX SBOM automatically (the SBOM builder reads them off the finished buildGoModule derivation’s goModules). No extra configuration needed. See SBOMs.

FIPS

Go’s FIPS story is BoringCrypto (ADR-0026). Pass fips = true only if you built the package under the FIPS package set — the flag applies FIPS labels but does not convert a non-FIPS build. See FIPS.

Python

mkSecureArtifact detects a Python project by a pyproject.toml at the root of src. It resolves dependencies from a Poetry lock file or a uv lock file (see uv projects), builds the application, and hands the result to mkHardenedImage.

The marker

The primary marker is pyproject.toml. A poetry.lock or uv.lock alongside it is the strongest signal for a hermetic build and is recorded as the buildConfigFile.

Required and optional `ecosystemArgs`

lock (required) — a vendored relative path to the Poetry lock file, e.g. ./poetry.lock. It must be a path in your repository, not a read out of the fetched src. Reading a lock file out of a fetched derivation is import-from-derivation, which nix flake check --no-build cannot evaluate and the repo’s no-ifd-lockfile lint forbids.
python (optional) — the interpreter (default python312).
overrides (optional) — { "package-name" = derivation; } to replace a generated dependency entirely. Use it for packages with native (maturin / C) build steps, non-PyPI sources, or private sources.
exclude (optional) — a list of exact lock names to skip (Windows-only, wheel-only-with-no-linux-source, or intentionally omitted packages).
format (optional) — the Python build format (default "pyproject").

Worked example

Vendor the lock file into your repo first, then:

hb.mkSecureArtifact {
  name = "my-api";
  version = "2.0.1";
  src = ./.;
  ecosystemArgs = {
    lock = ./poetry.lock; # vendored, relative
    python = pkgs.python312;
    exclude = [ "pywin32" "pyroscope-io" ];
    overrides = {
      "some-rust-pkg" = mySomeRustPkgDrv;
    };
  };
  image.cmd = [ "/bin/my-api" ];
}

Under the hood, the emitter reads poetry.lock at eval time with builtins.fromTOML (Poetry locks carry per-package sha256 hashes, so no build-time conversion and no IFD), builds every dependency that nixpkgs does not already provide via buildPoetryDeps, and wires them in as propagatedBuildInputs. Packages already present in python.pkgs are reused, not rebuilt.

Generated dependency derivations skip their upstream test suites (doCheck = false) — those virtually always need network, live services, or dev-only deps not in the lock. If you need an import check on a specific package, supply it through overrides.

uv projects

When lock points at a uv.lock, the emitter builds the project with uv2nix instead of buildPoetryDeps. uv2nix reads uv.lock at eval time with builtins.fromTOML (no IFD), and build-system-pkgs supplies the build backends (setuptools, flit-core, hatchling, …) that uv.lock doesn’t record per package.

Unlike the Poetry path, every package comes from the lock at its locked version, including packages nixpkgs also carries, as the Go, Rust and Ruby emitters do. The result is a virtual environment with the project and its default dependencies installed (no optional extras), so the project’s console scripts end up in its bin/.

By default every package in uv.lock is built from its source distribution, and a dependency that only publishes wheels fails the evaluation. uv.lock doesn’t record build backends, so each source-built dependency needs its backend added through overrides (or tool.uv.extra-build-dependencies). The backends themselves come from build-system-pkgs, which installs uv-build (the uv_build backend uv init sets up) from a prebuilt PyPI wheel. It’s only used during the build and doesn’t end up in the image. Dependencies from git sources, and wheels without a hash, aren’t supported, since uv2nix fetches them without a hash check. Any such entry anywhere in uv.lock fails the evaluation, including ones in dev groups or for other platforms.

lock (required) — a vendored relative path to uv.lock, e.g. ./uv.lock, with a copy of the project’s pyproject.toml next to it (and of each workspace member’s, at the same relative path). uv2nix reads them at eval time; the project itself is built from src.
python (optional) — the interpreter (default python312). It must satisfy the project’s requires-python.
sourcePreference (optional) — "sdist" (default) or "wheel". "wheel" installs the locked, hash-pinned PyPI wheels where they exist, so dependencies don’t need their build backends added. AGENTS.md prefers building from source, so state the reason next to it in the project’s flake. Compiled wheels can bundle native libraries (e.g. OpenSSL in cryptography’s) that the SBOM’s closure walk doesn’t list.
overrides (optional) — { "package-name" = derivation; } to replace a package, or an overlay final: prev: { ... } to patch one, e.g. to point a package at a nixpkgs library.

format and exclude don’t apply to uv projects: the build format comes from each package’s metadata, and uv2nix evaluates each dependency’s environment markers, so platform-specific packages (e.g. Windows-only) are skipped on their own.

hb.mkSecureArtifact {
  name = "my-api";
  version = "2.0.1";
  src = ./.;
  ecosystemArgs = {
    lock = ./uv.lock; # vendored, relative
    python = pkgs.python313;
    overrides = final: prev: {
      some-pkg = prev.some-pkg.overrideAttrs (old: {
        buildInputs = (old.buildInputs or [ ]) ++ [ pkgs.zlib ];
      });
    };
  };
  image.cmd = [ "/bin/my-api" ];
}

Derivation-first alternative

If your build doesn’t fit the Poetry-lock shape, build the application yourself and image it directly:

let
  myApi = pkgs.python312.pkgs.buildPythonApplication {
    pname = "my-api";
    version = "2.0.1";
    src = ./.;
    format = "pyproject";
    propagatedBuildInputs = with pkgs.python312.pkgs; [ fastapi uvicorn ];
  };
in
hb.mkHardenedImage {
  name = "my-api";
  version = "2.0.1";
  package = myApi;
  cmd = [ "/bin/my-api" ];
}

SBOM

Python wheels/sdists in the closure are captured in the CycloneDX SBOM. See SBOMs for how ecosystem dependencies are folded in and how to override auto-detection when needed.

Ruby

mkSecureArtifact detects a Ruby project by a Gemfile.lock at the root of src. It builds a bundlerEnv from an enriched gemset and hands the result to mkHardenedImage.

The marker

The primary marker is Gemfile.lock. A Gemfile alongside it is recorded as the buildConfigFile.

Required and optional `ecosystemArgs`

gemset (required) — a vendored relative path to a gemset.nix, e.g. ./gemset.nix. Unlike Poetry’s lock, a Gemfile.lock does not carry content hashes, so gemset.nix (produced by bundix as an offline pre-step) is what supplies them. It must be a vendored path in your repo — never a read out of the fetched src (that is import-from-derivation, forbidden by the no-ifd-lockfile lint).
ruby (optional) — the interpreter (default ruby_3_3, falling back to ruby).
gemdir (optional) — the directory holding the Gemfile/Gemfile.lock (default src).

Worked example

Generate gemset.nix with bundix, vendor it into your repo, then:

hb.mkSecureArtifact {
  name = "my-rails-app";
  version = "3.1.0";
  src = ./.;
  ecosystemArgs = {
    gemset = ./gemset.nix; # vendored, relative
    ruby = pkgs.ruby_3_3;
  };
  image.cmd = [ "/bin/rails" "server" ];
}

The emitter imports the gemset and runs it through enrichGemset, which substitutes gems already built in nixpkgs for their pre-built store paths so bundlerEnv only source-fetches the gems nixpkgs doesn’t carry. The default match mode is exact (substitute only on an exact version match), which keeps Bundler’s strict lockfile-version enforcement happy. enrichGemset also guards against a substitution dragging a conflicting version of a monkey-patched gem (e.g. net-http) onto GEM_PATH.

Derivation-first alternative

If you need finer control over the bundlerEnv (custom matchMode, extra nativeBuildInputs, explicit nixpkgsGems), build it yourself and image it:

let
  gems = pkgs.bundlerEnv {
    name = "my-rails-app-gems";
    ruby = pkgs.ruby_3_3;
    gemdir = ./.;
  };
  app = pkgs.stdenv.mkDerivation {
    pname = "my-rails-app";
    version = "3.1.0";
    src = ./.;
    nativeBuildInputs = [ gems gems.wrappedRuby ];
    # …install phase…
  };
in
hb.mkHardenedImage {
  name = "my-rails-app";
  version = "3.1.0";
  package = app;
  cmd = [ "/bin/rails" "server" ];
}

SBOM

Ruby gems cannot be inferred from the built derivation the way Go modules or Rust crates can — their inventory lives in the gemset.nix. So the SBOM builder needs you to point at the vendored gemset explicitly with sbomEcosystems:

hb.mkSecureArtifact {
  name = "my-rails-app";
  version = "3.1.0";
  src = ./.;
  ecosystemArgs.gemset = ./gemset.nix;
  sbomEcosystems = [ { kind = "ruby"; gemset = ./gemset.nix; } ];
}

That vendored-path rule is the same no-IFD discipline as everywhere else — see SBOMs.

Rust

mkSecureArtifact detects a Rust project by a Cargo.toml at the root of src. It builds the crate with rustPlatform.buildRustPackage from a vendored Cargo.lock and hands the result to mkHardenedImage.

The marker

The primary marker is Cargo.toml. A rust-toolchain.toml alongside it is read for the toolchain channel and recorded as the buildConfigFile.

Required and optional `ecosystemArgs`

cargoLock (required) — a vendored relative path to Cargo.lock, written exactly as ./Cargo.lock.
outputHashes (optional) — cargoLock.outputHashes for git dependencies. Git deps have no crates.io checksum, so they need an explicit "<crate>-<version>" -> sha256 entry. Omit it entirely when the lock has no git dependencies.

The vendored `Cargo.lock` / no-IFD rule

This one bites people, so it’s worth stating plainly: cargoLock must be a vendored relative path, never "${src}/Cargo.lock". Reading the lock out of the fetched source is an import-from-derivation — nix flake check --no-build can’t evaluate it, and the repo’s no-ifd-lockfile lint rejects it. The emitter even asserts against a /nix/store/ string sneaking in and throws with a pointer to this rule. Copy Cargo.lock into your repo and reference it relatively.

hb.mkSecureArtifact {
  name = "my-cli";
  version = "0.9.0";
  src = ./.;
  ecosystemArgs = {
    cargoLock = ./Cargo.lock; # vendored — NOT "${src}/Cargo.lock"
    # outputHashes = { "some-git-crate-1.2.3" = "sha256-…"; };
  };
  image.cmd = [ "/bin/my-cli" ];
}

Derivation-first alternative

If your crate needs build inputs, features, or flags the emitter doesn’t take, build it yourself and image it directly:

let
  myCli = pkgs.rustPlatform.buildRustPackage {
    pname = "my-cli";
    version = "0.9.0";
    src = ./.;
    cargoLock.lockFile = ./Cargo.lock; # still vendored, still relative
    buildInputs = [ pkgs.openssl ];
    nativeBuildInputs = [ pkgs.pkg-config ];
  };
in
hb.mkHardenedImage {
  name = "my-cli";
  version = "0.9.0";
  package = myCli;
  cmd = [ "/bin/my-cli" ];
}

FIPS composition (aws-lc-rs, ADR-0028)

Rust’s FIPS path is aws-lc-rs in FIPS mode (ADR-0028), not a flag you flip on an ordinary build. To ship a FIPS Rust artifact you build the crate under the FIPS package set — which composes the aws-lc-rs FIPS module — and only then pass fips = true so the image carries truthful FIPS labels. As everywhere, fips = true is a truthfulness contract: it labels; it does not convert a non-FIPS build. See FIPS.

SBOM

Rust crates are folded into the CycloneDX SBOM automatically — the SBOM builder reads the Cargo.lock inside the vendored cargoDeps on the finished derivation, so no extra configuration is needed. See SBOMs.

Bring your own derivation

Ecosystem detection covers Go, Rust, Python, and Ruby. When your project isn’t one of those — an unsupported ecosystem, a C/C++ build, a mixed build, or anything you’d rather assemble by hand — you skip detection entirely. There are two ways.

Option 1: `mkHardenedImage` directly

If you already have (or can build) the derivation, this is the simplest path. mkHardenedImage wraps an already-built derivation into a hardened image and attaches its SBOM. It does no detection at all.

let
  myThing = pkgs.stdenv.mkDerivation {
    pname = "my-thing";
    version = "1.0.0";
    src = ./.;
    nativeBuildInputs = [ pkgs.cmake ];
    # …your build…
  };
in
hb.mkHardenedImage {
  name = "my-thing";
  version = "1.0.0";
  package = myThing;
  cmd = [ "/bin/my-thing" ];
}

This is the headline entry point — mkSecureArtifact funnels into it once it has a derivation. If you’re not using the ecosystem dispatch, prefer this over mkSecureArtifact; there’s no reason to route through detection you don’t want.

Option 2: `mkSecureArtifact` with `overrideDerivation`

If you’re inside a pipeline that’s already shaped around mkSecureArtifact and you want to keep that shape but bypass detect-and-build for one artifact, pass overrideDerivation. It short-circuits detection and building entirely and images the derivation you hand it:

hb.mkSecureArtifact {
  name = "my-thing";
  version = "1.0.0";
  overrideDerivation = myThing; # skip detect + build, image THIS
  image.cmd = [ "/bin/my-thing" ];
}

When you use overrideDerivation, you don’t need src — the throw that mkSecureArtifact raises for an undetectable src doesn’t fire, because detection is skipped. The result’s passthru.ecosystem is { ecosystem = "custom"; }, a marker that this artifact came from an override rather than a detected ecosystem.

Which one?

They produce the same image and SBOM. Use mkHardenedImage when you’re building images directly, and overrideDerivation only when you want a single uniform mkSecureArtifact call site across a mix of detected and custom artifacts.

Everything else still applies

However you produce the derivation, the rest is unchanged: the CI component signs, attests, and scans it exactly the same way (see Integrate an external project), the SBOM covers its Nix closure (see SBOMs), and fips = true remains a truthfulness contract you must back with a real FIPS build (see FIPS).

SBOMs

Every hardened image comes with a CycloneDX SBOM. This page covers what it covers, how to get it, and the one rule you have to follow to keep it honest.

What it covers

The SBOM builder (lib/sbom, ADR-0036) wraps bombon to produce a complete inventory:

The Nix runtime closure — every store path the image needs at runtime, the same walk sbomnix did (ADR-0015).
The language-ecosystem dependencies that Nix vendors into a single store path and that a closure-only walk therefore misses: Go modules plus the Go stdlib, Rust crates, Ruby gems, Python wheels/sdists, and yarn/npm packages.

That second half is the part that matters for vulnerability matching. A CVE against a specific gem, crate, module, or wheel only shows up if that dependency is named in the SBOM — a closure-only SBOM can’t match it, so the scan gate would silently miss it. See VEX & vulnerability scanning.

How to get it

In pure Nix, the SBOM hangs off the image’s passthru:

$ nix build .#my-service-image.passthru.sbom

mkHardenedImage (and therefore mkSecureArtifact) attaches it by default (sbom = true). Set sbom = false to skip it, in which case passthru.sbom is absent.

In CI, the component’s hardened:sbom job builds passthru.sbom. Under slsa-l1 it substitutes from the build job’s cached closure where it can, and builds or fetches anything missing. Under slsa-l3 it runs on the shared runner with --max-jobs 0 (substitute-only — the closure comes from the offline build’s Attic push, never a rebuild), copies out the *.cdx.json, and — when sign = true — signs it. See Integrate an external project.

Auto-detection vs the `sbomEcosystems` override

The builder auto-detects go and rust from robust markers on the finished derivation (goModules, cargoDeps) and consumes them without rebuilding.

Ruby and yarn/npm can’t be auto-detected — their inventory lives in a gemset.nix or a yarn.lock, not in anything readable off the built derivation. For those you declare the ecosystem explicitly with sbomEcosystems, which is threaded onto the package before imaging:

hb.mkHardenedImage {
  name = "my-rails-app";
  version = "3.1.0";
  package = myRailsApp;
  sbomEcosystems = [
    { kind = "ruby"; gemset = ./gemset.nix; }
    { kind = "yarn"; yarnLock = [ ./yarn.lock ]; }
  ];
}

The no-IFD vendored-path rule

Every lockfile, gemset, or yarn.lock path in sbomEcosystems must be a vendored relative path (./gemset.nix, ./yarn.lock) — never an interpolated read out of a fetched source like "${src}/yarn.lock". Reading a lock file out of a fetched derivation is an import-from-derivation, which nix flake check cannot evaluate and the repo’s no-ifd-lockfile lint rejects. Copy the lock/gemset into your repository and reference it relatively.

This is the same discipline the Rust cargoLock, Python lock, and Ruby gemset args follow throughout the ecosystem emitters — see those pages for the per-ecosystem detail.

Reference

The design and rationale (why bombon, why our own consuming emitters rather than bombon’s rebuild-the-package emitters) are in ADR-0036.

Signing & provenance

Signing and provenance are delivered by the CI component, not the Nix API. This page explains what gets signed, why it can’t be pure Nix, where it runs, and how to verify it.

Of the two CI components, only slsa-l3 (hardened-artifact-slsa-l3.yml) signs. The slsa-l1 component signs nothing; its SLSA provenance is the unsigned artifacts-metadata.json GitLab Runner writes for the build job. See Integrate an external project.

What gets signed

The component’s hardened:sign job produces three keyless Sigstore signatures (ADR-0015):

The artifact — cosign sign-blob over the built image path.
The SBOM — when sbom = true, the CycloneDX *.cdx.json.
A SLSA v1.0 provenance statement — when attest = true, an in-toto Statement with a https://slsa.dev/provenance/v1 predicate naming the flake target, the builder, and the artifact digest, itself signed.

Each produces a .sigstore.bundle artifact. Signing is keyless: the job requests a Sigstore OIDC token (SIGSTORE_ID_TOKEN, aud: sigstore) and cosign records the signature in the transparency log against that CI identity.

Why it can’t be pure Nix

mkHardenedImage / mkSecureArtifact produce the image and SBOM as deterministic, IFD-free Nix — no secrets, no network. Signing is the opposite: it needs an OIDC identity, network access to the Sigstore infrastructure, and the transparency-log upload. A Nix function you import into your own flake can’t hold any of that, so it doesn’t pretend to. The honest boundary is: pure Nix makes the thing; CI signs the thing.

Where it runs, and why it’s a boundary

Signing runs only on the networked nix-attic-shared runner, never on the offline SLSA L3 build VM (ADR-0035). The build VM has no key, no network, and no secrets by construction — that’s what makes its build trustworthy. Adding a signing step, a registry login, or any secret to the build job would break that invariant, so the component never does. The signing job resolves the already-built image with nix build … --max-jobs 0 (substitute-only, so it signs exactly what the offline VM built) and signs it there.

See SLSA Level 3 builds for the full isolation model.

Verifying

With cosign, verify a bundle against the CI identity that produced it:

$ cosign verify-blob \
    --bundle my-service.sigstore.bundle \
    --certificate-identity-regexp 'https://gitlab\.com/.*' \
    --certificate-oidc-issuer https://gitlab.com \
    "$IMAGE_PATH"

Use the SBOM bundle to verify the SBOM the same way, and the provenance bundle to verify provenance.json. Match --certificate-identity / --certificate-oidc-issuer to the project and issuer that ran the pipeline.

Reference

Sigstore-over-Nix and the SBOM/provenance shape are ADR-0015; the offline-build / signing-on-shared-runner boundary is ADR-0035.

SLSA Level 3 builds

The from-source build runs on an ephemeral, offline VM with no secrets and no network. Everything downstream substitutes that build’s output rather than rebuilding it. That combination is what earns SLSA Level 3, and it’s a security boundary the component enforces (ADR-0035).

Choosing this tier

Include /ci/components/hardened-artifact-slsa-l3.yml. This requires access to specific tagged runners, including an offline builder runner. The alternative, hardened-artifact-slsa-l1.yml, runs the same build, SBOM and scan steps on any available runner, but does not provide offline isolation or signing. See Integrate an external project.

The two runner roles

CI uses two runner roles, and which one a job lands on is a security decision:

nix-slsa-l3-amd64 / nix-slsa-l3-arm64 — ephemeral, offline VMs that realise derivations from upstream source under isolation. No network egress, no Attic client, no secrets, no signing key. The runner-manager powers the VM off after the build and extracts the outputs out-of-band. This is the only place a from-source build runs.
nix-attic-shared — the persistent, networked host: shared Nix store, Attic substituter/push, network, and the secrets (Sigstore OIDC, registry creds, signing key). Everything that is not a from-source build runs here.

How the component uses them

In hardened-artifact-slsa-l3.yml, the hardened:build job carries the slsa-build-tag (nix-slsa-l3-amd64 by default) and does exactly one thing:

script:
  - nix build ".#$[[ inputs.flake-target ]]" --print-out-paths --no-link

It runs offline. Nothing secret happens. The runner-manager extracts the closure and pushes it to the shared Attic afterward.

Every downstream job — SBOM, scan, sign, attest — runs on nix-attic-shared and resolves the artifact with:

- nix build ".#$[[ inputs.flake-target ]]" --print-out-paths --no-link --max-jobs 0

--max-jobs 0 means “do not build anything; get it from a substituter.” A cache miss fails the job rather than quietly rebuilding on the shared runner. So the SBOM’d, scanned, and signed artifact is provably the one the offline VM produced — no off-VM rebuild can slip in.

Why this is SLSA L3

SLSA Level 3 asks for a hardened, isolated build platform whose provenance is non-forgeable. Here:

the build is hermetic (every input is a pinned, hash-checked fetcher);
it runs on an ephemeral, isolated VM with no network and no secrets;
the VM cannot sign anything, so provenance is generated afterward on a separate, credentialed host over the exact substituted output.

The security invariant

Signing, secrets, and network must not touch the offline VM. The component never adds a signing step, an Attic push, a registry login, or a secret to hardened:build. Signing happens post-build on nix-attic-shared, where the key lives and the transparency-log upload can reach the network. See Signing & provenance.

Reference

The runner-role model, the offline-build invariant, and the substitute-only downstream discipline are ADR-0035.

VEX & vulnerability scanning

The component scans the SBOM with Grype, applies OpenVEX exceptions so a known-not-affected CVE doesn’t block your release, and gates on Critical findings. This page explains the scan, the VEX layer, and why scanning and gating are split.

The scan

hardened:scan runs when scan = true. It scans the CycloneDX SBOM produced by hardened:sbom — not a re-derived inventory — so the crates, modules, gems, and wheels folded into the SBOM (see SBOMs) are all in scope:

$ grype "sbom:sbom-<artifact-name>.cdx.json" -o json > grype.json

Scanning the SBOM (rather than the image) is what makes ecosystem-dependency CVEs matchable at all — a closure-only scan would miss them.

OpenVEX exceptions

Not every reported CVE actually affects your build. A vulnerability might be in a code path you don’t compile, or already mitigated. OpenVEX (Vulnerability Exploitability eXchange) lets you record, as signed data, that a specific CVE is not_affected for this artifact — so the gate doesn’t block on it (ADR-0014).

You ship your exceptions in your own .openvex/ directory, the same way this repo does. Each exception is a deliberate, reviewed statement, not a blanket mute — it names the CVE and the justification. A CVE with no exception is treated as live.

The scan → gate split

Scanning and gating are deliberately two concerns (ADR-0033):

Scan produces the full Grype report (grype.json, kept as an artifact when: always) — the complete picture, exceptions and all.
Gate is the pass/fail decision: after VEX exceptions are applied, if any Critical finding remains, the job exits non-zero and the pipeline fails.

Keeping them separate means you always have the full report to triage from, even on a failed pipeline, and the gate’s yes/no is a clean, auditable step rather than buried in scan output.

CRIT=$(jq '[.matches[] | select(.vulnerability.severity=="Critical")] | length' grype.json)
# CRIT > 0  ⇒  gate FAILS

Adding an exception

When the gate flags a Critical you’ve determined is not applicable, add an OpenVEX statement to your .openvex/ directory with the CVE ID and a justification, and re-run. The scan still reports it; the gate no longer blocks on it. Treat this as a reviewed decision — an exception is an assertion you’re standing behind, per this project’s allowlisting discipline.

Reference

OpenVEX-for-Nix-backported-CVEs is ADR-0014; the scan/gate split (and the provenance/dashboard split alongside it) is ADR-0033.

FIPS

fips = true is a truthfulness contract, not a switch that makes a build FIPS. This page is short on purpose, because the honesty of the flag matters more than anything else about it.

What `fips = true` actually does

Passing fips = true to mkHardenedImage / mkSecureArtifact builds the wrapping image under the FIPS package set, which flips buildGitlabImage’s FIPS marker so the image carries FIPS OCI labels (e.g. com.gitlab.image.fips = "true").

That is all it does. It applies labels. It does not convert a non-FIPS build into a FIPS one.

The contract

The flag is a promise you are making: the caller MUST have actually built package under the FIPS package set. If you label a non-FIPS build as FIPS, you’ve shipped a lie — an image that claims validated crypto it doesn’t have.

So the correct sequence is always:

Build your derivation under the FIPS package set, so it composes a validated FIPS module:
- Go: BoringCrypto (ADR-0026).
- Rust: aws-lc-rs in FIPS mode (ADR-0028).
- The base crypto libraries follow the FIPS composition (ADR-0002).
Then pass fips = true so the labels tell the truth.

For source-first builds via mkSecureArtifact, fips = true also selects the FIPS package set for the ecosystem build itself, so the derivation and the labels stay consistent.

The component asserts it

Because the flag is only a label, the CI component adds a runtime check so a mislabelled image can’t slip through. When you pass fips: true to the component, it refuses to go further unless the image genuinely carries the FIPS label: under slsa-l3, hardened:sign refuses to sign; under slsa-l1, hardened:build fails before publishing any artifact. Both components run the same check:

$ nix eval ".#<flake-target>.passthru.labels" --raw \
    --apply 'l: l."com.gitlab.image.fips" or "false"'
# anything but "true" (including a failed eval) ⇒ refuse a mislabelled image

This asserts the label is present. It’s the last line of defence, not a substitute for actually building under the FIPS set — a build that isn’t FIPS but is wrongly labelled would still pass the label check. The truthfulness starts with you building under the FIPS package set; the assertion just stops an unlabelled-but-claimed-FIPS image from being signed.

Reference

Go FIPS (BoringCrypto) is ADR-0026, Rust FIPS (aws-lc-rs) is ADR-0028, and the crypto-library FIPS composition is ADR-0002.

The public hardened-artifact API (ADR-0039), generated from the doc-comments in lib/api.nix.

`lib.api.mkHardenedImage`

Derivation-first core (ADR-0039, FR-092..095): wrap an ALREADY-BUILT derivation in a hardened OCI image (via buildGitlabImage) and, by default, attach + build its CycloneDX SBOM (via lib/sbom). This is the headline “I have a derivation, give me a hardened image + SBOM” entry point, and the one mkSecureArtifact funnels into.

Inputs (attrset):

name (string, required) — image name, e.g. “my-service”
version (string, required) — image tag, e.g. “1.2.3”
package (derivation, required) — the built artifact to bundle
entrypoint / cmd (list|null) — OCI entrypoint/cmd (default null)
env (attrset) — extra env vars (default {})
extraDeps (list) / extraLabels (attrset) — extra runtime deps / labels
user / workDir / debug — passthrough to buildGitlabImage (debug = false ⇒ no shell in the image, FR-002)
fips (bool, default false) — build the image under the FIPS package set so it carries FIPS labels. TRUTHFULNESS CONTRACT (FR-095): the caller MUST have built package under the FIPS set; this flag does NOT convert a non-FIPS build into a FIPS one.
sbom (bool, default true) — attach + build a CycloneDX SBOM
sbomEcosystems (list|null) — override lib/sbom auto-detection (e.g. ruby/yarn lock paths that cannot be inferred from the derivation)

Returns the nix2container image derivation, with passthru: sbom (only when sbom = true), package, labels, fips.

Keyboard shortcuts

GitLab Hardened Builds