Use the IaC Scan API Version 2

Create an IaC scan asset in Prisma Cloud.

The following API enables you to create an IaC scan asset. An IaC scan asset represents a collection of one or more templates whose contents have been scanned or will be scanned by the Prisma Cloud scan service to check against Prisma Cloud IaC policies.The Prisma Cloud scan service performs this scan asynchonously.

Method	Endpoint URL
POST	https://<Prisma Cloud API base URL>/iac/v2/scans

The following is an example of a cURL request to create an IaC scan asset.

curl -X POST 'https:/<Prisma Cloud API URL>/iac/v2/scans' \
    --header 'x-redlock-auth: <JWT Token>' \
    --header 'Content-Type: application/vnd.api+json' \
    --data-raw '
{
  "data": {
    "type": "async-scan",
    "attributes": {
      "assetName": "my-asset",
      "assetType": "IaC-API",
      "tags": {
        "env": "dev"
      },
      "scanAttributes": {
        "projectName": "my-project"
      },
      "failureCriteria": {
        "high": 1,
        "medium": 10,
        "low": 30,
        "operator": "or"
      }
    }
  }
}'

The request body parameters both provide metadata about your scan and define failure criteria for an IaC scan job. The required

data.type

value must currently be

async-scan

. The parameters in this example includes the following attributes:

assetName
: Can be a project name or any identifier you want to attach to the scan. Some examples are a CI/CD project name or a Git repository name.
assetType
: Identifies where the IaC scan is being done. For the IaC scan API the standard value is IaC-API. You are allowed to use other values as well. For example, if you are requesting a scan through a GitHub action and using the IaC scan API, you can set the
assetType
to
GitHub
. See the Async Scan API in the Prisma Cloud API Reference for a list of supported asset types.
tags
: Prisma Cloud tags are different from cloud tags that you might have included in your IaC templates. Prisma Cloud tags will facilitate use of upcoming Prisma Cloud features like role-based access control and policy selection. An example tag list is
owner:johndoe, team:creditapp, env:dev
.
scanAttributes
: Can be any additional details that you want to send as key/value pairs with each scan. Some examples are Git pull request numbers or specific build numbers inside a CI/CD project.
failureCriteria
: Enables you to evaluate scan results against set failure criteria to obtain failed or passed verdicts. You can set the count for high, medium, and low severity issues and use
and
or
or
operators to refine your criteria. The IaC scan API checks each severity violation number separately against scan results and applies the operator to each evaluation. The scan triggers a failure if the number of violations is greater than or equal to the
failureCriteria
values. For example, if you want a scan to fail when it detects any type of issue, you can set the failure criteria to
“high”: 1
,
“medium”: 1
,
“low”: 1
and
”operator”: “or”
. With this
failureCriteria
setting, if the scan finds any type of issue, the job will fail. An example of
failureCriteria
that causes the IaC scan API to run checks in warning mode is
“high”: 1000
,
“medium”: 1000
,
“low”: 1000
,
“operator”: and
.

Details about all the body parameters for this request are in Async Scan API in the Prisma Cloud API Reference.

The following example shows the response of a successful request. In this example, the

data.id

value is a scan id that you will use in subsequent requests to manage your scan job. The

data.url

value is a presigned URL you will use to upload the files you want scanned to Prisma Cloud.

{ 
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "links": {
      "url": "https://s3.amazonaws.com/s3sign2-bucket-hchq3nwuo8ns/s3-sign-demo.json?X-Amz-Security-Token=FQ…&X-Amz-Credential=ASIAJF3BXG…&X-Amz-Date=20170125T044127Z&X-Amz-Expires=60&X-Amz-Signature=24db0"
    }
  }
}	

Use the presigned URL from the scan asset creation to upload the templates to be scanned.

Prisma Cloud uses a presigned URL that gives you temporary access to upload an object. In the example above, the presigned URL is the value of the key

data.url

. The following is an example of a cURL request to upload a file to the presigned URL.

curl -v -X PUT '<presigned URL>' -T <path and file name of file to be uploaded>

