Chainguard Libraries access

Learn how to access Chainguard Libraries for enhanced security in Java and Python dependencies, including authentication and organization setup

16 min read

Chainguard Libraries

Chainguard Libraries provide controlled access to security-enhanced Java and Python dependencies through the unified Chainguard platform authentication system. This guide explains how to access (download) Chainguard library artifacts for your organization.

Getting started

Prerequisites

Ensure you have access to Chainguard Libraries.
- If you are not a Chainguard user yet, a new Chainguard account must be created and you must add an entitlement to Chainguard Libraries.
Confirm the name of your organization so you can use it with the --parent parameter to specify your organization when running commands with chainctl.

Direct access vs. artifact manager

There are two approaches to access: Using an artifact manager or direct access.

Artifact manager

If your organization uses an artifact manager such as Cloudsmith, JFrog Artifactory, or Sonatype Nexus, you can set up and configure credentials once per language ecosystem. Then, all projects and developers automatically inherit the configuration. This option is recommended for organizations with multiple teams, and provides centralized access controls and consistent uptime.

Direct access

Set up authentication directly in each project’s build configuration. This option allows for faster initial setup, but it does not allow for global configuration. It requires configuration per project and workstation, which creates more overhead as you scale across teams and projects.

Both approaches require pull tokens for authentication; see Pull token characteristics and use for more information.

NOTE: For Python users, the Chainguard keyring provider uses short-lived credentials and is the preferred method where your environment supports it.

Initial authentication

Once your user account is created and access is confirmed, install the Chainguard Control chainctl command line tool and log in to your account:

chainctl auth login

After authentication in a browser window, a successful login displays a message and a token:

Successfully exchanged token.
Valid! Id: 8a4141a........7d9904d98c

Creating pull tokens for libraries

Pull tokens authenticate requests to download library artifacts from Chainguard. You can create the pull tokens:

With the chainctl command, or
Using the Chainguard console.

For environments where short-lived credentials are not suitable, such as some CI/CD platforms, you can generate a pull token, which provides longer-lived access to Chainguard Libraries.

To create a pull token you must have the relevant entitlement for the ecosystem and the libraries.java.pull_token_creator, libraries.javascript.pull_token_creator, or libraries.python.pull_token_creator role.

Creating pull tokens with chainctl

Create a new pull token for the Chainguard Libraries for Java with the chainctl auth pull-token command:

chainctl auth pull-token --repository=java --parent=example --ttl=8670h

--repository=java: retrieve the token for use with Chainguard Libraries for Java. Use python for a token to use Chainguard Libraries for Python and javascript for a token to use Chainguard Libraries for JavaScript.
--parent=example: specify the parent organization for your account as provided when requesting access to Chainguard Libraries and replace example.
--ttl=8670h: set the duration for the validity of the token, defaults to 720h (equivalent to 30 days), maximum valid value is 8760h (equivalent to 365 days), valid unit strings range from nanoseconds to hours and are ns, us, ms, s, m, and h.

Use the optional --name flag to supply a meaningful and short name for the token, to be able to locate it easier at a later stage.

When omitting the parent parameter, potentially a list of organizations is displayed. Use the arrow keys to navigate the selection displayed after the question “With which location is the pull token associated?” and select the organization that has the entitlement to access Chainguard Libraries for Java. Press / to filter the list.

chainctl returns a username and password suitable for basic authentication in the response:

Username: 45a.....424eb0

Password: eyJhbGciO..........WF0IjoxN

Creating pull tokens with the Chainguard console

Follow these steps to create a pull token for Chainguard Libraries in the Chainguard console:

Use your authentication details to access the console at https://console.chainguard.dev/.
In the left-hand navigation, click Overview.
Click the Manage pull tokens tab, then click Create access token.
- Alternatively, select Access Tokens from the menu at the top of the Settings page.
Configure the access token:
- Name: Provide a name. The name can later be used to locate the token in the list.
- Description: Optionally provide a description of the token.
- Access: Choose the library that this token should access.
- Expiration: Set an expiration date for the token. The default is 30 days.
Click Create token.
When the username and password values are displayed, note these values in a secure location, as you will need them for pull token use. These values will not be displayed again.

Pull token characteristics and use

The returned username and password combination is a new credential set in the organization that is independent of the account used to create and retrieve the credential set. It is therefore suitable for use in any service application, such as a repository manager or a build tool that is not tied to a specific user. You can also use the token as an individual for your development with direct access to Chainguard Libraries.

To use the pull token in another environment, supply the username and password for basic authentication. Note that the actual returned values are much longer.

Note: Chainguard does not offer an SLA for uptime availability of the Chainguard Libraries repositories at libraries.cgr.dev. To reduce production risk and ensure reliability, we recommend proxying the repositories through your own artifact repository whenever possible.

For artifact manager setup, see the global configuration guides:

For direct access, see the build configuration guides:

Use environment variables for pull token credentials

Using environment variables for username and password is more secure than hard coding the values in configuration files. In addition, you can use the same configuration and files for all users to simplify setup and reduce errors.

Use the env environment output option to create a snippet for a new token suitable for integration in a script.

$ chainctl auth pull-token --output env --repository=java --parent=example
export CHAINGUARD_JAVA_IDENTITY_ID=45a.....424eb0
export CHAINGUARD_JAVA_TOKEN=eeyJhbGciO..........WF0IjoxN

Combine the call with eval to populate the environment variables directly by calling chainctl:

eval $(chainctl auth pull-token --output env --repository=java --parent=example)

Equivalent commands for Python and JavaScript are supported and result in values for the CHAINGUARD_PYTHON_IDENTITY_ID/CHAINGUARD_PYTHON_TOKEN and CHAINGUARD_JAVASCRIPT_IDENTITY_ID/CHAINGUARD_JAVASCRIPT_TOKEN variables.

Use the export commands in a ~/.env or similar file or use your preferred secrets management application to reuse the token in multiple sessions. Source the file or load the secrets from the app to have access to the tokens in your shell session, including build configurations file that can load from environment variables, for example a Maven settings.xml file.

Running this command as part of a login script or some other automation allows your organization to replace actual username and password values in your build tool configuration with environment variable placeholders:

.netrc for authentication

curl and a number of other tools support configuration of username and password authentication details for a specific domain in the .netrc file, typically located in the user’s home directory.

Use this approach for authentication to a repository manager in your organization or to Chainguard Libraries directly, for example with pip and others for Chainguard Libraries for Python, with bazel for Chainguard Libraries for Java or for manual testing with curl.

The following example shows a suitable setup for a repo manager available at repo.example.com:

machine repo.example.com
login YOUR_USERNAME_FOR_REPOSITORY_MANAGER
password YOUR_PASSWORD

For a direct connection to Chainguard Libraries, for example for testing with curl, use the following example with the username CHAINGUARD_PYTHON_IDENTITY_ID and password CHAINGUARD_PYTHON_TOKEN value for the pull token for the desired language ecosystem:

machine libraries.cgr.dev
login CHAINGUARD_PYTHON_IDENTITY_ID
password CHAINGUARD_PYTHON_TOKEN

Note that the long string for the password value must use only one line.

Verification

Use the credentials for manual testing in a browser or with a script and curl if you know the URL for a specific library artifact. Refer to the following sections for more details:

Python keyring provider

Python users can leverage an alternative to pull tokens. The Chainguard keyring implementation provides short-lived credentials from supported environments, such as local development and CI/CD platforms that can use assumable identities.

Where possible, Chainguard recommends using short-lived credentials to access Chainguard Libraries.

To set up the keyring, install the keyrings-chainguard-libraries package:

pip install keyrings-chainguard-libraries

