saltstack/salt

View on GitHub
salt/modules/mac_shadow.py

Summary

Maintainability
D
2 days
Test Coverage
# -*- coding: utf-8 -*-
'''
Manage macOS local directory passwords and policies

.. versionadded:: 2016.3.0

Note that it is usually better to apply password policies through the creation
of a configuration profile.
'''
# Authentication concepts reference:
# https://developer.apple.com/library/mac/documentation/Networking/Conceptual/Open_Directory/openDirectoryConcepts/openDirectoryConcepts.html#//apple_ref/doc/uid/TP40000917-CH3-CIFCAIBB

from __future__ import absolute_import, unicode_literals, print_function
from datetime import datetime


try:
    import pwd
    HAS_PWD = True
except ImportError:
    HAS_PWD = False

# Import salt libs
import logging
import salt.utils.mac_utils
import salt.utils.platform
from salt.exceptions import CommandExecutionError

log = logging.getLogger(__name__)  # Start logging

__virtualname__ = 'shadow'


def __virtual__():
    # Is this macOS?
    if not salt.utils.platform.is_darwin():
        return False, 'Not macOS'

    if HAS_PWD:
        return __virtualname__
    else:
        return (False, 'The pwd module failed to load.')


def _get_account_policy(name):
    '''
    Get the entire accountPolicy and return it as a dictionary. For use by this
    module only

    :param str name: The user name

    :return: a dictionary containing all values for the accountPolicy
    :rtype: dict

    :raises: CommandExecutionError on user not found or any other unknown error
    '''

    cmd = 'pwpolicy -u {0} -getpolicy'.format(name)
    try:
        ret = salt.utils.mac_utils.execute_return_result(cmd)
    except CommandExecutionError as exc:
        if 'Error: user <{0}> not found'.format(name) in exc.strerror:
            raise CommandExecutionError('User not found: {0}'.format(name))
        raise CommandExecutionError('Unknown error: {0}'.format(exc.strerror))

    try:
        policy_list = ret.split('\n')[1].split(' ')
        policy_dict = {}
        for policy in policy_list:
            if '=' in policy:
                key, value = policy.split('=')
                policy_dict[key] = value
        return policy_dict
    except IndexError:
        return {}


def _set_account_policy(name, policy):
    '''
    Set a value in the user accountPolicy. For use by this module only

    :param str name: The user name
    :param str policy: The policy to apply

    :return: True if success, otherwise False
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error
    '''
    cmd = 'pwpolicy -u {0} -setpolicy "{1}"'.format(name, policy)

    try:
        return salt.utils.mac_utils.execute_return_success(cmd)
    except CommandExecutionError as exc:
        if 'Error: user <{0}> not found'.format(name) in exc.strerror:
            raise CommandExecutionError('User not found: {0}'.format(name))
        raise CommandExecutionError('Unknown error: {0}'.format(exc.strerror))


def _get_account_policy_data_value(name, key):
    '''
    Return the value for a key in the accountPolicy section of the user's plist
    file. For use by this module only

    :param str name: The username
    :param str key: The accountPolicy key

    :return: The value contained within the key
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error
    '''
    cmd = 'dscl . -readpl /Users/{0} accountPolicyData {1}'.format(name, key)
    try:
        ret = salt.utils.mac_utils.execute_return_result(cmd)
    except CommandExecutionError as exc:
        if 'eDSUnknownNodeName' in exc.strerror:
            raise CommandExecutionError('User not found: {0}'.format(name))
        raise CommandExecutionError('Unknown error: {0}'.format(exc.strerror))

    return ret


def _convert_to_datetime(unix_timestamp):
    '''
    Converts a unix timestamp to a human readable date/time

    :param float unix_timestamp: A unix timestamp

    :return: A date/time in the format YYYY-mm-dd HH:MM:SS
    :rtype: str
    '''
    try:
        unix_timestamp = float(unix_timestamp)
        return datetime.fromtimestamp(unix_timestamp).strftime('%Y-%m-%d %H:%M:%S')
    except (ValueError, TypeError):
        return 'Invalid Timestamp'


