Source code for tenable.io.session

"""
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




class SessionAPI(TIOEndpoint):
    """
    Tenable Vulnerability Management session API is deprecated.
    it is recommended to use ``users`` endpoint instead
    """



    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': str(name), 'email': str(email)}
        ).json()




    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()




    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': str(new_password),
                'current_password': str(old_password),
            },
        )




    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()




    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)




    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)},
        )




    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)},
        )




    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})