Update Registry Settings

PUT 
/api/v33.01/settings/registry

x-prisma-cloud-target-env: {"permission":"policyContainers"}

Updates the registries to scan. The list of registries to scan is updated in a single shot.

To invoke this endpoint in the Console UI:

1. Navigate to Defend > Vulnerabilities > Images > Registry settings.
2. Under the Registries table, add a registry item using + Add registry
3. Click the Save button.

Note: From 22.11 (Lagrange) release or later, you can add a maximum of 19,999 registry entries in Defend > Vulnerabilities > Images > Registry settings.

The API response returns an HTTP 400 error, if the number of registry specifications exceeds the maximum allowable limit of 19,999 registry entries.

General Set up and Scan Process

This endpoint works hand-in-hand with the /policies endpoints.

To set up a registry for scanning:

1. Add your registry account information using this endpoint.

   For example, specify the location and credentials of an ECR registry in your AWS account.

2. Prisma Cloud auto-discovers the images in the registries specified with this endpoint.

3. The list of auto-discovered images is passed to the scanner for evaluation.

   The scanner uses the corresponding /policies/vulnerability/images and /policies/compliance/images endpoints to assess each image.

cURL Request

Each registry to scan is specified as an item in the specifications array.

Note: Submitting a PUT request with the specifications array will first erase all the existing Registry entries, and then insert the new specifications array from the PUT request.

An empty body will also erase all the existing Registry entries. For more information, see Remove a Registry.

We recommend that you send a GET scan settings request via Get Registry Settings and save the JSON response before sending a PUT API request to update the Registry Settings.

The critical fields for this endpoint are:

• registry - String specifying the registry URL.
• credentialID - String specifying the registry credential.
• version - String specifying the type of registry to scan and may be one of the following strings:

Version	Description
aws	Amazon EC2 Container Registry
azure	Azure Container Registry
2	Docker Registry v2
dtr	Docker Trusted Registry
gcr	Google Container Registry
jfrog	JFrog Artifactory
sonatype	Sonatype Nexus
coreos	CoreOS Quay
redhat	Red Hat OpenShift
bluemix	IBM Cloud Container Registry

The remaining fields in the specifications object (e.g., repository, exclusions, etc.) are optional. They let you refine the scope of what Prisma Cloud auto-discovers.

Note: An empty string in registry implicitly refers to Docker Hub. In repository, use the library/ namespace to specify a Docker official image. To see the current list of Docker official images, see here.

Set up a Private Registry for Scanning

Most registries you'll configure for scanning will be private. Prisma Cloud needs credentials to access private registries. To set this up:

• Create the credentials with the /credentials endpoint.
• Retrieve the credential ID from the /credentials endpoint (_id).
• Create the registry setting with the recommended minimum required fields (version, registry, and credentialID).

Example cURL Request

The following cURL command overwrites the current list of registries to scan with two new registries:

• The official Ubuntu 18.04 image in Docker Hub
• All repositories in a private AWS ECR registry

$ curl 'https://<CONSOLE>/api/v<VERSION>/settings/registry' \
  -k \
  -X PUT \
  -u <USER> \
  -H 'Content-Type: application/json' \
  -d \
  '{
    "specifications": [
      {
        "version": "2",
        "registry": "",
        "repository": "library/ubuntu",
        "tag": "18.04",
        "os": "linux",
        "cap": 5,
        "credentialID": "<CREDENTIAL_ID1>",
        "scanners": 2,
        "collections": ["All"]
      },
      {
        "version": "aws",
        "registry": "<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com",
        "os": "linux",
        "credentialID": "<CREDENTIAL_ID2>",
        "scanners": 2,
        "cap": 5,
        "collections": ["All"]
      }
    ]
  }'

Note: No response will be returned upon successful execution.

Remove a Registry

To remove a registry from the list:

1. Retrieve the current list using the GET method.
2. Remove the entry from the specifications JSON array in the response.
3. Use the PUT method to submit the updated JSON object.

To delete all entries, submit an empty specifications array. For example:

curl -k \
  -u <USER> \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"specifications":[]}' \
  https://<CONSOLE>/api/v<VERSION>/settings/registry

Request

Query Parameters

scanLater boolean

ScanLater indicates to save the setting without starting a scan.

application/json

Body

harborScannerUrlSuffix string

Relative path to the Harbor scanner endpoint.

