Quick start for Chainguard Libraries

Most supply chain attacks succeed the same way: malicious code is injected into a package after the source is written — either as a backdoored binary with no verifiable source, or as a malicious install-time script that runs the moment a dependency is pulled. Recent attacks on LiteLLM, Telnyx, and Axios all followed this pattern.

Chainguard Libraries are rebuilt from verified source in an isolated build environment, making them malware-resistant by design. When a package is available as a Chainguard-built library, that rebuilt package is served first. When you use the upstream fallback, the same ecosystem endpoint can also serve eligible upstream packages that Chainguard has not yet built, subject to configurable policy controls such as cooldown and malware scanning.

This gives your engineers drop-in replacements for the packages they already use, with no breaking changes.

This guide covers the high-level steps to get up and running. For full reference documentation on any step, follow the links provided.

Prerequisites

Before getting started:

• If you’re not yet a Chainguard user, you must create an account.

• Install chainctl and log in:

  chainctl auth login

• Entitle access for yourself to Chainguard Libraries.

  • Chainguard Libraries are available to Catalog Starter and Free tier users, and trial users.
  • Run the following chainctl libraries command to create an entitlement for libraries:

chainctl libraries entitlements create --ecosystems=JAVASCRIPT

The available ecosystems are JAVASCRIPT, JAVA, and PYTHON.

Alternatively, you can create an entitlement and pull token in the Chainguard Console: while viewing a library ecosystem page, follow the prompts to create an access token.

Step 1: Choose your access method

There are two ways to access Chainguard Libraries: using an artifact manager or direct access.

Artifact manager

Configure credentials once in a tool like JFrog Artifactory, Sonatype Nexus, or Cloudsmith. This centralizes policy, logging, and fallback behavior, and is the safest approach for organizations with multiple teams and applications.

If you configure upstream fallback, the same ecosystem endpoint can serve both:

• Libraries rebuilt from source by Chainguard, and
• Eligible packages from the upstream public registry when Chainguard has not built that package or version yet

Upstream packages served through the Chainguard Repository are subject to configurable policy controls such as cooldown and malware protection. It is strongly recommended that you follow this approach.

Alternatively, you can configure your repository manager to fallback to the upstream public repositories for packages not available from Chainguard Libraries, as described in the global configuration docs for each ecosystem. Packages sourced from public registries are not covered by Chainguard’s malware-resistance guarantees. If you choose this option, we strongly recommend configuring a quarantine or cooldown period on your fallback repository so that newly published or updated packages are not immediately available to developers. Chainguard has no control over malware protection for packages sourced from public registries.

Direct access

Configure authentication directly in each project’s build configuration.

This option is faster to set up initially, but requires per-project and per-workstation configuration. This increases the risk of credentials being committed to source control or going stale.

Learn how to set up direct access in the build configuration documentation for Python, JavaScript, and Java.

Step 2: Create a pull token

Pull tokens are required for authentication. You can create one using chainctl:

chainctl auth pull-token --repository=java --ttl=720h

chainctl auth pull-token --repository=python --ttl=720h

chainctl auth pull-token --repository=javascript --ttl=720h

The default TTL is 720h (30 days); the maximum is 8760h (365 days).

The command returns a username and password for basic authentication. Store these securely, as they won’t be shown again.

You can also create pull tokens via the Chainguard Console under Overview > Manage pull tokens > Create access token.

Learn more about pull tokens, and using environment variables for pull token credentials, in the Libraries Access documentation.

Step 3: Configure your build tools

Once you have a pull token, you can configure your build tool. Configuration steps vary by build tool and ecosystem. See the ecosystem-specific documentation pages for instructions.

If you configure upstream fallback, the same endpoint can serve both Chainguard-built artifacts and upstream arfifacts through the Chainguard Repository.

Note on upstream fallback: The upstream fallback is available as an opt-in setting for both repository manager or direct access approaches, and is turned off by default. Learn more about upstream fallback policy and controls in the Libraries overview.

Step 4: Verify your libraries

After setup, you can verify which dependencies were built from source by Chainguard:

chainctl libraries verify /path/to/artifact

Learn more in Chainguard Libraries verification.

FAQs

See the Chainguard Libraries FAQ page for common questions and issues.