salt/utils/win_lgpo_auditpol.py
# -*- coding: utf-8 -*-
r'''
A salt util for modifying the audit policies on the machine. This util is used
by the ``win_auditpol`` and ``win_lgpo`` modules.
Though this utility does not set group policy for auditing, it displays how all
auditing configuration is applied on the machine, either set directly or via
local or domain group policy.
.. versionadded:: 2018.3.4
.. versionadded:: 2019.2.1
This util allows you to view and modify the audit settings as they are applied
on the machine. The audit settings are broken down into nine categories:
- Account Logon
- Account Management
- Detailed Tracking
- DS Access
- Logon/Logoff
- Object Access
- Policy Change
- Privilege Use
- System
The ``get_settings`` function will return the subcategories for all nine of
the above categories in one dictionary along with their auditing status.
To modify a setting you only need to specify the subcategory name and the value
you wish to set. Valid settings are:
- No Auditing
- Success
- Failure
- Success and Failure
Usage:
.. code-block:: python
import salt.utils.win_lgpo_auditpol
# Get current state of all audit settings
salt.utils.win_lgpo_auditpol.get_settings()
# Get the current state of all audit settings in the "Account Logon"
# category
salt.utils.win_lgpo_auditpol.get_settings(category="Account Logon")
# Get current state of the "Credential Validation" setting
salt.utils.win_lgpo_auditpol.get_setting(name='Credential Validation')
# Set the state of the "Credential Validation" setting to Success and
# Failure
salt.utils.win_lgpo_auditpol.set_setting(name='Credential Validation',
value='Success and Failure')
# Set the state of the "Credential Validation" setting to No Auditing
salt.utils.win_lgpo_auditpol.set_setting(name='Credential Validation',
value='No Auditing')
'''
# Import Python libs
from __future__ import absolute_import, unicode_literals, print_function
import logging
import re
import tempfile
# Import Salt libs
import salt.modules.cmdmod
import salt.utils.files
import salt.utils.platform
from salt.exceptions import CommandExecutionError
# Import 3rd Party libs
from salt.ext.six.moves import zip
log = logging.getLogger(__name__)
__virtualname__ = 'auditpol'
categories = ['Account Logon',
'Account Management',
'Detailed Tracking',
'DS Access',
'Logon/Logoff',
'Object Access',
'Policy Change',
'Privilege Use',
'System']
settings = {'No Auditing': '/success:disable /failure:disable',
'Success': '/success:enable /failure:disable',
'Failure': '/success:disable /failure:enable',
'Success and Failure': '/success:enable /failure:enable'}
# Although utils are often directly imported, it is also possible to use the
# loader.
def __virtual__():
'''
Only load if on a Windows system
'''
if not salt.utils.platform.is_windows():
return False, 'This utility only available on Windows'
return __virtualname__
def _auditpol_cmd(cmd):
'''
Helper function for running the auditpol command
Args:
cmd (str): the auditpol command to run
Returns:
list: A list containing each line of the return (splitlines)
Raises:
CommandExecutionError: If the command encounters an error
'''
ret = salt.modules.cmdmod.run_all(cmd='auditpol {0}'.format(cmd),
python_shell=True)
if ret['retcode'] == 0:
return ret['stdout'].splitlines()
msg = 'Error executing auditpol command: {0}\n'.format(cmd)
msg += '\n'.join(ret['stdout'])
raise CommandExecutionError(msg)
def get_settings(category='All'):
'''
Get the current configuration for all audit settings specified in the
category
Args:
category (str):
One of the nine categories to return. Can also be ``All`` to return
the settings for all categories. Valid options are:
- Account Logon
- Account Management
- Detailed Tracking
- DS Access
- Logon/Logoff
- Object Access
- Policy Change
- Privilege Use
- System
- All
Default value is ``All``
Returns:
dict: A dictionary containing all subcategories for the specified
category along with their current configuration
Raises:
KeyError: On invalid category
CommandExecutionError: If an error is encountered retrieving the settings
Usage:
.. code-block:: python
import salt.utils.win_lgpo_auditpol
# Get current state of all audit settings
salt.utils.win_lgpo_auditpol.get_settings()
# Get the current state of all audit settings in the "Account Logon"
# category
salt.utils.win_lgpo_auditpol.get_settings(category="Account Logon")
'''
# Parameter validation
if category.lower() in ['all', '*']:
category = '*'
elif category.lower() not in [x.lower() for x in categories]:
raise KeyError('Invalid category: "{0}"'.format(category))
cmd = '/get /category:"{0}"'.format(category)
results = _auditpol_cmd(cmd)
ret = {}
# Skip the first 2 lines
for line in results[3:]:
if ' ' in line.strip():
ret.update(dict(list(zip(*[iter(re.split(r"\s{2,}", line.strip()))]*2))))
return ret
def get_setting(name):
'''
Get the current configuration for the named audit setting
Args:
name (str): The name of the setting to retrieve
Returns:
str: The current configuration for the named setting
Raises:
KeyError: On invalid setting name
CommandExecutionError: If an error is encountered retrieving the settings
Usage:
.. code-block:: python
import salt.utils.win_lgpo_auditpol
# Get current state of the "Credential Validation" setting
salt.utils.win_lgpo_auditpol.get_setting(name='Credential Validation')
'''
current_settings = get_settings(category='All')
for setting in current_settings:
if name.lower() == setting.lower():
return current_settings[setting]
raise KeyError('Invalid name: {0}'.format(name))
def _get_valid_names():
if 'auditpol.valid_names' not in __context__:
settings = get_settings(category='All')
__context__['auditpol.valid_names'] = [k.lower() for k in settings]
return __context__['auditpol.valid_names']
def set_setting(name, value):
'''
Set the configuration for the named audit setting
Args:
name (str):
The name of the setting to configure
value (str):
The configuration for the named value. Valid options are:
- No Auditing
- Success
- Failure
- Success and Failure
Returns:
bool: True if successful
Raises:
KeyError: On invalid ``name`` or ``value``
CommandExecutionError: If an error is encountered modifying the setting
Usage:
.. code-block:: python
import salt.utils.win_lgpo_auditpol
# Set the state of the "Credential Validation" setting to Success and
# Failure
salt.utils.win_lgpo_auditpol.set_setting(name='Credential Validation',
value='Success and Failure')
# Set the state of the "Credential Validation" setting to No Auditing
salt.utils.win_lgpo_auditpol.set_setting(name='Credential Validation',
value='No Auditing')
'''
# Input validation
if name.lower() not in _get_valid_names():
raise KeyError('Invalid name: {0}'.format(name))
for setting in settings:
if value.lower() == setting.lower():
cmd = '/set /subcategory:"{0}" {1}'.format(name, settings[setting])
break
else:
raise KeyError('Invalid setting value: {0}'.format(value))
_auditpol_cmd(cmd)
return True
def get_auditpol_dump():
'''
Gets the contents of an auditpol /backup. Used by the LGPO module to get
fieldnames and GUIDs for Advanced Audit policies.
Returns:
list: A list of lines form the backup file
Usage:
.. code-block:: python
import salt.utils.win_lgpo_auditpol
dump = salt.utils.win_lgpo_auditpol.get_auditpol_dump()
'''
# Just get a temporary file name
# NamedTemporaryFile will delete the file it creates by default on Windows
with tempfile.NamedTemporaryFile(suffix='.csv') as tmp_file:
csv_file = tmp_file.name
cmd = '/backup /file:{0}'.format(csv_file)
_auditpol_cmd(cmd)
with salt.utils.files.fopen(csv_file) as fp:
return fp.readlines()