Skip to main content

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 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 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"
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 string

    Cloud account ID.

  • awsExecutionEnv string

    AWS execution environment (e.g. EC2/Fargate).

  • image string

    Image name.

  • 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

    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

    Instance name.

  • provider common.CloudProvider

    Possible values: [aws,azure,gcp,alibaba,oci,others]

    CloudProvider specifies the cloud provider name

  • region string

    Instance 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 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[]

    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.

  • 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 is external. Available values are: true: external false: Not external.

  • 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[]

    Specifies a list of specific endpoints for use in STS sessions in various regions.

  • tokens object
  • 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

    Possible values: [aws,azure,gcp,ibmCloud,oci,apiToken,githubToken,githubEnterpriseToken,basic,dtr,kubeconfig,certificate]

    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[]

    Repositories to exclude from scanning.

  • excludedTags string[]

    Tags to exclude from scanning.

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

  • jfrogRepoTypes shared.JFrogRepoType[]

    Possible values: [local,remote,virtual]

    JFrog Artifactory repository types to scan.

  • namespace string

    IBM Bluemix namespace https://console.bluemix.net/docs/services/Registry/registry_overview.html#registry_planning.

  • os shared.RegistryOSType

    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.

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

  • tag object

    ImageTag represents an image repository and its associated tag or registry digest

  • digest string

    Image digest (requires V2 or later registry).

  • id string

    ID of the image.

  • registry string

    Registry name to which the image belongs.

  • repo string

    Repository name to which the image belongs.

  • tag string

    Image tag.

  • type integer

    Type indicates the type of the scan request.

Responses

OK

Loading...