Skip to content

Latest commit

 

History

History
55 lines (36 loc) · 3.15 KB

SecurityCenter5_REST_API.md

File metadata and controls

55 lines (36 loc) · 3.15 KB
Raw

Basic Usage

The SecurityCenter 5 RESTful API is a significant departure from the JSON/RPC API that SecurityCenter 4 had used. As a result of that, a different methodology was approached to building the API linkage into python. The SC5 module leverages the request module to handle communication between your python code and the API. Further because of this, a lot of the functions that used to be needed in order to make the module useful are no longer needed. Connecting to SecurityCenter using the SC5 API is as simple as the following:

>>> from securitycenter import SecurityCenter5
>>> sc = SecurityCenter5('HOSTNAME')
>>> sc.login('USERNAME','PASSWORD')

Instead of functionalizing every API call thats available, the methodology instead is to provide a base layer into the API, and only functionalize things that are seen to be dofficult and/or cumbersome to handle gracefully. As a result of this, the calls that will be primarially used here are the following:

  • sc.get()
  • sc.post()
  • sc.put()
  • sc.patch()
  • sc.delete()
  • sc.head()

The SecurityCenter5 object will prepend all of the selevent connection information and base API slug. So for example, to get the current status of the SecurityCenter system, you will need to perform the following:

response = sc.get('status')

There has been a convience function added for querying the system, as the analysis API call has a lot of capability, and as such, leverages a fairly complex call. You are ofcourse welcome to use a sc.post call to perform this operation yourself, but sc.analysis() is there to make your life a little easier.

Firstly, the analysis function is coded a it differently than query is in the SC4 API. This is an attempt to both make the function more useful, as well as to conform to the new API calls behind the scene. For example, to get the top 100 most vulnerable hosts, you would perform the following:

hosts = sc.analysis(tool='sumip', page=0, page_size=100, sortDir='desc', sortField='score')

Now if we only wanted the hosts that were part of the 10.10.0.0/16 network range, we would make the following changes:

homenet_hosts = sc.analysis(('ip', '=', '10.10.0.0/16'), tool='sumip', page=0, page_size=100, sortDir='desc',sortField='score')

Filters always exist at the front of the call, and multiple can exist in the same query. For example, if I wanted the vulnerability details of plugin ID 20811 for the hosts in 10.10.0.0/16, I woudl do the following:

details = sc.analysis(('ip', '=', '10.10.0.0/16'), ('pluginID', '=', '20811'), tool='vulndetails')

For more information as to whats possible, please see the Tenable API documentation. Further, there are cases where forcibly sending a bad call (such as an analysis call without a tool) will let you know what can be done.

To better understand what arguments are available for get/post/put/patch/delete/head, please see the python-requests documentation.

Please note that this document will be expanded upon over time.