Note: If you haven’t set up access to Chainguard Libraries for Python, the above command installs the package from PyPI. After installing and configuring Chainguard Libraries for Python, you can get the private package again, to get the package built by Chainguard. To re-install the package:

pip install keyrings-chainguard-libraries --ignore-installed --no-cache-dir

Once the keyring package is installed, when you request to install packages from Chainguard Libraries for Python, the keyring automatically retrieves short-lived credentials for you, using chainctl.

To use the keyring with a project uv, install the keyring:

uv pip install keyrings-chainguard-libraries

uv pip install keyrings-chainguard-libraries --reinstall --no-cache

By default, uv disables keyring auth.

To enable it in the global uv.toml:

keyring-provider = "subprocess"

To enable it in a project-specific pyproject.toml:

[tool.uv]
keyring-provider = "subprocess"

Pull token management

Pull tokens are separate identities with username and password that are used for access to Chainguard Libraries. The tokens have a limited Time to Live (TTL) with a default of 30 days and a maximum TTL of 365 days.

As a result, pull tokens become invalid after the TTL and are flagged as expired. For your use of Chainguard Libraries you must replace the token with a new one.

Expired tokens can no longer be used for access to Chainguard Libraries, but otherwise do not cause any issues and continue to exist until you delete them.

Inspect all pull tokens for your organization in the Chainguard console:

Use your authentication details to access the console at https://console.chainguard.dev/.
Select Overview in the left-hand navigation.
Select the Manage pull tokens tab.
- Alternatively, select Settings in the left-hand navigation, and select Pull Tokens in the menu on the settings page.

The list includes the following columns:

Name - the name of the pull token, expired pull token are identified by a red Expired warning.
Description - the description of the pull token
Created - the date when the pull token was created
Expiration - string description of the expiration status of the token, such as in 8 months or 4 days ago.
Actions - menu button to perform actions on the pull token, only a Delete action is available.

Use the action to remove a pull token:

Locate the row of the desired pull token, typically an expired token.
Use the menu button in the Actions column of the same row and select Delete.
Confirm the deletion in the dialog by pressing Delete pull token.

Alternatively use chainctl with the auth pull-token and iam identities commands for various inspection and management tasks.

List all pull tokens with the list command:

chainctl auth pull-token list

The displayed list includes the following columns:

ID - the identifying username of the pull token
NAME - the name of the pull token
DESCRIPTION - the description of the pull token
ROLES - the assigned organization and role for the pull token. The value shows the name of the organization separate from the role with a colon. Valid roles are all pull authorization from for apk packages apk.pull, container images registry.pull, Python libraries libraries.python.pull, Java libraries libraries.java.pull, and JavaScript libraries libraries.javascript.pull .
EXPIRES - the number of days until the end of the TTL period. Negative values indicate expired tokens.

List all pull tokens for Chainguard Libraries for Java that are not yet expired:

chainctl auth pull-token list --repository=java

List all expired pull tokens for Chainguard Libraries for Python:

chainctl auth pull-token list --repository=python --expired=true

Use the delete command for IAM identities to delete a specific pull token using its ID 45a0c61ea6fd97...:

chainctl iam identities delete 45a0c61ea6fd97...

Use the identifier or name of your organization example and the --expired flag to remove all expired pull tokens:

chainctl iam ids rm --expired --parent=example

Manage library entitlements

You can create, list, and remove entitlements using chainctl libraries entitlements.

Create entitlements

As administrator you can use chainctl libraries entitlements create for one or more ecosystems:

chainctl libraries entitlements create --ecosystems=JAVASCRIPT,JAVA,PYTHON

To enable upstream fallback for JavaScript, use the --policy flag:

chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM

To update the upstream fallback policy on an existing entitlement, rerun the create command with the new --policy value.

Remove entitlements

You can delete an ecosystem library entitlement for a specific ecosystem from your organization with chainctl libraries entitlements delete:

chainctl libraries entitlements delete --ecosystem=JAVASCRIPT --parent=example

List entitlements

