Start a Registry Scan
x-prisma-cloud-target-env: {"permission":"monitorImages","saas":true,"self-hosted":true}
x-public: true
Triggers a new scan for all images when a new image is added to the registry or a new scan for an individual image.
You can use the scanning feature in the following ways:
Regular scan
This feature allows you to trigger a new scan immediately for all the images when a new image is added to the registry or trigger a scan for an individual image.
Consider the following points for a regular scan:
- You cannot make multiple parallel scan requests with a regular scan.
- You either need to stop the on-going scan using the
api/vVERSION/registry/stop
or wait for the on-going scan to finish. For information on stopping a regular scan, see Stop Registry Scan - You can view the scan result or response for all the images by using the
api/vVERSION/registry
API endpoint. For information on scan result, see Get Registry Scan Report
cURL Request
Refer to the following example cURL command that forces Prisma Cloud Compute to rescan all registry images:
$ curl -k \
-u <USER> \
-H 'Content-Type: application/json' \
-X POST \
https://<CONSOLE>/api/v<VERSION>/registry/scan
Refer to the following example cURL command that forces Prisma Cloud Compute to re-scan a specific image:
$ curl -k \
-u <USER> \
-H 'Content-Type: application/json' \
-X POST \
-d '{"tag":{"registry":"<REGISTRY>","repo":"<REPO>","tag":"<TAG>","digest":""}}'\
https://<CONSOLE>/api/v<VERSION>/registry/scan
On-demand scan
This feature allows you to trigger a new scan immediately for an individual image and not wait for the next periodic scan.
Note: For an on-demand scan, you must pre-define the image registry scope in the registry scanning configuration.
Consider the following points for an on-demand scan:
- You can trigger multiple on-demand image scans without interrupting the main registry scanning process.
- You cannot stop a running on-demand scan, you can only initiate a new parallel scan.
- You can view the on-demand scan result or response by using query parameter
name
that specifies the full image name in theapi/vVERSION/registry
API endpoint. For information on scan result, see Get Registry Scan Report
cURL Request
Refer to the following example cURL command to trigger an on-demand scan for an image:
$ curl -k \
-u <USER> \
-H 'Content-Type: application/json' \
-X POST \
-d '{“onDemandScan”:true,“tag”:{“registry” :“<REGISTRY>”,“repo”:“<REPO>”,“digest”:“”}}' \
"https://<CONSOLE>/api/v<VERSION>/registry/scan"
- application/json
Request Body
- onDemandScan boolean
OnDemandScan indicates whether to handle request using the on-demand scanner.
- scanID integer
ScanID is the ID of the scan.
settings object
RegistrySpecification contains information for connecting to local/remote registry
azureCloudMetadata object
CloudMetadata is the metadata for an instance running in a cloud provider (AWS/GCP/Azure)
accountID stringCloud account ID.
awsExecutionEnv stringAWS execution environment (e.g. EC2/Fargate).
image stringImage name.
labels object[]
Cloud provider metadata labels.
Array [key stringLabel key.
sourceName stringSource name (e.g., for a namespace, the source name can be 'twistlock').
sourceType common.ExternalLabelSourceTypePossible values: [
namespace,deployment,aws,azure,gcp,oci
]ExternalLabelSourceType indicates the source of the labels
timestamp date-timeTime when the label was fetched.
value stringValue of the label.
]name stringInstance name.
provider common.CloudProviderPossible values: [
aws,azure,gcp,alibaba,oci,others
]CloudProvider specifies the cloud provider name
region stringInstance region.
resourceID stringUnique ID of the resource.
resourceURL stringServer-defined URL for the resource.
type stringInstance type.
vmID stringAzure unique vm ID.
vmImageID stringVMImageID holds the VM image ID.
caCert stringCACert is the Certificate Authority that signed the registry certificate.
cap integerSpecifies the maximum number of images from each repo to fetch and scan, sorted by most recently modified.
collections 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 stringSpecifies the unique ID for credential.
accountGUID stringSpecifies the unique ID for an IBM Cloud account.
accountID stringSpecifies the account identifier. Example: a username, access key, account GUID, and so on.
accountName stringSpecifies 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 stringSpecifies an encrypted value of the secret.
plain stringSpecifies the plain text value of the secret.
azureSPInfo object
AzureSPInfo contains the Azure credentials needed for certificate based authentications
clientId stringClientID is the client identifier.
subscriptionId stringSubscriptionID is a GUID that uniquely identifies the subscription to use Azure services.
tenantId stringTenantID is the ID of the AAD directory in which the application was created.
caCert stringSpecifies the CA certificate for a certificate-based authentication.
cloudProviderAccountID stringSpecifies the cloud provider account ID.
created date-timeSpecifies the time when the credential was created (or, when the account ID was changed for AWS).
description stringSpecifies the description for a credential.
external booleanIndicates whether the credential is external. Available values are: true: external false: Not external.
global booleanIndicates 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-timeSpecifies the time when the credential was last modified.
ociCred object
OCICred are additional parameters required for OCI credentials
fingerprint stringFingerprint is the public key signature.
tenancyId stringTenancyID is the OCID of the tenancy.
owner stringSpecifies the user who created or modified the credential.
prismaLastModified int64Specifies the time when the account was last modified by Prisma Cloud Compute.
roleArn stringSpecifies 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 stringSpecifies an encrypted value of the secret.
plain stringSpecifies the plain text value of the secret.
skipVerify booleanIndicates whether to skip the certificate verification in TLS communication.
stsEndpoints 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 stringSpecifies 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 stringSpecifies an encrypted value of the secret.
plain stringSpecifies the plain text value of the secret.
duration int64Specifies a duration for the token.
expirationTime date-timeSpecifies 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 stringSpecifies an encrypted value of the secret.
plain stringSpecifies the plain text value of the secret.
type cred.TypePossible values: [
aws,azure,gcp,ibmCloud,oci,apiToken,githubToken,githubEnterpriseToken,basic,dtr,kubeconfig,certificate
]Type specifies the credential type
url stringSpecifies the base server URL.
useAWSRole booleanIndicates 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 booleanIndicates 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 stringID of the credentials in the credentials store to use for authenticating with the registry.
excludedRepositories string[]Repositories to exclude from scanning.
excludedTags string[]Tags to exclude from scanning.
harborDeploymentSecurity booleanIndicates whether the Prisma Cloud plugin uses temporary tokens provided by Harbor to scan images in projects where Harbor's deployment security setting is enabled.
jfrogRepoTypes shared.JFrogRepoType[]Possible values: [
local,remote,virtual
]JFrog Artifactory repository types to scan.
namespace stringIBM Bluemix namespace https://console.bluemix.net/docs/services/Registry/registry_overview.html#registry_planning.
os shared.RegistryOSTypePossible values: [
linux,linuxARM64,windows
]RegistryOSType specifies the registry images base OS type
registry stringRegistry address (e.g., https://gcr.io).
repository stringRepositories to scan.
scanners integerNumber of Defenders that can be utilized for each scan job.
tag stringTags to scan.
version stringRegistry type. Determines the protocol Prisma Cloud uses to communicate with the registry.
versionPattern stringPattern heuristic for quickly filtering images by tags without having to query all images for modification dates.
tag object
ImageTag represents an image repository and its associated tag or registry digest
digest stringImage digest (requires V2 or later registry).
id stringID of the image.
registry stringRegistry name to which the image belongs.
repo stringRepository name to which the image belongs.
tag stringImage tag.
- type integer
Type indicates the type of the scan request.
- 200
- default
OK