# Chainguard Libraries verification

URL: https://edu.chainguard.dev/chainguard/libraries/verification.md
Last Modified: January 6, 2026
Tags: Chainguard Libraries

Learn how to verify libraries and packages are from Chainguard Libraries using the chainctl tool for enhanced supply chain security

 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, APK, and npm tarballs (.tgz), 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, details also in the reference documentation. 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 versioncosign version Authentication and configuration You can authenticate with your Chainguard organization using chainctl. First, initiate the login flow:
chainctl auth loginIf you are a member of one organization only, you can proceed to use libraries verify and other commands.
If you are a 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 libraries verify --parent <your-organization> /path/to/artifact.jarTo 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 listSet the configuration for the default group:
chainctl config set default.group <your-organization>Verify the configuration:
chainctl config viewEnsure that you use this configuration or add the --parent parameter in all the following examples as necessary.
File analysis Analyze a Python wheel file Analyze a Python wheel file in the current directory:
chainctl libraries verify flask-3.0.1-py3-none-any.whlThe analysis of wheel files is fast because the provenance information is available within the archive. Python development tools often unpack the wheel file and you can also scan these extracted packages. For example, if you create a virtual environment in your Python project, you can subsequently analyze the package in the virtual environment:
python3 -m venv venv source ./venv/bin/activate pip3 install -r requirements.txt chainctl libraries verify --detailed ./venv/ Analyze a Java JAR file Analyze a Java .jar file:
chainctl libraries verify commons-lang3-3.17.0.jarVerifying 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. Typically, you find the JAR files in the local Maven repository cache in ~/.m2/repository. For best results, verify individual JAR files from this cache before packaging your application. See Java fat JAR limitations for more details.
Analyze a deployment archive for your custom application that contains other libraries:
chainctl libraries verify example-application.tar.gzNote that if your deployment archive is a fat JAR, uber JAR, or shaded JAR, verification returns 0% coverage. This is expected behavior; see Java fat JAR limitations for the recommended verification approach.
For other archive types such as tarballs that contain individual unmodified JAR files, scanning can take a significant amount of time if numerous libraries are included. 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.zipAnalyze a file and create JSON output:
chainctl libraries verify -o json commons-lang3-3.17.0.jar Java fat JAR limitations The fat JAR packaging approach merges the class files from all dependency JARs into one combined archive, which means the original JAR boundaries are lost.
Because chainctl libraries verify identifies libraries by checking checksums and provenance information against individual JAR files, it cannot trace merged class files back to their source JARs. As a result, running chainctl libraries verify against a fat JAR returns 0% coverage, even if the dependencies inside it were sourced from Chainguard Libraries.
Recommended verification approach for fat JARs To verify that your Java dependencies come from Chainguard Libraries, run chainctl libraries verify during your build process against the individual JAR files in your local Maven repository cache, before fat JAR assembly.
After resolving dependencies with Maven, the individual JAR files are available in ~/.m2/repository. The following example uses net.logstash.logback:logstash-logback-encoder:8.1 as the library, but you can replace the path with the specific JAR you want to verify:
chainctl libraries verify ~/.m2/repository/net/logstash/logback/logstash-logback-encoder/8.1/logstash-logback-encoder-8.1.jarTo integrate this into your build pipeline, add the verification step after dependency resolution and before the packaging phase.
Analyze JavaScript packages chainctl libraries verify can scan local package manager caches and stores to confirm that your installed JavaScript packages were built by Chainguard. It supports the following JavaScript package managers:
pnpm store: auto-detected by v10/index/ or v11/index/ structure (pnpm v10 and v11 supported) npm cache: auto-detected by _cacache/index-v5/ structure Yarn Classic: v1.x, requires yarn: prefix Analyze an npm tarball Verify an npm package tarball to confirm it was built by Chainguard:
chainctl libraries verify PACKAGE-VERSION.tgzReplace PACKAGE and VERSION with the package name and version (for example, @eslint-js and 9.0.0)
Verification uses SLSA provenance attestations. chainctl computes a SHA-512 digest of the tarball locally, fetches the signed attestation bundle, and uses cosign to confirm that the signature is valid, the certificate chains to the Sigstore root, the signer identity matches the Chainguard JavaScript builder, and the digest matches what was attested at build time.
Verify an npm cache Verify your npm cache:
chainctl libraries verify "$(npm config get cache)" Verify a pnpm store Verify your pnpm store:
chainctl libraries verify "$(pnpm store path)"pnpm v9 and earlier are not supported. Verification works by comparing the tarball hash recorded in your local store against the hash in Chainguard’s signed SLSA attestation. pnpm v10 records this hash in the index file path; pnpm v9 does not.
Verify a Yarn Classic cache Verify a Yarn Classic (v1) cache:
chainctl libraries verify yarn:To specify a non-default cache location:
chainctl libraries verify yarn:~/Library/Caches/Yarn/v6Unlike npm and pnpm, Yarn Classic requires the yarn: prefix because its cache directory layout cannot be reliably auto-detected.
Verify a node_modules directory Verify npm packages installed in a node_modules directory:
chainctl libraries verify ./node_modulesIf .package-lock.json is not present, the directory is not recognized as an npm tree and verification will not run.
Verify a container image Verify JavaScript packages inside a container image:
chainctl libraries verify IMAGE:TAGCoverage is reported as the percentage of JavaScript packages in the image that are confirmed Chainguard-rebuilt libraries.
Images built with npm versions earlier than v7, or where .package-lock.json was removed during the build, cannot be verified this way.
Other bundled artifact formats The same limitation applies to other ecosystems where dependencies are bundled into a single output artifact, such as JavaScript bundles and Python applications packaged with tools that inline dependencies. Dependencies may also be minified, partially copied, or otherwise transformed during the build process. In all of these cases, verification should also be performed against the original package files before bundling rather than against the final output artifact.
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:latestNote 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. Note that authentication to the repository is not supported and you must download artifacts to a local directory as an alternative method to verify them.
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.jarAnalyze a remote artifact on PyPI:
chainctl libraries verify remote:files.pythonhosted.org/packages/...../requests-2.31.0-py3-none-any.whl Built-in help Use the help command for more command options and details for the verify command:
chainctl help libraries verify Resources Chainguard Libraries Overview Chainguard Libraries Authentication chainctl libraries verify reference documentation Learning Lab: Chainguard Libraries for Java Learning Lab: Chainguard Libraries for Python