win_firewall_rule - support ICMP types and codes (#60361)

* win_firewall_rule - support ICMP types and codes

* Update main.yml

* Add more examples and change type to list

changelogs/fragments/win_firewall_rule-add-support-for-icmptypecode.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "win_firewall_rule - add parameter to support ICMP Types and Codes (https://github.com/ansible/ansible/issues/46809)"

lib/ansible/modules/windows/win_firewall_rule.ps1

@@ -129,6 +129,7 @@ $protocol = Get-AnsibleParam -obj $params -name "protocol" -type "str"
 $interfacetypes = Get-AnsibleParam -obj $params -name "interfacetypes" -type "list"
 $edge = Get-AnsibleParam -obj $params -name "edge" -type "str" -validateset "no","yes","deferapp","deferuser"
 $security = Get-AnsibleParam -obj $params -name "security" -type "str" -validateset "notrequired","authnoencap","authenticate","authdynenc","authenc"
+$icmp_type_code = Get-AnsibleParam -obj $params -name "icmp_type_code" -type "list"
 
 $state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "present","absent"
 
@@ -137,6 +138,11 @@ if ($diff_support) {
     $result.diff.prepared = ""
 }
 
+if ($null -ne $icmp_type_code) {
+    # COM representation is just "<type>:<code>,<type2>:<code>" so we just join our list
+    $icmp_type_code = $icmp_type_code -join ","
+}
+
 try {
     $fw = New-Object -ComObject HNetCfg.FwPolicy2
 
@@ -160,6 +166,7 @@ try {
     if ($null -ne $remoteport -and $remoteport -ne "any") { $new_rule.RemotePorts = $remoteport }
     if ($null -ne $localip -and $localip -ne "any") { $new_rule.LocalAddresses = $localip }
     if ($null -ne $remoteip -and $remoteip -ne "any") { $new_rule.RemoteAddresses = $remoteip }
+    if ($null -ne $icmp_type_code -and $icmp_type_code -ne "any") { $new_rule.IcmpTypesAndCodes = $icmp_type_code }
     if ($null -ne $direction) { $new_rule.Direction = Parse-Direction -directionStr $direction }
     if ($null -ne $action) { $new_rule.Action = Parse-Action -actionStr $action }
     # Profiles value cannot be a uint32, but the "all profiles" value (0x7FFFFFFF) will often become a uint32, so must cast to [int]
@@ -178,8 +185,8 @@ try {
         }
     }
 
-    $fwPropertiesToCompare = @('Name','Description','Direction','Action','ApplicationName','Grouping','ServiceName','Enabled','Profiles','LocalAddresses','RemoteAddresses','LocalPorts','RemotePorts','Protocol','InterfaceTypes', 'EdgeTraversalOptions', 'SecureFlags')
+    $fwPropertiesToCompare = @('Name','Description','Direction','Action','ApplicationName','Grouping','ServiceName','Enabled','Profiles','LocalAddresses','RemoteAddresses','LocalPorts','RemotePorts','Protocol','InterfaceTypes', 'EdgeTraversalOptions', 'SecureFlags','IcmpTypesAndCodes')
-    $userPassedArguments = @($name, $description, $direction, $action, $program, $group, $service, $enabled, $profiles, $localip, $remoteip, $localport, $remoteport, $protocol, $interfacetypes, $edge, $security)
+    $userPassedArguments = @($name, $description, $direction, $action, $program, $group, $service, $enabled, $profiles, $localip, $remoteip, $localport, $remoteport, $protocol, $interfacetypes, $edge, $security, $icmp_type_code)
 
     if ($state -eq "absent") {
         if ($null -eq $existingRule) {

lib/ansible/modules/windows/win_firewall_rule.py

@@ -105,6 +105,18 @@ options:
       - Defaults to C(domain,private,public) when creating a new rule.
     type: list
     aliases: [ profile ]
+  icmp_type_code:
+    description:
+      - The ICMP types and codes for the rule.
+      - This is only valid when I(protocol) is C(icmpv4) or C(icmpv6).
+      - Each entry follows the format C(type:code) where C(type) is the type
+        number and C(code) is the code number for that type or C(*) for all
+        codes.
+      - Set the value to just C(*) to apply the rule for all ICMP type codes.
+      - See U(https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml)
+        for a list of ICMP types and the codes that apply to them.
+    type: list
+    version_added: '2.10'
 seealso:
 - module: win_firewall
 author:
@@ -163,5 +175,18 @@ EXAMPLES = r'''
     profiles: private
     action: allow
     direction: in
-    protocol: "icmpv4:8,any"
+    protocol: icmpv4
+    icmp_type_code:
+    - '8:*'
+
+- name: Firewall rule to alloc ICMP v4 on all type codes
+  win_firewall_rule:
+    name: ICMP Allow incoming V4 echo request
+    enabled: yes
+    state: present
+    profiles: private
+    action: allow
+    direction: in
+    protocol: icmpv4
+    icmp_type_code: '*'
 '''

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

@@ -438,6 +438,7 @@
   assert:
     that:
     - add_firewall_rule_with_var_expand_path.changed == false
+
 - name: Add firewall rule for application group
   win_firewall_rule:
     name: Rule for application group
@@ -454,3 +455,20 @@
   assert:
     that:
     - add_firewall_rule_with_group.changed == true
+
+# Test icmptypecode
+- name: Add rule with icmptypecode
+  win_firewall_rule:
+    name: icmptest
+    enabled: yes
+    state: present
+    action: allow
+    direction: in
+    protocol: icmpv4
+    icmp_type_code: '8:*'
+  register: add_firewall_rule_with_icmptypecode
+
+- name: Check that creating same firewall rule with expanded vars identified
+  assert:
+    that:
+    - add_firewall_rule_with_icmptypecode.changed == true