Close
Edit on GitHub

Upcoming API changes in the H1Y21 release

1. Overview

This article outlines important upcoming changes to the API in the next release of Prisma Cloud Compute.

The current release is 20.12 (code-named Galileo).

The next release (code-named Hamilton) is scheduled to ship in H1Y21.

2. Compliance stats

A new compliance dashboard will be introduced. It will simplify compliance visibility across regulations, CIS benchmarks, and policy rules.

As a result of this enhancement, the endpoint that provides the compliance statistics for the dashboard will change to include new metrics and data. The impacted endpoint is /api/v1/stats/compliance. It will add the following data:

  • Compliance rate by each regulation, CIS benchmark, and policy rule.

  • Trend of failed compliance checks over time.

  • List of all compliance checks with their compliance rate.

The data currently provided by this endpoint will no longer be available.

In addition, a new endpoint will be added: api/v1/stats/compliance/download. This endpoint will let you get a list of all compliance checks in CSV format.

3. Serverless scanning scope settings

The mechanism for specifying the serverless scanning scope will be improved. You will be able to set scopes per account rather than specifying a scope for each region in the account.

As a result of this enhancement, the ServerlessScanSpecification schema will change as follows:

  • Region and Pattern will be removed.

  • Multiple credential IDs will be supported.

In addition, the method for POST api/v1/settings/serverless-scan will change from POST to PUT to align with the way PUT works for other similar endpoints in the product. The current POST method completely replaces all scanning scopes. In the next release, the PUT method will be used to replace all scanning scopes. A new POST method will be added. The POST method will let you add a single serverless scan spec without sending an aggregated list of all specs each time you add a new spec.

4. Custom rules

The route path for api/v1/policies/runtime/custom-rules will change to api/v1/custom-rules.

5. twistcli output file

The schema of the JSON output file exported from twistcli images scanning will be stabilized. The purpose of this enhancement is to ensure backward compatibility of the schema in future releases.

Some new fields will be added to the schema and some existing fields will be adjusted as follows:

  • results.vulnerabilities.riskFactors - Will change from key:value array to strings array

  • results.vulnerabilities.publishedDays - Will change from the number of days since published date to the published date itself. The new name of the field will be publishedDate.

  • results.vulnerabilities.discoveredDays - Will change from the number of days since discovered date to the discovered date itself. The new name of the field will be discoveredDate.

6. Parameter rename

For better consistency and clarity across the product, the terms protect and protected have been replaced with the terms defend and defended. The terms indicate a Defender is protecting a resource.

The impacted endpoints are:

  • /api/v1/serverless

  • /api/v1/cloud/discovery

  • /api/v1/statuses

6.1. /api/v1/serverless

The changes in /api/v1/serverless are:

GET /api/v1/serverless/download:

  • Query parameter protected was deprecated and replaced with defended.

  • Column header in the downloaded CSV file has changed from protected to defended.

GET /api/v1/serverless/names:

  • Query parameter protected was deprecated and replaced with defended.

GET /api/v1/serverless:

  • Query param protected was deprecated and replaced with defended.

  • Key name protected in the response object was deprecated and replaced with defended.

6.2. /api/v1/cloud

The changes in /api/v1/cloud are:

GET /api/v1/cloud/discovery/download:

  • Column header in the downloaded CSV file has changed from protected to defended.

GET /api/v1/cloud/discovery:

  • Key name protected in the response objected was deprecated and replaced with defended.

6.3. /api/v1/statuses

The changes in /api/v1/statuses are:

GET /api/v1/statuses/serverless-auto-deploy

  • Key name serverlessAutoDeploy.specs.protected in the response object was deprecated and replaced with serverlessAutoDeploy.specs.defended.

GET /api/v1/statuses/host-auto-deploy

  • Key name hostAutoDeploy.status.protected in the response object was deprecated and replaced with hostAutoDeploy.status.defended.

7. Deprecated field in image scan reports

In 20.12, image scan reports returned from GET /api/v1/images contain the binaries[].layerTime field. In Hamilton, the layerTime field in objects in the binaries[] array will be deprecated.

In it’s place, there will be a new top-level object named applications that contains an equivalent layerTime field. The following table summarizes the change:

20.12 Hamilton

Endpoint: GET /api/v1/images

Field: binaries[].layerTime

Endpoint: GET /api/v1/images

Field: applications[].layerTime

As a reminder, software is typically added to an image with a package manager. Sometimes, however, a binary might be added directly to an image with the Dockerfile ADD instruction (for example, when software is built from source). The binaries[].layerTime field maps a binary added to an image to a layer in the image. In practice, this field is rarely populated. As such, we expect the impact of this change on any automation you’ve built around image scan reports to be negligible.

In Hamilton, we’re extending the number of binaries we can identify and assess for vulnerabilities. As part of this extended capability, we’re introducing the applications object with its associated layerTime field, and we’re deprecating binaries[].layerTime. Any data you previously found in binaries[].layerTime can now be found in applications[].layerTime.