Built-in roles and capabilities reference

A resource documenting the capabilities and permissions of Chainguard's built-in IAM roles.

12 min read

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, and can run Guardener sessions
- limited_owner: Owner of a Starter organization, with viewer access plus pull tokens, 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, 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 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 actions each built-in role has on that resource.

Resource	Purpose	Roles with access to this resource
`account_associations`	Link cloud provider accounts to organization	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`actions`	View the Chainguard Actions catalog	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `actions.viewer` (list)
`advisories`	View security advisories for the packages in Chainguard images	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`apk`	Manage APK packages in the registry	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull_token_creator` (list) `apk.pull` (list) `apk.push` (create, delete, list)
`apk.blobs`	Download APK package binary content	`owner` (get) `editor` (get) `viewer` (get) `limited_owner` (get) `registry.pull_token_creator` (get) `apk.pull` (get) `apk.push` (get)
`billing`	Manage the organization’s billing and payment method	`owner` (manage) `limited_owner` (manage)
`build_report`	Access detailed build and scan reports for images and packages	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`group_invites`	Send and manage invitations to join Chainguard organization	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (create, delete, list) `console_viewer` (list)
`groups`	Manage organization and hierarchical structures	`owner` (create, delete, list, rename, update) `editor` (list) `viewer` (list) `limited_owner` (list, rename) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (create, list) `registry.editor` (list) `apk.pull` (list) `apk.push` (list) `libraries.java.pull_token_creator` (list) `libraries.python.pull_token_creator` (list) `libraries.javascript.pull_token_creator` (list) `guardener.user` (list) `guardener.admin` (list)
`guardener.actions`	Have Guardener migrate a repository’s GitHub Actions to Chainguard Actions by opening a pull request	`owner` (migrate) `editor` (migrate) `viewer` (migrate) `limited_owner` (migrate) `guardener.user` (migrate) `guardener.admin` (migrate)
`guardener.association`	View and manage the GitHub organizations connected through the Chainguard App	`owner` (list, manage) `editor` (list) `viewer` (list) `limited_owner` (list, manage) `guardener.user` (list) `guardener.admin` (list, manage)
`guardener.dfc`	Convert Dockerfiles to use Chainguard images with Guardener	`owner` (convert) `editor` (convert) `viewer` (convert) `limited_owner` (convert) `guardener.user` (convert) `guardener.admin` (convert)
`guardener.entitlement`	View the organization’s Guardener settings, such as which repositories Guardener can access	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`guardener.images`	Request and view container image migrations for a repository	`owner` (migrate) `editor` (migrate) `viewer` (migrate) `limited_owner` (migrate) `guardener.user` (migrate) `guardener.admin` (migrate)
`guardener.scan`	View the dependency scans Guardener runs on connected repositories	`owner` (get, list) `editor` (get, list) `viewer` (get, list) `limited_owner` (get, list) `console_viewer` (get, list) `guardener.user` (get, list) `guardener.admin` (get, list)
`identity`	Create and manage user identities, service accounts, and pull tokens	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (create, list) `console_viewer` (list) `registry.pull_token_creator` (create) `libraries.java.pull_token_creator` (create) `libraries.python.pull_token_creator` (create) `libraries.javascript.pull_token_creator` (create)
`identity_providers`	Configure custom identity providers (OIDC, SAML) for authentication	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`identity_providers.scim`	Turn on SCIM provisioning for a custom identity provider and manage its tokens	`owner` (manage)
`identity_providers.scim.users`	View the users a custom identity provider provisioned through SCIM	`owner` (list)
`libraries.artifacts`	View Chainguard Library artifact metadata and information	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.aws_marketplace.subscriptions`	Manage Chainguard Libraries subscriptions bought through AWS Marketplace	`owner` (create, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.cache`	View and clear the organization’s Chainguard Libraries resolution cache	`owner` (invalidate, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.entitlements`	Manage access permissions for Chainguard Libraries	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `libraries.java.pull` (list) `libraries.java.pull_token_creator` (list) `libraries.java.push` (list) `libraries.python.pull` (list) `libraries.python.pull_token_creator` (list) `libraries.python.push` (list) `libraries.javascript.pull` (list) `libraries.javascript.pull_token_creator` (list) `libraries.javascript.push` (list)
`libraries.java`	Access Chainguard Libraries for Java	`owner` (create, list) `libraries.java.pull` (list) `libraries.java.pull_token_creator` (list) `libraries.java.push` (create, list)
`libraries.javascript`	Access Chainguard Libraries for JavaScript	`owner` (create, list) `libraries.javascript.pull` (list) `libraries.javascript.pull_token_creator` (list) `libraries.javascript.push` (create, list)
`libraries.policy`	Create and manage the cooldown and malware policies applied to upstream library pulls	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.policy.binding`	Apply Chainguard Libraries policies to the organization	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.policy.block_event`	View the library pulls a policy blocked	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.python`	Access Chainguard Libraries for Python	`owner` (create, list) `libraries.python.pull` (list) `libraries.python.pull_token_creator` (list) `libraries.python.push` (create, list)
`libraries.remote_registries`	Configure the upstream registries the organization’s virtual repositories pull from	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.request_groups`	Request library versions for Chainguard to build, and track those requests	`owner` (create, delete, list, submit, update) `editor` (create, delete, list, update) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`libraries.request_groups.items`	Edit the individual libraries in a draft build request	`owner` (update) `editor` (update)
`libraries.storage_usage`	View how much storage the organization’s uploaded libraries use in each ecosystem	`owner` (get)
`manifest`	Access and manage container image manifests	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (create, delete, list, update) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`manifest.metadata`	View container image manifest metadata and attestations	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (list) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`mcp.tool`	Call tools on Chainguard MCP servers	`owner` (call) `mcp.tool_user` (call)
`packages.entitlements`	View which tier of Chainguard OS Packages the organization is entitled to, base or FIPS	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`policies.binding`	Turn image pull policies on for the organization	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`policies.decision`	View the allow and block decisions image pull policies made	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`policies.override`	Exempt a specific image from policy enforcement	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`policies.policy`	View and manage image pull policies, such as blocking end-of-life images	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`record_signatures`	View cryptographic signature verification records	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (list) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`referrers`	View the signatures, attestations, and other artifacts attached to an image	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (list) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`registry.deployments`	View the Helm charts associated with a container repository	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`registry.entitlements`	View registry access entitlements and permissions	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`registry.entitlements.images`	Add, remove, and swap the images in the organization’s registry entitlement	`owner` (add, remove, swap) `limited_owner` (add)
`registry.overlays`	View and edit Custom Assembly overlays	`owner` (edit, list) `editor` (edit, list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.editor` (edit, list)
`registry.settings`	View the organization’s registry settings, such as whether unique tags and the End-of-Life Grace Period are on by default	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`repo`	Create and manage container repositories (including Custom Assembly resources)	`owner` (check_policies, create, delete, list, update) `editor` (create, delete, list, update) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (create, delete, list, update) `registry.editor` (create, delete, list, update) `guardener.user` (list) `guardener.admin` (list)
`repo.blobs`	Download container image binary content	`owner` (get) `editor` (get) `viewer` (get) `limited_owner` (get) `registry.pull` (get) `registry.pull_token_creator` (get) `registry.push` (get) `registry.editor` (get) `guardener.user` (get) `guardener.admin` (get)
`role_bindings`	Assign roles to identities (users and service accounts)	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (create, delete, list) `console_viewer` (list) `registry.pull_token_creator` (create) `libraries.java.pull_token_creator` (create) `libraries.python.pull_token_creator` (create) `libraries.javascript.pull_token_creator` (create)
`roles`	Create, modify, and manage custom Chainguard IAM roles	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull_token_creator` (list) `libraries.java.pull_token_creator` (list) `libraries.python.pull_token_creator` (list) `libraries.javascript.pull_token_creator` (list)
`sandbox.identity`	Create the Chainguard identity a Workspaces session acts through, and define and use shared session identities	`owner` (admin, create, use) `sandbox.user` (create) `sandbox.identity.user` (use)
`sandbox.run`	Start, view, and cancel Chainguard Checks runs	`owner` (cancel, create, list) `limited_owner` (cancel, create) `sandbox.user` (cancel, create, list)
`sandbox.session`	Open Chainguard Workspaces sessions, and list every user’s sessions in the organization	`owner` (create, list) `limited_owner` (create) `sandbox.user` (create)
`sboms`	Access Software Bill of Materials for packages and images	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (list) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`skills`	View the Chainguard Agent Skills catalog and publish skills	`owner` (list, publish) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`skills.entitlements`	Manage which Chainguard Agent Skills the organization can access	`owner` (create, delete, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`skills.harden`	Submit, track, and cancel skill hardening jobs	`owner` (cancel, read, write)
`subscriptions`	Manage CloudEvent subscriptions for notifications and automation	`owner` (create, delete, list, update) `editor` (create, delete, list, update) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`tag`	Manage Chainguard container image tags	`owner` (create, delete, list, update) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (create, delete, list, update) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)
`telemetry.containers`	View the container images that connected repositories use, as Guardener observes them	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `guardener.user` (list) `guardener.admin` (list)
`terms`	View and accept the legal terms a Chainguard product requires before you can use it	`owner` (accept, list) `editor` (list) `viewer` (list) `limited_owner` (accept, list) `guardener.user` (list) `guardener.admin` (accept, list)
`version`	View version information across all resources and assets	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`vuln`	Create vulnerability reports and assessments	`owner` (create)
`vuln_report`	Manage detailed vulnerability assessments for specific resources	`owner` (create, list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list)
`vuln_reports`	View high-level vulnerability report summaries	`owner` (list) `editor` (list) `viewer` (list) `limited_owner` (list) `console_viewer` (list) `registry.pull` (list) `registry.pull_token_creator` (list) `registry.push` (list) `registry.editor` (list) `guardener.user` (list) `guardener.admin` (list)

Role capabilities comparison

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

Role	Pull Images	List Tags/Repos	View SBOMs/Diffs	Create IAM Resources	Create Pull Tokens	Libraries Access
`owner`	✅	✅	✅	✅	✅	✅
`editor`	✅	✅	✅	✕	✕	✕
`viewer`	✅	✅	✅	✕	✕	✕
`limited_owner`	✅	✅	✅	✅	✅	✕
`console_viewer`	✕	✅	✅	✕	✕	✕
`registry.pull`	✅	✅	✅	✕	✕	✕
`registry.pull_token_creator`	✅	✅	✅	✅	✅	✕
`registry.push`	✅	✅	✅	✕	✕	✕
`registry.editor`	✅	✅	✅	✕	✕	✕
`apk.pull`	✕	✕	✕	✕	✕	✕
`apk.push`	✕	✕	✕	✕	✕	✕
`libraries.java.pull`	✕	✕	✕	✕	✕	✅
`libraries.java.pull_token_creator`	✕	✕	✕	✅	✅	✅
`libraries.java.push`	✕	✕	✕	✕	✕	✅
`libraries.python.pull`	✕	✕	✕	✕	✕	✅
`libraries.python.pull_token_creator`	✕	✕	✕	✅	✅	✅
`libraries.python.push`	✕	✕	✕	✕	✕	✅
`libraries.javascript.pull`	✕	✕	✕	✕	✕	✅
`libraries.javascript.pull_token_creator`	✕	✕	✕	✅	✅	✅
`libraries.javascript.push`	✕	✕	✕	✕	✕	✅
`guardener.user`	✅	✅	✅	✕	✕	✕
`guardener.admin`	✅	✅	✅	✕	✕	✕
`sandbox.user`	✕	✕	✕	✕	✕	✕
`sandbox.identity.user`	✕	✕	✕	✕	✕	✕
`mcp.tool_user`	✕	✕	✕	✕	✕	✕
`actions.viewer`	✕	✕	✕	✕	✕	✕

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), 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.

Learn more

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

Last updated: 2026-10-13 13:55

Built-in roles and capabilities reference

Built-in roles summary

Chainguard role capabilities

Role capabilities comparison

Pull token creator roles

Learn more

Was this helpful?

Related Articles

chainctl

chainctl actions

chainctl actions catalog

chainctl actions catalog list

chainctl actions discover