Use the Prisma Cloud IaC Scan REST API

Use the Prisma Cloud REST API directly to scan IaC templates and test them against Prisma Cloud security policies.
Prisma Cloud makes the IaC scanning functionality available as a SaaS solution through a REST API. The Prisma Cloud IaC scan service supports Terraform templates, CloudFormation templates, and Kubernetes app manifests. While it is recommended that you take advantage of the IaC scan plugins that are available, there are situations where you might want to use the IaC scan REST API directly.
The following support exists.

REST API Authentication

The Prisma Cloud IaC scan REST API uses authentication based on JSON web tokens (JWT). To gain secure access to the API, you need to start with a Prisma Cloud access key, which your Prisma Cloud administrator normally assigns. You can use the access key to obtain a JWT through a Prisma Cloud REST API request for authentication. You will, in turn, enter the JWT in the header of your IaC scan REST API request. See Access the Prisma Cloud REST API for details.

REST API Base URL

All IaC scan REST API request paths are relative to a base URL. Your IaC scan REST API base URL depends on the region and cluster of your Prisma Cloud tenant. For example, if your Prisma Cloud admin console URL is
https://app.prismacloud.io
, then your Prisma Cloud API base URL is
https://api.prismacloud.io
. See the Prisma Cloud REST API Reference for a list of Prisma Cloud API URLs.

REST API Request to Scan Terraform Files

Method
Endpoint URL
POST
https://<Prisma Cloud API base URL>/iac/tf/v1/scan
This REST API request scans a Terraform file or a zip archive that contains multiple Terraform files for comparison against Prisma Cloud security policies. The body of the API request contains the file or zip archive to be scanned.
Note that the with a request to scan Terraform files, the IaC scan service will not scan any non-Terraform files or any Terraform files that have invalid formats.
The module you scan can have either Terraform 0.12 or prior version templates.The request-header fields differ, depending on the type of Terraform module you want to scan.

Terraform 0.12

