Skip to main content

Start a Registry Scan

POST 
/api/v33.01/registry/scan
x-prisma-cloud-target-env: {"permission":"monitorImages"}

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

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