Hosts

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

Methods available on sc.hosts:

class HostsAPI(api: APISession)[source]
list(fields: List[str] | None = None, limit: int = 10000, offset: int = 0, pages: int | None = None, pagination: bool = True, return_json: bool = False) → HostsResultsIterator | Dict[source]

Retrieve the list of hosts from the system.

Parameters:

  • fields (list[str], optional) – What fields should be returned in the response.

  • limit (int, 1000) – How many hosts should be returned?

  • offset (int, 0) – At what index should

  • pages (int, optional) – The maximum number of pages to return for the iterator.

  • pagination (bool, False) – Should pagination be used?

  • return_json (bool, False) – Should we return the json response instead of an iterator?

Response:

The response will be either the HostResultsIterator to handle pagination of the data (preferred) or the raw response from the API (if return_json is set to True).

Examples

>>> for host in sc.hosts.list():
...     print(host)
search(*filters: Tuple[str, str, str], filter_type: Literal['and', 'or'] = 'and', fields: List[str] | None = None, limit: int = 10000, offset: int = 0, pages: int | None = None, pagination: bool = True, return_json: bool = False) → HostsResultsIterator | Dict[source]

Retrieve the list of hosts from the system.

Parameters:

  • filters (list[tuple[str, str, str]], optional) – List of search filter tuples.

  • filter_type (Literal['and', 'or'], optional) – The filtering boolean logic to use for multiple filters. If left unspecified it defaults to and.

  • fields (list[str], optional) – What fields should be returned in the response.

  • limit (int, 1000) – How many hosts should be returned?

  • offset (int, 0) – At what index should

  • pages (int, optional) – The maximum number of pages to return for the iterator.

  • pagination (bool, False) – Should pagination be used?

  • return_json (bool, False) – Should we return the json response instead of an iterator?

Response:

The response will be either the HostResultsIterator to handle pagination of the data (preferred) or the raw response from the API (if return_json is set to True).

Examples

>>> for host in sc.hosts.search(filters=[('ip', 'eq', '1.2.3.4')]):
...     print(host)
update_acr(host_uuid: str, reasoning: List[int] | None = None, score: int | None = None, notes: str | None = None, overwritten: bool = True) → Dict[source]

Override the Asset Criticality Rating (ACR) score and the reasons for the specified host.

Parameters:

  • host_uuid (str) – The Host UUID to modify

  • reasonings (list[int], optional) – The list of reasoning objects noting why the score was changed

  • score (int, optional) – The updated ACR score

  • notes (str, optional) – Notes detailing why the score was changed

  • overwritten (bool) – Should we use the overwritten score or the default one?

Returns:

The updated host object.

Example

>>> sc.host.update_acr(
...     host_uuid='12345678-1234-1234-123456789012',
...     score=7,
...     reasonings=[4],
...     notes='Why we changed this score...',
... )