4.4.1. Device assets¶

API for working with device assets.

class axonius_api_client.api.assets.devices.Devices(auth, **kwargs)[source]¶

Bases: axonius_api_client.api.assets.asset_mixin.AssetMixin

API for working with device assets.

Examples

For all examples for this asset type, create a client using axonius_api_client.connect.Connect and assume apiobj is client.devices

>>> apiobj = client.devices

Get count of assets: count()
Get count of assets from a saved query: count_by_saved_query()
Get assets: get()
Get assets from a saved query: get_by_saved_query()
Get the full data set for a single asset: get_by_id()
Work with saved queries: axonius_api_client.api.assets.saved_query.SavedQuery
Work with fields: axonius_api_client.api.assets.fields.Fields
Work with tags: axonius_api_client.api.assets.labels.Labels

See also

User assets axonius_api_client.api.assets.users.Users

Parameters: auth (axonius_api_client.auth.models.Model) –

property fields_default¶

Fields to use by default for getting assets.

Return type: typing.List[str]

property router¶

Router for this API model.

Return type: axonius_api_client.api.routers.Router

get_by_hostnames(values, **kwargs)[source]¶

Build a query to get assets where FIELD_HOSTNAME in values.

Parameters

values (typing.List[str]) – list of hostnames
**kwargs – passed to get_by_values()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_hostname_regex(value, **kwargs)[source]¶

Build a query to get assets where FIELD_HOSTNAME regex matches value.

Parameters

value (str) – regex of hostname to match
**kwargs – passed to get_by_value_regex()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_hostname(value, **kwargs)[source]¶

Build a query to get assets where FIELD_HOSTNAME == value.

Parameters

value (str) – hostname
**kwargs – passed to get_by_value()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_macs(values, **kwargs)[source]¶

Build a query to get assets where FIELD_MAC in values.

Parameters

values (typing.List[str]) – list of mac addresss
**kwargs – passed to get_by_values()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_mac_regex(value, **kwargs)[source]¶

Build a query to get assets where FIELD_MAC regex matches value.

Parameters

value (str) – regex of mac adress to match
**kwargs – passed to get_by_value_regex()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_mac(value, **kwargs)[source]¶

Build a query to get assets where FIELD_MAC == value.

Parameters

value (str) – mac adress
**kwargs – passed to get_by_value()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_ips(values, **kwargs)[source]¶

Build a query to get assets where FIELD_IP in values.

Parameters

values (typing.List[str]) – list of ip address
**kwargs – passed to get_by_values()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_ip_regex(value, **kwargs)[source]¶

Build a query to get assets where FIELD_IP regex matches value.

Parameters

values – regex of ip address to match to match
**kwargs – passed to get_by_value_regex()
value (str) –

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_ip(value, **kwargs)[source]¶

Build a query to get assets where FIELD_IP == value.

Parameters

value (str) – ip address
**kwargs – passed to get_by_value()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_subnet(value, not_flag=False, pre='', post='', **kwargs)[source]¶

Build a query to get assets where ip address is in FIELD_IP_RAW.

Parameters

value (str) – subnet
**kwargs – passed to get()
not_flag (bool) –
pre (str) –
post (str) –

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

FIELD_ASSET_NAME: str = 'specific_data.data.name'¶: Asset Name field.

FIELD_HOSTNAME: str = 'specific_data.data.hostname'¶: Hostname field.

FIELD_IP: str = 'specific_data.data.network_interfaces.ips'¶: Network Interfaces IPs field.

FIELD_IP_RAW: str = 'specific_data.data.network_interfaces.ips_raw'¶: Network Interfaces IPs raw field.

FIELD_MAC: str = 'specific_data.data.network_interfaces.mac'¶: Network Interfaces MACs field.

FIELD_SUBNET: str = 'specific_data.data.network_interfaces.subnets'¶: Network Interfaces Subnets field.

FIELD_OS_TYPE: str = 'specific_data.data.os.type'¶: OS Type field.

FIELDS_API: List[str] = ['internal_axon_id', 'adapters', 'labels', 'adapter_list_length']¶

FIELD_ADAPTERS: str = 'adapters'¶

FIELD_ADAPTER_LEN: str = 'adapter_list_length'¶

FIELD_AXON_ID: str = 'internal_axon_id'¶

FIELD_LAST_SEEN: str = 'specific_data.data.last_seen'¶

FIELD_TAGS: str = 'labels'¶

__init__(auth, **kwargs)¶

Mixins for API Models.

Parameters

auth (axonius_api_client.auth.models.Model) – object to use for auth and sending API requests
**kwargs – passed to _init()

__repr__()¶

Show info for this model object.

Return type: str

__str__()¶

Show info for this model object.

Return type: str

_build_err_msg(response, error=None, exc=None)¶

Build an error message from a response.

Parameters

response (requests.Response) – response that originated the error
error (typing.Optional[str]) – error message to include in exception
exc (typing.Optional[Exception]) – exception that was thrown if any

Return type

str

_build_query(inner, not_flag=False, pre='', post='')¶

Query builder with basic functionality.

Notes

It is better to use wizard, wizard_text, or wizard_csv to build queries!

Parameters

inner (str) – inner query portion to wrap in parens and prefix with not
not_flag (bool) – prefix query with ‘not’
pre (str) – query to add to the beginning of the query
post (str) – query to add to the end of the query

Return type

str

_check_response_code(response, error_status=True)¶

Check the status code of a response.

Parameters

response – requests.Response object to check
error_status (bool) – throw exc if response status code is bad

Raises

ResponseNotOk – if response has a status code that is an error and error_status is True

_check_response_json(response, error_json_bad_status=True, error_json_invalid=True, uses_api_response=False)¶

Check the text body of a response is JSON.

Parameters

response – requests.Response object to check
error_json_bad_status (typing.Optional[bool]) – throw an exc if error key is not empty or status key == error
error_json_invalid (typing.Optional[bool]) – throw an exc if response is invalid json
uses_api_response (typing.Optional[bool]) –

Raises

JsonInvalid – if error_json_invalid is True and response has invalid json
JsonError – if error_json_bad_status is True and response is a json dict that has a non-empty error key or a status key that == error

Return type

typing.Any

_count(query=None, history_date=None)¶

Private API method to get the count of assets.

Parameters

query (typing.Optional[str]) – if supplied, only return the count of assets that match the query
history_date (typing.Optional[str]) – return count for a given historical date

Return type

int

_destroy(destroy, history)¶

Private API method to destroy ALL assets.

Parameters

destroy (bool) – Must be true in order to actually perform the delete
history (bool) – Also delete all historical information

Return type

dict

_get(query=None, fields=None, row_start=0, page_size=2000, include_details=False, history_date=None, sort_field=None, sort_descending=False)¶

Private API method to get a page of assets.

Parameters

query (typing.Optional[str]) – if supplied, only return the assets that match the query
fields (typing.Union[typing.List[str], str, None]) – CSV or list of fields to include in return
row_start (int) – start at row N
page_size (int) – fetch N assets
include_details (bool) – include details fields showing the adapter source of agg values
sort_field (typing.Optional[str]) – sort the returned assets on a given field
sort_descending (bool) – reverse the sort of the returned assets
history_date (typing.Optional[str]) – return assets for a given historical date

Return type

dict

_get_by_id(id)¶

Private API method to get the full metadata of all adapters for a single asset.

Parameters: id (str) – internal_axon_id of asset to get all metadata for
Return type: dict

_get_cursor(query=None, fields=None, row_start=0, page_size=2000, cursor=None, include_details=False, history_date=None, sort_field=None, sort_descending=False)¶

Private API method to get a page of assets using a cursor.

Parameters

query (typing.Optional[str]) – if supplied, only return the assets that match the query
fields (typing.Union[typing.List[str], str, None]) – CSV or list of fields to include in return
row_start (int) – start at row N
page_size (int) – fetch N assets
include_details (bool) – include details fields showing the adapter source of agg values
sort_field (typing.Optional[str]) – sort the returned assets on a given field
sort_descending (bool) – reverse the sort of the returned assets
history_date (typing.Optional[str]) – return assets for a given historical date
cursor (typing.Optional[str]) – cursor returned by previous call to continue paging through

Return type

dict

_history_dates()¶

Private API method to get all known historical dates.

Return type: dict

_init(**kwargs)¶: Post init method for subclasses to use for extra setup.

_page_cursor(state, store)¶

Get a page of assets using the cursor get method.

Parameters

state (dict) – current state tracker of get()
store (dict) – current store tracker of get()

Return type

dict

_page_normal(state, store)¶

Get a page of assets using the normal get method.

Parameters

state (dict) – current state tracker of get()
store (dict) – current store tracker of get()

Return type

dict

count(query=None, history_date=None, wiz_entries=None)¶

Get the count of assets from a query.

Examples

Get count of all assets

>>> count = apiobj.count()

Get count of all assets for a given date

>>> count = apiobj.count(history_date="2020-09-29")

Get count of assets matching a query built by the GUI query wizard

>>> query='(specific_data.data.name == "test")'
>>> count = apiobj.count(query=query)

Get count of assets matching a query built by the API client query wizard

>>> entries = [{'type': 'simple', 'value': 'name equals test'}]
>>> count = apiobj.count(wiz_entries=entries)

Parameters

query (typing.Optional[str]) – if supplied, only return the count of assets that match the query if not supplied, the count of all assets will be returned
history_date (typing.Union[str, datetime.timedelta, datetime.datetime, None]) – return asset count for a given historical date
wiz_entries (typing.Optional[typing.List[dict]]) – wizard expressions to create query from

Return type

int

count_by_saved_query(name, history_date=None)¶

Get the count of assets for a query defined in a saved query.

Examples

Get count of assets returned from a saved query

>>> count = apiobj.count_by_saved_query(name="test")

Get count of assets returned from a saved query for a given date

>>> count = apiobj.count_by_saved_query(name="test", history_date="2020-09-29")

Parameters

name (str) – saved query to get count of assets from
history_date (typing.Union[str, datetime.timedelta, datetime.datetime, None]) – return count for a given historical date

Return type

int

destroy(destroy, history)¶

Delete ALL assets.

Notes

Enable the Enable API destroy endpoints setting under Settings > Global Settings > API Settings > Enable advanced API settings for this method to function.

Parameters

destroy (bool) – Must be true in order to actually perform the delete
history (bool) – Also delete all historical information

Return type

dict

get(generator=False, **kwargs)¶

Get assets from a query.

Examples

Get all assets with the default fields defined in the API client

>>> assets = apiobj.get()

Get all assets using an iterator

>>> assets = [x for x in apiobj.get(generator=True)]

Get all assets with fields that equal names

>>> assets = apiobj.get(fields=["os.type", "aws:aws_device_type"])

Get all assets with fields that fuzzy match names and no default fields

>>> assets = apiobj.get(fields_fuzzy=["last", "os"], fields_default=False)

Get all assets with fields that regex match names a

>>> assets = apiobj.get(fields_regex=["^os\."])

Get all assets with all root fields for an adapter

>>> assets = apiobj.get(fields_root="aws")

Get all assets for a given date in history and sort the rows on a field

>>> assets = apiobj.get(history_date="2020-09-29", sort_field="name")

Get all assets with details of which adapter connection provided the agg data

>>> assets = apiobj.get(include_details=True)

Get assets matching a query built by the GUI query wizard

>>> query='(specific_data.data.name == "test")'
>>> assets = apiobj.get(query=query)

Get assets matching a query built by the API client query wizard

>>> entries=[{'type': 'simple', 'value': 'name equals test'}]
>>> assets = apiobj.get(wiz_entries=entries)

See also

This method is used by all other get* methods under the hood and their kwargs are passed thru to this method and passed to get_generator() which are then passed to whatever callback is used based on the export argument.

If export is not supplied, see axonius_api_client.api.asset_callbacks.base.Base.args_map().

If export equals json, see axonius_api_client.api.asset_callbacks.base_json.Json.args_map().

If export equals csv, see axonius_api_client.api.asset_callbacks.base_csv.Csv.args_map().

If export equals json_to_csv, see axonius_api_client.api.asset_callbacks.base_json_to_csv.JsonToCsv.args_map().

If export equals table, see axonius_api_client.api.asset_callbacks.base_table.Table.args_map().

If export equals xlsx, see axonius_api_client.api.asset_callbacks.base_xlsx.Xlsx.args_map().

Parameters

generator (bool) – return an iterator for assets that will yield rows as they are fetched
**kwargs – passed to get_generator()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_id(id)¶

Get the full data set of all adapters for a single asset.

Examples

>>> asset = apiobj.get_by_id(id="3d69adf54879faade7a44068e4ecea6e")

Parameters: id (str) – internal_axon_id of asset to get all data set for
Raises: NotFoundError – if id is not found
Return type: dict

get_by_saved_query(name, **kwargs)¶

Get assets that would be returned by a saved query.

Examples

First, create a client using axonius_api_client.connect.Connect and assume apiobj is client.devices or client.users

>>> apiobj = client.devices

Get assets from a saved query with complex fields flattened

>>> assets = apiobj.get_by_saved_query(name="test", field_flatten=True)

Notes

The query and the fields defined in the saved query will be used to get the assets.

Parameters

name (str) – name of saved query to get assets from
**kwargs – passed to get()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_value(value, field, not_flag=False, pre='', post='', field_manual=False, **kwargs)¶

Build a query to get assets where field equals a value.

Notes

It is better to use wizard, wizard_text, or wizard_csv to build queries!

Parameters

value (str) – value that must equal field
field (str) – name of field to query against
not_flag (bool) – prefix query with ‘not’
pre (str) – query to add to the beginning of the query
post (str) – query to add to the end of the query
field_manual (bool) – consider supplied field as a fully qualified field name
**kwargs – passed to get()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_value_regex(value, field, cast_insensitive=True, not_flag=False, pre='', post='', field_manual=False, **kwargs)¶

Build a query to get assets where field regex matches a value.

Notes

