Merge pull request #11702 from chef/defender_resources

Add windows_defender and windows_defender_exclusion resources

8 files changed, 451 insertions, 1 deletions

diff --git a/cspell.json b/cspell.json
index d6434022e8..614bb8f06d 100644
--- a/cspell.json
+++ b/cspell.json
@@ -14,6 +14,7 @@
   "dictionaries": ["chef"],
   // words - list of words to be always considered correct
   "words": [
+    "IOAV",
     "abcz",
     "Abdulin",
     "ABORTIFHUNG",
diff --git a/kitchen-tests/cookbooks/end_to_end/recipes/_windows_defender.rb b/kitchen-tests/cookbooks/end_to_end/recipes/_windows_defender.rb
new file mode 100644
index 0000000000..90a0403ae3
--- /dev/null
+++ b/kitchen-tests/cookbooks/end_to_end/recipes/_windows_defender.rb
@@ -0,0 +1,25 @@
+#
+# Cookbook:: end_to_end
+# Recipe:: _windows_defender
+#
+# Copyright:: Copyright (c) Chef Software Inc.
+#
+
+windows_defender "Configure Windows Defender" do
+  realtime_protection true
+  intrusion_protection_system true
+  lock_ui true
+  scan_archives true
+  scan_scripts true
+  scan_email true
+  scan_removable_drives true
+  scan_network_files false
+  scan_mapped_drives false
+  action :enable
+end
+
+windows_defender_exclusion "Exclude PNG files" do
+  extensions "png"
+  process_paths 'c:\\windows\\system32'
+  action :add
+end
diff --git a/kitchen-tests/cookbooks/end_to_end/recipes/windows.rb b/kitchen-tests/cookbooks/end_to_end/recipes/windows.rb
index f4cd74e3bf..20140ff7e0 100644
--- a/kitchen-tests/cookbooks/end_to_end/recipes/windows.rb
+++ b/kitchen-tests/cookbooks/end_to_end/recipes/windows.rb
@@ -178,3 +178,4 @@ windows_certificate "c:/mordor/ca.cert.pem" do
 end
 
 include_recipe "::_windows_printer"
+include_recipe "::_windows_defender"
diff --git a/lib/chef/resource/windows_defender.rb b/lib/chef/resource/windows_defender.rb
new file mode 100644
index 0000000000..23894ac4a5
--- /dev/null
+++ b/lib/chef/resource/windows_defender.rb
@@ -0,0 +1,163 @@
+#
+# Copyright:: Chef Software, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative "../resource"
+
+class Chef
+  class Resource
+    class WindowsDefender < Chef::Resource
+      unified_mode true
+      provides :windows_defender
+
+      description "Use the **windows_defender** resource to enable or disable the Microsoft Windows Defender service."
+      introduced "17.3"
+      examples <<~DOC
+      **Configure Windows Defender AV settings**:
+
+      ```ruby
+      windows_defender 'Configure Defender' do
+        realtime_protection true
+        intrusion_protection_system true
+        lock_ui true
+        scan_archives true
+        scan_scripts true
+        scan_email true
+        scan_removable_drives true
+        scan_network_files false
+        scan_mapped_drives false
+        action :enable
+      end
+      ```
+
+      **Disable Windows Defender AV**:
+
+      ```ruby
+      windows_defender 'Disable Defender' do
+        action :disable
+      end
+      ```
+      DOC
+
+      # DisableIOAVProtection
+      property :realtime_protection, [true, false],
+        default: true,
+        description: "Enable realtime scanning of downloaded files and attachments."
+
+      # DisableIntrusionPreventionSystem
+      property :intrusion_protection_system, [true, false],
+        default: true,
+        description: "Enable network protection against exploitation of known vulnerabilities."
+
+      # UILockdown
+      property :lock_ui, [true, false],
+        description: "Lock the UI to prevent users from changing Windows Defender settings.",
+        default: false
+
+      # DisableArchiveScanning
+      property :scan_archives, [true, false],
+        default: true,
+        description: "Scan file archives such as .zip or .gz archives."
+
+      # DisableScriptScanning
+      property :scan_scripts, [true, false],
+        default: false,
+        description: "Scan scripts in malware scans."
+
+      # DisableEmailScanning
+      property :scan_email, [true, false],
+        default: false,
+        description: "Scan e-mails for malware."
+
+      # DisableRemovableDriveScanning
+      property :scan_removable_drives, [true, false],
+        default: false,
+        description: "Scan content of removable drives."
+
+      # DisableScanningNetworkFiles
+      property :scan_network_files, [true, false],
+        default: false,
+        description: "Scan files on a network."
+
+      # DisableScanningMappedNetworkDrivesForFullScan
+      property :scan_mapped_drives, [true, false],
+        default: true,
+        description: "Scan files on mapped network drives."
+
+      load_current_value do
+        values = powershell_exec!("Get-MPpreference").result
+
+        lock_ui values["UILockdown"]
+        realtime_protection !values["DisableIOAVProtection"]
+        intrusion_protection_system !values["DisableIntrusionPreventionSystem"]
+        scan_archives !values["DisableArchiveScanning"]
+        scan_scripts !values["DisableScriptScanning"]
+        scan_email !values["DisableEmailScanning"]
+        scan_removable_drives !values["DisableRemovableDriveScanning"]
+        scan_network_files !values["DisableScanningNetworkFiles"]
+        scan_mapped_drives !values["DisableScanningMappedNetworkDrivesForFullScan"]
+      end
+
+      action :enable do
+        windows_service "Windows Defender" do
+          service_name "WinDefend"
+          action %i{start enable}
+          startup_type :automatic
+        end
+
+        converge_if_changed do
+          powershell_exec!(set_mppreference_cmd)
+        end
+      end
+
+      action :disable do
+        windows_service "Windows Defender" do
+          service_name "WinDefend"
+          action %i{disable stop}
+        end
+      end
+
+      action_class do
+        require "chef/mixin/powershell_type_coercions"
+        include Chef::Mixin::PowershellTypeCoercions
+
+        PROPERTY_TO_PS_MAP = {
+          realtime_protection: "DisableIOAVProtection",
+          intrusion_protection_system: "DisableIntrusionPreventionSystem",
+          scan_archives: "DisableArchiveScanning",
+          scan_scripts: "DisableScriptScanning",
+          scan_email: "DisableEmailScanning",
+          scan_removable_drives: "DisableRemovableDriveScanning",
+          scan_network_files: "DisableScanningNetworkFiles",
+          scan_mapped_drives: "DisableScanningMappedNetworkDrivesForFullScan",
+        }.freeze
+
+        def set_mppreference_cmd
+          cmd = "Set-MpPreference -Force"
+          cmd << " -UILockdown #{type_coercion(new_resource.lock_ui)}"
+
+          # the values are the opposite in Set-MpPreference and our properties so we have to iterate
+          # over the list and negate the provided values so it makes sense with the cmdlet flag's expected value
+          PROPERTY_TO_PS_MAP.each do |prop, flag|
+            next if new_resource.send(prop).nil? || current_resource.send(prop) == new_resource.send(prop)
+
+            cmd << " -#{flag} #{type_coercion(!new_resource.send(prop))}"
+          end
+          cmd
+        end
+      end
+    end
+  end
+end
diff --git a/lib/chef/resource/windows_defender_exclusion.rb b/lib/chef/resource/windows_defender_exclusion.rb
new file mode 100644
index 0000000000..ad9afd77e2
--- /dev/null
+++ b/lib/chef/resource/windows_defender_exclusion.rb
@@ -0,0 +1,125 @@
+#
+# Copyright:: Chef Software, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative "../resource"
+
+class Chef
+  class Resource
+    class WindowsDefenderExclusion < Chef::Resource
+
+      provides :windows_defender_exclusion
+
+      description "Use the **windows_defender_exclusion** resource to exclude paths, processes, or file types from Windows Defender realtime protection scanning."
+      introduced "17.3"
+      examples <<~DOC
+      **Add excluded items to Windows Defender scans**:
+
+      ```ruby
+      windows_defender_exclusion 'Add to things to be excluded from scanning' do
+        paths 'c:\\foo\\bar, d:\\bar\\baz'
+        extensions 'png, foo, ppt, doc'
+        process_paths 'c:\\windows\\system32'
+        action :add
+      end
+      ```
+
+      **Remove excluded items from Windows Defender scans**:
+
+      ```ruby
+      windows_defender_exclusion 'Remove things from the list to be excluded' do
+        process_paths 'c:\\windows\\system32'
+        action :remove
+      end
+      ```
+      DOC
+      unified_mode true
+
+      property :paths, [String, Array], default: [],
+        coerce: proc { |x| to_consistent_path_array(x) },
+        description: "File or directory paths to exclude from scanning."
+
+      property :extensions, [String, Array], default: [],
+        coerce: proc { |x| to_consistent_path_array(x) },
+        description: "File extensions to exclude from scanning."
+
+      property :process_paths, [String, Array], default: [],
+        coerce: proc { |x| to_consistent_path_array(x) },
+        description: "Paths to executables to exclude from scanning."
+
+      def to_consistent_path_array(x)
+        fixed = x.dup || []
+        fixed = fixed.split(/\s*,\s*/) if fixed.is_a?(String)
+        fixed.map!(&:downcase)
+        fixed.map! { |v| v.gsub(%r{/}, "\\") }
+        fixed
+      end
+
+      load_current_value do |new_resource|
+        Chef::Log.debug("Running 'Get-MpPreference | Select-Object ExclusionExtension,ExclusionPath,ExclusionProcess' to get Windows Defender State")
+
+        values = powershell_exec!("Get-MPpreference | Select-Object ExclusionExtension,ExclusionPath,ExclusionProcess").result
+
+        values.transform_values! { |x| Array(x) }
+
+        paths new_resource.paths & values["ExclusionPath"]
+        extensions new_resource.extensions & values["ExclusionExtension"]
+        process_paths new_resource.process_paths & values["ExclusionProcess"]
+      end
+
+      action :add do
+        converge_if_changed do
+          powershell_exec!(add_cmd)
+        end
+      end
+
+      action :remove do
+        converge_if_changed do
+          powershell_exec!(remove_cmd)
+        end
+      end
+
+      action_class do
+        MAPPING = {
+          paths: "ExclusionPath",
+          extensions: "ExclusionExtension",
+          process_paths: "ExclusionProcess",
+        }.freeze
+
+        def add_cmd
+          cmd = "Add-MpPreference -Force"
+
+          MAPPING.each do |prop, flag|
+            to_add = new_resource.send(prop) - current_resource.send(prop)
+            cmd << " -#{flag} #{to_add.join(",")}" unless to_add.empty?
+          end
+
+          cmd
+        end
+
+        def remove_cmd
+          cmd = "Remove-MpPreference -Force"
+
+          MAPPING.each do |prop, flag|
+            to_add = new_resource.send(prop) & current_resource.send(prop)
+            cmd << " -#{flag} #{to_add.join(",")}" unless to_add.empty?
+          end
+
+          cmd
+        end
+      end
+    end
+  end
+end
diff --git a/lib/chef/resources.rb b/lib/chef/resources.rb
index ea39dd6437..3fabc18920 100644
--- a/lib/chef/resources.rb
+++ b/lib/chef/resources.rb
@@ -148,6 +148,8 @@ require_relative "resource/windows_ad_join"
 require_relative "resource/windows_audit_policy"
 require_relative "resource/windows_auto_run"
 require_relative "resource/windows_certificate"
+require_relative "resource/windows_defender"
+require_relative "resource/windows_defender_exclusion"
 require_relative "resource/windows_dfs_folder"
 require_relative "resource/windows_dfs_namespace"
 require_relative "resource/windows_dfs_server"
@@ -170,4 +172,4 @@ require_relative "resource/windows_uac"
 require_relative "resource/windows_workgroup"
 require_relative "resource/timezone"
 require_relative "resource/windows_user_privilege"
-require_relative "resource/windows_security_policy"
\ No newline at end of file
+require_relative "resource/windows_security_policy"
diff --git a/spec/unit/resource/windows_defender_exclusion_spec.rb b/spec/unit/resource/windows_defender_exclusion_spec.rb
new file mode 100644
index 0000000000..f776c07713
--- /dev/null
+++ b/spec/unit/resource/windows_defender_exclusion_spec.rb
@@ -0,0 +1,62 @@
+#
+# Copyright:: Copyright (c) Chef Software Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "spec_helper"
+
+describe Chef::Resource::WindowsDefenderExclusion do
+  let(:resource) { Chef::Resource::WindowsDefenderExclusion.new("fakey_fakerton") }
+
+  it "sets resource name as :windows_defender_exclusion" do
+    expect(resource.resource_name).to eql(:windows_defender_exclusion)
+  end
+
+  it "sets the default action as :add" do
+    expect(resource.action).to eql([:add])
+  end
+
+  it "supports :add, :remove actions" do
+    expect { resource.action :add }.not_to raise_error
+    expect { resource.action :remove }.not_to raise_error
+  end
+
+  it "paths property defaults to []" do
+    expect(resource.paths).to eql([])
+  end
+
+  it "paths coerces strings to arrays" do
+    resource.paths "foo,bar"
+    expect(resource.paths).to eq(%w{foo bar})
+  end
+
+  it "extensions property defaults to []" do
+    expect(resource.extensions).to eql([])
+  end
+
+  it "extensions coerces strings to arrays" do
+    resource.extensions "foo,bar"
+    expect(resource.extensions).to eq(%w{foo bar})
+  end
+
+  it "process_paths property defaults to []" do
+    expect(resource.process_paths).to eql([])
+  end
+
+  it "process_paths coerces strings to arrays" do
+    resource.process_paths "foo,bar"
+    expect(resource.process_paths).to eq(%w{foo bar})
+  end
+end
diff --git a/spec/unit/resource/windows_defender_spec.rb b/spec/unit/resource/windows_defender_spec.rb
new file mode 100644
index 0000000000..1cafd262a5
--- /dev/null
+++ b/spec/unit/resource/windows_defender_spec.rb
@@ -0,0 +1,71 @@
+#
+# Copyright:: Copyright (c) Chef Software Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "spec_helper"
+
+describe Chef::Resource::WindowsDefender do
+  let(:resource) { Chef::Resource::WindowsDefender.new("fakey_fakerton") }
+
+  it "sets resource name as :windows_defender" do
+    expect(resource.resource_name).to eql(:windows_defender)
+  end
+
+  it "sets the default action as :enable" do
+    expect(resource.action).to eql([:enable])
+  end
+
+  it "supports :enable, :disable actions" do
+    expect { resource.action :enable }.not_to raise_error
+    expect { resource.action :disable }.not_to raise_error
+  end
+
+  it "realtime_protection property defaults to true" do
+    expect(resource.realtime_protection).to eql(true)
+  end
+
+  it "intrusion_protection_system property defaults to true" do
+    expect(resource.intrusion_protection_system).to eql(true)
+  end
+
+  it "lock_ui property defaults to true" do
+    expect(resource.lock_ui).to eql(false)
+  end
+
+  it "scan_archives property defaults to true" do
+    expect(resource.scan_archives).to eql(true)
+  end
+
+  it "scan_scripts property defaults to true" do
+    expect(resource.scan_scripts).to eql(false)
+  end
+
+  it "scan_email property defaults to true" do
+    expect(resource.scan_email).to eql(false)
+  end
+
+  it "scan_removable_drives property defaults to true" do
+    expect(resource.scan_removable_drives).to eql(false)
+  end
+
+  it "scan_network_files property defaults to true" do
+    expect(resource.scan_network_files).to eql(false)
+  end
+
+  it "scan_mapped_drives property defaults to true" do
+    expect(resource.scan_mapped_drives).to eql(true)
+  end
+end