Hosts (risksense_api.__subject.__hosts.__hosts)

Hosts module defined for different hosts related api endpoints.

class risksense_api.__subject.__hosts.__hosts.Hosts(profile)[source]

Bases: Subject

Class for Hosts function defintions.

To utlise Hosts function:

Parameters:

profile (object) – Profile Object

Usage:

self.{risksenseobjectname}.hosts.{function}

Examples

To get dynamic columns using getdynamiccolumns() function

>>> self.rs.hosts.getdynamiccolumns()
__init__(profile)[source]

Initialization of Hosts Object .

Parameters:

profile (object) – Profile Object

downloadfilterinexport(filename, filters, client_id=None)[source]

Exports and Downloads a file based on the filters defined .

Parameters:

  • filename (str) – Name of the file to export as

  • filters (list) – Host search filters based on which the export performs

  • client_id (typing.Optional[int]) – The client id to get the data from. If not supplied, takes default client id

IGNORE INTERNAL FUNCTION

Examples

>>>  self.{risksenseobject}.hosts.downloadfilterinexport('hostdata',[])
create(group_id, group_ids, assessment_id, network_id, ip_address, hostname, subnet, disc_date, client_id=None, scannerFirstDiscoveredOn=None, scannerlastDiscoveredOn=None, services=None, criticality=None, os_scanner=None, createcmdb=None, lockCmdb=None)[source]

Creates a host based on the data provided by the user.

Parameters:

  • group_id (int) – Group ID

  • group_ids (list) – Group IDs

  • assessment_id (int) – Assessment ID

  • network_id (int) – Network ID

  • ip_address (str) – IP Address of host

  • hostname (str) – Hostname

  • subnet (str) – Subnet host belongs to

  • disc_date (str) – Discovered Date (Date formatted as “YYYY-MM-DDTHH:MM:SS”)

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

  • scannerFirstDiscoveredOn (typing.Optional[str]) –

  • scannerlastDiscoveredOn (typing.Optional[str]) –

  • services (typing.Optional[list]) –

  • criticality (typing.Optional[int]) –

  • os_scanner (typing.Optional[int]) –

  • createcmdb (typing.Optional[dict]) –

  • lockCmdb (typing.Optional[dict]) –

Keyword Arguments:

  • scanner_first_discovered_on (str) – Scanner First Discovered On

  • scanner_last_discovered_on (str) – Scanner Last Discovered On

  • criticality (int) – int 1-5

  • services (list) – list A list of dicts, each dict containing portNumber(int), and name (str)

  • os_scanner (str) –

    dict A dict containing name (str), family(str), :obj: class(str),

    vendor(str), product (str), and certainty (int)

  • createcmdb (dict) – dict

  • lockCmdb (dict) – dict

Return type:

int

Returns:

The host ID on the platform is returned.

getdynamiccolumns(client_id=None)[source]

Gets Dynamic columns for the hosts.

Parameters:

client_id (typing.Optional[int]) – If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

list

Returns:

The Dynamic columns

Examples

>>>  self.{risksenseobject}.hosts.getdynamiccolumns()
list_host_filter_fields(client_id=None)[source]

Lists all the host filter data from the platform

Parameters:

client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

list

Returns:

The JSON output from the platform is returned, listing the available filters.

Examples

>>>  self.{risksenseobject}.hosts.list_host_filter_fields()
delete(search_filters, csvdump=False, client_id=None)[source]

Delete hosts based on provided filters.

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The delete Job ID

Examples

To delete a host:

>>>  self.{risksenseobject}.hosts.delete([])

Note

You can also dump the data of the hosts that are going to be deleted in a csv file using csvdump=True argument:

>>>  self.{risksenseobject}.hosts.delete([],csvdump=True)
get_groupby_host(client_id=None)[source]

Gets all the groupby fields for hosts

Parameters:

client_id (typing.Optional[int]) – The client id , if none, default client id is taken

Return type:

dict

Returns:

The group by key metrics

IGNORE INTERNAL FUNCTION .. admonition:: Example

>>>  self.{risksenseobject}.hosts.get_groupby_host()

Note

This function just returns the groupbyfields

post_groupby_host(filters=[], sortorder=None, csvdump=False, client_id=None)[source]

Gets the groupby values for hosts based on the filter provided

Parameters:

  • filters (list) – The filters which will populate in groupby

  • sortorder (typing.Optional[str]) – The order to sort the groupby values, please choose ASC for ascending and DESC for descending

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – The client id , if none, default client id is taken

Return type:

dict

Returns:

The hosts data grouped based on the particular field provided

Example

>>>  self.{risksenseobject}.hosts.post_groupby_host({filter})

The filter must be provided for the group by to be used. The groupby fields will be displayed in the terminal and you must choose a group by filter to which the data will be populated

Note

This function also has an option to dump the data in a csv by a simple argument, csvdump=True

>>>  self.{risksenseobject}.hosts.post_groupby_host({filter},csvdump=True)
update_hosts_attrs(search_filters, csvdump=False, client_id=None, **kwargs)[source]

This function updates hosts attributes based on search filters

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

  • csvdump (bool) – dumps the data in csv

Keyword Arguments:

  • ip_address (str) – IP Address of host

  • hostname (str) – Hostname

  • subnet (str) – Subnet host belongs to

  • discovered_date (str) – Date formatted as “YYYY-MM-DD”

  • criticality (int) – 1-5

  • services (int) – A list of dicts, each dict containing portNumber(int), and name (str)

  • os_scanner (dict) – A dict containing name(str), family (str), class(str), vendor(str), product(str), and certainty(int)

Return type:

int

Returns:

The host ID on the platform is returned.

Example

>>> self.{risksenseobject}.hosts.update_hosts_attrs([],criticality=2)

An example to change the host attributes based on ip address

Note

You can also dump the job id data in a csv by simply using csvdump=True argument

>>> self.{risksenseobject}.hosts.update_hosts_attrs([],criticality=3,csvdump=True)
update_hosts_cmdb(search_filters, client_id=None, **kwargs)[source]

Updates host cmdb

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Keyword Arguments:

  • manufacturer (str) – Manufacturer

  • model_id (str) – Model id

  • mac_address (str) – Mac Address

  • location (str) – Location

  • managed_by (str) – Managed By

  • owned_by (str) – Owned By

  • supported_by (str) – Supported By

  • support_group (str) – Support Group

  • sys_id (str) – Sys id

  • os (str) – Operating System

  • last_scan_date (str) – Date formatted as “YYYY-MM-DD”

  • asset_tag (str) – Asset Tag

  • ferpa (bool) – Ferpa

  • hipaa (bool) – Hipaa

  • pci (bool) – PCI

  • cf_1 (str) – Custom field_1

  • cf_2 (str) – Custom field_2

  • cf_3 (str) – Custom field_3

  • cf_4 (str) – Custom field_4

  • cf_5 (str) – Custom field_5

  • cf_6 (str) – Custom field_6

  • cf_7 (str) – Custom field_7

  • cf_8 (str) – Custom field_8

  • cf_9 (str) – Custom field_9

  • cf_10 (str) – Custom field_10

  • am_1 (str) – Asset Matching field_1

  • am_2 (str) – Asset Matching field_2

  • am_3 (str) – Asset Matching field_3

Return type:

int

Returns:

The job ID

Example

An example to update hosts cmdb with manufacturer name or model id

>>> self.{risksenseobject}.hosts.update_hosts_cmdb([],manufacturer='manufacturername',model_id='R1234')

Use the keyword arguments depending on what cmdb data you need to update

lock_hosts_cmdb(search_filters, client_id=None, **kwargs)[source]

Locks The hosts cmdb data

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Keyword Arguments:

  • manufacturer (str) – Manufacturer

  • business_criticality (int) – business criticality

  • model_id (str) – Model id

  • mac_address (str) – Mac Address

  • location (str) – Location

  • managed_by (str) – Managed By

  • owned_by (str) – Owned By

  • supported_by (str) – Supported By

  • support_group (str) – Support Group

  • sys_id (str) – Sys id

  • os (str) – Operating System

  • last_scan_date (str) – Date formatted as “YYYY-MM-DD”

  • asset_tag (str) – Asset Tag

  • ferpa (bool) – Ferpa

  • hipaa (bool) – Hipaa

  • pci (bool) – PCI

  • cf_1 (str) – Custom field_1

  • cf_2 (str) – Custom field_2

  • cf_3 (str) – Custom field_3

  • cf_4 (str) – Custom field_4

  • cf_5 (str) – Custom field_5

  • cf_6 (str) – Custom field_6

  • cf_7 (str) – Custom field_7

  • cf_8 (str) – Custom field_8

  • cf_9 (str) – Custom field_9

  • cf_10 (str) – Custom field_10

  • am_1 (str) – Asset Matching field_1

  • am_2 (str) – Asset Matching field_2

  • am_3 (str) – Asset Matching field_3

Returns:

The job ID

Example

An example to lock hosts cmdb with manufacturer name or model id

>>> self.{risksenseobject}.hosts.lock_hosts_cmdb([],business_criticality=437)

Use the keyword arguments depending on what cmdb data you need to lock

get_single_search_page(search_filters, projection='basic', page_num=0, page_size=150, sort_field='id', sort_dir='ASC', client_id=None)[source]

Searches for and returns hosts based on the provided filter(s) and other parameters. This gets paginated results data

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • projection (str) – Projection to be used in API request. Projection.BASIC or Projection.DETAIL

  • page_num (int) – The page number of results to be returned.

  • page_size (int) – The number of results per page to be returned.

  • sort_field (str) – The field to be used for sorting results returned.

  • sort_dir (str) – The direction of sorting to be used. SortDirection.ASC or SortDirection.DESC

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

dict

Returns:

The JSON response from the platform is returned.

Example

An example to get single search page of hosts data

>>> self.{risksenseobject}.hosts.get_single_search_page([])

You can also try changing the other arguments to your liking to reflect the data as you suffice such as change page_size or page_num etc.

>>> self.{risksenseobject}.hosts.get_single_search_page([],page_num=2,page_size=10)
search(search_filters, projection='basic', page_size=150, sort_field='id', sort_dir='ASC', csvdump=False, client_id=None)[source]

Searches for and returns hosts based on the provided filter(s) and other parameters. Rather than returning paginated results, this function cycles through all pages of results and returns them all in a single list.

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • projection (str) – Projection to be used in API request. Projection.BASIC or Projection.DETAIL

  • page_size (int) – The number of results per page to be returned.

  • sort_field (str) – The field to be used for sorting results returned.

  • sort_dir (str) – The direction of sorting to be used. SortDirection.ASC or SortDirection.DESC

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

list

Returns:

A list containing all hosts returned by the search using the filter provided.

Example

An example to search for host data is

>>> self.{risksenseobject}.hosts.search([])

Where [] is the search filter for all hosts, you can provide your search filter there.

Note

You can also dump the search based data in a csv by simply providing csvdump=True argument

>>> self.{risksenseobject}.hosts.search([],csvdump=True)
get_count(search_filters, client_id=None)[source]

Gets a count of hosts identified using the provided filter(s).

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The number of hosts identified using the provided filter(s).

Example

An example to use get count function is as follows

>>> self.{risksenseobject}.hosts.get_count([])

Where [] is the search filter for all hosts, you can provide your search filter there.

add_tag(search_filters, tag_id, csvdump=False, client_id=None)[source]

Adds a tag to host(s).

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • tag_id (int) – ID of tag to tbe added to host(s).

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to add a tag is

>>> self.{risksenseobject}.hosts.add_tag([],1234)

Where

[] is the search filter for all hosts, you can provide your search filter there.

1234 is the tag id

Note

You can also dump the hosts from the search filters post the tag completion for more information by csvdump=True argument

>>> self.{risksenseobject}.hosts.add_tag([],1234,csvdump=True)
remove_tag(search_filters, tag_id, csvdump=False, client_id=None)[source]

Removes a tag from host(s).

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • tag_id (int) – ID of tag to be removed from host(s).

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

  • csvdump (bool) – dumps the data in csv

Return type:

int

Returns:

The job ID is returned.

Example

An example to use remove tag is

>>> self.{risksenseobject}.hosts.remove_tag([],123)

Where

[] is the search filter for all hosts, you can provide your search filter there.

123 is the tag id

Note

You can also dump the hosts which the tags will be removed from with a csvdump=True argument