def info(name, **kwargs):
    '''
    Return information for the specified user

    :param str name: The username

    :return: A dictionary containing the user's shadow information
    :rtype: dict

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.info admin
    '''
    try:
        data = pwd.getpwnam(name)
        return {'name': data.pw_name,
                'passwd': data.pw_passwd,
                'account_created': get_account_created(name),
                'login_failed_count': get_login_failed_count(name),
                'login_failed_last': get_login_failed_last(name),
                'lstchg': get_last_change(name),
                'max': get_maxdays(name),
                'expire': get_expire(name),
                'change': get_change(name),
                'min': 'Unavailable',
                'warn': 'Unavailable',
                'inact': 'Unavailable'}

    except KeyError:
        log.debug('User not found: %s', name)
        return {'name': '',
                'passwd': '',
                'account_created': '',
                'login_failed_count': '',
                'login_failed_last': '',
                'lstchg': '',
                'max': '',
                'expire': '',
                'change': '',
                'min': '',
                'warn': '',
                'inact': ''}


def get_account_created(name):
    '''
    Get the date/time the account was created

    :param str name: The username of the account

    :return: The date/time the account was created (yyyy-mm-dd hh:mm:ss)
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_account_created admin
    '''
    ret = _get_account_policy_data_value(name, 'creationTime')

    unix_timestamp = salt.utils.mac_utils.parse_return(ret)

    date_text = _convert_to_datetime(unix_timestamp)

    return date_text


def get_last_change(name):
    '''
    Get the date/time the account was changed

    :param str name: The username of the account

    :return: The date/time the account was modified (yyyy-mm-dd hh:mm:ss)
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_last_change admin
    '''
    ret = _get_account_policy_data_value(name, 'passwordLastSetTime')

    unix_timestamp = salt.utils.mac_utils.parse_return(ret)

    date_text = _convert_to_datetime(unix_timestamp)

    return date_text


def get_login_failed_count(name):
    '''
    Get the the number of failed login attempts

    :param str name: The username of the account

    :return: The number of failed login attempts
    :rtype: int

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_login_failed_count admin
    '''
    ret = _get_account_policy_data_value(name, 'failedLoginCount')

    return salt.utils.mac_utils.parse_return(ret)


def get_login_failed_last(name):
    '''
    Get the date/time of the last failed login attempt

    :param str name: The username of the account

    :return: The date/time of the last failed login attempt on this account
        (yyyy-mm-dd hh:mm:ss)
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_login_failed_last admin
    '''
    ret = _get_account_policy_data_value(name, 'failedLoginTimestamp')

    unix_timestamp = salt.utils.mac_utils.parse_return(ret)

    date_text = _convert_to_datetime(unix_timestamp)

    return date_text


def set_maxdays(name, days):
    '''
    Set the maximum age of the password in days

    :param str name: The username of the account

    :param int days: The maximum age of the account in days

    :return: True if successful, False if not
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_maxdays admin 90
    '''
    minutes = days * 24 * 60

    _set_account_policy(
        name, 'maxMinutesUntilChangePassword={0}'.format(minutes))

    return get_maxdays(name) == days


def get_maxdays(name):
    '''
    Get the maximum age of the password

    :param str name: The username of the account

    :return: The maximum age of the password in days
    :rtype: int

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_maxdays admin 90
    '''
    policies = _get_account_policy(name)

    if 'maxMinutesUntilChangePassword' in policies:
        max_minutes = policies['maxMinutesUntilChangePassword']
        return int(max_minutes) / 24 / 60

    return 0


def set_mindays(name, days):
    '''
    Set the minimum password age in days. Not available in macOS.

    :param str name: The user name

    :param int days: The number of days

    :return: Will always return False until macOS supports this feature.
    :rtype: bool

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_mindays admin 90
    '''
    return False


