Users¶

The following methods allow for interaction into the Tenable Vulnerability Management users API endpoints.

Methods available on tio.users:

class UsersAPI(api: APISession)[source]¶

This will contain all methods related to Users

change_password(user_id, old_password, new_password)[source]¶

Change the password for a specific user.

users: password

Parameters:

user_id (int) – The unique identifier for the user.
old_password (str) – The current password.
new_password (str) – The new password.

Returns:

The password has been successfully changed.

Return type:

None

Examples

>>> tio.users.change_password(1, 'old_pass', 'new_pass')

create(username, password, permissions, name=None, email=None, account_type=None)[source]¶

Create a new user.

users: create

Parameters:

username (str) – The username for the new user.
password (str) – The password for the new user.
permissions (int) – The permissions role for the user. The permissions integer is derived based on the desired role of the user. For details describing what permissions values mean what roles, please refer to the User Roles table to see what permissions are accepted.
name (str, optional) – The human-readable name of the user.
email (str, optional) – The email address of the user.
account_type (str, optional) – The account type for the user. The default is local.

Returns:

The resource record of the new user.

Return type:

dict

Examples

Create a standard user:

>>> user = tio.users.create('jsmith@company.com', 'password1', 32)

Create an admin user and add the email and name:

>>> user = tio.users.create('jdoe@company.com', 'password', 64,
...     name='Jane Doe', email='jdoe@company.com')

delete(user_id, *, successor_user_uuid=None)[source]¶

Removes a user from Tenable Vulnerability Management.

users: delete

Parameters:

user_id (int or str) – The unique identifier of the user, as either the integer ID or the user UUID.
successor_user_uuid (str, optional) – The UUID of the user to transfer the deleted user’s objects to, such as scans. The successor must have permissions that allow it to own those objects; otherwise, the API returns a 409 conflict and the user is not deleted. Web App Scanning scans are not transferred, so reassign them before deleting the user.

Raises:

UnexpectedValueError – If user_id is a string that is not a UUID, or successor_user_uuid is not a UUID.

Returns:

The user was successfully deleted.

Return type:

None

Examples

>>> tio.users.delete(1)

>>> tio.users.delete('00000000-0000-0000-0000-000000000000')

Transfer the deleted user’s objects to another user:

>>> tio.users.delete(
...     1, successor_user_uuid='00000000-0000-0000-0000-000000000000'
... )

details(user_id)[source]¶

Retrieve the details of a user.

users: details

Parameters:: user_id (int) – The unique identifier for the user.
Returns:: The resource record for the user.
Return type:: dict

Examples

>>> user = tio.users.details(1)

edit(user_id, permissions=None, name=None, email=None, enabled=None)[source]¶

Modify an existing user.

users: edit

Parameters:

user_id (int) – The unique identifier for the user.
permissions (int, optional) –
The permissions role for the user. The permissions integer is derived based on the desired role of the user. For details describing what permissions values mean what roles, please refer to the User Roles table to see what permissions are accepted.
name (str, optional) – The human-readable name of the user.
email (str, optional) – The email address of the user.
enabled (bool, optional) – Is the user account enabled?

Returns:

The modified user resource record.

Return type:

dict

Examples

>>> user = tio.users.edit(1, name='New Full Name')

edit_auths(user_id, api_permitted=None, password_permitted=None, saml_permitted=None)[source]¶

update user authorizations for accessing a Tenable Vulnerability Management instance.

users: edit-auths

Parameters:

user_id (int) – The unique identifier for the user.
api_permitted (bool) – Indicates whether API access is authorized for the user.
password_permitted (bool) – Indicates whether user name and password login is authorized for the user.
saml_permitted (bool) – Indicates whether SSO with SAML is authorized for the user.

Returns:

Returned if Tenable Vulnerability Management successfully updates the user’s authorizations.

Return type:

None

Examples

>>> tio.users.edit_auths(1, True, True, False)

enable_two_factor(user_id, phone, password)[source]¶

Enable phone-based two-factor authorization for a specific user.

users: two-factor-enable

Parameters:

user_id (int) – The user id
phone (str) – The phone number to use for two-factor auth.
password (str) – The user password.

Returns:

One-time activation code sent to the provided phone number.

Return type:

None

Examples

>>> tio.users.enable_two_factor(1, '9998887766')

enabled(user_id, enabled)[source]¶

Enable the user account.

users: enabled

Parameters:

user_id (int) – The unique identifier for the user.
enabled (bool) – Is the user enabled?

Returns:

The modified user resource record.

Return type:

dict

Examples

Enable a user:

>>> tio.users.enabled(1, True)

Disable a user:

>>> tio.users.enabled(1, False)

gen_api_keys(user_id)[source]¶

Generate the API keys for a specific user.

users: keys

Parameters:: user_id (int) – The unique identifier for the user.
Returns:: A dictionary containing the new API Key-pair.
Return type:: dict

Examples

>>> keys = tio.users.gen_api_keys(1)

impersonate(name)[source]¶

Impersonate as a specific user.

Parameters:: name (str) – The user-name of the user to impersonate.
Returns:: Impersonation successful.
Return type:: None

Examples

>>> tio.users.impersonate('jdoe@company.com')

list(*, with_roles=None)[source]¶

Retrieves a list of users.

users: list

Parameters:: with_roles (bool, optional) – If True, each user record includes an rbac_roles list with the name and uuid of each role-based access control (RBAC) role assigned to the user. If omitted or False, the records do not include roles.
Returns:: List of user resource records.
Return type:: list

Examples

>>> for user in tio.users.list():
...     pprint(user)

Include each user’s RBAC roles:

>>> for user in tio.users.list(with_roles=True):
...     print(user['username'], [r['name'] for r in user['rbac_roles']])

list_auths(user_id)[source]¶

list user authorizations for accessing a Tenable Vulnerability Management instance.

users: list-auths

Parameters:: user_id (int) – The unique identifier for the user.
Returns:: Returns authorizations for the user.
Return type:: dict

Examples

>>> auth = tio.users.list_auths(1)

two_factor(user_id, email, sms, phone=None)[source]¶

Configure two-factor authorization for a specific user.

users: two-factor

Parameters:

user_id (int) – The unique identifier for the user.
email (bool) – Whether two-factor should be additionally sent as an email.
sms (bool) – Whether two-factor should be enabled. This will send SMS codes.
phone (str, optional) – The phone number to use for two-factor authentication. Required when sms is set to True.

Returns:

Setting changes were successfully updated.

Return type:

None

Examples

Enable email authorization for a user:

>>> tio.users.two_factor(1, True, False)

Enable SMS authorization for a user:

>>> tio.users.two_factor(1, False, True, '9998887766')

verify_two_factor(user_id, code)[source]¶

Send the verification code for two-factor authorization.

users: two-factor-enable-verify

Parameters:: code (str) – The verification code that was sent to the device.
Returns:: The verification code was valid and two-factor is enabled.
Return type:: None

Examples

>>> tio.users.verify_two_factor(1, 'abc123')