20.12 porting guide
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.
If you’re using any of the following endpoints, you’ll need to update your integrations when migrating to 20.12.
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:
Instead, specify these fields when creating credentials in the credentials store endpoint:
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:
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
Allin 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.
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.
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:
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.
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.
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).
XSOAR (formerly Demisto)
In line with the product name change, the endpoint for XSOAR (Demisto) alerts has changed:
Previously, the product license key was returned to all users of any role in licenseKey from GET /api/v1/settings/system.
In 20.12, the raw license key is only returned to users with the admin role. For all other roles, a null string is returned.
The following endpoints have been deprecated in line with the features that have been deprecated in 20.12.
SCAP support has been deprecated in 20.12, along with the following endpoints: