salt.modules.win_lgpo_reg#

LGPO - Registry.pol#

New in version 3006.0.

A 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 "enable" that policy. Use those values to set/disable/delete policies using this module. The same values can also be used to create states for setting these policies.

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.

salt.modules.win_lgpo_reg.delete_value(key, v_name, policy_class='Machine')#

Delete a key/value pair from the Registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to Not Configured.

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • policy_class (str, optional) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:
Returns:

True if successful, otherwise False None: Key/value not present

Return type:

bool

CLI Example:

# Delete all values under a key
salt '*' lgpo_reg.delete_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.disable_value(key, v_name, policy_class='machine')#

Mark a registry value for deletion in the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to Disabled in the Group Policy editor (gpedit.msc)

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • policy_class (str, optional) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:
Returns:

True if successful, otherwise False None: If already disabled

Return type:

bool

CLI Example:

# Delete a value
salt '*' lgpo_reg.delete_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.get_key(key, policy_class='Machine')#

Get all the values set in a key in the Registry.pol file.

Parameters:

  • key (str) -- The registry key where the values reside

  • policy_class (str, optional) --

    The registry class to read from. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary containing the value data and the value type

Return type:

dict

CLI Example:

# Get all values from a key
salt '*' lgpo_reg.get_key "SOFTWARE\MyKey"
salt.modules.win_lgpo_reg.get_rsop_value(key, v_name)#

Query the Resultant Set of Policy (RSoP) for a specific Machine registry key/value. Returns information about the winning Group Policy Object (GPO) for that value, including whether it is managed by a Domain GPO.

Note

Only Machine (computer) policy is supported. User policy RSoP requires per-user SID scoping and a different WMI namespace, which is not practical when Salt runs as SYSTEM.

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name

Returns:

A dictionary containing the RSoP information, or {} if the value is not found in RSoP, if the machine is not domain-joined, or if WMI is unavailable. Keys when a result is found:

  • key (str): The registry key path

  • name (str): The registry value name

  • data: The value data

  • type (str): The registry value type (e.g. REG_DWORD)

  • gpo_id (str): The GUID of the winning GPO

  • gpo_name (str): The display name of the winning GPO

  • precedence (int): The policy precedence (1 = winning)

  • domain_managed (bool): True if managed by a Domain GPO

Return type:

dict

CLI Example:

salt '*' lgpo_reg.get_rsop_value "SYSTEM\CurrentControlSet\Services\Netlogon\Parameters" VulnerableChannelAllowList
salt.modules.win_lgpo_reg.get_value(key, v_name, policy_class='Machine')#

Get the value of a single value pair as set in the Registry.pol file.

Parameters:

  • key (str) -- The registry key where the value name resides

  • v_name (str) -- The value name to retrieve

  • policy_class (str, optional) --

    The registry class to read from. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary containing the value data and the value type found

Return type:

dict

CLI Example:

# Get a value
salt '*' lgpo_reg.get_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.read_reg_pol(policy_class='Machine')#

Read the contents of the Registry.pol file. Display the contents as a human-readable dictionary.

Parameters:

policy_class (str, optional) --

The registry class to retrieve. Can be one of the following:

  • Computer

  • Machine

  • User

Default is Machine.

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary representing the contents of the Registry.pol file

Return type:

dict

CLI Example:

# Read the machine Registry.pol
salt '*' lgpo_reg.read_reg_pol
salt.modules.win_lgpo_reg.set_value(key, v_name, v_data, v_type='REG_DWORD', policy_class='Machine')#

Add a key/value pair to the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting a policy to Enabled

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • v_data (str) -- The registry value

  • v_type (str, optional) --

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

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:
Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

# Set REG_DWORD value (default)
salt '*' lgpo_reg.set_value "SOFTWARE\MyKey" "MyValue" 1

# Set REG_SZ value
salt '*' lgpo_reg.set_value "SOFTWARE\MyKey" "MyValue" "string value" "REG_SZ"
salt.modules.win_lgpo_reg.write_reg_pol(data, policy_class='Machine')#

Write data to the Registry.pol file. The data is a dictionary that is then converted to the appropriate bytes format expected by Registry.pol

Parameters:

  • data (dict) -- A dictionary containing Registry.pol data

  • policy_class (str, optional) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine.

Raises:
Returns:

True if successful

Return type:

bool

CLI Example:

# Write to Machine Registry.pol
salt '*' lgpo_reg.write_reg_pol "{'SOFTWARE\MyKey': {'MyValue': 'data': 1, 'type': 'REG_DWORD'}}"