Hermeto is a CLI tool that pre-fetches our project’s dependencies so we can build our application without needing internet access. This is called a hermetic build. A build that is completely isolated from external influences.

Think of it like going grocery shopping before cooking. Instead of running to the store in the middle of a recipe (downloading packages during the build), you buy everything beforehand (pre-fetch), bring it home (store locally), and then cook with the kitchen door locked (a network-isolated build).

Hermeto is used by CI platforms like Konflux CI to make sure every container build is reproducible, secure, and auditable.

Why Hermetic Builds Matter

When building a container image, a Dockerfile often looks like this:

FROM python:3.12

RUN pip install flask requests

This downloads flask and requests from the internet during the build. That creates three serious problems:

• Not reproducible: if the package gets updated between builds, you get differen results.

• Not secure: a supply chain attack could swap the real package with a harmful one.

• Not auditable: you don't have a record of exactly what went into your build.

Hermeto solves all three problems. It pre-downloads dependencies, verifies their checksums and generates an SBOM (Software Bill of Materials) listing every dependency used in the build.

How Hermeto Works

Hermeto has three main commands that work together like a pipeline.

Step 1: fetch-deps- Download Everything

This command reads the lockfile in your project (like go.sum, package-lock.json or requirements.txt), downloads every dependency listed in it, verifies checksums and saves everything to the output directory. It also generates an SBOM.

Step 2: generate-env: Set Up Environment Variables

Some package managers need to know where the cached dependencies are. This command generates a shell script that sets the right environment variables so that tools like go, pip or npm look at the local cache instead of the internet.

Step 3: inject-files: Configure For Offline Use

Some package managers need extra configuration files. For example, the RPM backend generates repository metadata and .repo files so that dnf can install packages from the local cache.

Building Offline:

After these three steps, you can build your container with no network access:

The --network none flag blocks all internet access. Since all dependencies are already downloaded and available locally, the build works perfectly without needing the internet.

Hermeto's Architecture

Package Manager Backends

Hermeto supports multiple package ecosystems through a backend system. Each backend knows how to read a specific lockfile format, download the right packages and generate the correct SBOM entries.

Currently supported backends:

How a Backend Works Internally

• Every Hermeto backend follows the same pattern:

• Read the lockfile (project dependency list)

• Download all packages using Hermeto’s async downloader

• Verify checksums and file sizes

• Generate SBOM entries (PURLs) for every dependency

Here is how all backends are registered in Hermeto's resolver:

# hermeto/core/resolver.py

_package_managers = {
    "bundler": bundler.fetch_bundler_source,
    "cargo":   cargo.fetch_cargo_source,
    "gomod":   gomod.fetch_gomod_source,
    "npm":     npm.fetch_npm_source,
    "pip":     pip.fetch_pip_source,
    "yarn":    metayarn.fetch_yarn_source,
    "generic": generic.fetch_generic_source,
    "rpm":     rpm.fetch_rpm_source,
}

When you run hermeto fetch-deps gomod, Hermeto looks up "gomod" in this dictionary and calls gomod.fetch_gomod_source(). Adding a new backend means writing the fetch function and adding it to this dictionary.

The RPM Backend

The RPM backend is the closest reference for the DEB backend.

Here is how it works:

Input: The RPM backend reads rpms.lock.yaml which lists every RPM package with its download URL, checksum and repository ID.

Fetch: It downloads all .rpm files using async_download_files(). Hermeto's shared async HTTP downloader. No dnf or yum is used during download, because Hermeto avoids running arbitrary code from package managers.

Verify: After download, it verifies every file's checksum and size against the lockfile.

SBOM: It queries each downloaded .rpm file using rpm -q to extract metadata (name, version, vendor) then generates PURL entries.

Inject-files: It runs createrepo_c to generate repository metadata, then creates hermeto.repo files so that dnf can find the local packages during offline builds.

The DEB Backend

Adding Debian/Ubuntu Support to Hermeto

Hermeto supports RPM packages for Red Hat-based images, but a lot of container images use Debian or Ubuntu as their base.These images use .deb packages and apt for package management.

Right now, Hermeto cannot pre-fetch .deb packages, which means Debian-based builds cannot be hermetic.

A DEB backend for Hermeto can follow the same pattern as the existing RPM backend: Lockfile → Fetch → Verify → SBOM → Inject

Key Differences Between RPM and DEB

The Core Challenge

1. No Standard Lockfile

Unlike npm (package-lock.json) or Cargo (Cargo.lock), the Debian ecosystem has no lockfile format. When you run apt-get install curl, apt resolves dependencies, downloads packages and installs them but nothing pins the exact versions with checksums.

For a DEB backend, a lockfile such as debs.lock.yaml is needed to fill this gap. All required fields (URLs, versions, SHA256 checksums, sizes) are directly available in the Debian repository’s Packages.gz metadata.

2.The Lockfile Generator

Since no standard lockfile exists, a companion tool will generate debs.lock.yaml by taking package names as input, fetching Packages.gz from repositories, resolving transitive dependencies, and outputting a valid lockfile.

This follows the same approach as the rpm-lockfile-prototype project on GitHub for the RPM backend.

SBOM: Software Bill of Materials

It is a list of every component that goes into building your software, like an ingredient list on food packaging.Hermeto generates SBOMs in CycloneDX or SPDX format. Each dependency gets a Package URL (PURL) that uniquely identifies it:

Hermeto's Design Principles

Hermeto follows three strict rules:

• Never execute arbitrary code: Hermeto does not run pip install, npm install, or apt-get install. Instead, it downloads files directly via HTTP. This prevents supply chain attacks where a harmful package could run code during installation.

• Everything must be defined:Dependencies must be explicitly declared in a lockfile.
  No auto-detection and no guessing.

• Everything must be reproducible: Every dependency must be pinned to an exact version. Running Hermeto twice with the same lockfile must produce the same result.

These principles are what make Hermeto different from tools like pip download or apt-get download.

Hermeto is not a package manager. It is a dependency fetching tool that enables existing package managers to work without internet access.