Ecosystems and references

For each kind of code a server runs, this page says what the attesterThe component on the machine being checked. It collects facts and reports them; it never decides the result. reads on the machine, which reference the verifierThe component that runs elsewhere, typically in CI: it sends a nonce, obtains references itself and compares. obtains, and what makes a check fail or leaves it unverifiable. It covers installed packages (npm, PyPI, RubyGems, Hex, Composer, Maven, NuGet), Go and Rust binaries, native binaries and release manifests, the official Node.js release, containers and OCIOpen Container Initiative: the standard image and registry formats. Manifests and layers are addressed by SHA-256 digest. images, and Debian and Ubuntu packages through their signed archives.

How a package check works#

Every installed-package ecosystem is a plugin with the same shape (ecosystems.INSTALLED):

compare() returns the same shape for every ecosystem:

• summary: counts by status: verified, bundled, patched, built, failed, unverifiable, error.
• findings: one per package that did not verify, with status, package, path, reason, and up to 50 modified, missing and added files.
• issues: other observations with a severity fail, warn or info.
• passed: true only when nothing failed, nothing is unverifiable, nothing is error, every issue has severity warn or info, and the scan read every file (errors in a scan fail: what is not read is not compared).

The three non-passing statuses mean different things:

A reference whose content does not match the hash the lockfile pins is failed, not error: that is evidence of tampering somewhere.

The same loop works for every ecosystem:

const {ecosystems, ReleaseVerification} = require('attestium');

(async () => {
  const store = new ecosystems.ReferenceStore({cacheDir: './cache'});
  const release = new ReleaseVerification({cacheDir: './cache'});

  for (const install of ecosystems.detectInstalls('./app')) {
    const plugin = ecosystems[install.ecosystem];

    // Attester: hash what is installed.
    const scan = await plugin.scan(install.dir, {root: './app'});

    // Verifier: the lockfile at the deployed commit, from its own checkout.
    let lock = null;
    try {
      lock = plugin.readLock('./reference');
    } catch (error) {
      if (!(error instanceof ecosystems.NoLockfileError)) {
        throw error;
      }
    }

    const result = await plugin.compare({scan, lock, store, release});
    console.log(install.ecosystem, result.passed, result.summary);
    console.log(result.findings, result.issues);
  }
})();

ReferenceStore downloads references and caches their manifests in cacheDir. Its urls option replaces registry base URLs (pypi, pypiFiles, rubygems, hex, nuget, maven, packagist, crates, goproxy), for example for a mirror. Content-addressed references are checked by hash whatever the mirror.

npm (npm and pnpm)#

Global packages next to the Node.js runtime (npm, corepack, pnpm, pm2) have no lockfile. ReleaseVerification#verifyGlobalPackage() compares npm and corepack with the copies inside the official Node.js archive when the installed version is the one the release shipped, and anything else with the registry tarball named by registry metadata.

To verify a project on the machine itself, without the evidence format:

const {ReleaseVerification} = require('attestium');

(async () => {
  const release = new ReleaseVerification({projectRoot: './app', cacheDir: './cache'});
  const result = await release.verifyModules();
  console.log(result.passed, result.details);
})();

PyPI#

RubyGems (Bundler)#

rubygems.compareGemDirectory({name, version, files, store}) compares one gem directory no lockfile pins, such as the bundler gem bundle exec puts on RUBYLIB, with the .gem the registry serves under the registry's published checksum.

Hex (Erlang, Elixir)#

Composer (PHP)#

Git runs with hooks off, no prompts, no system or global configuration, and only https URLs.

Maven (Java)#

NuGet (.NET)#

Go binaries#

A Go binary (Go 1.18 and later) records the module it was built from, every dependency with its go.sum hash, and build settings. elf.goBuildInfo() reads that record from the file; ecosystems.go.compareBuildInfo() checks it against go.sum at the deployed commit.

const fs = require('node:fs');
const {execFileSync} = require('node:child_process');
const {elf, ecosystems} = require('attestium');

// Attester: the build information inside the running binary.
const info = elf.goBuildInfo(fs.readFileSync('./hello'));

// Verifier: go.mod, go.sum and the commit, from its own checkout.
const lock = ecosystems.go.readLock('./goref');
const commit = execFileSync('git', ['-C', './goref', 'rev-parse', 'HEAD'], {encoding: 'utf8'}).trim();

const result = ecosystems.go.compareBuildInfo({info, lock, commit, label: 'hello'});
console.log(info.goVersion, info.main, info.settings['vcs.revision']);
console.log(result.passed, result.summary, result.issues);

The record is written by the build, so a binary could claim anything. The binary's own hash proves what it is: a reproduced build, an attested artifact, or a signed checksum. This check shows that the binary was built with the pinned dependencies, and flags a build from another commit or a modified tree.

Rust binaries#

A binary built with cargo-auditable records every crate compiled into it in a .dep-v0 section. elf.cargoAuditable() reads it; ecosystems.cargo.compareAuditable() checks it against Cargo.lock at the commit.

const fs = require('node:fs');
const {elf, ecosystems} = require('attestium');

// Attester: the crate list inside the binary (null when it has none).
const packages = elf.cargoAuditable(fs.readFileSync('./rustapp/target/debug/rustapp'));

// Verifier: Cargo.lock at the commit.
const lock = ecosystems.cargo.readLock('./rustapp');
const result = ecosystems.cargo.compareAuditable({packages, lock});
console.log(result.passed, result.summary, result.findings);

A crate fails when it is not in Cargo.lock, or comes from another source than the lockfile says. A registry crate whose lockfile entry has no checksum, or a git crate pinned to no commit, is unverifiable. As with Go, the binary's own hash is what proves it.

Native binaries#

A native binary (a database server, a proxy, a tool from a release page) is explained by one of:

• its owning distribution package (see Debian and Ubuntu packages);
• an entry in the project's published checksum list, preferably signed (checksums.fetchChecksums(), see Signatures);
• a GitHub artifact attestation for its SHA-256 (attestations.verifyGithubAttestation());
• a pinned SHA-256 in the verifier's configuration;
• a reproduced build.

For your own releases deployed without git, publish a release manifest from CI and attest it. See Release manifests and SPEC.md.

Language runtimes#

