4.6.8. System Roles¶

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.