4.3.2. Connections

API for working with adapter connections.

class axonius_api_client.api.adapters.cnx.Cnx(parent)[source]

Bases: axonius_api_client.api.mixins.ChildMixins

API model for working with adapter connections.

Examples

Create a client using axonius_api_client.connect.Connect

Notes

All methods use the Core instance by default, but you can work with another instance by passing the name of the instance to adapter_node.

Supplying unknown keys/values for configurations will throw an error showing the valid keys/values.

Parameters

parent (axonius_api_client.api.mixins.Model) –

add(adapter_name, adapter_node=None, **kwargs)[source]

Add a connection to an adapter on a node.

Examples

First, create a client using axonius_api_client.connect.Connect.

Establish a connection dictionary

>>> config = dict(
...     dc_name="192.168.1.10",
...     user="svc_user",
...     password="test",
...     do_not_fetch_users=False,
...     fetch_disabled_users=False,
...     fetch_disabled_devices=False,
...     is_ad_gc=False,
...     connection_label="test label",
... )

Add a connection for an adapter to the Core instance

>>> cnx = client.adapters.cnx.add(adapter_name="active_directory", **config)
Parameters

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • **kwargs – configuration of new connection

Raises

CnxAddError – when an error happens while adding the connection

Return type

dict

get_by_adapter(adapter_name, adapter_node=None)[source]

Get all connections of an adapter on a node.

Examples

First, create a client using axonius_api_client.connect.Connect.

Get all connections for an adapter on the Core instance

>>> cnxs = client.adapters.cnx.get_by_adapter(adapter_name="active_directory")
Parameters

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

Return type

typing.List[dict]

get_by_uuid(cnx_uuid, adapter_name, adapter_node=None, **kwargs)[source]

Get a connection for an adapter on a node by UUID.

Examples

First, create a client using axonius_api_client.connect.Connect.

Get a single connection by UUID

>>> cnx = client.adapters.cnx.get_by_uuid(
...     cnx_id='5f76735be4557d5cba94237f', adapter_name='aws'
... )

Notes

UUID of connections change when a connection configuration is updated, the more persistent way to get a connection is get_by_id().

Parameters

  • cnx_uuid (str) – UUID to search for

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • **kwargs – passed to get_by_key()

Return type

dict

get_by_label(value, adapter_name, adapter_node=None)[source]

Get a connection for an adapter on a node using a specific connection identifier key.

Examples

First, create a client using axonius_api_client.connect.Connect.

Get a single connection by connection label

>>> cnx = client.adapters.cnx.get_by_label(
...     value='test label', adapter_name='active_directory'
... )
Parameters

  • value (str) – value that connection_label must match for a connection

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

Raises

NotFoundError – when no connections found with supplied connection label

Return type

dict

get_by_id(cnx_id, adapter_name, adapter_node=None, **kwargs)[source]

Get a connection for an adapter on a node by ID.

Examples

First, create a client using axonius_api_client.connect.Connect.

Get a single connection by ID

>>> cnx = client.adapters.cnx.get_by_id(
...     cnx_id='192.168.1.10', adapter_name='active_directory'
... )

Notes

ID is constructed from some variance of connection keys, usually “domain” (i.e. for active_directory TestDomain.test)

Parameters

  • cnx_id (str) – connection ID to get

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • **kwargs – passed to get_by_key()

Return type

dict

update_by_id(cnx_id, adapter_name, adapter_node=None, **kwargs)[source]

Update a connection for an adapter on a node by ID.

Examples

First, create a client using axonius_api_client.connect.Connect.

Change the connection label for a connection

>>> cnx = client.adapters.cnx.update_by_id(
...     cnx_id='TestDomain.test',
...     adapter_name='active_directory',
...     connection_label="new label",
... )
Parameters

  • cnx_id (str) – connection ID to update

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • **kwargs – passed to update_cnx()

Return type

dict

delete_by_id(cnx_id, adapter_name, adapter_node=None, delete_entities=False)[source]

Delete a connection for an adapter on a node by connection ID.

Examples

First, create a client using axonius_api_client.connect.Connect.

Delete a connection by ID

>>> cnx = client.adapters.cnx.delete_by_id(
...     cnx_id='192.168.1.10', adapter_name='active_directory'
... )
Parameters

  • cnx_id (str) – connection ID to delete

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • delete_entities (bool) – delete all asset entities associated with this connection

Return type

str

test_by_id(**kwargs)[source]

Test a connection for an adapter on a node by ID.

Examples

First, create a client using axonius_api_client.connect.Connect.

Test the reachability of a connection by ID

>>> cnx = client.adapters.cnx.test_by_id(
...     cnx_id='192.168.1.10', adapter_name='active_directory'
... )
Parameters

**kwargs – passed to get_by_id()

Return type

str

test(adapter_name, adapter_node=None, old_config=None, **kwargs)[source]

Test a connection to an adapter on a node.

Examples

First, create a client using axonius_api_client.connect.Connect.

Test the reachability of a connection without creating the connection

>>> config = dict(dc_name="192.168.1.10", user="svc_user", password="test")
>>> cnx = client.adapters.cnx.test(adapter_name="active_directory", **config)

