Asset Lists¶

The following methods allow for interaction into the Tenable Security Center Assets API. These items are typically seen under the Assets section of Tenable Security Center.

Methods available on sc.asset_lists:

class AssetListAPI(api: APISession)[source]¶

create(name, list_type, **kw)[source]¶

Creates an asset-list.

asset-list: create

Parameters:

name (str) – The name for the asset list to create.
list_type (str) – The type of list to create. Supported values are combination, dnsname, dnsnameupload, dynamic, ldapquery, static, staticeventfilter, staticvulnfilter, templates, upload, watchlist, watchlisteventfilter, and watchlistupload.
combinations (tuple, optional) – An asset combination tuple. For further information refer to the asset combination logic described at tenable.sc.analysis.
data_fields (list, optional) – A list of data fields as required for a given asset list type. Each item within the list should be formatted in the following way: {'fieldName': 'name', 'fieldValue': 'value'}
description (str, optional) – The description for the asset list being created.
dn (str, optional) – The base DN to use for an LDAP query. Must also provide a search_string and an ldap_id.
dns_names (list, optional) – When defining a DNS asset list, use this attribute to provide the list of DNS addresses.
exclude_managed_ips (bool, optional) – Determines whether or not managed IPs should be excluded from the asset list.
filters (list, optional) – A list of filter tuples to use when defining filtered asset list types. Follows the same format as filters within the rest of pyTenable.
fobj (FileObject, optional) – A file-like object to use when uploading an asset list.
ips (list, optional) – A list of IP Addresses, CIDRs, and/or IP Address ranges to use for the purposes of a static asset list.
lce_id (int, optional) – When defining a event-based asset list, which LCE should be used to generate the asset list query.
ldap_id (int, optional) – The numeric identifier pertaining to the LDAP server to use for an LDAP query. must also provide a dn and a search_string.
prep (bool, optional) – Should asset preparation be run after the list is created? If unspecified, the default action is True.
rules (tuple, optional) –
For a dynamic asset list, the tuple definition of the rules to determine what Ips are associated to this asset list. Rules follow a similar pattern to the asset combination logic and are written in a way to follow the same visual methodology as the UI.

For example, a simple dynamic ruleset may look like:
```
('any', ('dns', 'contains', 'svc.company.tld'),
        ('dns', 'contains', 'prod.company.tld'))
```
Which would match all assets with either svc.company.tld or prod.company.tld in their DNS names. Rule gropups can be nested as well, by supplying a new group tuple instead of a rule:
```
('any', ('dns', 'contains', 'svc.company.tld'),
        ('dns', 'contains', 'prod.company.tld'),
        ('any', ('ip', 'contains', '192.168.140'),
                ('ip', 'contains', '192.168.141')))
```
In this example we have nested another group requiring that the ip may contain either of the values in addition to any of the DNS rules.

It’s also possible to constrain the rule to a specific plugin or plugins as well by adding a 4th element in a rule tuple. Defining them would look like so:
```
# Singular Plugin ID
('plugintext', 'contains', 'credentialed', 19506)
# Multiple Plugin IDs
('plugintext', 'contains', 'stuff', [19506, 10180])
```
- Available rules are dns, exploitAvailable, exploitFrameworks, firstseen, mac, os, ip, uuid, lastseen, netbioshost, netbiosworkgroup, pluginid, plugintext, port, severity, sshv1, sshv2, tcpport, udpport, and xref.
- Available operators are contains, eq, lt, lte, ne, gt, gte, regex, pcre.
- Group alauses are either any or all. Any is a logical or. All is a logical and.
scan_id (int, optional) – When defining an “individual” source_type, the numeric id of the scan instance to base the query upon.
search_string (str, optional) – The search string to use as part of an LDAP Query. Must also provide a dn and an ldap_id.
sort_dir (str, optional) – When defining a filtered asset list type, determines the direction of the sort to use. This field must be passed when defining a sort_field.
sort_field (str, optional) – When defining a filtered asset list type, determines what field to sort the resulting query on.
source_type (str, optional) – The source of the data to query from when defining a filtered asset list type.
start_offset (int, optional) – The start offset of the filter to use when defining a filtered asset list type.
tags (str, optional) – A tag to associate to the asset list.
template (int, optional) – The numeric id of the template to use.
tool (str, optional) – When specifying filtered asset list types, the analysis tool to use for determining what IPs should be included within the asset list.
view (str, optional) – When the source_type is “individual”, the view defined what subset of the data to use.

Returns:

The newly created asset-list.

Return type:

dict

Examples

>>> asset-list = sc.asset_lists.create()

delete(id)[source]¶

Removes a asset-list.

asset-list: delete

Parameters:: id (int) – The numeric identifier for the asset-list to remove.
Returns:: The deletion response dict
Return type:: dict

Examples

>>> sc.asset_lists.delete(1)

details(id, org_id=None, fields=None)[source]¶

Returns the details for a specific asset-list.

asset-list: details

Parameters:

id (int) – The identifier for the asset-list.
org_id (int, optional) – The organizationID for the asset-list.
fields (list, optional) – A list of attributes to return.

Returns:

The details of asset id.

Return type:

dict

Examples

>>> asset_id_details = sc.asset_lists.details(1,1)
>>> pprint(asset_id_details)

edit(id, **kw)[source]¶

Edits an asset-list.

asset-list: edit

Parameters:

id (int) – The numeric id of the asset list to edit.
combinations (tuple, optional) – An asset combination tuple. For further information refer to the asset combination logic described at tenable.sc.analysis.
data_fields (list, optional) – A list of data fields as required for a given asset list type. Each item within the list should be formatted in the following way: {'fieldName': 'name', 'fieldValue': 'value'}
description (str, optional) – The description for the asset list being created.
dn (str, optional) – The base DN to use for an LDAP query. Must also provide a search_string and an ldap_id.
dns_names (list, optional) – When defining a DNS asset list, use this attribute to provide the list of DNS addresses.
exclude_managed_ips (bool, optional) – Determines whether or not managed IPs should be excluded from the asset list.
filters (list, optional) – A list of filter tuples to use when defining filtered asset list types. Follows the same format as filters within the rest of pyTenable.
fobj (FileObject, optional) – A file-like object to use when uploading an asset list.
ips (list, optional) – A list of IP Addresses, CIDRs, and/or IP Address ranges to use for the purposes of a static asset list.
lce_id (int, optional) – When defining a event-based asset list, which LCE should be used to generate the asset list query.
ldap_id (int, optional) – The numeric identifier pertaining to the LDAP server to use for an LDAP query. must also provide a dn and a search_string.
name (str, optional) – The name for the asset list to create.
prep (bool, optional) – Should asset preparation be run after the list is created? If unspecified, the default action is True.
rules (tuple, optional) – For a dynamic asset list, the tuple definition of the rules to determine what Ips are associated to this asset list. Rules follow a similar pattern to the asset combination logic and are written in a way to follow the same visual methodology as the UI.
scan_id (int, optional) – When defining an “individual” source_type, the numeric id of the scan instance to base the query upon.
search_string (str, optional) – The search string to use as part of an LDAP Query. Must also provide a dn and an ldap_id.
sort_dir (str, optional) – When defining a filtered asset list type, determines the direction of the sort to use. This field must be passed when defining a sort_field.
sort_field (str, optional) – When defining a filtered asset list type, determines what field to sort the resulting query on.
source_type (str, optional) – The source of the data to query from when defining a filtered asset list type.
start_offset (int, optional) – The start offset of the filter to use when defining a filtered asset list type.
tags (str, optional) – A tag to associate to the asset list.
template (int, optional) – The numeric id of the template to use.
tool (str, optional) – When specifying filtered asset list types, the analysis tool to use for determining what IPs should be included within the asset list.
type (str, optional) – The type of list to create. Supported values are combination, dnsname, dnsnameupload, dynamic, ldapquery, static, staticeventfilter, staticvulnfilter, templates, upload, watchlist, watchlisteventfilter, and watchlistupload.
view (str, optional) – When the source_type is “individual”, the view defined what subset of the data to use.

Returns:

The newly updated asset-list.

Return type:

dict

Examples

>>> asset-list = sc.asset_lists.edit()

export_definition(id, fobj=None)[source]¶

Exports an asset list definition and stored the data in the file-like object that was passed.

asset-list: export

Parameters:

id (int) – The numeric identifier for the asset list to export.
fobj (FileObject) – The file-like object to store the asset list XML definition.

Returns:

The file-like object containing the XML definition.

Return type:

FileObject

Examples

>>> with open('example.xml', 'wb') as fobj:
...     sc.asset_lists.export_definition(1, fobj)

import_definition(fobj, name=None)[source]¶

Imports an asset list definition from an asset list definition XML file.

asset-list: import

Parameters:

name (str) – The name of the asset definition to create.
fobj (FileObject) – The file-like object containing the XML definition.

Returns:

The created asset list from the import.

Return type:

dict

Examples

>>> with open('example.xml', 'rb') as fobj:
...     sc.asset_lists.import_definition('Example', fobj)

ldap_query(ldap_id, dn, search_string)[source]¶

Performs a LDAP test query on the specified LDAP service configured.

asset-list: test-ldap-query

Parameters:

ldap_id (int) – The numeric identifier for the configured LDAP service.
dn (str) – The valid search base to use.
search_string (str) – The search string to query the LDAP service with.

Returns:

The LDAP response.

Return type:

dict

Examples

>>> resp = sc.asset_lists.ldap_query(1, 'domain.com', '*')

list(fields=None)[source]¶

Retrieves the list of asset list definitions.

asset-list: list

Parameters:: fields (list, optional) – A list of attributes to return for each asset-list.
Returns:: A list of asset-list resources.
Return type:: list

Examples

>>> for asset-list in sc.asset_lists.list():
...     pprint(asset-list)

refresh(id, org_id, *repos)[source]¶

Initiates an on-demand recalculation of the asset list. Note this endpoint requires being logged in as an admin user.

asset-list: refresh

Parameters:

id (int) – The numeric identifier of the asset list to refresh.
org_id (int) – The organization associated to the asset list.
*repos (int) – Repository ids to perform the recalculation on.

Returns:

Response of the items that the asset list is associated to.

Return type:

dict

Examples

Perform the refresh against a single repo:

>>> sc.asset_lists.refresh(1, 1, 1)

Perform the refresh against many repos:

>>> sc.asset_lists.refresh(1, 1, 1, 2, 3)

share(id, *groups)[source]¶

Shares the specified asset list to another user group.

asset-lists: share

Parameters:

id (int) – The numeric id for the credential.
*groups (int) – The numeric id of the group(s) to share to.

Returns:

The updated asset-list resource.

Return type:

dict

Examples

>>> sc.asset_lists.share(1, group_1, group_2)

tags()[source]¶

Retrieves the list of unique tags associated to asset lists.

asset-lists: tags

Returns:: List of tags
Return type:: list

Examples

>>> tags = sc.asset_lists.tags()