An Introduction to Scripting using the CWPP API

cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
Announcements
Please sign in to see details of an important advisory in our Customer Advisories area.
L4 Transporter
100% helpful (3/3)

By Avery King, Cloud Security Engineer

and Paul Burega, Cloud Security Engineer

 

Throughout the security lifecycle of an application or cloud environment it is important to be able to understand the tools available to each security professional. One of the best tools for any security professional to be able to use is scripting. Scripting allows one to create a program that automates an individual task and, when coupled with the Prisma Cloud Compute Workload Protection Platform (CWPP), you can effectively complete your use cases with ease. All that it takes to create a script is an understanding of the tools available to you, practice, and studying the available documentation of API calls that can interface with your scripting program. 

 

Through the CWPP API and this article, you will be able to begin to establish a new way to be able to solve your company’s problems while enhancing your available tools in problem solving. In this article, we are utilizing a SaaS CWPP console for the examples and a text editor which can save text files for scripting along with a Linux command line available in MacOS terminal or in Windows with Subsystem for Linux. 

 

When interacting with a command line, you can type directly into the command prompt. As an example, to help those of you who have not yet worked with a Linux command line, you can navigate to different directories using the “cd” or ‘current directory’ command. You can determine the path to your current directory by typing “pwd,” or ‘print working directory’, and you can list the files in the current directory using “ls”.

 

Installing the Python Package 

 