Notes

This can be used to test the configuration of a connection before creating the connection. Usually you need just whatever configuration keys are related to hostname/domain/ip address to test a connection.

Parameters

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • old_config (typing.Optional[dict]) – old connection configuration

  • **kwargs – configuration of connection to test

Raises
Return type

str

test_cnx(cnx_test, **kwargs)[source]

Test a connection for an adapter on a node.

Parameters

  • cnx_test (dict) – connection fetched previously

  • **kwargs – passed to test()

Return type

str

update_cnx(cnx_update, **kwargs)[source]

Update a connection for an adapter on a node.

Parameters

  • cnx_test – connection fetched previously

  • **kwargs – configuration of connection to update

  • cnx_update (dict) –

Raises

CnxUpdateError – When an error occurs while updating the connection

Return type

dict

delete_cnx(cnx_delete, delete_entities=False)[source]

Delete a connection for an adapter on a node.

Parameters

  • cnx_delete (dict) – connection fetched previously

  • delete_entities (bool) – delete all asset entities associated with this connection

Return type

str

check_if_gone(result, cnx_id, adapter_name, adapter_node)[source]

Check if the result of updating a connection shows that the connection is gone.

Parameters

  • result (dict) – JSON response from updating a connection

  • cnx_id (str) – connection ID that was being updated

  • adapter_name (str) – name of adapter

  • adapter_node (str) – name of node running adapter

Raises

CnxGoneError – when a connection is updated by someone causing the connections UUID or ID to change

build_config(cnx_schemas, new_config, source, adapter_name, adapter_node, old_config=None)[source]

Build and parse a configuration for a connection.

Parameters

  • cnx_schemas (typing.List[dict]) – configuration schemas for connection

  • new_config (dict) – new configuration for connection

  • source (str) – description of what called this method

  • adapter_name (str) – name of adapter

  • adapter_node (str) – name of node running adapter

  • old_config (typing.Optional[dict]) – configuration that is being updated

Return type

dict

get_sane_defaults(adapter_name)[source]

Get the API client defined sane defaults for a specific adapter.

Parameters

adapter_name (str) – name of adapter

Return type

dict

get_by_key(value, value_key, adapter_name, adapter_node=None, retry=0, sleep=1)[source]

Get a connection for an adapter on a node using a specific connection identifier key.

Parameters

  • value (str) – value that value_key must match for a connection

  • value_key (str) – name of connection key to search for value of

  • adapter_name (str) – name of adapter

  • adapter_node (typing.Optional[str]) – name of node running adapter

  • retry (int) – number of times to retry to find the connection using value_key[value]

  • sleep (int) – seconds to sleep in between each retry

Raises

NotFoundError – when no connection found where value == cnx[value_key]

Return type

dict

cb_file_upload(value, schema, callbacks, source)[source]

Config parsing callback to upload a file for a connection.

Parameters

  • value (typing.Union[str, pathlib.Path, dict]) – file to upload

  • schema (dict) – connection configuration schema of type “file”

  • callbacks (dict) – callbacks supplied

  • source (str) – description of what called this method

Raises

ConfigInvalidValue – When value is a path that does not exist, or a dictionary that does not have ‘uuid’ and ‘filename’ keys’, or if value is not a file

Return type

dict

_add(adapter_name_raw, adapter_node_id, new_config)[source]

Private API method to add a connection to an adapter.

Parameters

  • adapter_name_raw (str) – raw name of the adapter i.e. aws_adapter

  • adapter_node_id (str) – id of node running adapter

  • new_config (dict) – configuration of new connection

Return type

str

_test(adapter_name_raw, adapter_node_id, config)[source]

Private API method to add a connection to an adapter.

Parameters

  • adapter_name_raw (str) – raw name of the adapter i.e. aws_adapter

  • adapter_node_id (str) – id of node running adapter

  • config (dict) – configuration to test

Return type

str

_delete(adapter_name_raw, adapter_node_id, cnx_uuid, delete_entities=False)[source]

Private API method to delete a connection from an adapter.

Parameters

  • adapter_name_raw (str) – raw name of the adapter i.e. aws_adapter

  • adapter_node_id (str) – id of node running adapter

  • cnx_uuid (str) – uuid of connection to delete

  • delete_entities (bool) – delete all asset entities associated with this connection

Return type

str

_update(adapter_name_raw, adapter_node_id, new_config, cnx_uuid)[source]

Private API method to update a connection on an adapter.

Parameters

  • adapter_name_raw (str) – raw name of the adapter i.e. aws_adapter

  • adapter_node_id (str) – id of node running adapter

  • cnx_uuid (str) – uuid of connection to delete

  • new_config (dict) – configuration of connection

Return type

str

__init__(parent)

Mixins model for API child objects.

Parameters

parent (axonius_api_client.api.mixins.Model) – parent API model of this child

__repr__()

Show info for this model object.

Return type

str

__str__()

Show info for this model object.

Return type

str

_init(parent)

Post init method for subclasses to use for extra setup.

Parameters

parent (axonius_api_client.api.mixins.Model) – parent API model of this child