You can upload a single file or multiple files as a zip archive to the presigned URL.

Some example templates and plan files are available at Prisma Cloud IaC samples on GitHub; you can use one of these files to experiment with an upload request.

Start a job to perform a scan of your uploaded templates.

The following API enables you start an asynchronous job to perform a scan of your uploaded file. The path parameter is the scan ID from the response of your earlier request to create a scan asset.

Method	Endpoint URL
POST	https://<Prisma Cloud API base URL>/iac/v2/scans/{scanID}

The path parameter

scanID

is the scan ID from the response of your earlier request to create a scan asset.

The following is an example of a cURL request to start a job that scans the file you’ve already uploaded.

curl -X POST 'https://<Prisma Cloud API URL>/iac/v2/scans/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
    --header 'x-redlock-auth: <JWT Token>' \
    --header 'Content-Type: application/vnd.api+json' \
    --data-raw '
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "templateType": "tf"
    }
  }
}'

The

data.id

in the request body parameter is the same as the path parameter

scanID

and is optional.

Optional request parameters are available to handle more complex scenarios, including specification of the following:

Runtime variables for templates.
Variable files if the IaC scan API cannot automatically detect the files.
A list of files to which the scan will be limited.
A list of folders to which the scan will be limited. With this specification, the IaC scan service will scan the content of the listed folders, including files and sub-folders.

Details about the API request are in the Initiate Scan Job API in the Prisma Cloud API Reference

A successful request will return an HTTP code of 200.

Query your job status.

The following API enables you to query the status of your asynchronous IaC scan job.

Method	Endpoint URL
GET	https://<Prisma Cloud API base URL>/iac/v2/{scanID}/status

The

scanID

path parameter is the id you received in the response object from the request to create a scan asset and which you also used as a path parameter to start the scan job. The following is an example cURL request to request the job status.

curl -X GET 'https://<Prisma Cloud API URL>/iac/v2/scans/3fa85f64-5717-4562-b3fc-2c963f66afa6/status' \
--header 'x-redlock-auth: <JWT Token>' \
--header 'Content-Type: application/vnd.api+json' 

The following example shows the response of a successful request.

{
  "data": {
    "id": 12345678-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "status": "processing"
    }
  }
}	

Request IaC scan results.

The following API enables you to request your IaC scan results after the scan job is done.

Method	Endpoint URL
GET	https://<Prisma Cloud API base URL>/iac/v2/scans/{scanID}/results

The

scanID

path parameter is the id you received in the response object from the request to create a scan asset and which you also used as a path parameter to start the scan job. The following is an example cURL request to request the job status.

curl -X GET 'https://<Prisma Cloud API URL>/iac/v2/scans/12345678-5717-4562-b3fc-2c963f66afa6/results' \
--header 'x-redlock-auth: <JWT Token>' \
--header 'Content-Type: application/vnd.api+json' 

The following example shows the response of a successful request.

{ 
  "meta": {
    "matchedPoliciesSummary": {
      "high": 1,
      "medium": 0,
      "low": 0
    },
    "errorDetails": []
  },
  "data": [
    {
      "id": "12345678-5717-4562-b3fc-2c963f66afa6",
      "attributes": {
        "severity": "high",
        "name": "AWS Security Groups allow internet traffic to SSH port (22)",
        "rule": "$.resource[*].aws_security_group exists and ($.resource.aws_security_group[*].ingress[?(@.protocol == 'tcp'&& @.from_port<23 && @.to_port>21 )].cidr_blocks contains 0.0.0.0/0",
        "desc": "This policy identifies AWS Security Groups which do allow inbound traffic on SSH port (22) from public internet",
        "files": [
          "./main.tf"
        ],
        "policyId": "617b9138-584b-4e8e-ad15-7fbabafbed1a",
        "docUrl": "https://docs.paloaltonetworks.com/prisma/prisma-cloud/prisma-cloud-policy-reference/configuration-policies/configuration-policies-build-phase/amazon-web-services-configuration-policies/policy_617b9138-584b-4e8e-ad15-7fbabafbed1a.html"
      }
    }
  ]
}