Chainguard Libraries Verification

Overview

Chainguard’s chainver tool verifies that your language ecosystem dependencies come from Chainguard Libraries, providing critical visibility into your software supply chain security. By verifying binary artifacts across your projects and repositories, you can ensure dependencies are sourced from Chainguard’s hardened build environment rather than potentially compromised public repositories, identify opportunities to improve security posture, and maintain compliance with supply chain security policies.

The chainver tool:

• Uses a signature-based binary identification and a checksum fallback.
• Supports different binary formats, including JAR, WAR, EAR, ZIP, TAR, WHL, and APK files as well as container images.
• Allows analysis of directories and nested archive files.
• Creates output in text, json, yaml, and CSV formats.

Requirements

Before installing chainver, ensure you have the following installed and available on your path:

• chainctl — A Chainguard-maintained tool used for authentication
• cosign — A Sigstore-maintained tool used to verify signatures

You also need:

• A Linux, macOS, or Windows system (x86_64 or arm64)
• Sufficient network access

Confirm that chainctl and cosign are installed and available on the PATH with the following commands: commands:

chainctl version

cosign version

Installation

Download the latest release - version 0.5.0

Version-Agnostic Download

Download the latest release using curl. Note that jq must be on the path.

LATEST_URL=$(curl -s https://dl.enforce.dev/chainver/latest/latest-metadata.json | jq -r '.download_url') && \
 curl -LO "${LATEST_URL}"

Once you’ve downloaded the archive, unpack the platform specific archive for your system, and place the binary chainver for your platform on the path.

Binary Install Script (macOS and Linux)

The following command downloads the latest version of chainver as an archive, extracts it, verifies the download, and moves the binary to /usr/local/bin.

First, set the ARCH variable to match your system using one of the following options:

• Linux_x86_64 - Linux with x86_64 processor
• Linux_arm64 - Linux with ARM processor
• Darwin_arm64 - macOS with Apple Silicon (M1/M2/M3)
• Darwin_x86_64 - macOS with Intel processor

ARCH=Linux_x86_64 && \
LATEST=$(curl -s "https://storage.googleapis.com/us.artifacts.prod-enforce-fabc.appspot.com/?prefix=chainver/" | \
  grep -oE 'chainver/[0-9]+\.[0-9]+\.[0-9]+/' | \
  sed 's|chainver/||g' | sed 's|/$||g' | \
  sort -V | tail -1) && \
curl -LO "https://dl.enforce.dev/chainver/${LATEST}/chainver-v${LATEST}.zip" && \
unzip -q chainver-*.zip && \
cd chainver-package && \
EXT=$([ "$ARCH" = "Windows_x86_64" ] && echo "zip" || echo "tar.gz") && \
./verify-signatures.sh archives/chainver_${LATEST}_${ARCH}.${EXT} && \
if [ "$ARCH" = "Windows_x86_64" ]; then \
  unzip -q archives/chainver_${LATEST}_${ARCH}.zip; \
else \
  tar xzf archives/chainver_${LATEST}_${ARCH}.tar.gz; \
fi && \
sudo mv chainver /usr/local/bin/ && \
cd .. && rm -rf chainver-*.zip chainver-package && \
chainver version

Authentication Setup

Using chainctl

You can authenticate with your Chainguard organization using chainctl. First, initiate the login flow:

chainctl auth login

Log in using one of the provided options:

Find your organization name:

chainctl iam organizations list

When using chainver commands, provide the name of your organization using the --parent flag as follows, replacing <your-organization> with the name of your organization:

chainver --parent <your-organization> /path/to/artifact.jar

Using Tokens

For CI/CD pipelines or environments without chainctl, you can use a token. First, create a pull token for Chainguard Libraries.

Once you have your token, you can authenticate by passing it to chainver using the --token flag:

chainver --token <your-chainguard-token> /path/to/artifact.jar

Alternatively, set the token as an environment variable:

export CHAINGUARD_TOKEN=your-chainguard-token
chainver /path/to/artifact.jar

The following environment variables are supported:

• CHAINCTL_TOKEN or CHAINGUARD_TOKEN - Authentication token
• JFROG_API_KEY - JFrog Artifactory access
• CLOUDSMITH_API_KEY - Cloudsmith access

Usage

Analyze a local .jar or .whl file:

chainver --parent <your-organization> commons-lang3-3.12.0.jar

Analyze a container image on a registry:

chainver --parent <your-organization> cgr.dev/chainguard/nginx:latest

Analyze a local container:

chainver redis:latest
chainver nginx:alpine
chainver ubuntu:20.04

Analyze a local image with localhost prefix:

chainver --parent <your-organization> localhost/myapp:latest

Analyze with detailed output:

chainver --detailed /path/to/archive.zip

Analyze multiple artifacts with detailed output:

chainver --detailed artifact1.jar artifact2.zip

Receive JSON output for CI/CD integration:

chainver -o json /path/to/artifact.jar

Generate inventory from repository. (Note that passing a URL from the public Maven Central repository will return a negative result, i.e. chainver will indicate that packages were not built by Chainguard.)

chainver inventory --ecosystem java remote:repo1.maven.org/maven2/org/apache

Analyze a remote artifact on Maven Central:

chainver --parent <your-organization> remote:repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar

Analyze a remote artifact on PyPI:

chainver --parent <your-organization> remote:files.pythonhosted.org/packages/70/8e/0e2d847013cb52cd35b38c009bb167a1a26b2ce6cd6965bf26b47bc0bf44/requests-2.31.0-py3-none-any.whl

Resources

• Chainguard Libraries Overview
• Chainguard Libraries Authentication
• Learning Lab: Chainguard Libraries for Java
• Learning Lab: Chainguard Libraries for Python