OCI Registry
Connect any registry that speaks the Open Container Initiative (OCI) distribution API to Safeguard. The access a username and token need, which credentials work, and step-by-step setup.
What it does
The OCI Registry card connects Safeguard to any container registry that implements the Open Container Initiative (OCI) distribution API (the /v2/ API Docker and most registries use). Safeguard lists repositories and tags, and each image you select becomes a project that Safeguard scans for an SBOM and vulnerability findings. Find the card under Integrations on the Project/Product tab.
Registries with a card of their own (Amazon ECR, Docker Hub, Azure Container Registry, Oracle Container Registry) work better through that card.
Public vs private
| Public | Private | |
|---|---|---|
| What you enter | An image or repository URL on the registry | Registry URL, Username and Access Token (or password) |
| Credential needed | None | A registry account or robot/service account with pull access |
| What you can select | The public repositories you add by URL | The repositories the registry's catalog lists for that account, or the ones you add by URL |
Private image scans
Safeguard uses the credential to list repositories and tags. The scan's image pull does not use this credential yet, so a private image the scanner cannot pull is reported as a failed scan with the registry's error.
Supported auth methods
| Method | Use it when | Notes |
|---|---|---|
| Username and token (or password), Bearer token flow | The registry answers /v2/ with 401 and WWW-Authenticate: Bearer realm=... | Safeguard asks the registry's token service for a short-lived token per operation |
| Username and token (or password), Basic flow | The registry answers /v2/ with 401 and WWW-Authenticate: Basic | The credential is sent as HTTP Basic auth |
| None | Public images | Anonymous pull, where the registry allows it |
Safeguard probes /v2/ first and follows whichever challenge the registry returns.
Permissions required
Safeguard only reads. It never pushes, deletes or retags images.
Username and token
| Registry access | Required? | What Safeguard uses it for |
|---|---|---|
Sign in to the registry (GET /v2/ succeeds after the challenge) | Required | Checking the credential when you click Verify Credentials |
Pull (token scope repository:<name>:pull) on each repository to scan | Required | Listing tags (GET /v2/<name>/tags/list) and reading manifests |
Catalog listing (token scope registry:catalog:*, GET /v2/_catalog) | Optional | Listing every repository the account can see. The catalog is not part of the OCI specification and many registries do not offer it; without it, add repositories by URL |
Least privilege: a robot or service account with read (pull) access to only the repositories you want scanned, and catalog access only if you want Safeguard to list them for you.
Token types
| Credential type | Works? | Notes |
|---|---|---|
| Robot, service or bot account with read/pull access | Yes (recommended) | For example a Harbor robot account or a Quay robot account |
| Personal access token with read-only registry access | Yes | For example a GitHub Container Registry PAT with read:packages |
| Account password | Works, not recommended | Prefer a token you can revoke on its own |
| Admin or read-write token | Works, not recommended | Safeguard never writes |
A token for a different service (for example a GitHub ghp_... token on a non-GitHub registry) | No | Safeguard detects a pasted GitHub token and says so |
| Mutual TLS or client certificates | No | Not available |
Expiry: use a token with an expiry your registry allows (90 days is a good default) and rotate it before it lapses.
What we never need: push, delete, admin or garbage-collection rights, or project or user management.
Step-by-step setup
Create the credential in your registry
Every registry names this differently. In general:
- In your registry's web console, open the project, organization or namespace that holds the images.
- Create a robot, service or bot account (or a personal access token) with pull or read permission on the repositories to scan.
- Copy the username and the token. Many registries show the token only once.
Or with the CLI
Check the credential from any machine before you paste it into Safeguard:
echo "<token>" | docker login <registry-host> --username "<username>" --password-stdin
docker pull <registry-host>/<repository>:<tag>
docker logout <registry-host>Connect it in Safeguard
- Open Integrations and choose the Project/Product tab.
- Click Connect on the OCI Registry card.
- For public images, choose Public, enter a Name, paste the image URL, click Add, then Next.
- For private images, choose Private and enter Name, Registry URL (for example
https://registry.example.com), Username and Access Token. - Click Verify Credentials. "OCI credentials verified successfully!" means the registry accepted the credential.
- Click Next, select repositories and tags, review, and choose a connect option (fast, progressive or deep scan).
Webhooks and triggers
This integration has no webhooks. Each selected image is scanned when you connect it; to rescan new tags, set a schedule under Integrations > Scheduled or rescan by hand from the project.
What we read and store
- Read: the registry's catalog (when offered), tag lists and manifests of the repositories you select, and the images you select for scanning.
- Stored: the connection's settings, the SBOM and findings of each scanned image, and the username and token, which are encrypted at rest and never shown again after you save them.
- Not stored: image layers. The image is read for the scan and not kept.
- No customer data from this integration is sent to third-party LLMs.
Troubleshooting
| Message you see | Cause | Fix |
|---|---|---|
Please enter both username and access token to verify | A field is empty | Enter the username and token |
Registry '<host>' rejected the credentials for user '<name>'. Verify the username and password/token are correct and that the user has read access to the registry. ... | Wrong credential, or the account has no read access | Check the robot or service account's permissions and re-copy the token |
Registry URL is required for OCI registry | The Registry URL is empty | Enter the registry's base URL, without a repository path |
Invalid OCI registry URL format | The URL is not a registry address | Use https://<host> or https://<host>/<repository> |
Repository requires authentication | A private repository was added on the Public tab | Use the Private tab |
Registry returned 401 with no Www-Authenticate header ... | The registry does not follow the distribution API's auth challenge | Check that the URL is the registry endpoint, not its web console |
Failed to fetch repositories: ... | The registry has no catalog, or the account cannot list it | Add repositories by URL instead |
Rotation and disconnect
- Rotate: create a new token, find the connection under Project Configurations on the Project/Product tab, choose Update from its menu, paste the new token and save, then revoke the old token in your registry.
- Disconnect: choose Delete from the connection's menu under Project Configurations and confirm Delete configuration, then revoke the token or delete the robot account.
Vendor references
- OCI Distribution Specification, checked 2026-10-16.
- Distribution token scope documentation, checked 2026-10-16.
- GitHub: Working with the Container registry (
read:packages), checked 2026-10-16.
Docker Hub
Connect Docker Hub to Safeguard. The access permission the personal access token needs, which token types work, and step-by-step setup.
Azure Container Registry
Connect Azure Container Registry (ACR) to Safeguard. The roles and token permissions each credential needs, which credentials work, and step-by-step setup.