specifications object[]
Information for connecting to the registries to be scanned.
Array [
azureCloudMetadata object
CloudMetadata is the metadata for a cloud provider managed asset (e.g., as part of AWS/GCP/Azure/OCI)
accountID string
Cloud account ID.
awsExecutionEnv string
AWS execution environment (e.g. EC2/Fargate).
image string
The name of the image the cloud managed host or container is based on.
labels object[]
Cloud provider metadata labels.
Array [
key string
Label key.
sourceName string
Source name (e.g., for a namespace, the source name can be 'twistlock').
sourceType common.ExternalLabelSourceType (string)
Possible values: [namespace,deployment,aws,azure,gcp,oci]
ExternalLabelSourceType indicates the source of the labels
timestamp date-time
Time when the label was fetched.
value string
Value of the label.
]
name string
Resource name.
provider common.CloudProvider (string)
Possible values: [aws,azure,gcp,alibaba,oci,others]
CloudProvider specifies the cloud provider name
region string
Resource's region.
resourceID string
Unique ID of the resource.
resourceURL string
Server-defined URL for the resource.
type string
Instance type.
vmID string
Azure unique vm ID.
vmImageID string
VMImageID holds the VM instance's image ID.
caCert string
CACert is the Certificate Authority that signed the registry certificate.
cap integer
Specifies the maximum number of images from each repo to fetch and scan, sorted by most recently modified.
collections string (string)[]
Specifies the set of Defenders in-scope for working on a scan job.
credential object
Credential specifies the authentication data of an external provider
_id string
Specifies the unique ID for credential.
accountGUID string
Specifies the unique ID for an IBM Cloud account.
accountID string
Specifies the account identifier. Example: a username, access key, account GUID, and so on.
accountName string
Specifies the name of the cloud account.
apiToken object
Secret Stores the plain and encrypted version of a value. The plain version is not stored in a database
encrypted string
Specifies an encrypted value of the secret.
plain string
Specifies the plain text value of the secret.
azureSPInfo object
AzureSPInfo contains the Azure credentials needed for certificate based authentications
clientId string
ClientID is the client identifier.
miType cred.AzureMIType (string)
Possible values: [user-assigned,system-assigned]
subscriptionId string
SubscriptionID is a GUID that uniquely identifies the subscription to use Azure services.
tenantId string
TenantID is the ID of the AAD directory in which the application was created.
caCert string
Specifies the CA certificate for a certificate-based authentication.
cloudProviderAccountID string
Specifies the cloud provider account ID.
created date-time
Specifies the time when the credential was created (or, when the account ID was changed for AWS).
description string
Specifies the description for a credential.
external boolean
Indicates whether the credential was onboarded from the Prisma platform.
global boolean
Indicates whether the credential scope is global. Available values are: true: Global false: Not Global Note: For GCP, the credential scope is the organization.
lastModified date-time
Specifies the time when the credential was last modified.
ociCred object
OCICred are additional parameters required for OCI credentials
fingerprint string
Fingerprint is the public key signature.
tenancyId string
TenancyID is the OCID of the tenancy.
owner string
Specifies the user who created or modified the credential.
prismaLastModified int64
Specifies the time when the account was last modified by Prisma Cloud Compute.
roleArn string
Specifies the Amazon Resource Name (ARN) of the role to be assumed.
secret object
Secret Stores the plain and encrypted version of a value. The plain version is not stored in a database
encrypted string
Specifies an encrypted value of the secret.
plain string
Specifies the plain text value of the secret.
skipVerify boolean
Indicates whether to skip the certificate verification in TLS communication.
stsEndpoints string (string)[]
Specifies a list of specific endpoints for use in STS sessions in various regions.
tokens object
TemporaryToken is a temporary session token for cloud provider APIs AWS - https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html GCP - https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials Azure - https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-single-sign-on
awsAccessKeyId string
Specifies a temporary access key.
awsSecretAccessKey object
Secret Stores the plain and encrypted version of a value. The plain version is not stored in a database
encrypted string
Specifies an encrypted value of the secret.
plain string
Specifies the plain text value of the secret.
duration int64
Specifies a duration for the token.
expirationTime date-time
Specifies an expiration time for the token.
token object
Secret Stores the plain and encrypted version of a value. The plain version is not stored in a database
encrypted string
Specifies an encrypted value of the secret.
plain string
Specifies the plain text value of the secret.
type cred.Type (string)
Possible values: [aws,azure,gcp,ibmCloud,oci,apiToken,basic,dtr,kubeconfig,certificate,gitlabToken]
Type specifies the credential type
url string
Specifies the base server URL.
useAWSRole boolean
Indicates whether to authenticate using the IAM Role attached to the instance. Available values are: true: Authenticate with the attached credentials false: Don’t authenticate with the attached credentials.
useSTSRegionalEndpoint boolean
Indicates whether to use the regional STS endpoint for an STS session. Available values are: true: Use the regional STS false: Don’t use the regional STS.
credentialID string
ID of the credentials in the credentials store to use for authenticating with the registry.
excludedRepositories string (string)[]
Repositories to exclude from scanning.
excludedTags string (string)[]
Tags to exclude from scanning.
gitlabRegistrySpec object
GitlabRegistrySpec represents a specification for registry scanning in GitLab
apiDomainName string
.
excludedGroupIDs string (string)[]
.
groupIDs string (string)[]
.
projectIDs string (string)[]
.
userID string
.
harborDeploymentSecurity boolean
Indicates whether the Prisma Cloud plugin uses temporary tokens provided by Harbor to scan images in projects where Harbor's deployment security setting is enabled.
id string
ID is a unique identifier of the registry spec.
jfrogRepoTypes shared.JFrogRepoType (string)[]
Possible values: [local,remote,virtual]
JFrog Artifactory repository types to scan.
lastScanStatus string
LastScanStatus is the last scan status. we keep both LastScanStatus and ScanStatus in order to not lose the latest scan status when a scan starts.
lastScanTime date-time
LastScanTime specifies the last time a scan was completed.
namespace string
IBM Bluemix namespace https://console.bluemix.net/docs/services/Registry/registry_overview.html#registry_planning.
os shared.RegistryOSType (string)
Possible values: [linux,linuxARM64,windows]
RegistryOSType specifies the registry images base OS type
registry string
Registry address (e.g., https://gcr.io).
repository string
Repositories to scan.
scanError string
ScanError is the error received while scanning the specification.
scanStatus string
ScanStatus is the scan status that's updated dynamically during the scan, when the scan finishes - its value is passed to the LastScanStatus field in the DB.
scanTime date-time
ScanTime specifies the time a scan was started.
scannedImagesSuccessTotal integer
ScannedImagesSuccessTotal is the total number of registry images that were scanned successfully on the last registry specification scan.
scanners integer
Number of Defenders that can be utilized for each scan job.
tag string
Tags to scan.
version string
Registry type. Determines the protocol Prisma Cloud uses to communicate with the registry.
versionPattern string
Pattern heuristic for quickly filtering images by tags without having to query all images for modification dates.
]
webhookUrlSuffix string

Relative path to the webhook HTTP endpoint.

Responses

200

OK

default

Loading...