4.6.8. System Roles

Warning

This API is deprecated.

Axonius API v2 is now available, we recommend you move to API v2.

New features will no longer be added to this API. Axonius will only provide bug fixes.

Read about API v2

API for working with system roles.

class axonius_api_client.api.system.system_roles.SystemRoles(auth, log_level='debug', **kwargs)[source]

Bases: ModelMixins

API for working with system roles.

Examples

Parameters:
  • auth (axonius_api_client.auth.model.AuthModel) –

  • log_level (typing.Union[int, str]) –

static _parse_cat_actions(raw)[source]

Parse the permission labels into a layered dict.

Parameters:

raw (dict) –

Return type:

dict

get(generator=False)[source]

Get Axonius system roles.

Examples

Create a client using axonius_api_client.connect.Connect

>>> roles = client.system_roles.get()
>>> [x['name'] for x in roles]
['Admin', 'Viewer', 'Restricted', 'No Access', 'abc']
Parameters:

generator (bool) – return an iterator for objects that will yield rows as they are fetched

Return type:

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

get_generator()[source]

Get Axonius system roles using a generator.

Return type:

typing.Generator[dict, None, None]

get_cached()[source]

Get Axonius system roles using a caching mechanism.

Return type:

typing.List[axonius_api_client.api.json_api.system_roles.SystemRole]

get_cached_single(value)[source]

Pass.

Parameters:

value (typing.Union[str, dict, axonius_api_client.api.json_api.system_roles.SystemRole]) –

Return type:

axonius_api_client.api.json_api.system_roles.SystemRole

get_by_name(name)[source]

Get a role by name.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.get_by_name(name="Admin")
>>> role["uuid"]
'5f76721bebd8d8b5459b56c8'
Parameters:

name (str) – name of role to get

Raises:

NotFoundError – if role not found

Return type:

dict

get_by_uuid(uuid)[source]

Get a role by uuid.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.get_by_name(name="5f76721bebd8d8b5459b56c8")
>>> role["name"]
'Admin'
Parameters:

uuid (str) – uuid of role to get

Raises:

NotFoundError – if role not found

Return type:

dict

add(name, data_scope=None, **kwargs)[source]

Add a role.

Examples

Create a client using axonius_api_client.connect.Connect

Create a role with the default permissions (none except dashboard view)

>>> role = client.system_roles.add(name="test1")

Create a role with specific permissions:

>>> role = client.system_roles.add(
...     name="test2", adapters="get", users_assets="get,saved_queries.run"
... )

Create a role with all permissions for all categories:

>>> role = client.system_roles.add(
...     name="test2",
...     adapters="all",
...     dashboard="all",
...     devices_assets="all",
...     enforcements="all",
...     instances="all",
...     reports="all",
...     settings="all",
...     users_assets="all",
... )
Parameters:
  • name (str) – name of role to add

  • data_scope (typing.Optional[str]) – name or UUID of data scope to assign to role

  • **kwargs – keys as categories, values as list or CSV of actions to allow for category

Raises:

ApiError – if role already exists matching name

Return type:

dict

check_exists(name)[source]

Pass.

Parameters:

name (str) –

update_data_scope(name, data_scope=None, remove=False)[source]

Update the data scope of a role.

Parameters:
  • name (str) – Name of role to update

  • data_scope (t.Optional[str], optional) – Name or UUID of data scope

  • remove (bool, optional) – Remove data scope from role

Return type:

dict

set_name(name, new_name)[source]

Change the name of a role.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.set_name(name="test1", new_name="test3")
>>> role["name"]
'test3'
Parameters:
  • name (str) – name of role to update

  • new_name (str) – new name of role

Return type:

dict

set_perms(name, grant=True, **kwargs)[source]

Change the permissions of a role.

Examples

Create a client using axonius_api_client.connect.Connect

Add all permissions for adapters to a role

>>> role = client.system_roles.set_perms(name="test1", adapters="all")

Remove all permissions for adapters to a role

>>> role = client.system_roles.set_perms(name="test1", grant=False, adapters="all")

Add all permissions for all categories to a role:

>>> role = client.system_roles.set_perms(
...     name="test1",
...     adapters="all",
...     dashboard="all",
...     devices_assets="all",
...     enforcements="all",
...     instances="all",
...     reports="all",
...     settings="all",
...     users_assets="all",
... )
Parameters:
  • name (str) – name of role to update

  • grant (bool) – add or remove access to the categories and actions supplied

  • **kwargs – keys as categories, values as list of actions to allow for category

Return type:

dict

delete_by_name(name)[source]

Delete a role.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.delete_by_name(name="test1")
Parameters:

name (str) – name of role to delete

Return type:

dict

pretty_perms(role)[source]

Get a user readable version of the permissions for a role.

Examples

Create a client using axonius_api_client.connect.Connect

Pretty print a roles permission sets:

>>> print(client.system_roles.pretty_perms(role=role))
adapters             Adapters
connections.delete   Delete connection              False
connections.post     Edit connections               False
(...trimmed...)
Parameters:

role (dict) – role returned from get_by_name(), get(), or get_by_uuid()

Return type:

str

_get()[source]

Direct API method to get all users.

Parameters:
  • limit – limit to N rows per page

  • offset – start at row N

Return type:

typing.List[axonius_api_client.api.json_api.system_roles.SystemRole]

_add(name, permissions, data_scope_restriction=None)[source]

Direct API method to add a role.

Parameters:
  • name (str) – name of new role

  • permissions (dict) – permissions for new role

  • data_scope_restriction (typing.Optional[dict]) –

Return type:

axonius_api_client.api.json_api.system_roles.SystemRole

_update(uuid, name, permissions, data_scope_restriction=None)[source]

Direct API method to update a roles permissions.

Parameters:
  • name (str) – name of role to update

  • permissions (dict) – permissions to update on new role

  • uuid (str) –

  • data_scope_restriction (typing.Optional[dict]) –

Return type:

axonius_api_client.api.json_api.system_roles.SystemRole

_delete(uuid)[source]

Direct API method to delete a role.

Parameters:
  • name – name of role to delete

  • uuid (str) –

Return type:

axonius_api_client.api.json_api.system_roles.SystemRole

_get_labels()[source]

Direct API method to get role labels.

Return type:

dict

property cat_actions: dict

Get permission categories and their actions.

_check_predefined(role)[source]

Check if a role is predefined.

Parameters:

role (dict) – role to check

Raises:

ApiError – if role is a predefined role

cat_actions_to_perms(role_perms=None, grant=True, src=None, **kwargs)[source]

Create an updated set of role permissions based on categories and actions.

Parameters:
  • role_perms (typing.Optional[dict]) – permissions of a role to update

  • grant (bool) – add or remove access to the actions supplied

  • **kwargs – keys as categories, values as list of actions to allow for category

  • src (typing.Optional[str]) –

Return type:

dict

_init(**kwargs)[source]

Post init method for subclasses to use for extra setup.

property data_scopes

Work with data scopes.

LOG: logging.Logger = None

Logger for this object.

__init__(auth, log_level='debug', **kwargs)

Mixins for API Models.

Parameters:
  • auth (axonius_api_client.auth.model.AuthModel) – object to use for auth and sending API requests

  • log_level (typing.Union[int, str]) – logging level to use for this objects logger

  • **kwargs – passed to _init()

__repr__()

Show info for this model object.

Return type:

str

__str__()

Show info for this model object.

Return type:

str

_init_auth(**kwargs)

Post init method for subclasses to use for overriding auth setup.

auth: axonius_api_client.auth.model.AuthModel = None

Authentication model with bound Http object to use for requests.

http: axonius_api_client.http.Http = None

Http object to use for requests.