20.12 porting guide
1. Overview
This article outlines the differences in the API between 20.12 and 20.09. It’s intended to help you port your code forward to the latest version of Prisma Cloud Compute.
2. Breaking changes
If you’re using any of the following endpoints, you’ll need to update your integrations when migrating to 20.12.
2.1. Credentials for settings, policies, and alerts
In 20.12, we’ve streamlined how AWS credentials are created and used throughout the product. Previously, configuring how credentials were obtained (IAM role, STS) were specified directly in the subsystem integration dialogs. Now, it’s all managed centrally from the credentials store.
As a result, the useAWSRole
and roleArn
fields are no longer supported when creating scan, alert, and secret store configurations in the following endpoints:
-
api/v1/alert-profiles
-
api/v1/policies/cloud-platforms
-
api/v1/settings/registry
-
api/v1/settings/serverless-scan
-
api/v1/settings/secrets
-
api/v1/settings/host-auto-deploy
-
api/v1/settings/serverless-auto-deploy
-
api/v1/settings/vm
Instead, specify these fields when creating credentials in the credentials store endpoint:
-
api/v1/credentials
2.2. Policy rule scope
In 20.09, the scope of a rule (or the range of target resource to which a rule applies) were specified inline in the policy endpoints. In 20.12, the scope of a rule is now defined by referencing the relevant collections. We’ve centralized scope settings under collections to make it easier to re-use scope settings across the product, and to give users a better visibility into what resources rules target.
As part of this change, the rules.resources
object has been deprecated and replaced with the rules.collections
object in the following endpoints:
-
/api/v1/policies/runtime/app-embedded
-
/api/v1/policies/runtime/container
-
/api/v1/policies/runtime/host
-
/api/v1/policies/runtime/serverless
-
/api/v1/policies/firewall/app/container
-
/api/v1/policies/firewall/app/host
-
/api/v1/policies/firewall/app/app-embedded
-
/api/v1/policies/firewall/app/serverless
-
/api/v1/policies/firewall/network
-
/api/v1/policies/secrets
-
/api/v1/policies/vulnerability/images
-
/api/v1/policies/vulnerability/ci/images
-
/api/v1/policies/vulnerability/host
-
/api/v1/policies/vulnerability/serverless
-
/api/v1/policies/vulnerability/ci/serverless
-
/api/v1/policies/vulnerability/vms
-
/api/v1/policies/vulnerability/coderepos
-
/api/v1/policies/compliance/container
-
/api/v1/policies/compliance/ci/images
-
/api/v1/policies/compliance/host
-
/api/v1/policies/compliance/serverless
-
/api/v1/policies/compliance/ci/serverless
-
/api/v1/policies/compliance/vms
-
/api/v1/policies/docker
-
/api/v1/settings/serverless-auto-deploy
-
/api/v1/settings/host-auto-deploy
In 20.12, every rule must now specify at least one collection. In the UI, the default collection is All, a collection created by the system on install/upgrade. If you want to specify All in the API, you must explicitly specify it.
When creating or updating a rule, only the collection names are required (in list format). The relevant collections must exist before creating the rule. If not, the API returns an error. If the collections exist, Console fetches the collections and fills out the remaining resource fields for you.
When upgrading from 20.09 to 20.12, the system automatically converts your rule’s inline scope settings to collections, and updates your rules to comply with the new structure.
2.3. Scan settings
By default, Prisma Cloud now prunes scan results of images deleted from the registry. Alternatively, you can configure Prisma Cloud to retain the scan results of deleted images for up to 30 days.
As a result of this change, the POST /api/v1/settings/scan
endpoint has a new mandatory request parameter called registryScanRetentionDays
.
If left unspecified, calls to this endpoint will fail.
2.4. VMWare Tanzu TAS (formerly Pivotal PAS)
In line with VMWare’s acquisition of Pivotal and the product name changes from Pivotal PAS to Tanzu TAS, the following endpoints have changed:
20.09 | 20.12 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2.5. Serverless Defender policy
The method for the endpoint that encodes the Serverless Defender policy has changed from GET to POST. The encoded policy, TW_POLICY, must be set when Serverless Defender is deployed.
20.09 | 20.12 |
---|---|
|
|
In 20.12, we’ve enhanced how Defenders can be configured to connect to Console. Each Defender deployment can now be independently configured to connect to specific proxies or ports, depending on where it runs in your environment. As part of this change, the Serverless Defender policy has been extended to optionally specify a proxy through which Defender connects to Console.
In 20.09, all policy options were passed to this endpoint as query parameters because they were of limited size. In 20.12, the proxy settings contain a root CA, which can be of unknown size, and cannot be passed to this endpoint via query parameters. As a result, all policy option must now be passed to this endpoint via the request body, and the method has changed from GET to POST.
2.6. Base images
In GET /api/v1/images
, the filterBaseImage
query parameter filters out base image vulnerabilties from the response.
In 20.12, the funtionality of filterBaseImage
stays the same, but it now depends on the base image being declared in Defend > Vulnerabilities > Images > Base images (or alternatively POST /api/v1/policies/vulnerability/base-images
).