The attester detects each process's runtime from its executable name and mapped libraries (libjvm.so is the JVM, whatever the launcher is called): Node.js, Python, JVM, Ruby, .NET, BEAM, PHP, Perl, Deno, Bun, or native. For each, ProcessIntegrity reports that runtime's code injection vectors: environment variables that load code (NODE_OPTIONS, PYTHONPATH, JAVA_TOOL_OPTIONS, RUBYOPT, DOTNET_STARTUP_HOOKS, ERL_FLAGS, PHP_INI_SCAN_DIR, PERL5OPT, and the dynamic linker's LD_PRELOAD and LD_AUDIT), command-line options that do the same, debugger and management ports, and attach mechanisms.

The runtime binary itself is explained like any executable. Node.js has an official release reference:

const {ReleaseVerification} = require('attestium');

(async () => {
  const release = new ReleaseVerification({cacheDir: './cache'});
  // In a verifier, pass the executable's sha256 and the version from the evidence.
  const result = await release.verifyNodeRelease();
  console.log(result.passed, result.details);
})();

verifyNodeRelease() downloads SHASUMS256.txt for the version, the official .tar.gz for the platform, checks the archive against the list, and compares bin/node inside it with the binary (on Windows, node.exe is listed directly). Set nodeKeyring to a keyring of the Node.js release keys to require a valid signature on SHASUMS256.txt (checked with gpgv). A binary repackaged by a distribution differs from the official one; explain it by its distribution package instead.

Other runtimes are explained by their distribution package, their project's signed checksums, or a pinned hash.

Containers and OCI images#

For a process in a container, the attester reports:

• the container, from the process's cgroup (containers.containerOf(): Docker, containerd, CRI-O, Podman, Kubernetes);
• the image the runtime says it started from (containers.inspectDocker(), or containers.inspectCri() through crictl);
• mounts that bring in files from outside the image;
• the overlay's writable layer: files written and files deleted (containers.walkUpper());
• every file of the root filesystem, hashed through /proc/<pid>/root, other mounts left out (containers.walkRootfs()).

The verifier does not trust the runtime's claims. It fetches the image by digest from the registry, checks every manifest and layer against the digest that names it, applies the layers in order (whiteouts included), and compares the files:

const {containers, oci} = require('attestium');

(async () => {
  const pid = process.argv[2]; // a process inside the container

  // Attester: the container, the image the runtime names, the files it runs from.
  const {id} = containers.containerOf(pid);
  const inspected = await containers.inspectDocker(id);
  const rootfs = await containers.walkRootfs(pid);
  const repoDigest = inspected.image.repoDigests[0]; // registry/repository@sha256:...

  // Verifier: the image, fetched by digest; the platform manifest; every layer applied.
  const registry = new oci.Registry();
  const reference = oci.parseReference(repoDigest);
  const {manifest} = await registry.platformManifest(reference, inspected.platform);
  const expected = await oci.imageFiles(registry, reference, manifest);

  // Files the runtime writes into every container are not image files.
  const runtimeFiles = new Set(['.dockerenv', 'etc/hostname', 'etc/hosts', 'etc/resolv.conf']);
  const result = oci.compareRootfs(rootfs.files, expected, {ignore: file => runtimeFiles.has(file)});
  console.log(result); // {modified, missing, added, modeChanged}
})();

Pass credentials to oci.Registry for private registries ({token} or {username, password} per registry name), and endpoints to map a registry name to a mirror. A registry with no configured endpoint is a name taken from evidence: it, and the token service it names, is never reached at a private address (loopback, RFC 1918, link-local, cloud metadata) unless httpOptions.denyPrivateAddresses is false. Code in a volume or bind mount is not part of the image; explain it as a directory service or report it.

Debian and Ubuntu packages#

The runtime and the shared libraries a process maps usually come from the distribution. The reference is the distribution's signed archive:

• The attester finds the owning package of each file in the dpkg database (distro.DpkgDatabase#ownerOf()), with its version, architecture, the path it is listed as (merged-/usr aliases included), and when it was installed.
• The verifier checks the archive's InRelease signature with the distribution's keyring (gpgv, reading its status lines from a descriptor of their own, so a signature by a revoked or expired key, which gpgv accepts with exit status 0, is refused), follows the SHA-256 chain to the Packages index and to the .deb, extracts it with dpkg-deb, and compares the file.

const fs = require('node:fs');
const {distro, ecosystems, util} = require('attestium');

(async () => {
  const file = '/usr/lib/x86_64-linux-gnu/libc.so.6';

  // Attester: the owning package, from the dpkg database, and the file's hash.
  const owner = new distro.DpkgDatabase().ownerOf(file);
  const sha256 = util.sha256(fs.readFileSync(file));

  // Verifier: the same file inside that package, from the signed archive.
  const release = distro.osRelease();
  const archives = distro.defaultArchives(release, owner.arch);
  const store = new ecosystems.ReferenceStore({cacheDir: './cache'});
  const reference = new distro.ArchiveReference({archives, store});
  const files = await reference.files(owner.name, owner.version, owner.arch, owner.installedAt);

  const expected = files[owner.listedAs] ?? files[file];
  console.log(owner, expected === sha256 ? 'matches the archive' : 'differs from the archive');
})();

The dpkg database is the server's claim. The package it names must hold the file with the same contents, so a false claim fails. A file owned by no package is reported as unexplained.

defaultArchives() returns the release's main, updates and security suites, with the keyrings in /usr/share/keyrings (install debian-archive-keyring or ubuntu-keyring on the verifier). Archive indexes may be fetched over plain HTTP: their contents are authenticated by the signature and the hash chain, not by the transport.

A version that has since been superseded is no longer in the archive. ArchiveReference#files() then looks it up in the archive's snapshot service (snapshot.debian.org, snapshot.ubuntu.com) at the hour the package was installed, and a day later. When neither has it, it throws with code ENOTINARCHIVE: upgrade the package, or configure an archive snapshot that has it.