The following table shows request-header fields required to request a scan of Terraform 0.12 modules.
Request-Header Field
Value
Notes
x-redlock-auth
Your JWT token
Required
content-type
To scan single files:
text/plain
. To scan zip archives:
multipart/form-data
Required
terraform-version
0.12
Required
terraform-012-parameters
An array of key/value pairs that describe the variables in your module. See details below.
Required
The value of
terraform-012-parameters
differs, depending on whether your Terraform 0.12 module has (1) standard variables or (2) custom variable file names and/or external variables.
  • If the Terraform module has variable files but no external variables, then the array elements that make up the value of
    terraform-012-parameters
    is as follows.
    Key
    Value
    root-module
    Terraform 0.12 root module
    The following example shows a cURL request to scan a Terraform 0.12 module that has standard variables.
    curl -X POST ’https://<Prisma Cloud API URL>/iac/tf/v1/scan' \ --header 'x-redlock-auth: '<JWT token> \ --header 'Content-Type: multipart/form-data' \ --header 'terraform-version: 0.12' \ --header 'terraform-012-parameters: [{"root-module":"/scan/rich-value-types/"},{"root-module":"/scan/rich-value-types/network/"}]' \ --form 'templateFile=@<path and file name of single Terraform file or zip archive>'
    The following example shows the response of a successful request.
    { "result": { "is_successful": true, "rules_matched": [ { "severity": "medium", "name": "AWS S3 Object Versioning is disabled", "rule": " $.resource[*].aws_s3_bucket exists and ($.resource[*].aws_s3_bucket.*[*].*.versioning[*].enabled does not exist or $.resource[*].aws_s3_bucket.*[*].*.versioning[*].enabled anyFalse)", "description": "This policy identifies the S3 buckets which have Object Versioning disabled. S3 Object Versioning is an important capability in protecting your data within a bucket. Once you enable Object Versioning, you cannot remove it; you can suspend Object Versioning at any time on a bucket if you do not wish for it to persist. It is recommended to enable Object Versioning on S3.", "files": [ "/scan/for-expressions" ], "id": "89ea62c1-3845-4134-b337-cc82203b8ff9" } ], "severity_stats": { "high": 0, "low": 0, "medium": 1 } }, "response_id": "bb3ba05a-2e31-4fc3-9a8e-91b31f673500" }
  • You can set the value of
    terraform-012-parameters
    to enable a scan of Terraform variable files with custom names or Terraform external variables. If your Terraform module has either of these variable uses, then the value of
    terraform-012-parameters
    is an array of key/value pairs where the key/value pairs can be one or more of the following.
    Key
    Value
    root-module
    Terraform 0.12 root module
    variable-files
    An array of custom variable file names. The path of each file is relative to your root module.
    variables
    An array of key/value pairs. Each array element has a name and value that together identify an input variable (e.g. [{“name”:”varName1”,”value”:”varValue1},{“name”:”varName2”,”value”:”varValue2”}]
    The following example shows a cURL request to scan a Terraform 0.12 zip archive that has a custom variable file name and external variables.
    curl -X POST 'https://<Prisma Cloud API URL>/iac/tf/v1/scan' \ --header 'x-redlock-auth: <JWT token>' \ --header 'Content-Type: multipart/form-data' \ --header 'terraform-version: 0.12' \ --header 'terraform-012-parameters: [{"root-module":"/scan/rich-value-types/"},{"root-module":"/scan/rich-value-types/network/","variable-files":["/scan/rich-value-types/network/variables.tf"]},{"root-module":"/scan/for-expressions/"}]' \ --form 'templateFile=@<absolute file path of template or zip>'

Terraform 0.11

The following table shows request-header fields required to request a scan of Terraform 0.11 modules that have only standard variables.
Request-header Field
Value
Notes
x-redlock-auth
Your JWT token
Required
content-type
To scan single files:
text/plain
. To scan zip archives:
multipart/form-data
Required
The following is an example of a cURL request to scan a Terraform 0.11 module that has only standard variable file names.
curl -X POST 'https://<Prisma Cloud API URL>/iac/tf/v1/scan' \ --header 'x-redlock-auth: <JWT token>' \ --header 'Content-Type: multipart/form-data' \ --form 'templateFile=@<absolute file path of template or zip>'
The following table shows request-header fields required to request a scan of Terraform 0.11 modules that have custom variable file names or external variables.
Request-header Field
Value
Notes
x-redlock-auth
Your JWT token
Required
content-type
To scan single files:
text/plain
. To scan zip archives:
multipart/form-data
Required
rl-parameters
An array of key/value pairs. Each array element has a name and value that together identify an input variable (e.g. [{“name”:”varName1”,”value”:”varValue1}, {“name”:”varName2”,”value”:”varValue2”}])
Required for input variables
rl-variable-file-names
An array of variable file names. The path of each file is relative to your repository branch root directory
Required for variable files
The following is an example of a cURL request to scan a Terraform 0.11 module that has custom file names and external variables.
curl -X POST 'https://<Prisma Cloud API URL>/iac/tf/v1/scan' \ --header 'x-redlock-auth: <JWT token>' \ --header 'Content-Type: multipart/form-data' \ --header ‘rl-parameters: “[{"name":"varName1","value":"varValue1"},{"name":"varName2","value":"varValue2"}]”’ \ --header 'rl-variable-file-names: ["vars.tf.json", "file1.tf"]' \ --form 'templateFile=@<absolute file path of template or zip>'
The following is an example of a successful response to the request above.
{ "result": { "is_successful": true, "rules_matched": [ { "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 or $.resource[*].aws_security_group[*].*[*].ingress[?( @.protocol == 'tcp' && @.from_port<23 && @.to_port>21 )].ipv6_cidr_blocks[*] contains ::/0)", "description": "This policy identifies AWS Security Groups which do allow inbound traffic on SSH port (22) from public internet. Doing so, may allow a bad actor to brute force their way into the system and potentially get access to the entire network.", "files": [ "demo/securitygroup22.tf" ], "id": "617b9138-584b-4e8e-ad15-7fbabafbed1a" }, "severity_stats": { "high": 0, "low": 0, "medium": 1 } }, "response_id": "bb3ba05a-2e31-4fc3-9a8e-91b31f673500" }

REST API Request to Scan AWS CloudFormation Templates

Method
Endpoint URL
POST
https://<Prisma Cloud API base URL>/iac/cft/v1/scan
This REST API request scans AWS CloudFormation template files for comparison against Prisma Cloud security policies. Support exists for both JSON and YAML formats. Prisma Cloud IaC API also supports parameters for CloudFormation templates. You can also scan either a single template or a zip archive of template files with a single API request. Note that scan support does not currently exist for nested references, macros, or intrinsic functions in CloudFormation templates.
The following table shows the request-header fields. The body of the API request contains the file or zip archive to be scanned.
Request-header Field
Value
Notes
x-redlock-auth
Your JWT token
Required
content-type
To scan single files:
text/plain
. To scan zip archives:
multipart/form-data
Required
rl-parameters
An array of key/value pairs. Each array element has a name and value that together identify a parameter (e.g. [{“name”:”varName1”,”value”:”varValue1}, {“name”:”varName2”,”value”:”varValue2”}])
Required for parameters
The following example shows a cURL request to scan an AWS CloudFormation template with external variables.
curl -X POST ’https://<Prisma Cloud API URL>/iac/cft/v1/scan' \ --header 'x-redlock-auth: <JWT token>' \ --header 'Content-Type: multipart/form-data' \ --header ‘rl-parameters: “[{"name":"varName1","value":"varValue1"},{"name":"varName2","value":"varValue2"}]”’ \ --form 'templateFile=@<absolute file path of template or zip>'
The following is an example of a successful response to this request.
{ "result": { "is_successful": true, "rules_matched": [ { "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 or $.resource[*].aws_security_group[*].*[*].ingress[?( @.protocol == 'tcp' && @.from_port<23 && @.to_port>21 )].ipv6_cidr_blocks[*] contains ::/0)", "description": "This policy identifies AWS Security Groups which do allow inbound traffic on SSH port (22) from public internet. Doing so, may allow a bad actor to brute force their way into the system and potentially get access to the entire network.", "files": [ "cftdemo/cft_sg.json" ], "id": "617b9138-584b-4e8e-ad15-7fbabafbed1a" }, "severity_stats": { "high": 0, "low": 0, "medium": 1 } }, "response_id": "bb3ba05a-2e31-4fc3-9a8e-91b31f673500" }

REST API Request to Scan Kubernetes Templates

Method
Endpoint URL
POST
https://<Prisma Cloud API base URL>/iac/k8s/v1/scan
This REST API request scans Kubernetes manifests to compare against Prisma Cloud security policies, including manifests that you generate from Helm charts. You can scan either a single manifest or a zip archive of manifest files with a single API request.
The following table shows the request-header fields. The body of the API request contains the file or zip archive to be scanned.
Request-header Field
Value
Notes
x-redlock-auth
Your JWT token
Required
content-type
To scan single files:
text/plain
. To scan zip archives:
multipart/form-data
Required
The following example shows a cURL request to scan a single Kubernetes manifest file.
curl --location --request POST 'https://<Prisma Cloud API URL>/iac/k8s/v1/scan' \ --header 'x-redlock-auth: <JWT token>' \ --header 'Content-Type: multipart/form-data' \ --form 'templateFile=@<absolute file path of template or zip>'
The following is an example of a successful response object.
{ "result": { "is_successful": true, "rules_matched": [ { "severity": "high", "name": "All capabilities should be dropped", "rule": "$.spec.template.spec.containers[*].securityContext.capabilities.drop exists and not $.spec.templates.spec.containers[*].securityContext.capabilities.drop[*] contains ALL", "description": "Ensure that all capabilities are dropped.", "id": "4682a6f1-2a1b-4f5a-938c-cdd3fa421a63" }, { "severity": "medium", "name": "Do not run containers with dangerous capabilities", "rule": "$.spec.template.spec.containers[*].securityContext.capabilities exists and $.spec.template.spec.containers[*].securityContext.capabilities.add[*] is member of (FSETID, SETUID, SETGID,SYS_CHROOT,SYS_PTRACE,CHOWN,NET_RAW,NET_ADMIN,SYS_ADMIN,NET_BIND_SERVICE)", "description": "Ensure not running containers with dangerous capabilities.", "id": "135420a6-3206-4c29-b944-846f65cea43e" } ], "severity_stats": { "high": 1, "low": 0, "medium": 1 } }, "response_id": "ddd6d597-e560-4e67-abd1-4bc2cedee062" }

Legacy Prisma Cloud IaC Scan REST API (Deprecated)

Method
Endpoint URL
POST
https://<Prisma Cloud API base URL>/iac_scan
This REST API offers the ability to scan IaC templates and test them against Prisma Cloud IaC policies.
This API is deprecated. All the functionality this API offers is available through the other IaC scan REST APIs listed in this chapter.
You can submit a template for scanning either by (1) copying the template content directly into the REST API body parameter or (2) specifying a template file. You can scan templates that are in either JSON or YAML format. You can also scan a zip archive that contains Terraform templates.

Specify Template Content in the Body Parameter

If you want to scan a single template for vulnerabilities, you can specify the template content in the body parameter of your REST API request. The following example shows how to use cURL to scan a single template by submitting the template content (
CFT.json
in this example) in the body parameter of your API request.Note that the request requires a header parameter
Content-Type: text/plain
.
curl --data-binary @CFT.json -X POST https://<Prisma Cloud API>/iac_scan \ -H 'Content-Type: text/plain' \ -H 'x-redlock-auth: <JWT>'

Scan a Template by Uploading the Template File

The following example shows how to scan a single template by uploading the template file through the REST API request.
Note that the request requires a header parameter
Content-Type: text/plain
.
curl -X POST https://<Prisma Cloud API URL>/iac_scan \ -H 'Content-Type: text/plain' \ -H 'x-redlock-auth: <JWT>' \ -F templateFile=@/Users/ab/CFT.json
You can scan multiple templates that are in a zip archive, such as a zip file containing compressed Terraform files. The following example shows how to upload a zip archive to scan all the templates in that archiver for vulnerabilities.
curl -X POST https://<Prisma Cloud API>/iac_scan \ -H 'Content-Type: multipart/form-data' \ -H 'x-redlock-auth: <JWT>' \ -F templateFile=@/Users/ab/Templates.zip
If you scan a zip archive that contains both compressed Terraform files and custom variable files, you can specify the Terraform custom variable files that are in the zip archive to ensure these files are included in the scan for vulnerabilities. The following is an example of a cURL call that identifies a Terraform custom variable file vars.tf.json in the zip archive Terraform.zip. Standard variable files in the zip archive, like
variable.tf
, will be scanned for vulnerabilities without being listed in
rl-variable-file-nam
e.
curl -X POST https://<Prisma Cloud API>/iac_scan \ -H 'rl-variable-file-name:["vars.tf.json"]' -H 'Content-Type: multipart/form-data' \ -H 'x-redlock-auth" <JWT> \ -F templateFile=@/Users/ab/Terraform.zip

See the Response Schema

The following example show the format of the response for a successful request that discovered one or more vulnerabilities.
{ "result": { "rules_matched": [ { "severity": "", "name": "", "id": "" } ], "severity_stats": { "high": 0, "low": 0, "medium": 1 }, "is_successful": "true" } }

Recommended For You