>>> self.{risksenseobject}.hosts.remove_tag([],123,csvdump=True)
getexporttemplate(client_id=None)[source]

Gets configurable export template for Hosts.

Parameters:

client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

list

Returns:

The Exportable fields

Example

An example to use getexporttemplate

>>> self.{risksenseobject}.hosts.getexporttemplate()

This gets all the export templates for hosts

merge_host(search_filter, host_id_to_merge_to, csvdump=False, client_id=None)[source]

Merges host(s).

Parameters:

  • search_filter (list) – A list of dictionaries containing filter parameters.

  • host_id_to_merge_to (int) – The host id to which the hosts based on the filter will be merged to

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, it will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use merge_host is

>>> self.{risksenseobject}.hosts.merge_host([],123)

Where

[] is the search filter for all hosts, you can provide your search filter there.

123 is the host id to which the hosts will be merged to.

Note

You can also dump the hosts that are going to be merged before merging them by csvdump=True argument

>>> self.{risksenseobject}.hosts.merge_host([],123,csvdump=True)
set_asset_criticality(filter, assetcriticality, csvdump=False, client_id=None)[source]

Sets asset criticality of the host.

Parameters:

  • filter (list) – Search filters

  • assetcriticality (int) – The asset criticality to provide.

  • csvdump (bool) – Dump the csv data.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use set_asset_criticality is

>>> self.{risksenseobject}.hosts.set_asset_criticality([],4)

Where

[] is the search filter for all hosts, you can provide your search filter there.

4 is the criticality of the asset to set to

Note

You can also dump the hosts to which asset criticality should be changed by csvdump=True argument

>>> self.{risksenseobject}.hosts.set_asset_criticality([],4,csvdump=True)
set_address_type(filter, addresstype, csvdump=False, client_id=None)[source]

Sets address type of the host.

Parameters:

  • filter (list) – Search filters

  • addresstype (str) – Provide external for external address and internal for internal

  • csvdump (bool) – Dump the csv data.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use set_address_type is

>>> self.{risksenseobject}.hosts.set_address_type([],'external')

Where

[] is the search filter for all hosts, you can provide your search filter there.

external is to set the address type as external address.

Note

You can also dump the hosts which the address type will be set by csvdump=True argument

>>> self.{risksenseobject}.hosts.set_address_type([],'external',csvdump=True)
export(search_filters, file_name, row_count='All', file_type='CSV', client_id=None)[source]

Initiates an export job on the platform for host(s) based on the provided filter(s).

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • file_name (str) – The name to be used for the exported file.

  • row_count (str) – No of rows to be exported. Available options ExportRowNumbers.ROW_10000, ExportRowNumbers.ROW_25000, ExportRowNumbers.ROW_50000, ExportRowNumbers.ROW_100000, ExportRowNumbers.ROW_ALL

  • file_type (str) – File type to export. ExportFileType.CSV, ExportFileType.JSON, or ExportFileType.XLSX

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID in the platform from is returned.

Example

An example to use export is

>>> self.{risksenseobject}.hosts.export([],'testingexport')

Where

[] is the search filter for all hosts, you can provide your search filter there.

testingexport is the filename to export the file to

You can change the filetype to any of the names above or even the other positional arguments as mentioned

>>> self.{risksenseobject}.hosts.export([],'testingexport',file_type=ExportFileType.JSON)
network_move(search_filters, network_identifier, is_force_merge=False, csvdump=False, client_id=None)[source]

Moves host(s) into a new network as specified.

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • network_identifier (int) – Network ID to move the hosts to

  • is_force_merge (bool) – Force merge of hosts?

  • csvdump (bool) – Dump the csv data.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use network_move is

>>> self.{risksenseobject}.hosts.network_move([],12345,False)

Where

[] is the search filter for all hosts, you can provide your search filter there.

12345 is the network id to which the hosts will move to

False is to not force merge the hosts

Note

You can also dump the hosts that are going to be moved before moving them by csvdump=True argument

>>> self.{risksenseobject}.hosts.network_move([],12345,False,csvdump=True)
run_urba(search_filters, csvdump=False, client_id=None)[source]

Initiates the update of remediation by assessment for hosts specified in filter(s).

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • csvdump (bool) – Dump the data in csv

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, it will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use run_urba is