You can verify entitlements for your organization example.com to verify which ecosystems are enabled:

chainctl libraries entitlements list

The output includes the ecosystem and configured policy in the table:

Ecosystem Library Entitlements for example (45a0...p7q)

                            ID                             | ECOSYSTEM  |             POLICY
-----------------------------------------------------------|------------|--------------------------------
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/12345abc67890 | JAVASCRIPT | POLICY_CHAINGUARD_AND_UPSTREAM
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/45678abc67890 | JAVA       | POLICY_CHAINGUARD
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/56789abc67890 | PYTHON     | POLICY_CHAINGUARD

Manage library policies

Users with the Owner role can create, enable, disable, and list library policies using chainctl libraries policy commands. These policies apply to all packages pulled through Chainguard Repository. The upstream fallback must be enabled for an ecosystem in order to use policies.

One custom policy per ecosystem can be enabled at a time. This policy should include all the rules you need, which may include a cooldown period, package block rules, and any overrides.

Chainguard Libraries supports the following types of policies:

Cooldown: Delays upstream newly published package versions for a set number of days after the upstream registry publish date.
Block: Deny a package or version outright. Use a block rule when your organization never wants to allow a package or version.
Override: Permit a package or version that would otherwise be denied by a cooldown policy or malware and greyware blocking. Use an override when you need a specific, deliberate exception.
- An override policy takes precedence over a block policy.

Note: The commands in this section require chainctl v0.2.291 or newer.

Identify packages with a purl

Library policies use package URLs, or purls, to identify packages across ecosystems:

Python: pkg:pypi/<name>
- Example: pkg:pypi/requests
JavaScript: pkg:npm/<name> or pkg:npm/%40<scope>/<name> for scoped packages
- Example: pkg:npm/lodash or pkg:npm/%40angular/core
Java: pkg:maven/<group>/<artifact>
- Example: pkg:maven/com.fasterxml.jackson.core/jackson-databind

Omit the version to match all versions of the package.

Append @<version> to target one version. For example:

pkg:pypi/requests@2.31.0
pkg:npm/lodash@4.17.20, pkg:npm/%40angular/core@17.0.0
pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.15.0

Preview a policy

To understand the impact before enforcing a policy, use --mode=PREVIEW with the chainctl libraries policy enable command. In preview mode, installs continue to succeed, but Chainguard records what would have been blocked over the last 30 days if the policy had been enforced.

In the following example, a policy called 3day-cooldown has already been created. To preview what would have been blocked if that policy had been enforced, run this command:

chainctl libraries policy enable --policy=3day-cooldown --ecosystem=JAVASCRIPT --mode=PREVIEW

This returns a list of successful installs that would have been blocked by this policy over the last 30 days.

Enable a policy

After creating a policy, use --mode=ENFORCE to enable it for the ecosystem where you want to apply it. For example:

chainctl libraries policy create --name=disable-cooldown --cooldown-days=0
chainctl libraries policy enable --policy=disable-cooldown --ecosystem=JAVASCRIPT --mode=ENFORCE

Create and enable a cooldown policy

When upstream fallback is enabled, users with the Owner role can create and enable a cooldown policy with chainctl. The cooldown period provides an additional layer of defense on top of malware and greyware scanning, giving the broader security community time to surface threats that may not be immediately detectable.

In the following example, a 10-day cooldown policy is created, then it is enforced on the JavaScript ecosystem:

chainctl libraries policy create --name=js-cooldown --cooldown-days=10
chainctl libraries policy enable --policy=js-cooldown --ecosystem=JAVASCRIPT --mode=ENFORCE

The default cooldown period is 7 days.

Preview a cooldown policy

To understand the impact before enforcing a policy, use --mode=PREVIEW. In preview mode, installs continue to succeed, but Chainguard records what would have been blocked if the policy were enforced.

Disable cooldown

To disable the cooldown, set it to 0. In the example below, the policy is created, then it is enforced on the Java ecosystem:

chainctl libraries policy create --name=no-cooldown --cooldown-days=0
chainctl libraries policy enable --policy=no-cooldown --ecosystem=JAVA --mode=ENFORCE

Block a package or version

Create a custom policy with one or more --block entries to deny packages explicitly. Block rules are helpful if your organization has deliberately decided not to allow certain packages. To understand the impact before enforcing a block, use --mode=PREVIEW.

For example, if your organization standardizes on React and wants to prevent teams from pulling in Angular, you can add a --block entry for each Angular package you want to deny. In the following example, a policy called team-policy has previously been created, and this command is run to update the policy to add blocks of specific Angular packages:

chainctl libraries policy update --name=team-policy \
  --block=purl=pkg:npm/%40angular/core \
  --block=purl=pkg:npm/%40angular/common \
  --block=purl=pkg:npm/%40angular/router
chainctl libraries policy enable --name=team-policy --ecosystem=JAVASCRIPT --mode=ENFORCE

To block one specific version, include the version in the purl. For example, if a particular release is flagged with a known vulnerability that you want to block within your organization, you can block just the affected version while allowing the other versions. Use a command like the following:

chainctl libraries policy update --name=team-policy \
  --block=purl=pkg:npm/ua-parser-js@0.7.29
chainctl libraries policy enable --name=team-policy --ecosystem=JAVASCRIPT --mode=ENFORCE

To block all versions of a package, omit the version. For example, the following command updates the existing team-policy to add a block of all versions of a package:

chainctl libraries policy update team-policy \
  --block=purl=pkg:pypi/<name>
chainctl libraries policy enable --name=team-policy --ecosystem=PYTHON --mode=ENFORCE

You can also combine block rules with a custom cooldown in the same policy. The following example creates a policy that blocks colourama, a typosquat of the colorama package. In addition, a cooldown is included:

chainctl libraries policy create --name=team-policy \
  --cooldown-days=2 \
  --block=purl=pkg:pypi/colourama
chainctl libraries policy enable --name=team-policy --ecosystem=PYTHON --mode=ENFORCE

Check blocked packages

Use chainctl libraries packages blocked to review what a policy has blocked. By default, this shows pull events that were blocked under any enforced policies. For example:

chainctl libraries packages blocked --ecosystem=JAVASCRIPT

If you have policies enabled in Preview mode, you can check successful pulls that would have been blocked in the last 30 days if the policy were to be enforced. For example:

chainctl libraries policy enable --policy=example-policy --ecosystem=JAVASCRIPT --mode=PREVIEW
chainctl libraries packages blocked --mode=PREVIEW --ecosystem=JAVASCRIPT

Replace example-policy with the name of the policy you want to preview.

Override a blocked package

Use --allow to permit a package that has been blocked by a policy or by malware and greyware scanning.

Override policies takes precedence over block policies.

Override cooldown for a package version

A cooldown override is useful when a newly published version includes an urgent fix and you need it before the cooldown window expires. For example:

chainctl libraries policy update team-policy \
    --allow='purl=pkg:npm/undici@8.4.1,override-cooldown=true,justification="urgent patch"'

If the new version pulls in transitive dependencies that are also blocked under a cooldown policy, those transitive packages must be overridden too.

Override malware or greyware blocking

A malware override should be used sparingly and only after your security team has explicitly reviewed the package. A justification is required when you set override-malware=true.

chainctl libraries policy update team-policy \
  --allow='purl=pkg:npm/node-ipc@10.1.3,override-malware=true,justification="approved in SEC-1234"'

List policies and verify bindings

To list available policies, run the following:

chainctl libraries policy list

To verify which policy is active and its cooldown settings, run the following:

chainctl libraries policy binding list

Prior to chainctl version 0.2.291, cooldown policies were enabled via the chainctl entitlements command. Cooldown policies configured prior to this version of chainctl are migrated under the new chainctl libraries policies system.

Last updated: 2025-07-23 15:09