Built-in Roles and Capabilities Reference

Chainguard provides customers with a set of built-in roles as part of its Identity and Access Management (IAM) system. These roles have different permissions and capabilities that allow them to serve specialized purposes, from general administrative access to access for specific resources like registries, APK packages, and programming language libraries.

This reference provides an overview of all Chainguard IAM capabilities and shows which built-in roles include each capability. Each capability represents a specific permission or action that can be performed within the Chainguard platform.

For more information on roles and role-bindings within Chainguard’s IAM model, please refer to our Overview of Roles and Role-bindings.

Built-in Roles Summary

This guide outlines the built-in Chainguard IAM roles available to most customer organizations. You can find more info about specific roles in your organization with the following chainctl command:

chainctl iam roles list

Every role has at least one of four capabilities (create, list, update, delete) in relation to at least one Chainguard resource. For example, the owner role can create, delete, list, and update custom roles within Chainguard, while the viewer role can only list them.

This guide outlines the following twelve built-in roles provided by Chainguard:

• Administrative Roles:
  • owner - Full administrative access with all capabilities
  • editor - Limited administrative access with mostly read permissions and event management
  • viewer - Read-only access across all resources
• Registry and Container Roles:
  • registry.pull - Container image access
  • registry.pull_token_creator - Chainguard registry token management with additional repository capabilities
  • apk.pull - Access to the organization’s APK packages, including the private APK repository
• Library Roles:
  • libraries.java.pull - Java library access
  • libraries.java.pull_token_creator - Java token management
  • libraries.python.pull - Python library access
  • libraries.python.pull_token_creator - Python library token management
  • libraries.javascript.pull - JavaScript library access
  • libraries.javascript.pull_token_creator - JavaScript library token management

The administrative roles are useful for user profiles that require broad, but clearly defined capabilities. The registry, container, and library roles have limited permissions, allowing them to manage only one specific Chainguard resource. These specialized, resource-specific roles grant minimal required access.

For example, the apk.pull role only grants list access for APK packages and groups. This means identities with this role can pull the organization’s APK packages and retrieve information about the organization, but won’t have general access to the organization’s Chainguard registry access.

Chainguard Role Capabilities

The following table maps Chainguard resources to the built-in roles that have permissions for them. Each row represents a specific resource type (like apk, repo, identity, etc.), describes its purpose, and lists which built-in roles have what capabilities (create, delete, list, update) for that resource.

Role Capabilities Comparison

The following table compares the general abilities of the twelve built-in roles described in the previous summary:

Notes

• Pull Images/List Tags/Repos/View SBOMs: These capabilities refer to container registry operations relating to the manifest, repo, tag, and sboms resources
• APK Pull: The apk.pull role is specialized for APK package management, not container operations

Pull token creator roles

The following roles are used for managing pull tokens for certain resources:

• registry.pull_token_creator
• libraries.java.pull_token_creator
• libraries.python.pull_token_creator
• libraries.javascript.pull_token_creator

For example, the libraries.*.pull_token_creator roles are focused on their respective library ecosystems and don’t have container registry access.

These roles are able to create pull tokens because of the identity.create capability. However, none of these roles have the identity.list capability, meaning that they aren’t able to view the pull tokens they’ve created.

The reason for this is that Chainguard doesn’t distinguish pull token identities from other assumable identities at the IAM level. If these roles also had the identity.list capability, they would be able to view all the identities in that scope. By not including identity.list among their capabilities, the pull token creator roles have a more limited, as intended.

Learn More

• Overview of Roles and Role-bindings in Chainguard - Conceptual overview and basic management
• Overview of Chainguard IAM Model - Complete IAM architecture