'''
Session
=======
The following methods allow for interaction into the Tenable Vulnerability Management
:devportal:`session <session>` API endpoints.
Methods available on ``tio.session``:
.. rst-class:: hide-signature
.. autoclass:: SessionAPI
:members:
'''
from .base import TIOEndpoint
[docs]class SessionAPI(TIOEndpoint):
'''
Tenable Vulnerability Management session API is deprecated.
it is recommended to use ``users`` endpoint instead
'''
[docs] def edit(self, name, email):
'''
Modify the currently logged-in user.
:devportal:`session: edit <session-edit>`
Args:
name (str): The full name of the user.
email (str): The email address of the user.
Returns:
:obj:`dict`:
The session data for the current user.
Examples:
>>> tio.session.edit('John Doe', 'joe@company.com')
'''
return self._api.put('session', json={
'name': self._check('name', name, str),
'email': self._check('email', email, str)
}).json()
[docs] def details(self):
'''
Retrieve the current users resource record.
:devportal:`session: get <session-get>`
Returns:
:obj:`dict`:
The user's session resource record.
Examples:
>>> user = tio.session.details()
>>> pprint(user)
'''
return self._api.get('session').json()
[docs] def change_password(self, old_password, new_password):
'''
Change the password of the current user.
:devportal:`session: password <session-password>`
Args:
old_password (str): The current password.
new_password (str): The new password.
Returns:
:obj:`None`:
The password has been successfully changed.
Examples:
>>> tio.session.change_password('old_pass', 'new_pass')
'''
self._api.put('session/chpasswd', json={
'password': self._check('new_password', new_password, str),
'current_password': self._check('old_password', old_password, str)
})
[docs] def gen_api_keys(self):
'''
Generate new API keys for the current user.
:devportal:`session: keys <session-keys>`
Returns:
:obj:`dict`:
A dictionary containing the new API Keypair.
Examples:
>>> keys = tio.session.gen_api_keys()
'''
return self._api.put('session/keys').json()
[docs] def two_factor(self, email, sms, phone=None):
'''
Configure two-factor authorization.
:devportal:`session: two-factor <session-two-factor-settings>`
Args:
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:
:obj:`None`:
Setting changes were successfully updated.
Example:
Configure email multi-factor auth:
>>> tio.session.two_factor(True, False)
Configure SMS multi-factor auth:
>>> tio.session.two_factor(False, True, '9998887766')
'''
payload = {
'email_enabled': self._check('email', email, bool),
'sms_enabled': self._check('sms', sms, bool)
}
if phone:
payload['sms_phone'] = self._check('phone', phone, str)
self._api.put('session/two-factor', json=payload)
[docs] def enable_two_factor(self, phone):
'''
Initiate the phone-based two-factor authorization verification process.
:devportal:`session: two-factor-enable <session-send-code>`
Args:
phone (str): The phone number to use for two-factor auth.
Returns:
:obj:`None`:
One-time activation code sent to the provided phone number.
Examples:
>>> tio.session.enable_two_factor('9998887766')
'''
self._api.post('session/two-factor/send-verification', json={
'sms_phone': self._check('phone', phone, str)
})
[docs] def verify_two_factor(self, code):
'''
Send the verification code for two-factor authorization.
:devportal:`session: verify-code <session-verify-code>`
Args:
code (str): The verification code that was sent to the device.
Returns:
:obj:`None`:
The verification code was valid and two-factor is enabled.
Examples:
>>> tio.session.verify_two_factor('abc123')
'''
self._api.post('session/two-factor/verify-code', json={
'verification_code': self._check('code', code, str)
})
[docs] def restore(self):
'''
Restore the session to the logged-in user. This will remove any user
impersonation setting that have been set.
:devportal:`session: restore <session-restore>`
Returns:
:obj:`None`:
The session has properly been restored to the original user.
Example:
>>> tio.session.restore()
'''
self._api._session.headers.update({
'X-Impersonate': None
})