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

Get all roles: get()
Get a role by name: get_by_name()
Get a role by uuid: get_by_uuid()
Add a role: add()
Change the name of a role: set_name()
Change the permissions of a role: set_perms()
Delete a role: delete_by_name()
Get a user readable version of the permissions for a role: pretty_perms()

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.