[chef-16] INFC-303 - Backport changes from v18 to v16 for documentation and missing privilege in verify list

Signed-off-by: Corey Hemminger <hemminger@hotmail.com>

1 files changed, 37 insertions, 27 deletions

diff --git a/lib/chef/resource/windows_user_privilege.rb b/lib/chef/resource/windows_user_privilege.rb
index e6883dc80d..e9bd0b789c 100644
--- a/lib/chef/resource/windows_user_privilege.rb
+++ b/lib/chef/resource/windows_user_privilege.rb
@@ -24,7 +24,7 @@ class Chef
       unified_mode true
 
       provides :windows_user_privilege
-      description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege.\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
+      description "The windows_user_privilege resource allows to add a privilege to a principal or (User/Group).\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
 
       introduced "16.0"
 
@@ -39,23 +39,32 @@ class Chef
       end
       ```
 
-      **Add the SeDenyRemoteInteractiveLogonRight Privilege to the Builtin Guests and Local Accounts User Groups**:
+      **Provide only the Builtin Guests and Administrator Groups with the SeCreatePageFile Privilege**:
+
+      ```ruby
+      windows_user_privilege 'Create Pagefile' do
+        privilege      'SeCreatePagefilePrivilege'
+        users          ['BUILTIN\\Guests', 'BUILTIN\\Administrators']
+        action         :set
+      end
+      ```
+
+      **Add the SeDenyRemoteInteractiveLogonRight Privilege to the 'Remote interactive logon' principal**:
 
       ```ruby
       windows_user_privilege 'Remote interactive logon' do
         privilege      'SeDenyRemoteInteractiveLogonRight'
-        users          ['Builtin\\Guests', 'NT AUTHORITY\\Local Account']
         action         :add
       end
       ```
 
-      **Provide only the Builtin Guests and Administrator Groups with the SeCreatePageFile Privilege**:
+      **Add to the Builtin Guests Group the SeCreatePageFile Privilege**:
 
       ```ruby
-      windows_user_privilege 'Create Pagefile' do
+      windows_user_privilege 'Guests add Create Pagefile' do
+        principal      'BUILTIN\\Guests'
         privilege      'SeCreatePagefilePrivilege'
-        users          ['BUILTIN\\Guests', 'BUILTIN\\Administrators']
-        action         :set
+        action         :add
       end
       ```
 
@@ -90,6 +99,7 @@ class Chef
                            SeCreateSymbolicLinkPrivilege
                            SeCreateTokenPrivilege
                            SeDebugPrivilege
+                           SeDelegateSessionUserImpersonatePrivilege
                            SeDenyBatchLogonRight
                            SeDenyInteractiveLogonRight
                            SeDenyNetworkLogonRight
@@ -126,20 +136,20 @@ class Chef
                           }.freeze
 
       property :principal, String,
-        description: "An optional property to add the user to the given privilege. Use only with add and remove action.",
-        name_property: true
+               description: "An optional property to add the privilege for given principal. Use only with add and remove action. Principal can either be a User/Group or one of special identities found here Ref: https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/special-identities",
+               name_property: true
 
       property :users, [Array, String],
-        description: "An optional property to set the privilege for given users. Use only with set action.",
-        coerce: proc { |v| Array(v) }
+               description: "An optional property to set the privilege for given users. Use only with set action.",
+               coerce: proc { |v| Array(v) }
 
       property :privilege, [Array, String],
-        description: "One or more privileges to set for users.",
-        required: true,
-        coerce: proc { |v| Array(v) },
-        callbacks: {
-          "Privilege property restricted to the following values: #{PRIVILEGE_OPTS}" => lambda { |n| (n - PRIVILEGE_OPTS).empty? },
-        }, identity: true
+               description: "One or more privileges to set for principal or users/groups. For more information on what each privilege does Ref: https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment",
+               required: true,
+               coerce: proc { |v| Array(v) },
+               callbacks: {
+                 "Privilege property restricted to the following values: #{PRIVILEGE_OPTS}" => lambda { |n| (n - PRIVILEGE_OPTS).empty? },
+               }, identity: true
 
       load_current_value do |new_resource|
         if new_resource.principal && (new_resource.action.include?(:add) || new_resource.action.include?(:remove))
@@ -147,15 +157,15 @@ class Chef
         end
       end
 
-      action :add do
-        ([*new_resource.privilege] - [*current_resource.privilege]).each do |user_right|
-          converge_by("adding user '#{new_resource.principal}' privilege #{user_right}") do
-            Chef::ReservedNames::Win32::Security.add_account_right(new_resource.principal, user_right)
+      action :add, description: "Add a privileges to a principal." do
+        ([*new_resource.privilege] - [*current_resource.privilege]).each do |principal_right|
+          converge_by("adding principal '#{new_resource.principal}' privilege #{principal_right}") do
+            Chef::ReservedNames::Win32::Security.add_account_right(new_resource.principal, principal_right)
           end
         end
       end
 
-      action :set do
+      action :set, description: "Set the privileges that are listed in the `privilege` property for only the users listed in the `users` property. All other users not listed with given privilege will be have the privilege removed." do
         if new_resource.users.nil? || new_resource.users.empty?
           raise Chef::Exceptions::ValidationFailed, "Users are required property with set action."
         end
@@ -190,7 +200,7 @@ class Chef
         end
       end
 
-      action :clear do
+      action :clear, description: "Clear all user privileges" do
         new_resource.privilege.each do |privilege|
           accounts = Chef::ReservedNames::Win32::Security.get_account_with_user_rights(privilege)
 
@@ -204,7 +214,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove a principal privilege" do
         curr_res_privilege = current_resource.privilege
         missing_res_privileges = (new_resource.privilege - curr_res_privilege)
 
@@ -212,9 +222,9 @@ class Chef
           Chef::Log.info("User \'#{new_resource.principal}\' for Privilege: #{missing_res_privileges.join(", ")} not found. Nothing to remove.")
         end
 
-        (new_resource.privilege - missing_res_privileges).each do |user_right|
-          converge_by("removing user #{new_resource.principal} from privilege #{user_right}") do
-            Chef::ReservedNames::Win32::Security.remove_account_right(new_resource.principal, user_right)
+        (new_resource.privilege - missing_res_privileges).each do |principal_right|
+          converge_by("removing principal #{new_resource.principal} from privilege #{principal_right}") do
+            Chef::ReservedNames::Win32::Security.remove_account_right(new_resource.principal, principal_right)
           end
         end
       end