Analysis¶

The following methods allow for interaction into the Tenable Security Center analysis API. The analysis area in Tenable Security Center is highly complex and allows for a wide range of varied inputs and outputs. This single endpoint has been broken down in pyTenable to several methods in order to apply some defaults to the expected data-types and options most likely to be returned. As the filters are dependent on the tool and data-type that is being referenced, the best solution to understanding what filters are available when getting started is to simply pass a known bad filter string and use the resulting error as an indicator of what’s available. For example, you could perform the following action below while attempting to see the available filters for the mobile data-type when using the vulndetails tool:

>>> x = sc.analysis.mobile(('something', '=', ''))
>>> x.next()
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    x.next()
  File "tenable/base.py", line 75, in next
    self._get_page()
  File "tenable/sc/analysis.py", line 43, in _get_page
    resp = self._api.post('analysis', json=query).json()
  File "tenable/base.py", line 436, in post
    return self._request('POST', path, **kwargs)
  File "tenable/base.py", line 379, in _request
    raise self._error_codes[status](resp)
ForbiddenError: 00000000-0000-0000-0000-000000000000:403 {"type":"regular",
"response":"","error_code":146,"error_msg":"Invalid parameters specified for
mobile vuln query.  The filter 'something' is invalid (valid filters:
repositoryIDs, port, pluginID, familyID, pluginOutput, lastSeen,
lastMitigated, severity, protocol, pluginName, baseCVSSScore,
exploitAvailable, pluginPublished, pluginModified, vulnPublished,
patchPublished, deviceID, mdmType, deviceModel, serialNumber, deviceUser,
deviceVersion, osCPE).","warnings":[],"timestamp":1545060739}

The resulting error details specifically what filters can be set.

When it comes to constructing filters, TenableSC uses a common filter structure for the collapsed filter-set. This format is in the form of a 3 entry tuple consisting of (‘filtername’, ‘operator’, ‘value’). For example, if you’re looking to set the pluginID filter to 19506 the filter would look like ('pluginID', '=', '19506'). Severities are in level of criticality, from 0 (informational) to 4 (critical). Filters like these can be a string of comma- separated values to indicate multiple items. So for high and critical vulns, ('severity', '=', '3,4') would return only what your looking for.

Asset list calculations in filters are a bit more complex, but still shouldn’t be too difficult. Tenable Security Center leverages nested pairs for the asset calculations combined with a operator to define how that pair are to be combined. Each of the elements within the pair can further be nested, allowing for some quite complex asset list math to happen.

On the simple side, if you just want to look for The the combined results of asset lists 1 or 2, you would perform: ('asset', '~', ('or', 1, 2)). Note the tilda, informing the filtering engine that it will need to perform some sort of calculation first. The tilda is only used when using the asset filter.

Now for a more complex calculation, you could look for the IPs that exist in both 1 or 2, but not 3: ('asset', '~', ('and', ('or', 1, 2), ('not', 3))) As you can see it’s just a matter of nesting out from “1 or 2”. The only new concept here is the paired tuple for not. asking for the inverse of an asset list requires that you wrap it in a tuple with the not operator.

Methods available on sc.analysis:

class AnalysisAPI(api: APISession)[source]¶

console(*filters, **kw)[source]¶

Queries the analysis API for log data from the Tenable Security Center Console itself.

analysis: sclog-type

Parameters:

filters (tuple, optional) – The analysis module provides a more compact way to write filters to the analysis endpoint. The purpose here is to aid in more readable code and reduce the amount of boilerplate that must be written to support a filtered call to analysis. The format is simply a list of tuples. Each tuple is broken down into (field, operator, value).
date (str, optional) – A date in YYYYMM format. the default is simply “all”.
pages (int, optional) – The number of pages to query. Default is all.
limit (int, optional) – How many entries should be in each page? Default is 200.
offset (int, optional) – How many entries to skip before processing. Default is 0.
sort_field (str, optional) – The field to sort the results on.
sort_direction (str, optional) – The direction in which to sort the results. Valid settings are asc and desc. The default is asc.

Returns:

An iterator object handling data pagination.

Return type:

:obj:` AnalysisResultsIterator`

events(*filters, **kw)[source]¶

Queries the analysis API for event data from the Log Correlation Engine

analysis: event-type

Parameters:

filters (tuple, optional) – The analysis module provides a more compact way to write filters to the analysis endpoint. The purpose here is to aid in more readable code and reduce the amount of boilerplate that must be written to support a filtered call to analysis. The format is simply a list of tuples. Each tuple is broken down into (field, operator, value).
pages (int, optional) – The number of pages to query. Default is all.
limit (int, optional) – How many entries should be in each page? Default is 200.
offset (int, optional) – How many entries to skip before processing. Default is 0.
source (str, optional) – The data source location. Allowed sources are lce and archive. Defaults to lce.
silo_id (int, optional) – If a silo id is specified, then the results fetched will be from the lce silo specified and not from the cumulative result set.
sort_field (str, optional) – The field to sort the results on.
sort_direction (str, optional) – The direction in which to sort the results. Valid settings are asc and desc. The default is asc.
tool (str, optional) – The analysis tool for formatting and returning a specific view into the information. If no tool is specified, the default will be vulndetails. Available tools are: listdata, sumasset, sumclassa, sumclassb, sumclassc, sumconns, sumdate, sumdstip, sumevent, sumevent2, sumip, sumport, sumprotocol, sumsrcip, sumtime, sumtype, sumuser, syslog, timedist

Returns:

An iterator object handling data pagination.

Return type:

AnalysisResultsIterator

mobile(*filters, **kw)[source]¶

Queries the analysis API for mobile data collected from querying one or many MDM solutions.

analysis: mobile-type

Parameters:

filters (tuple, optional) – The analysis module provides a more compact way to write filters to the analysis endpoint. The purpose here is to aid in more readable code and reduce the amount of boilerplate that must be written to support a filtered call to analysis. The format is simply a list of tuples. Each tuple is broken down into (field, operator, value).
pages (int, optional) – The number of pages to query. Default is all.
limit (int, optional) – How many entries should be in each page? Default is 200.
offset (int, optional) – How many entries to skip before processing. Default is 0.
sort_field (str, optional) – The field to sort the results on.
sort_direction (str, optional) – The direction in which to sort the results. Valid settings are asc and desc. The default is asc.
tool (str, optional) – The analysis tool for formatting and returning a specific view into the information. If no tool is specified, the default will be vulndetails. Available tools are: listvuln, sumdeviceid, summdmuser, summodel, sumoscpe, sumpluginid, sumseverity, vulndetails

Returns:

An iterator object handling data pagination.

Return type:

AnalysisResultsIterator

scan(scan_id, *filters, **kw)[source]¶

Queries the analysis API for vulnerability data from a specific scan.

analysis: vuln-type

Parameters:

scan_id (int) – If a scan id is specified, then the results fetched will be from the scan specified and not from the cumulative result set.
filters (tuple, optional) – The analysis module provides a more compact way to write filters to the analysis endpoint. The purpose here is to aid in more readable code and reduce the amount of boilerplate that must be written to support a filtered call to analysis. The format is simply a list of tuples. Each tuple is broken down into (field, operator, value).
pages (int, optional) – The number of pages to query. Default is all.
limit (int, optional) – How many entries should be in each page? Default is 200.
offset (int, optional) – How many entries to skip before processing. Default is 0.
source (str, optional) – The data source location. Allowed sources are cumulative and patched. Defaults to cumulative.
sort_field (str, optional) – The field to sort the results on.
sort_direction (str, optional) – The direction in which to sort the results. Valid settings are asc and desc. The default is asc.
tool (str, optional) – The analysis tool for formatting and returning a specific view into the information. If no tool is specified, the default will be vulndetails. Available tools are: cceipdetail, cveipdetail, iavmipdetail, iplist, listmailclients, listservices, listos, listsoftware, listsshservers, listvuln, listwebclients, listwebservers, sumasset, sumcce, sumclassa, sumclassb, sumclassc, sumcve, sumdnsname, sumfamily, sumiavm, sumid, sumip, summsbulletin, sumprotocol, sumremediation, sumseverity, sumuserresponsibility, sumport, trend, vulndetails, vulnipdetail, vulnipsummary
view (str, optional) – The type of vulnerability slice you’d like to have returned. The returned data can be either all, new, or patched. If no view is specified, then the default will be all.

Returns:

An iterator object handling data pagination.

Return type:

AnalysisResultsIterator

Examples

A quick example showing how to get the information for a specific scan from SecurityCenter. As the default is for the scan method to return data from the vulndetails tool, we can handle this without actually doing anything other than calling

>>> for vuln in sc.analysis.scan(1):
...     pprint(vuln)

To ask for a specific subset of information (like only critical and exploitable vulns) you’d want to pass the filter tuples into the query like so:

>>> vulns = sc.analysis.scan(1
...    ('severity', '=', '4'),
...    ('exploitAvailable', '=', 'true'))

To request a different data format (like maybe an IP summary of vulns) you just need to specify the appropriate tool:

>>> ips = sc.analysis.scan(1
...    ('severity', '=', '4'),
...    ('exploitAvailable', '=', 'true'), tool='sumip')

vulns(*filters, **kw)[source]¶

Query’s the analysis API for vulnerability data within the cumulative repositories.

analysis: vuln-type

Parameters:

filters (tuple, optional) – The analysis module provides a more compact way to write filters to the analysis endpoint. The purpose here is to aid in more readable code and reduce the amount of boilerplate that must be written to support a filtered call to analysis. The format is simply a list of tuples. Each tuple is broken down into (field, operator, value).
query_id (int, optional) – The ID number of the SC Query where filters should be pulled from in place of the tuple filters. This is mutually exclusive with the tuple filters.
pages (int, optional) – The number of pages to query. Default is all.
limit (int, optional) – How many entries should be in each page? Default is 200.
offset (int, optional) – How many entries to skip before processing. Default is 0.
source (str, optional) – The data source location. Allowed sources are cumulative and patched. Defaults to cumulative.
scan_id (int, optional) – If a scan id is specified, then the results fetched will be from the scan specified and not from the cumulative result set.
sort_field (str, optional) – The field to sort the results on.
sort_direction (str, optional) – The direction in which to sort the results. Valid settings are asc and desc. The default is asc.
tool (str, optional) – The analysis tool for formatting and returning a specific view into the information. If no tool is specified, the default will be vulndetails. Available tools are: cceipdetail, cveipdetail, iavmipdetail, iplist, listmailclients, listservices, listos, listsoftware, listsshservers, listvuln, listwebclients, listwebservers, sumasset, sumcce, sumclassa, sumclassb, sumclassc, sumcve, sumdnsname, sumfamily, sumiavm, sumid, sumip, summsbulletin, sumprotocol, sumremediation, sumseverity, sumuserresponsibility, sumport, trend, vulndetails, vulnipdetail, vulnipsummary, sumwasurl, wasvulndetail, waslistvuln

Returns:

An iterator object handling data pagination.

Return type:

AnalysisResultsIterator

Examples

A quick example showing how to get all of the information stored in SecurityCenter. As the default is for the vulns method to return data from the vulndetails tool, we can handle this without actually doing anything other than calling

>>> from pprint import pprint
>>> for vuln in sc.analysis.vulns():
...     pprint(vuln)

To ask for a specific subset of information (like only critical and exploitable vulns) you’d want to pass the filter tuples into the query like so:

>>> vulns = sc.analysis.vulns(
...    ('severity', '=', '4'),
...    ('exploitAvailable', '=', 'true'))

To request a different data format (like maybe an IP summary of vulns) you just need to specify the appropriate tool:

>>> ips = sc.analysis.vulns(
...    ('severity', '=', '4'),
...    ('exploitAvailable', '=', 'true'), tool='sumip')