This article uses Python 3 to write a script. Palo Alto Networks provides a GitHub library: Prisma Cloud Python Integration - PCPI which contains our Python3 toolkit for Prisma Cloud APIs. (https://github.com/PaloAltoNetworks/pc-python-integration)

 

Here is how to install the PCPI library from your command line in either Linux, MacOS, or Windows with the Windows Subsystem for Linux installed:

 

$ pip3 install pcpi

Collecting pcpi

  Downloading pcpi-0.1.0-py3-none-any.whl (15 kB)

Installing collected packages: pyyaml, charset-normalizer, certifi, idna, urllib3, requests, pcpi

Successfully installed certifi-2022.9.24 charset-normalizer-2.1.1 idna-3.4 pcpi-0.1.0 pyyaml-5.4.1 requests-2.28.1 urllib3-1.26.12

$

 

The Python Script

 

Create your script file using any editor that allows you to save as a plain text file “my-script.py” using the below Python code:

 

from pcpi import session_loader

import json

session_man = session_loader.load_from_file()

cwp_session = session_man.create_cwp_session()

#

#Get Defenders

#

res = cwp_session.request('GET', '/api/v1/defenders')

# print(res.json())

# print(json.dumps(res.json(), indent=4))

print(json.dumps(res.json()[0], indent=4))

print()

print()

#

#Get Vulnerbilties

#

res = cwp_session.request('GET', '/api/v1/stats/vulnerabilities')

# print(json.dumps(res.json(), indent=4))

print(json.dumps(res.json()[0], indent=4))

print()

print()

#

#GET CVE INFO

#

res = cwp_session.request('GET', '/api/v1/stats/vulnerabilities/impacted-resources?cve=<CVE-2021-44228>')

print(json.dumps(res.json(), indent=4))

print()

print()

 

Conventions Used in Python Script

 

Comments are lines starting with “#”

#This is a comment to tell us what the script is doing here

 

This prints the raw json returned by the API.  It is not very readable in most cases, but is very compact:

print(res.json()) 

 

This will print all the json return by the API, but will format the print, and indent the json:

print(json.dumps(res.json(), indent=4))

 

This will print only the first json object returned by the API, formatting and indenting the json:

print(json.dumps(res.json()[0], indent=4))

 

For purposes of the demo script, we have commented out the full json print, and only printed the first json object.  Feel free to experiment with printing all the json, and the compacted json, to see what would be useful for your scripting needs.

 

Obtain a Prisma Cloud Access Key

 

Before you can use the Prisma Cloud APIs, you will need to generate an Access Key in order to log into Prisma Cloud.  When you use the Prisma Cloud GUI, your organization probably has enabled some single sign-on security for your user. Please note - you cannot use single sign-on to run scripts.  Instead, you need an Access Key generated from Prisma Cloud.  

 

You will need to get authorization from your Prisma Cloud Administrator to have the ability to create an Access Key.  Please follow the best practices for security listed in: 

Scripting and Automation Best Practices with Prisma Cloud CSPM JWT  

Which includes setting an expiration date of your Access Key, 30-90 days from the date of generation.  Do not create Access Keys without expiry dates, as these are a security exposure.

 

The CWPP API documentation for all the CWPP API’s used by the CWPP GUI is documented here:  CWPP API - 22.06

 

View Defenders

 

Let us look at a couple of API endpoints that can help with everyday protocols when utilizing the CWPP console. These endpoints will allow you to have a view into where the affected threat surface could be based on the view that the console has into your organization's resources as well as the defended endpoints within your organization.  With this information, you can now begin to piece together where to map out a procedure to remediate your environment and have a better security posture.

 

To be able to see the defended endpoints you use the defenders api.

Defenders Overview (22.06.213)

 

Once run, this will give you updated information around defender deployment as well as useful pieces of data to be able to determine the protected surface within your organization. This is a useful data collection because it will help you to have a baseline of where defenders are deployed. This information is available within the console but there are lower level data points that can be additionally helpful when extracting what you need from the API. Utilizing this command can help you to have a scheduled baseline of how your defense area changes over time. 

#

#Get Defenders

#

res = cwp_session.request('GET', '/api/v1/defenders')

print(json.dumps(res.json()[0], indent=4))

 

Creates the output:

{

    "hostname": "EC2AMAZ-3URTI4O",

    "version": "22.06.213",

    "lastModified": "2022-10-11T08:49:21.695Z",

    "type": "serverWindows",

    "category": "host",

    "connected": true,

    "features": {

        "proxyListenerType": "none"

    },

    "status": {

        "lastModified": "0001-01-01T00:00:00Z",

        "filesystem": {},

        "network": {},

        "appFirewall": {

            "enabled": true

        },

        "containerNetworkFirewall": {},

        "hostNetworkFirewall": {},

        "features": {},

        "hostCustomCompliance": {}

    },

   …

 

View Vulnerability Trends

 

Next we can look at vulnerability trends. To able to view these via API you can utilize the command:  stats/vulnerabilities

#

#Get Vulnerbilties

#

res = cwp_session.request('GET', '/api/v1/stats/vulnerabilities')

print(json.dumps(res.json()[0], indent=4))

 

Creates the output:

{

    "_id": "2022-09-18",

    "modified": "2022-09-18T22:51:57.162Z",

    "images": {

        "impacted": {

            "critical": 129,

            "high": 23,

            "medium": 9,

            "low": 4,

            "total": 184

        },

        "cves": {

            "critical": 137,

            "high": 635,

            "medium": 856,

            "low": 424,

            "total": 2052

        }

    },

    "hosts": {

      …

    },

    "functions": {

        …

    },

    "containers": {

        …

    },

    "codeRepos": {

        …

    },

    "registryImages": {

        …

}

 

View a Particular CVE

 

To be able to scope the API call to one vulnerability, specify the vulnerability you are interested in: stats/vulnerabilities/impacted-resources?cve=<CVE-ID>'

To see the Log4J vulnerability, the CVE-ID would be CVE-2021-44228: 

stats | Prisma Developer Docs

 

#

#GET CVE INFO

#

res = cwp_session.request('GET', '/api/v1/stats/vulnerabilities/impacted-resources?cve=<CVE-2021-44228>')

print(json.dumps(res.json(), indent=4))

 

Creates the output:

{

    "_id": "<CVE-2021-44228>",

    "imagesCount": 0,

    "hostsCount": 0,

    "functionsCount": 0,

    "codeReposCount": 0,

    "registryImagesCount": 0

}

 

Running the Python Script

 

$ python3 my-script.py 

No credentials file found. Generating...

Enter credentials for the tenant

Enter tenant name or any preferred identifier:

log-my-first-script

Enter tenant url. (ex: https://app.ca.prismacloud.io)

https://app.prismacloud.io

 

Adjusted URL:

https://api.prismacloud.io

 

Enter tenant access key:

00000000-0000-0000-0000-000000000000

Enter tenant secret key:

0000000000000000000000000

 

API - Validating credentials

SUCCESS

…  

lots of output follows

 

Conclusion

 

You now have a foundation to be able to grow your knowledge in scripting to any other API endpoint available within the console’s capabilities. You can now begin to build a set of scripts to automate routine tasks. 

 

Now that you have a base level understanding in scripting, you can begin to practice creating additional utility programs with API endpoints. With this foundation to help you in building out your security protocols via available API endpoints in the CWPP console you can now begin to utilize additional documented endpoints.

 

 

About the Authors

 

Avery King and Paul Burega are cloud security engineers specializing in Cloud Security Posture Management. Paul and Avery utilize collaborative approaches to break down complex problems into solutions for global enterprise customers and leverage their multi-industry knowledge to inspire success.

Rate this article:
(1)
  • 2872 Views
  • 0 comments
  • 3 Likes
Register or Sign-in
Labels
Article Dashboard
Version history
Last Updated:
‎09-19-2023 06:39 PM
Updated by: