Panoptica REST API Jumpstart With Python

yawming · ‎10-21-2022

Cisco Panoptica provides rich REST APIs which can do most of things you can do with the Panoptica UI Dashboard.

The Panoptica API document is thorough. You can access the API document after logging to the Paoptica.app web site and click the “API” on the upper right corner. Or, you can use the following links:

Panoptica REST API Documentation

Panoptica REST API Reference

Here is a step-by-step guide to make it easier to use the API.

The Panoptica REST API is not much different from the other REST APIs, but it uses Escher authentication. You’ll need some additional information when making an HTTP request. We will have more details later.

Pre-requisites:

Make sure your Python version 3 is running ok, simple do “python3 -V” or “python -V” to show your python version

$ python3 -V

Python 3.10.2

Do “pip -V” too to make sure pip is running ok as well.

Step 1. Get your login for panoptica.app site if you haven’t done so

You will need to access the GUI to get the necessary keys for authentication.

It’s free to sign up!

Step 2. Create a Python virtual environment and activate it

(This step is optional but recommended)

$ python3 -m venv Panoptica (you can replace Panoptica with any name you like to use)

$ source Panoptica/bin/activate

$ cd Panoptica

Step 3. Install required python modules (packages)

We will create a barebones python script which only requires 3 modules – “requests”, “datetime” and “escherauth”. We need at least these 3 modules for every Panoptica API query.

$ pip install requests

$ pip install datetime

$ pip install escherauth

If you run into the following error later when executing your python script, no worries, there are couple of ways to fix it:

Traceback (most recent call last):

File "/Users/xxxx/Panoptica/get_service_user.py", line 3, in <module>

from escherauth import EscherRequestsAuth

ImportError: cannot import name 'EscherRequestsAuth' from 'escherauth' (/Users/xxxx/Panoptica/lib/python3.10/site-packages/escherauth/__init__.py)

Edit __init__.py file, change the line “from escherauth import *” to “from .escherauth import *” (Add a “.” before escherauth, so it can find the right path)
You can also get the escherauth from this repo if you have trouble to install escherauth module just place eschersuth.py in directory where you create your python script, it will do the same job.

The Panoptica REST API uses Escher authentication and escherauth module is used for this purpose. We need to provide current time for the authentication that’s why we need datetime module.

Step 4. Obtain Access Key and Secret Key for the API Escher authentication

After logging onto the panoptica.app site you should see the following screen (below).

Click on System to go to System page.

Click on MANAGE USERS then click on “+ New User”.

Once New User window pop up select role as “Service User” then provide a name, for example “api_user” then click FINISH button.

You should see a Token window pop up. Copy the Access Key and Secret Key and keep them in a safe place. These will be the keys to use escher authentication for the API request.

Step 5. Gather required parameters for Escher authentication

According to Escher Specification we need to have a mandatory header called “host” . In our case the key-value pair of this header is 'host': 'securecn.cisco.com'

The 'securecn.cisco.com' is a string constant.

You may also need a date in the header, 'X-Escher-Date': <date_string>

The date_string is in the ISO 8601 basic format, like “YYYYMMDD + T + HHMMSS + Z”. We get it from the datetime library function.

So, for the header we have:

headers={'X-Escher-Date': <date_string>,'host': 'securecn.cisco.com'}

For the authentication we will call a function EscherRequestsAuth from the escherauth module. One of the parameters we need pass to the function is the credential scope , in our case is the string constant of "global/services/portshift”.

We also need to pass api_key and api_secret which are Access Key and Secret Key we have obtained in Step 4.

Then, pass the current time in this format - YYYY-MM-DD HH:MM:SS – use a datetime module function to get this, as shown below in our sample script.

Summarize things are needed for the Escher Authentication:

For the headers :
- 'X-Escher-Date': <date_string>
- 'host': 'securecn.cisco.com'

For the parameters of EscherRequestsAuth function:
- "global/services/portshift_request” - string constant
- api_key – string (Access key from step 4)
- api_secret – string (Secret Key from step 4)
- date – string

Example of EscherRequestsAuth function call:

auth=EscherRequestsAuth("global/services/portshift_request",

{'current_time': <date string>},

{'api_key': <access_key>, 'api_secret': <secret_key>}))

