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 grants actions on at least one Chainguard resource. Most actions are create, list, update, or delete, and a few resources use others, such as get, accept, or call. 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 built-in roles provided by Chainguard:

• Administrative Roles:
  • owner: Full administrative access with all capabilities
  • editor: viewer access plus creating, updating, and deleting container repositories, editing Custom Assembly overlays, drafting library build requests, and managing event subscriptions
  • viewer: Read-only access across all resources, can pull images, can run Guardener sessions, and can call tools on Chainguard MCP servers
  • limited_owner: Owner of a Starter organization, with viewer access plus pull tokens, library access, adding catalog images and Helm charts to the organization, invites limited to the organization’s email domain, removing members, billing, and turning on Chainguard Checks and Chainguard Workspaces
  • console_viewer: Read-only access across all resources and cannot pull images or APK packages, run Guardener sessions, call tools on Chainguard MCP servers, or view legal terms
• Registry and Container Roles:
  • registry.pull: Container image access
  • registry.pull_token_creator: Chainguard registry token management with additional repository capabilities
  • registry.push: registry.pull access plus pushing images, and creating, updating, and deleting repositories and tags
  • registry.editor: registry.pull access plus creating, updating, and deleting repositories, and editing Custom Assembly overlays
  • apk.pull: Access to the organization’s APK packages, including the private APK repository
  • apk.push: apk.pull access plus uploading and deleting APK packages
• Library Roles:
  • libraries.java.pull: Java library access
  • libraries.java.pull_token_creator: Java token management
  • libraries.java.push: libraries.java.pull access plus Java library uploads
  • libraries.python.pull: Python library access
  • libraries.python.pull_token_creator: Python library token management
  • libraries.python.push: libraries.python.pull access plus Python library uploads
  • libraries.javascript.pull: JavaScript library access
  • libraries.javascript.pull_token_creator: JavaScript library token management
  • libraries.javascript.push: libraries.javascript.pull access plus JavaScript library uploads
• Guardener Roles:
  • guardener.user: Minimum role for running Guardener sessions, including Guardener conversion, terms lookup, and registry pull access
  • guardener.admin: Extends guardener.user with permission to accept the legal terms required before Guardener sessions can start
• Checks and Workspaces Roles:
  • sandbox.user: Start, view, and cancel Chainguard Checks runs, and open Chainguard Workspaces sessions
  • sandbox.identity.user: Use shared identities in Chainguard Workspaces sessions
• MCP Roles:
  • mcp.tool_user: Call tools on Chainguard MCP servers
• Actions Roles:
  • actions.viewer: View the Chainguard Actions catalog

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 grants list access for APK packages and groups, and get access to APK package content. 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 resources.

Chainguard role capabilities

The following table maps Chainguard capabilities to the built-in roles that hold them. Each row covers one resource, such as repo or identity. The first column lists the full name of every capability on that resource, and the last column lists the actions each built-in role holds on it.

A capability’s name is its resource and its action, joined by a dot. For example, registry.entitlements.images.add is the add action on the registry.entitlements.images resource. Use these full names when you create a custom role that grants only the capabilities a task needs, as in Create a role for managing image entitlements.

Role capabilities comparison

The following table compares the general abilities of the 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
• Console Viewer: Has the same broad list access as viewer, but can’t pull blobs (apk.blobs, repo.blobs), view legal terms (terms), run Guardener conversions or migrations (guardener.dfc, guardener.actions, guardener.images), call tools on Chainguard MCP servers (mcp.tool), or list the GitHub organizations connected through the Chainguard App (guardener.association). This makes it a safe role for inviting team members who need Console visibility without the ability to pull images or APKs.

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 scope, as intended.

Create a role for managing image entitlements

An organization’s registry entitlement lists the Chainguard Containers it can use. Of the built-in roles, only owner can add, remove, and swap the images in it, and limited_owner can add them. To let someone manage the entitlement without the rest of the owner role, create a custom role with only the capabilities the task needs.

Which capabilities you need depends on your organization’s plan:

• Per-image plans: The entitlement holds each image individually, and the registry.entitlements.images capabilities control which images it holds.
• Catalog Pricing: The entitlement already covers every image in your catalog, so you don’t change it. Adding an image to your organization creates a repository instead, which needs the repo capabilities described in Self-serve catalog experience.

On a per-image plan, the following command creates a role that can manage the entitlement with the chainctl images entitlements commands. Replace $ORGANIZATION with the name of your organization. Creating a custom role requires the owner role:

chainctl iam roles create entitlement-manager \
  --parent=$ORGANIZATION \
  --capabilities=groups.list,registry.entitlements.list,registry.entitlements.images.add,registry.entitlements.images.remove,registry.entitlements.images.swap

The role includes these capabilities:

• groups.list: Lets the commands find your organization when you pass --parent.
• registry.entitlements.list: Lets chainctl images entitlements list show the entitlement and the images it holds.
• registry.entitlements.images.add, registry.entitlements.images.remove, and registry.entitlements.images.swap: Let add-image, remove-image, and swap-image change the images. Each image that remove-image or swap-image takes out counts against your organization’s 30-day swap quota.

To let the role add images but not remove or swap them, leave out registry.entitlements.images.remove and registry.entitlements.images.swap.

To give the role to a user, create a role-binding, as described in Managing role-bindings.

Learn more

• Overview of roles and role-bindings in Chainguard - Conceptual overview and basic management
• Overview of Chainguard IAM model - Complete IAM architecture