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.

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 referenceRegistry hostnameStatus
mycompany.jfrog.io/docker-local/app:1.0mycompany.jfrog.io, your JFrog Platform base URLTrusted. JFrog Runtime adds this hostname.
docker.corp.example.com/app:1.0docker.corp.example.com, a custom CNAMEUntrusted until you add it, including when the name points at your JFrog Artifactory.
cgr.dev/chainguard/nginx:latestcgr.dev, an external or mirror registryUntrusted 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: true

On 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.

trustedsupportedResult
truetrueTrusted. JFrog Runtime compares the JFrog Artifactory manifest digest with the running image. Use this for an Artifactory hostname, such as a custom CNAME.
truefalseTrusted. 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 entryAny valueUntrusted 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.

APIRequestPurpose
List Trusted RegistriesGET /runtime/api/v1/trusted_registriesReturns every entry, including the platform hostname JFrog Runtime adds.
Get a Trusted RegistryGET /runtime/api/v1/trusted_registries/{registryUrl}Returns one entry.
Add a Trusted RegistryPUT /runtime/api/v1/trusted_registriesAdds an entry.
Update a Trusted RegistryPOST /runtime/api/v1/trusted_registries/{registryUrl}Changes the name, trusted, and supported values.
Delete a Trusted RegistryDELETE /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:

  1. Go to Runtime > Live Assessment. The Images table is displayed.
  2. Select the Untrusted Registry checkbox in Filters. The table lists images from untrusted registries.
  3. Copy the registry name shown for the affected image. Use that hostname, in lowercase, as registryUrl.

The following values show the form to send.

ValueResult
docker.corp.example.comSend this hostname.
https://docker.corp.example.comRemove the protocol.
docker.corp.example.com/docker-localRemove the path.
Docker.Corp.Example.comUse 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 supported to true.

      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 supported to false.

      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.

FieldTypeRequiredDescription
namestringYesA display name for the registry.
registryUrlstringYesThe registry hostname only. For more information, see Find the Registry Hostname.
trustedbooleanYesSet to true to trust images from this hostname.
supportedbooleanNoSet 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:

  1. 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>"
  2. 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, and supported.

    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.

ResponseCauseWhat to do
400 Could not parse request bodyThe request body is missing or isn't valid JSON.Check the JSON syntax.
401 Unauthorized; authentication is requiredThe request has no token, or the caller is anonymous.Send a valid access token.
403 Forbidden; resource manager is requiredThe 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 registryThe hostname is already registered, or the entry could not be created.List the trusted registries. To change the flags, update the existing entry.

Did this page help you?