win_firewall: check-mode support, integration tests (#25127)

* win_firewall: check-mode support, integration tests

This PR includes:
- Check-mode implementation
- Documentation improvements
- Ensure module output is consistent (no matter what profiles are provided)
- Fixed indentation
- Cosmetic changes
- Integration tests

* win_firewall: check-mode support, integration tests

This PR includes:
- Check-mode implementation
- Documentation improvements
- Ensure module output is consistent (no matter what profiles are provided)
- Fixed indentation
- Cosmetic changes
- Integration tests

lib/ansible/modules/windows/win_firewall.ps1

@@ -19,49 +19,59 @@
 # WANT_JSON
 # POWERSHELL_COMMON
 
+$ErrorActionPreference = "Stop"
+$firewall_profiles = @('Domain', 'Private', 'Public')
 
-# get params
+$params = Parse-Args $args -supports_check_mode $true
-$params = Parse-Args $args -supports_check_mode $false
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
 
-$profiles = Get-AnsibleParam -obj $params -name "profiles" -type "list" -default [ "Public", "Domain", "Private" ]
+$profiles = Get-AnsibleParam -obj $params -name "profiles" -type "list" -default @("Domain", "Private", "Public")
-$wantedstate = Get-AnsibleParam -obj $params -name "state" -type "str" -failifempty $true -validateset 'enabled', 'disabled'
+$state = Get-AnsibleParam -obj $params -name "state" -type "str" -failifempty $true -validateset 'disabled','enabled'
 
 $result = @{
     changed = $false
+    profiles = $profiles
+    state = $state
+}
 
+if ($PSVersionTable.PSVersion -lt [Version]"5.0") {
+    Fail-Json $result "win_firewall requires Windows Management Framework 5 or higher."
 }
 
 Try {
 
-  ForEach($profile in $profiles)
+    ForEach ($profile in $firewall_profiles) {
-
-  {
 
         $currentstate = (Get-NetFirewallProfile -Name $profile).Enabled
+        $result.$profile = @{
+            enabled = ($currentstate -eq 1)
+            considered = ($profiles -contains $profile)
+            currentstate = $currentstate
+        }
 
-      if ($wantedstate -eq 'enabled')
+        if ($profiles -notcontains $profile) {
-      {
+            continue
-        if ($currentstate -eq $false)
+        }
-        {
+
-            Set-NetFirewallProfile -name $profile -Enabled true
+        if ($state -eq 'enabled') {
-            $result.enabled = $true
+
+            if ($currentstate -eq $false) {
+                Set-NetFirewallProfile -name $profile -Enabled true -WhatIf:$check_mode
                 $result.changed = $true
+                $result.$profile.enabled = $true
             }
-      }
+
-      else
+        } else {
-      {
+
-        if ($currentstate -eq $true)
+            if ($currentstate -eq $true) {
-        {
+                Set-NetFirewallProfile -name $profile -Enabled false -WhatIf:$check_mode
-           Set-NetFirewallProfile -name $profile -Enabled false
-           $result.enabled = $false
                 $result.changed = $true
+                $result.$profile.enabled = $false
             }
 
         }
-
     }
-}
+} Catch {
-Catch {
     Fail-Json $result "an error occurred when attempting to change firewall status for profile $profile $($_.Exception.Message)"
 }
 

lib/ansible/modules/windows/win_firewall.py

@@ -28,36 +28,36 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
 DOCUMENTATION = r'''
 ---
 module: win_firewall
-version_added: "2.4"
+version_added: '2.4'
-short_description: Manages Windows Firewall
+short_description: Enable or disable the Windows Firewall
 description:
-    - Manages Windows Firewall
+- Enable or Disable Windows Firewall profiles.
 options:
-  profile:
+  profiles:
     description:
-    - specify the profile to change
+    - Specify one or more profiles to change.
     choices:
-    - Public
     - Domain
     - Private
+    - Public
+    default: [Domain, Private, Public]
   state:
     description:
-    - set state of firewall for given profile
+    - Set state of firewall for given profile.
     choices:
     - enabled
     - disabled
-
+author: Michael Eaton (@MichaelEaton83)
-author: "Michael Eaton (@MichaelEaton83)"
 '''
 
 EXAMPLES = r'''
-- name: Enable all firewalls
+- name: Enable firewall for Domain, Public and Private profiles
   win_firewall:
     state: enabled
     profiles:
     - Domain
-      - Public
     - Private
+    - Public
   tags: enable_firewall
 
 - name: Disable Domain firewall
@@ -69,14 +69,19 @@ EXAMPLES = r'''
 '''
 
 RETURN = r'''
-profile:
-    description: chosen profile
-    returned: always
-    type: string
-    sample: Domain
 enabled:
     description: current firewall status for chosen profile (after any potential change)
     returned: always
     type: bool
     sample: true
+profiles:
+    description: chosen profile
+    returned: always
+    type: string
+    sample: Domain
+state:
+    description: desired state of the given firewall profile(s)
+    returned: always
+    type: list
+    sample: enabled
 '''

test/integration/targets/win_firewall/aliases

@@ -0,0 +1 @@
+windows/ci/group2

test/integration/targets/win_firewall/tasks/main.yml

@@ -0,0 +1,52 @@
+# NOTE: The win_firewall module only works on WMF 5+
+
+- setup:
+
+- name: Test Windows capabilities
+  raw: Get-Command Get-NetFirewallProfile -ErrorAction SilentlyContinue; return $?
+  failed_when: no
+  register: get_netfirewallprofile
+
+- name: Only run tests when Windows is capable
+  when: get_netfirewallprofile.rc == 0 and ansible_powershell_version >= 5
+  block:
+  - name: Turn off Windows Firewall (begin)
+    win_firewall:
+      profiles: [ Domain, Private, Public ]
+      state: disabled
+    register: firewall_off
+
+  - name: Test firewall_off
+    assert:
+      that:
+      - not firewall_off.Domain.enabled
+      - not firewall_off.Private.enabled
+      - not firewall_off.Public.enabled
+
+
+  - name: Test in normal mode
+    include: tests.yml
+    vars:
+      in_check_mode: no
+
+
+  - name: Test in check-mode
+    include: tests.yml
+    vars:
+      in_check_mode: yes
+    check_mode: yes
+
+
+  - name: Turn on Windows Firewall (end)
+    win_firewall:
+      profiles: [ Domain, Private, Public ]
+      state: enabled
+    register: firewall_on
+
+  - name: Test firewall_on
+    assert:
+      that:
+      - firewall_on|changed
+      - firewall_on.Domain.enabled
+      - firewall_on.Private.enabled
+      - firewall_on.Public.enabled

test/integration/targets/win_firewall/tasks/tests.yml

@@ -0,0 +1,185 @@
+# We start with firewall turned off
+
+- name: Turn off Windows Firewall again
+  win_firewall:
+    profiles: [ Domain, Private, Public ]
+    state: disabled
+  register: firewall_off_again
+
+- name: Test firewall_off_again
+  assert:
+    that:
+    - not firewall_off_again|changed
+    - not firewall_off_again.Domain.enabled
+    - not firewall_off_again.Private.enabled
+    - not firewall_off_again.Public.enabled
+
+- name: Turn on Windows Firewall on Public
+  win_firewall:
+    profiles: [ Public ]
+    state: enabled
+  register: firewall_public_on
+
+- name: Test firewall_public_on
+  assert:
+    that:
+    - firewall_public_on|changed
+    - not firewall_public_on.Domain.enabled
+    - not firewall_public_on.Private.enabled
+    - firewall_public_on.Public.enabled
+
+
+- name: Turn on Windows Firewall on Public again
+  win_firewall:
+    profiles: [ Public ]
+    state: enabled
+  register: firewall_public_on_again
+
+- name: Test firewall_public_on_again (normal mode)
+  assert:
+    that:
+    - not firewall_public_on_again|changed
+    - not firewall_public_on_again.Domain.enabled
+    - not firewall_public_on_again.Private.enabled
+    - firewall_public_on_again.Public.enabled
+  when: not in_check_mode
+
+- name: Test firewall_public_on_again (check-mode)
+  assert:
+    that:
+    - firewall_public_on_again|changed
+    - not firewall_public_on_again.Domain.enabled
+    - not firewall_public_on_again.Private.enabled
+    - firewall_public_on_again.Public.enabled
+  when: in_check_mode
+
+
+# On purpose not a list
+- name: Turn on Windows Firewall on Domain
+  win_firewall:
+    profiles: Domain
+    state: enabled
+  register: firewall_domain_on
+
+- name: Test firewall_domain_on (normal mode)
+  assert:
+    that:
+    - firewall_domain_on|changed
+    - firewall_domain_on.Domain.enabled
+    - not firewall_domain_on.Private.enabled
+    - firewall_domain_on.Public.enabled
+  when: not in_check_mode
+
+- name: Test firewall_domain_on (check-mode)
+  assert:
+    that:
+    - firewall_domain_on|changed
+    - firewall_domain_on.Domain.enabled
+    - not firewall_domain_on.Private.enabled
+    - not firewall_domain_on.Public.enabled
+  when: in_check_mode
+
+
+- name: Turn on Windows Firewall on Domain again
+  win_firewall:
+    profiles: [ Domain ]
+    state: enabled
+  register: firewall_domain_on_again
+
+- name: Test firewall_domain_on_again (normal mode)
+  assert:
+    that:
+    - not firewall_domain_on_again|changed
+    - firewall_domain_on.Domain.enabled
+    - not firewall_domain_on.Private.enabled
+    - firewall_domain_on.Public.enabled
+  when: not in_check_mode
+
+- name: Test firewall_domain_on_again (check-mode)
+  assert:
+    that:
+    - firewall_domain_on_again|changed
+    - firewall_domain_on.Domain.enabled
+    - not firewall_domain_on.Private.enabled
+    - not firewall_domain_on.Public.enabled
+  when: in_check_mode
+
+
+- name: Turn on Windows Firewall
+  win_firewall:
+    profiles: [ Domain, Private, Public ]
+    state: enabled
+  register: firewall_on
+
+- name: Test firewall_on
+  assert:
+    that:
+    - firewall_on|changed
+    - firewall_on.Domain.enabled
+    - firewall_on.Private.enabled
+    - firewall_on.Public.enabled
+
+
+# On purpose no profiles added
+- name: Turn on Windows Firewall again
+  win_firewall:
+    state: enabled
+  register: firewall_on_again
+
+- name: Test firewall_on_again (normal mode)
+  assert:
+    that:
+    - not firewall_on_again|changed
+    - firewall_on_again.Domain.enabled
+    - firewall_on_again.Private.enabled
+    - firewall_on_again.Public.enabled
+  when: not in_check_mode
+
+- name: Test firewall_on_again (check-mode)
+  assert:
+    that:
+    - firewall_on_again|changed
+    - firewall_on_again.Domain.enabled
+    - firewall_on_again.Private.enabled
+    - firewall_on_again.Public.enabled
+  when: in_check_mode
+
+
+# On purpose no profiles added
+- name: Turn off Windows Firewall
+  win_firewall:
+    state: disabled
+  register: firewall_off2
+
+- name: Test firewall_off2 (normal mode)
+  assert:
+    that:
+    - firewall_off2|changed
+    - not firewall_off2.Domain.enabled
+    - not firewall_off2.Private.enabled
+    - not firewall_off2.Public.enabled
+  when: not in_check_mode
+
+- name: Test firewall_off2 (check-mode)
+  assert:
+    that:
+    - not firewall_off2|changed
+    - not firewall_off2.Domain.enabled
+    - not firewall_off2.Private.enabled
+    - not firewall_off2.Public.enabled
+  when: in_check_mode
+
+
+- name: Turn off Windows Firewall again
+  win_firewall:
+    profiles: [ Domain, Private, Public ]
+    state: disabled
+  register: firewall_off2_again
+
+- name: Test firewall_off2_again (normal mode)
+  assert:
+    that:
+    - not firewall_off2_again|changed
+    - not firewall_off2_again.Domain.enabled
+    - not firewall_off2_again.Private.enabled
+    - not firewall_off2_again.Public.enabled