Step 6. The base URL

Last thing we need to know is the base URL for the REST API which is https://securecn.cisco.com/api

Now we have prepared everything we need. We can start composing our first Panoptica APi python script.

Step 7. Compose python script

First, we import the 3 modules we installed in step 3:

import datetime

import requests

from escherauth import EscherRequestsAuth

Assign access_key and secret key we obtained in step 4:

api_key="<your access key>"

api_secret="<your secret key> "

Define date format and get current time:

date_format = '%Y%m%dT%H%M%SZ'

date_string = datetime.datetime.utcnow().strftime(date_format)

date = datetime.datetime.strptime(date_string, date_format)

Use the list current users API (https://securecn.cisco.com/api/users) with filter “SERVICE” users (?roles=SERVICE). Let’s assign the full URL path of API.

full_url = "https://securecn.cisco.com/api/users?roles=SERVICE"

Assign the headers we discussed in step 5

headers={'X-Escher-Date': date_string,'host': 'securecn.cisco.com'}

(remember the value for the ‘host’ key is 'securecn.cisco.com')

Make the GET request:

response=requests.get(full_url,headers=headers,auth=EscherRequestsAuth("global/services/portshift_request",{'current_time': date},{'api_key': access_key, 'api_secret': secret_key}))

Then we print out the request status and output

print ("status: ",response.status_code)

print (response.text)

That is all, let’s put them together:

The script:

import datetime
import requests
from escherauth import EscherRequestsAuth

access_key="<your access key"
secret_key="<your secret key"

date_format = '%Y%m%dT%H%M%SZ'
date_string = datetime.datetime.utcnow().strftime(date_format)
date = datetime.datetime.strptime(date_string, date_format)

full_url = "https://securecn.cisco.com/api/users?roles=SERVICE"

headers={'X-Escher-Date': date_string,'host': 'securecn.cisco.com'}

response = requests.get(full_url,headers=headers,auth=EscherRequestsAuth("global/services/portshift_request",{'current_time': date},{'api_key': access_key, 'api_secret': secret_key}))

print ("status: ",response.status_code)
print ("list of service users:\n",response.text)

The output:

status:  200
list of service users:
 [{"id":"145c73ee-66b6-4c19-827f-25d8d3e17bd1","accountId":"51f0bc6b-9612-4665-8971-ee978047f821","lastLogin":"2022-10-17T15:33:42.415Z","fullName":"api_user","description":null,"status":"ENABLED","role":"SERVICE","normalizedRole":"Service User","email":null}]\

We can see it does list the user we just created in step 4 - "fullName":"api_user", but the format is not easy to read, isn’t it ?

Let’s tweak a little bit of script:

Add the json module to improve the format. Use json.dumps() to print pretty format.

Here is the modified script:

The final script:

import datetime
import requests
from escherauth import EscherRequestsAuth
import json

access_key="<your access key"
secret_key="<your secret key"

date_format = '%Y%m%dT%H%M%SZ'
date_string = datetime.datetime.utcnow().strftime(date_format)
date = datetime.datetime.strptime(date_string, date_format)

full_url = "https://securecn.cisco.com/api/users?roles=SERVICE"

headers={'X-Escher-Date': date_string,'host': 'securecn.cisco.com'}

response = requests.get(full_url,headers=headers,auth=EscherRequestsAuth("global/services/portshift_request",{'current_time': date},{'api_key': access_key, 'api_secret': secret_key}))

print ("status: ",response.status_code)
print ("list of service users:\n",json.dumps(response.json(),indent=4))

The output:

status:  200
list of service users:
 [
    {
        "id": "145c73ee-66b6-4c19-827f-25d8d3e17bd1",
        "accountId": "51f0bc6b-9612-4665-8971-ee978047f821",
        "lastLogin": "2022-10-17T15:54:26.145Z",
        "fullName": "api_user",
        "description": null,
        "status": "ENABLED",
        "role": "SERVICE",
        "normalizedRole": "Service User",
        "email": null
    }
]

Conclusion:

Once you know all the ingredients for the Escher authentication to program Panoptica REST APIs is just like programming other REST APIs.

You can use “deactivate’ command to deactivate virtual environment and use “rm -r Panoptica” to remove entire directory we created for the virtual environment.