| Dir : /proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/states/ |
| Server: Linux ngx353.inmotionhosting.com 4.18.0-553.22.1.lve.1.el8.x86_64 #1 SMP Tue Oct 8 15:52:54 UTC 2024 x86_64 IP: 209.182.202.254 |
| Dir : //proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/states/win_lgpo_reg.py |
"""
LGPO - Registry.pol
===================
.. versionadded:: 3006.0
A state module for working with registry based policies in Windows Local Group
Policy (LGPO). This module contains functions for working with the
``Registry.pol`` file. The ``Registry.pol`` file is the source of truth for
registry settings and LGPO.
Group Policy is refreshed every 90 seconds by default. During that refresh the
contents of the ``Registry.pol`` file are applied to the Registry. If the
setting is changed outside of Group Policy to something other than what is
contained in the ``Registry.pol`` file, it will be changed back during the next
refresh.
In the Group Policy Editor (``gpedit.msc``) these policies can be set to three
states:
- Not Configured
- Enabled
- Disabled
A policy that is "Not Configured" does not have an entry in the ``Registry.pol``
file. A Group Policy refresh will not make any changes to key/value pairs in the
registry that are not specified in the ``Registry.pol`` file.
An "Enabled" policy will have an entry in the ``Registry.pol`` files that
contains its key path, value name, value type, value size, and value data. When
Group Policy is refreshed, existing values will be overwritten with those
contained in the ``Registry.pol`` file.
A "Disabled" policy will have an entry in the ``Registry.pol`` file with the key
path and the value name, but the value name will be prepended with ``**del.``.
When Group Policy is refreshed the key/value will be deleted from the registry.
If the key contains no values, it will also be deleted.
Working with LGPO Reg
---------------------
The easiest way to figure out the values needed for this module is to set the
policy using the Group Policy Editor (``gpedit.msc``) and then run the
``lgpo_reg.read_reg_pol`` function. This function will display a dictionary of
all registry-based policies in the ``Registry.pol`` file. From its return you
can get the ``key``, ``v_name``, ``v_type``, and ``v_data`` required to
configure that policy.
.. note::
Not all policies in the Group Policy Editor (``gpedit.msc``) that write to
the registry make that change in the ``Registry.pol`` file. Those policies
could still be enforced via the ``Registry.pol`` file... theoretically. But
you will have to find the values needed to set them with this module using a
different method.
"""
import salt.utils.data
import salt.utils.platform
__virtualname__ = "lgpo_reg"
def __virtual__():
"""
Only works on Windows with the lgpo_reg module
"""
if not salt.utils.platform.is_windows():
return False, "LGPO_REG State: Only available on Windows"
if "lgpo_reg.get_value" not in __salt__:
return False, "LGPO_REG State: lgpo_reg module not available"
return __virtualname__
def _get_current(key, name, policy_class):
"""
Helper function to get the current state of the policy
"""
hive = "HKLM"
if policy_class == "User":
hive = "HKCU"
pol = __salt__["lgpo_reg.get_value"](
key=key, v_name=name, policy_class=policy_class
)
reg_raw = __utils__["reg.read_value"](hive=hive, key=key, vname=name)
reg = {}
if reg_raw["vdata"] is not None:
reg["data"] = reg_raw["vdata"]
if reg_raw["vtype"] is not None:
reg["type"] = reg_raw["vtype"]
return {"pol": pol, "reg": reg}
def value_present(name, key, v_data, v_type="REG_DWORD", policy_class="Machine"):
r"""
Ensure a registry setting is present in the Registry.pol file.
Args:
name (str): The registry value name within the key
key (str): The registry key path
v_data(str): The registry value
v_type (str): The registry value type. Must be one of the following:
- REG_BINARY
- REG_DWORD
- REG_EXPAND_SZ
- REG_MULTI_SZ
- REG_QWORD
- REG_SZ
Default is REG_DWORD
policy_class (str): The registry class to write to. Can be one of the
following:
- Computer
- Machine
- User
Default is ``Machine``
CLI Example:
.. code-block:: yaml
# Using the name parameter in the definition
set_reg_pol_value:
lgpo_reg.value_present:
- key: SOFTWARE\MyKey
- name: MyValue
- v_type: REG_SZ
- v_data: "some string data"
- policy_class: Machine
# Using the name as the parameter and modifying the User policy
MyValue:
lgpo_reg.value_present:
- key: SOFTWARE\MyKey
- v_type: REG_SZ
- v_data: "some string data"
- policy_class: User
"""
ret = {"name": name, "changes": {}, "result": False, "comment": ""}
old = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = (
str(old["pol"].get("data", "")) == str(v_data)
and old["pol"].get("type", "") == v_type
)
reg_correct = (
str(old["reg"].get("data", "")) == str(v_data)
and old["reg"].get("type", "") == v_type
)
if pol_correct and reg_correct:
ret["comment"] = "Policy value already present\nRegistry value already present"
ret["result"] = True
return ret
if __opts__["test"]:
if not pol_correct:
ret["comment"] = "Policy value will be set"
if not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Registry value will be set"
ret["result"] = None
return ret
__salt__["lgpo_reg.set_value"](
key=key,
v_name=name,
v_data=v_data,
v_type=v_type,
policy_class=policy_class,
)
new = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = (
str(new["pol"]["data"]) == str(v_data) and new["pol"]["type"] == v_type
)
reg_correct = (
str(new["reg"]["data"]) == str(v_data) and new["reg"]["type"] == v_type
)
if pol_correct and reg_correct:
ret["comment"] = "Registry policy value has been set"
ret["result"] = True
elif not pol_correct:
ret["comment"] = "Failed to set policy value"
elif not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Failed to set registry value"
changes = salt.utils.data.recursive_diff(old, new)
if changes:
ret["changes"] = changes
return ret
def value_disabled(name, key, policy_class="Machine"):
r"""
Ensure a registry setting is disabled in the Registry.pol file.
Args:
key (str): The registry key path
name (str): The registry value name within the key
policy_class (str): The registry class to write to. Can be one of the
following:
- Computer
- Machine
- User
Default is ``Machine``
CLI Example:
.. code-block:: yaml
# Using the name parameter in the definition
set_reg_pol_value:
lgpo_reg.value_disabled:
- key: SOFTWARE\MyKey
- name: MyValue
- policy_class: Machine
# Using the name as the parameter and modifying the User policy
MyValue:
lgpo_reg.value_disabled:
- key: SOFTWARE\MyKey
- policy_class: User
"""
ret = {"name": name, "changes": {}, "result": False, "comment": ""}
old = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = old["pol"].get("data", "") == f"**del.{name}"
reg_correct = old["reg"] == {}
if pol_correct and reg_correct:
ret["comment"] = "Registry policy value already disabled"
ret["result"] = True
return ret
if __opts__["test"]:
if not pol_correct:
ret["comment"] = "Policy value will be disabled"
if not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Registry value will be removed"
ret["result"] = None
return ret
__salt__["lgpo_reg.disable_value"](key=key, v_name=name, policy_class=policy_class)
new = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = new["pol"].get("data", "") == f"**del.{name}"
reg_correct = new["reg"] == {}
if pol_correct and reg_correct:
ret["comment"] = "Registry policy value disabled"
ret["result"] = True
elif not pol_correct:
ret["comment"] = "Failed to disable policy value"
elif not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Failed to remove registry value"
changes = salt.utils.data.recursive_diff(old, new)
if changes:
ret["changes"] = changes
return ret
def value_absent(name, key, policy_class="Machine"):
r"""
Ensure a registry setting is not present in the Registry.pol file.
Args:
key (str): The registry key path
name (str): The registry value name within the key
policy_class (str): The registry class to write to. Can be one of the
following:
- Computer
- Machine
- User
Default is ``Machine``
CLI Example:
.. code-block:: yaml
# Using the name parameter in the definition
set_reg_pol_value:
lgpo_reg.value_absent:
- key: SOFTWARE\MyKey
- name: MyValue
- policy_class: Machine
# Using the name as the parameter and modifying the User policy
MyValue:
lgpo_reg.value_absent:
- key: SOFTWARE\MyKey
- policy_class: User
"""
ret = {"name": name, "changes": {}, "result": False, "comment": ""}
old = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = old["pol"] == {}
reg_correct = old["reg"] == {}
if pol_correct and reg_correct:
ret["comment"] = "Registry policy value already deleted"
ret["result"] = True
return ret
if __opts__["test"]:
if not pol_correct:
ret["comment"] = "Policy value will be deleted"
if not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Registry value will be deleted"
ret["result"] = None
return ret
__salt__["lgpo_reg.delete_value"](key=key, v_name=name, policy_class=policy_class)
new = _get_current(key=key, name=name, policy_class=policy_class)
pol_correct = new["pol"] == {}
reg_correct = new["reg"] == {}
if pol_correct and reg_correct:
ret["comment"] = "Registry policy value deleted"
ret["result"] = True
elif not pol_correct:
ret["comment"] = "Failed to delete policy value"
elif not reg_correct:
if ret["comment"]:
ret["comment"] += "\n"
ret["comment"] += "Failed to delete registry value"
changes = salt.utils.data.recursive_diff(old, new)
if changes:
ret["changes"] = changes
return ret