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: restfly.session.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()