def set_inactdays(name, days):
    '''
    Set the number if inactive days before the account is locked. Not available
    in macOS

    :param str name: The user name

    :param int days: The number of days

    :return: Will always return False until macOS supports this feature.
    :rtype: bool

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_inactdays admin 90
    '''
    return False


def set_warndays(name, days):
    '''
    Set the number of days before the password expires that the user will start
    to see a warning. Not available in macOS

    :param str name: The user name

    :param int days: The number of days

    :return: Will always return False until macOS supports this feature.
    :rtype: bool

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_warndays admin 90
    '''
    return False


def set_change(name, date):
    '''
    Sets the date on which the password expires. The user will be required to
    change their password. Format is mm/dd/yyyy

    :param str name: The name of the user account

    :param date date: The date the password will expire. Must be in mm/dd/yyyy
        format.

    :return: True if successful, otherwise False
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_change username 09/21/2016
    '''
    _set_account_policy(
        name, 'usingExpirationDate=1 expirationDateGMT={0}'.format(date))

    return get_change(name) == date


def get_change(name):
    '''
    Gets the date on which the password expires

    :param str name: The name of the user account

    :return: The date the password will expire
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_change username
    '''
    policies = _get_account_policy(name)

    if 'expirationDateGMT' in policies:
        return policies['expirationDateGMT']

    return 'Value not set'


def set_expire(name, date):
    '''
    Sets the date on which the account expires. The user will not be able to
    login after this date. Date format is mm/dd/yyyy

    :param str name: The name of the user account

    :param datetime date: The date the account will expire. Format must be
        mm/dd/yyyy.

    :return: True if successful, False if not
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.set_expire username 07/23/2015
    '''
    _set_account_policy(
        name, 'usingHardExpirationDate=1 hardExpireDateGMT={0}'.format(date))

    return get_expire(name) == date


def get_expire(name):
    '''
    Gets the date on which the account expires

    :param str name: The name of the user account

    :return: The date the account expires
    :rtype: str

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.get_expire username
    '''
    policies = _get_account_policy(name)

    if 'hardExpireDateGMT' in policies:
        return policies['hardExpireDateGMT']

    return 'Value not set'


def del_password(name):
    '''
    Deletes the account password

    :param str name: The user name of the account

    :return: True if successful, otherwise False
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' shadow.del_password username
    '''
    # This removes the password
    cmd = "dscl . -passwd /Users/{0} ''".format(name)
    try:
        salt.utils.mac_utils.execute_return_success(cmd)
    except CommandExecutionError as exc:
        if 'eDSUnknownNodeName' in exc.strerror:
            raise CommandExecutionError('User not found: {0}'.format(name))
        raise CommandExecutionError('Unknown error: {0}'.format(exc.strerror))

    # This is so it looks right in shadow.info
    cmd = "dscl . -create /Users/{0} Password '*'".format(name)
    salt.utils.mac_utils.execute_return_success(cmd)

    return info(name)['passwd'] == '*'


def set_password(name, password):
    '''
    Set the password for a named user (insecure, the password will be in the
    process list while the command is running)

    :param str name: The name of the local user, which is assumed to be in the
        local directory service

    :param str password: The plaintext password to set

    :return: True if successful, otherwise False
    :rtype: bool

    :raises: CommandExecutionError on user not found or any other unknown error

    CLI Example:

    .. code-block:: bash

        salt '*' mac_shadow.set_password macuser macpassword
    '''
    cmd = "dscl . -passwd /Users/{0} '{1}'".format(name, password)
    try:
        salt.utils.mac_utils.execute_return_success(cmd)
    except CommandExecutionError as exc:
        if 'eDSUnknownNodeName' in exc.strerror:
            raise CommandExecutionError('User not found: {0}'.format(name))
        raise CommandExecutionError('Unknown error: {0}'.format(exc.strerror))

    return True