
- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
on 10-21-2022 12:48 PM
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
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.