Resolve Untrusted Registry Images
JFrog Runtime decides whether to trust a running container image from the registry hostname in the image reference. It adds the hostname of your JFrog Platform base URL as a trusted registry. Images from any other hostname are marked Untrusted registry in Live Assessment, and their JFrog Xray results stay hidden.
This page explains that status and how you add a custom canonical name (CNAME) or an external registry with the Trusted Registries REST API. To find the affected images, use the Untrusted Registry quick filter. For more information, see Strengthening Runtime Trust Through Image Verification.
Note
Trusted registries are managed with the JFrog Runtime REST API. Managing them in the JFrog Platform UI is coming soon.
Prerequisite: You need an access token for your JFrog Platform. Add, update, and delete require Runtime Manager permissions. A platform admin or a Project Admin on the default project has these permissions. Any authenticated token can list trusted registries.
- Find the Registry Hostname
- Add a Trusted Registry
- Confirm the Image Is Trusted
- Update a Trusted Registry
- Delete a Trusted Registry
Registry Trust
For every running image, JFrog Runtime reads the registry hostname and looks it up in the trusted registries list. JFrog Runtime stores the Artifactory platform base URL host automatically, with trusted and supported set to true.
| Image reference | Registry hostname | Status |
|---|---|---|
mycompany.jfrog.io/docker-local/app:1.0 | mycompany.jfrog.io, your JFrog Platform base URL | Trusted. JFrog Runtime adds this hostname. |
docker.corp.example.com/app:1.0 | docker.corp.example.com, a custom CNAME | Untrusted until you add it, including when the name points at your JFrog Artifactory. |
cgr.dev/chainguard/nginx:latest | cgr.dev, an external or mirror registry | Untrusted until you add it. |
A custom CNAME is a domain name you own that points at JFrog Artifactory. That hostname, or a registry outside your JFrog Platform, needs its own trusted registry entry. Each hostname your clusters pull from has its own entry.
JFrog Artifactory can also serve a Docker repository on a subdomain of your JFrog Platform base URL, such as docker-local.company.jfrog.io/myapp:tag. This support is off until you opt in. The setting defaults to false. While it's off, a subdomain hostname stays untrusted until you add it as a trusted registry.
On a self-managed JFrog Platform, the setting is runtimeAudit.enableArtifactoryDockerSubdomain in the JFrog Runtime system.yaml file.
runtimeAudit:
enableArtifactoryDockerSubdomain: trueOn SaaS, your JFrog Customer Success representative turns this support on.
After you turn it on, and JFrog Artifactory uses the subdomain Docker access method, JFrog Runtime treats that subdomain as your JFrog Platform. You don't add a trusted registry entry for each repository subdomain. JFrog Runtime leaves stored image rows unchanged. To correct those rows, contact JFrog customer support.
For more information, see Integrity Violation Explainability.
Trusted and Supported Flags
Each trusted registry entry has two flags. trusted decides whether JFrog Runtime trusts images from the hostname. supported decides whether JFrog Runtime also checks the image digest against JFrog Artifactory. If you omit supported, JFrog Runtime stores false.
The flags have the following results.
trusted | supported | Result |
|---|---|---|
true | true | Trusted. JFrog Runtime compares the JFrog Artifactory manifest digest with the running image. Use this for an Artifactory hostname, such as a custom CNAME. |
true | false | Trusted. JFrog Runtime skips the digest check. Use this for an external or mirror registry that isn't a JFrog Artifactory Docker API, such as cgr.dev. |
false, or no entry | Any value | Untrusted registry. JFrog Xray results stay hidden. |
Trusted Registries APIs
Send every request to the JFrog Runtime service path, https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries. Include /runtime in the path.
The Trusted Registries REST API includes the following requests.
| API | Request | Purpose |
|---|---|---|
| List Trusted Registries | GET /runtime/api/v1/trusted_registries | Returns every entry, including the platform hostname JFrog Runtime adds. |
| Get a Trusted Registry | GET /runtime/api/v1/trusted_registries/{registryUrl} | Returns one entry. |
| Add a Trusted Registry | PUT /runtime/api/v1/trusted_registries | Adds an entry. |
| Update a Trusted Registry | POST /runtime/api/v1/trusted_registries/{registryUrl} | Changes the name, trusted, and supported values. |
| Delete a Trusted Registry | DELETE /runtime/api/v1/trusted_registries/{registryUrl} | Removes an entry. |
Find the Registry Hostname
Live Assessment shows the registry name that JFrog Runtime will match. JFrog Runtime stores registryUrl as you send it. Add, update, and delete requests match that stored value exactly, including case, so CGR.dev and cgr.dev are different entries. The trust check lowercases the hostname and removes a trailing dot. If those folded names match more than one entry, and any entry has trusted set to false, the image stays untrusted.
To find the registry hostname:
- Go to Runtime > Live Assessment. The Images table is displayed.
- Select the Untrusted Registry checkbox in Filters. The table lists images from untrusted registries.
- Copy the registry name shown for the affected image. Use that hostname, in lowercase, as
registryUrl.
The following values show the form to send.
| Value | Result |
|---|---|
docker.corp.example.com | Send this hostname. |
https://docker.corp.example.com | Remove the protocol. |
docker.corp.example.com/docker-local | Remove the path. |
Docker.Corp.Example.com | Use lowercase. |
docker.corp.example.com. | Remove the trailing dot. |
Add a Trusted Registry
Add the hostname from Live Assessment with Add a Trusted Registry. A successful request returns 200 and the message Created trusted registry: <registry-hostname>.
To add a trusted registry:
- Send the add request for the kind of registry.
-
For an Artifactory hostname, such as a custom CNAME, set
supportedtotrue.curl -X PUT "https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "<display-name>", "registryUrl": "<registry-hostname>", "trusted": true, "supported": true }'Where:
<JFrogPlatformURL>is the hostname of your JFrog Platform. For example,mycompany.jfrog.io.<Token>is an access token for a Runtime Manager.<display-name>is the display name for the registry.<registry-hostname>is the hostname from Live Assessment.
curl -X PUT "https://mycompany.jfrog.io/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "example-registry", "registryUrl": "docker.corp.example.com", "trusted": true, "supported": true }' -
For an external or mirror registry, set
supportedtofalse.curl -X PUT "https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "<display-name>", "registryUrl": "<registry-hostname>", "trusted": true, "supported": false }'Where:
<JFrogPlatformURL>is the hostname of your JFrog Platform. For example,mycompany.jfrog.io.<Token>is an access token for a Runtime Manager.<display-name>is the display name for the registry.<registry-hostname>is the hostname from Live Assessment.
curl -X PUT "https://mycompany.jfrog.io/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "chainguard", "registryUrl": "cgr.dev", "trusted": true, "supported": false }'
-
The request body uses the following fields.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | A display name for the registry. |
registryUrl | string | Yes | The registry hostname only. For more information, see Find the Registry Hostname. |
trusted | boolean | Yes | Set to true to trust images from this hostname. |
supported | boolean | No | Set to true for an Artifactory hostname. Set to false for an external or mirror registry. Defaults to false. |
Confirm the Image Is Trusted
The running workload can stay in place. JFrog Runtime applies the new trust decision the next time the cluster reports that image. It rechecks an image that is already running at most every 5 minutes by default. The JF_IMAGE_INTEGRITY_CACHE_IN_MIN environment variable sets that interval, in minutes. If JFrog Xray has already scanned the image, Live Assessment shows that vulnerability data after the trust check passes.
To confirm the image is trusted:
-
List the trusted registries and confirm that the new entry is present.
curl "https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>"Where:
<JFrogPlatformURL>is the hostname of your JFrog Platform. For example,mycompany.jfrog.io.<Token>is an access token. Any authenticated token can list trusted registries.
curl "https://mycompany.jfrog.io/runtime/api/v1/trusted_registries" \ -H "Authorization: Bearer <Token>" -
Go to Runtime > Live Assessment and find the image. After the cluster reports the image again, Live Assessment clears the Untrusted registry status.
Update a Trusted Registry
You can change the display name and the trusted and supported flags of an existing entry with Update a Trusted Registry. The hostname in the path is the stored value, and this request doesn't change it. To use a different hostname, delete the entry and add the new hostname. Send name, trusted, and supported. Omitting one returns 500. A hostname that isn't registered returns 404 and the message Could not update trusted registry.
To update a trusted registry:
-
Send the stored hostname with
name,trusted, andsupported.curl -X POST "https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries/<registry-hostname>" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "<display-name>", "trusted": true, "supported": false }'Where:
<JFrogPlatformURL>is the hostname of your JFrog Platform. For example,mycompany.jfrog.io.<Token>is an access token for a Runtime Manager.<registry-hostname>is the hostname exactly as stored.<display-name>is the display name for the registry.
curl -X POST "https://mycompany.jfrog.io/runtime/api/v1/trusted_registries/cgr.dev" \ -H "Authorization: Bearer <Token>" \ -H "Content-Type: application/json" \ -d '{ "name": "chainguard", "trusted": true, "supported": false }'
A successful request returns 200 and the message Updated trusted registry.
Delete a Trusted Registry
Remove an entry with Delete a Trusted Registry. The delete request returns 200 and a message that includes the hostname, including when no entry matched. After you delete an entry, JFrog Runtime marks images from that hostname Untrusted registry the next time it rechecks them.
To delete a trusted registry:
-
Send the stored hostname.
curl -X DELETE "https://<JFrogPlatformURL>/runtime/api/v1/trusted_registries/<registry-hostname>" \ -H "Authorization: Bearer <Token>"Where:
<JFrogPlatformURL>is the hostname of your JFrog Platform. For example,mycompany.jfrog.io.<Token>is an access token for a Runtime Manager.<registry-hostname>is the hostname exactly as stored.
curl -X DELETE "https://mycompany.jfrog.io/runtime/api/v1/trusted_registries/cgr.dev" \ -H "Authorization: Bearer <Token>"
Trusted Registry API Responses
The add request can return the following responses.
| Response | Cause | What to do |
|---|---|---|
400 Could not parse request body | The request body is missing or isn't valid JSON. | Check the JSON syntax. |
401 Unauthorized; authentication is required | The request has no token, or the caller is anonymous. | Send a valid access token. |
403 Forbidden; resource manager is required | The token doesn't have Runtime Manager permissions. | Ask a platform admin or a Project Admin on the default project to send the request. |
404 Could not create trusted registry | The hostname is already registered, or the entry could not be created. | List the trusted registries. To change the flags, update the existing entry. |
Updated 3 days ago