>>> self.{risksenseobject}.hosts.run_urba([])

Where

[] is the search filter for all hosts, you can provide your search filter there.

This will run the urba for all the hosts fetched from the search filter

Note

You can also dump the hosts to which urba is being run by csvdump=True argument

>>> self.{risksenseobject}.hosts.run_urba([],csvdump=True)
add_note(search_filters, new_note, csvdump=False, client_id=None)[source]

Adds a note to host(s) based on the filter(s) provided.

Parameters:

  • search_filters (list) – A list of dictionaries containing filter parameters.

  • new_note (str) – The note to be added to the host(s).

  • csvdump (bool) – Dump the csv data.

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

Return type:

int

Returns:

The job ID is returned.

Example

An example to use add_note is

>>> self.{risksenseobject}.hosts.add_note([],'test')

Where

[] is the search filter for all hosts, you can provide your search filter there.

test is the note which will be given to the hosts

Note

You can also dump the hosts to which notes will be added post adding the note by csvdump=True argument

>>> self.{risksenseobject}.hosts.add_note([],'test',csvdump=True)
get_model(client_id=None)[source]

Get available projections and models for Hosts.

Parameters:

client_id (typing.Optional[int]) – Client ID

Return type:

dict

Returns:

Hosts projections and models are returned.

Example

An example to use get_model is

>>> self.{risksenseobject}.hosts.get_model()
suggest(search_filter_1, search_filter_2, client_id=None)[source]

Suggest values for filter fields.

Parameters:

  • search_filter_1 (list) – Search Filter 1

  • search_filter_2 (dict) – Search Filter 2

  • client_id (typing.Optional[int]) – Client ID

Return type:

list

Returns:

Value suggestions

Example

To use suggest function is

>>> self.{risksenseobject}.hosts.suggest([],{})

Where

[] is the first search filter

{} is the seconf search filter

add_group(search_filter, group_ids, csvdump=False, client_id=None)[source]

Add host(s) to one or more groups.

Parameters:

  • search_filter (list) – Search filter

  • group_ids (list) – List of Group IDs to add to host(s).

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID

Return type:

int

Returns:

Job ID of group add job

Example

An example to use add_group is

>>> self.{risksenseobject}.hosts.add_group([],[2,3,4])

Where

[] is the search filter for all hosts, you can provide your search filter there.

[2,3,4] are the group ids to add the hosts to .

Note

You can also dump the hosts which will be addedd to the groups by csvdump=True argument

>>> self.{risksenseobject}.hosts.add_group([],[2,3,4],csvdump=True)
remove_group(search_filter, group_ids, csvdump=False, client_id=None)[source]

Remove host(s) from one or more groups.

Parameters:

  • search_filter (list) – Search filter

  • group_ids (list) – List of Group IDs to add to host(s).

  • csvdump (bool) – dumps the data in csv

  • client_id (typing.Optional[int]) – Client ID

Return type:

int

Returns:

Job ID of group remove job

Example

An example to use remove_group is

>>> self.{risksenseobject}.hosts.remove_group([],[2,3,4])

Where

[] is the search filter for all hosts, you can provide your search filter there.

[2,3,4] are the group ids to remove the hosts from .

Note

You can also dump the hosts which will be removed from the groups by csvdump=True argument

>>> self.{risksenseobject}.hosts.remove_group([],[2,3,4],csvdump=True)
risksense_api.__subject.__hosts.__hosts.apply_system_filters(self, csvdump=False, client_id=None)[source]

Get data of the hosts based on system filter.

Parameters:

  • client_id (typing.Optional[int]) – Client ID. If an ID isn’t passed, will use the profile’s default Client ID.

  • csvdump (bool) – dumps the data in csv

Return type:

list

Returns:

The data of the system filter based host values are returned

Example

An example to use apply_system_filters is

>>> self.{risksenseobject}.hosts.apply_system_filters()

Where

[] is the search filter for all hosts, you can provide your search filter there.

The system filters will be displayed in the terminal to which you must provide a key value and the data returned will reflect based on the system filter chosrn

Note

You can also dump the hosts from the system filters search by csvdump=True argument

>>> self.{risksenseobject}.hosts.apply_system_filters(csvdump=True)