It is better to use wizard, wizard_text, or wizard_csv to build queries!

Parameters

value (str) – regex that must match field
field (str) – name of field to query against
case_insensitive – ignore case when performing the regex match
not_flag (bool) – prefix query with ‘not’
pre (str) – query to add to the beginning of the query
post (str) – query to add to the end of the query
field_manual (bool) – consider supplied field as a fully qualified field name
**kwargs – passed to get()
cast_insensitive (bool) –

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_by_values(values, field, not_flag=False, pre='', post='', field_manual=False, **kwargs)¶

Build a query to get assets where field in values.

Notes

It is better to use wizard, wizard_text, or wizard_csv to build queries!

Parameters

values (typing.List[str]) – list of values that must match field
field (str) – name of field to query against
not_flag (bool) – prefix query with ‘not’
pre (str) – query to add to the beginning of the query
post (str) – query to add to the end of the query
field_manual (bool) – consider supplied field as a fully qualified field name
**kwargs – passed to get()

Return type

typing.Union[typing.Generator[dict, None, None], typing.List[dict]]

get_generator(query=None, fields=None, fields_manual=None, fields_regex=None, fields_fuzzy=None, fields_default=True, fields_root=None, max_rows=None, max_pages=None, row_start=0, page_size=2000, page_start=0, page_sleep=0, use_cursor=True, export='base', include_details=False, sort_field=None, sort_descending=False, history_date=None, wiz_entries=None, **kwargs)¶

Get assets from a query.

Parameters

query (typing.Optional[str]) – if supplied, only get the assets that match the query
fields (typing.Union[typing.List[str], str, None]) – fields to return for each asset (will be validated)
fields_manual (typing.Union[typing.List[str], str, None]) – fields to return for each asset (will NOT be validated)
fields_regex (typing.Union[typing.List[str], str, None]) – regex of fields to return for each asset
fields_fuzzy (typing.Union[typing.List[str], str, None]) – string to fuzzy match of fields to return for each asset
fields_default (bool) – include the default fields in fields_default
fields_root (typing.Optional[str]) – include all fields of an adapter that are not complex sub-fields
max_rows (typing.Optional[int]) – only return N rows
max_pages (typing.Optional[int]) – only return N pages
row_start (int) – start at row N
page_size (int) – fetch N rows per page
page_start (int) – start at page N
page_sleep (int) – sleep for N seconds between each page fetch
use_cursor (bool) – use the endpoint that fetches rows using a DB cursor
export (str) – export assets using a callback method
include_details (bool) – include details fields showing the adapter source of agg values
sort_field (typing.Optional[str]) – sort the returned assets on a given field
sort_descending (bool) – reverse the sort of the returned assets
history_date (typing.Union[str, datetime.timedelta, datetime.datetime, None]) – return assets for a given historical date
wiz_entries (typing.Optional[typing.List[dict]]) – wizard expressions to create query from
**kwargs – passed thru to the asset callback defined in export

Return type

typing.Generator[dict, None, None]

history_dates()¶

Get all known historical dates.

Return type: dict

request(path, method='get', raw=False, is_json=True, empty_ok=False, error_status=True, error_json_bad_status=True, error_json_invalid=True, **kwargs)¶

Send a REST API request.

Parameters

path (str) – path to use in request
method (str) – method to use in request
raw (bool) – return the raw response object
is_json (bool) – return the response as deserialized json or just return the text body
error_status (bool) – throw error if response has a bad status code
error_json_bad_status (bool) – throw error if json response has non-empty error key
error_json_invalid (bool) – throw error if response can not be deserialized into json
**kwargs – Passed to axonius_api_client.http.Http.__call__()
empty_ok (bool) –

Return type

typing.Any

Returns

requests.Response or str or dict or int or list

validate_history_date(value)¶

Validate that a given date is known historical date.

Parameters: value (typing.Union[str, datetime.timedelta, datetime.datetime]) – date time to validate
Raises: ApiError – if supplied value is not an available history date to pick from
Return type: str

FIELD_MAIN: str = 'specific_data.data.hostname'¶: Field name of the main identifier.

FIELD_SIMPLE: str = 'specific_data.data.hostname'¶: Field name of a simple field.

FIELD_COMPLEX: str = 'specific_data.data.network_interfaces'¶: Field name of a complex field.

FIELD_COMPLEX_SUB: str = 'name'¶: Field name of a complex sub field.

wizard: str = None¶

Query wizard for python objects.

Type: axonius_api_client.api.wizards.wizard.Wizard

wizard_text: str = None¶

Query wizard for text files.

Type: axonius_api_client.api.wizards.wizard_text.WizardText

wizard_csv = None¶

Query wizard for CSV files.

Type: axonius_api_client.api.wizards.wizard_csv.WizardCsv