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.

Breaking changes

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

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.

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.

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
POST /api/v1/pcf-droplets/stop
POST /api/v1/tas-droplets/stop
POST /api/v1/pcf-droplets/scan
POST /api/v1/tas-droplets/scan
GET /api/v1/pcf-droplets/progress
GET /api/v1/tas-droplets/progress
GET /api/v1/pcf-droplets/download
GET /api/v1/tas-droplets/download
GET /api/v1/pcf-droplets/addresses
GET /api/v1/tas-droplets/addresses
GET /api/v1/pcf-droplets
GET /api/v1/tas-droplets
POST /api/v1/settings/pcf
POST /api/v1/settings/tas
GET /api/v1/settings/pcf
GET /api/v1/settings/tas

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
GET /api/v1/policies/runtime/serverless/encode
POST /api/v1/policies/runtime/serverless/encode
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.

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

XSOAR (formerly Demisto)

In line with the product name change, the endpoint for XSOAR (Demisto) alerts has changed:
20.09
20.12
GET /api/v1/demisto-alerts
GET /api/v1/xsoar-alerts

License key

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.

Deprecated

The following endpoints have been deprecated in line with the features that have been deprecated in 20.12.

SCAP

SCAP support has been deprecated in 20.12, along with the following endpoints:
  • POST /api/v1/scap
  • GET /api/v1/scap
  • DELETE /api/v1/scap/{id}

Recommended For You