This post is the first of a series focused on the ESM API. There's no shortage of information on REST APIs, Python and the like for those that have a deeper interest so I'm going to keep this very high level and focus on the "how" as opposed to the "why".

 

The Application Programming Interface (API) is a set of commands that can be issued to the ESM via the web interface. There are a number of tasks that can be completed by executing a command in a script instead of manually logging into the GUI and clicking a series of buttons. You can see a full list of these commands at https://<your-ESM-IP>/rs/esm/help/commands, but here are some examples:

 

alarmGetUnacknowledgedTriggeredAlarms

Retrieves a list of alarms that have been triggered and have not been acknowledged

 

sysAddWatchlistValues

Add values to a watchlist.

 

qryExecuteDetail

Execute a standard detail (non-grouped) query.

 

From these examples, we can start to see how a custom integration with solutions that provide case management, reporting, detection can be performed by querying data from the ESM or inserting values into a watchlist.

 

For this example, we'll use the basic API method (the commands are called methods by the way), to get the current time and version from the ESM. While time from the ESM isn't particularly special, the same script framework is used to setup all of the queries. In our script, we import 3 libraries for use:

1. base64 - to construct the authentication string,

2. json - To parse the return

3. requests* - 3rd party library to handle the HTTP part of the API

* requests is not part of the Python standard library and may be installed via 'pip install requests' or from the official site.

 

The first line after the imports disable the warning about a self signed certificate if you have one. Beyond that, configure the IP address of your ESM, username and password. The same role-based access control that applies to users in the GUI is the same level of access available at the API. Make sure the username has sufficient permissions to access the resources being queried for.

 

The set of lines from 16-29 construct the URLs that will be used. Lines 23-24 perform the initial login and establish the session. Lines 27-38 perform the actual query and print the result. The queries are returned in a format called JSON. For more complex query results, we can convert the results to a dictionary or list and manipulate them, but for this basic example we'll just print the output as a string.

 

 

#!/usr/bin/python

import base64
import requests

requests.packages.urllib3.disable_warnings()

esm_ip = '<ESM-IP>'
username = '<USERNAME>'
passwd = '<PASSWORD>'
query = 'essmgtGetESSTime'

#####################
# Setup some variables for logging in

authString = base64.encodestring('%s:%s' % (username, passwd)).strip()
url = 'https://'+esm_ip+'/rs/esm/'
login_url = url +'login'
login_headers = {'Authorization':'Basic '+authString, 'Content-Type': 'application/json'}
                 
# Create the login session
login_response = requests.post(login_url, headers=login_headers, verify=False)
session = login_response.headers['location']
session_header = {'Authorization':'Session '+session, 'Content-Type': 'application/json'}

# Execute the query
result = requests.post(url + query, headers=session_header, verify=False)
print(result.content)

 

You can paste in some of the other basic methods into query field to get different results. I call them basic because they don't require extra parameters passed beyond the URL. Other methods require some configuration as part of the query but those will be covered in a later post. Any of the methods below could be dropped into the script and will work.