Chainguard Libraries Verification

Overview

Chainguard’s chainctl tool with the command libraries verify 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.

Command characteristics:

• 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 using chainctl to verify libraries, ensure you have the following installed and available on your path:

• chainctl — Chainguard-maintained tool that includes the libraries verify command.
• 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
• Your organization must include entitlement for access to Chainguard Libraries

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

chainctl version

cosign version

Authentication and configuration

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

chainctl auth login

If you are member of one organization only, you can proceed to use libraries verify and other commands.

If you are member of multiple organizations you must provide the name of your organization using the --parent flag as follows, replacing <your-organization> with the name of your organization, with every command:

chainctl libaries verify --parent <your-organization> /path/to/artifact.jar

To avoid the need for the additional parameter, you can configure a default organization with the following steps:

Find your organization name with the entitlement:

chainctl iam organizations list

Set the configuration for the default group: TBD - this does NOT yet work, also maybe default.org-name instead??

chainctl config set default.group <your-organization>

Verify the configuration:

chainctl config view

Ensure to use this configuration or add the --parent parameter in all following examples as necessary.

File analysis

Analyze a Python wheel file in the current directory:

chainctl libraries verify flask-3.0.1-py3-none-any.whl

The analysis of wheel files is fast because the provenance information is available within the archive.

Analyze a local Java .jar file:

chainctl libraries verify commons-lang3-3.17.0.jar

Verifying a JAR file is performed by looking up checksums and provenance information from the Chainguard repositories. This requires network access and can take longer if you analyze multiple files or archives that contain multiple libraries.

Analyze a deployment archive for your custom application that contains other libraries:

chainctl libraries verify example-application.tar.gz

Note that scanning larger archives that contain numerous libraries can take a significant amounts of time. Consider detailed output with the --detailed flag for more information about the performed verification steps, and potentially pipe the output into a file.

chainctl libraries verify --detailed commons-lang3-3.17.0.jar > run.log 

Use the --verbose flag for even more details.

Analyze multiple artifacts output:

chainctl libraries verify artifact1.jar artifact2.zip

Analyze a file and create JSON output:

chainver libraries verify -o json commons-lang3-3.17.0.jar

Container analysis

You can also analyze container images to verify the libraries contained within the container. Note that this requires more time to verify depending on the container size, and the number and type of included libraries.

Analyze a container image:

chainctl libraries verify cgr.dev/chainguard/maven:latest

Note that the analysis separately downloads the container tarball and analyzes it, rather than any container available in your local container setup.

Analyze a local image with localhost prefix:

chainctl libraries verify localhost/myapp:latest

Other examples

The following examples use Maven Central and PyPI URLs and returns a negative result, because packages were not built by Chainguard. A practical use of this functionality points to an internal repository manager with a mixture of artifacts from Chainguard and elsewhere.

Analyze a remote artifact on Maven Central:

chainctl libraries verify remote:repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.17.0/commons-lang3-3.17.0.jar

Analyze a remote artifact on PyPI:

chainver libraries verify remote:files.pythonhosted.org/packages/...../requests-2.31.0-py3-none-any.whl

Inventory creation

The chainctl tool also supports a libraries inventory command. Use it to create a list of artifacts available in a specific location. Set the --ecosystem flag to java for Java artifacts and python for Python files.

chainctl libraries inventory --ecosystem java remote:repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.20.0

Built-in help

Use the help command for more command options and details for the verify and inventory commands:

chainctl help libraries verify
chainctl help libraries inventory

Resources

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