1 #!powershell
2
3 # Copyright: (c) 2014, Timothy Vandenbrande <timothy.vandenbrande@gmail.com>
4 # Copyright: (c) 2017, Artem Zinenko <zinenkoartem@gmail.com>
5 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7 #Requires -Module Ansible.ModuleUtils.Legacy
8
ConvertTo-ProtocolType()9 function ConvertTo-ProtocolType {
10 param($protocol)
11
12 $protocolNumber = $protocol -as [int]
13 if ($protocolNumber -is [int]) {
14 return $protocolNumber
15 }
16
17 switch -wildcard ($protocol) {
18 "tcp" { return [System.Net.Sockets.ProtocolType]::Tcp -as [int] }
19 "udp" { return [System.Net.Sockets.ProtocolType]::Udp -as [int] }
20 "icmpv4*" { return [System.Net.Sockets.ProtocolType]::Icmp -as [int] }
21 "icmpv6*" { return [System.Net.Sockets.ProtocolType]::IcmpV6 -as [int] }
22 default { throw "Unknown protocol '$protocol'." }
23 }
24 }
25
26 # See 'Direction' constants here: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364724(v=vs.85).aspx
ConvertTo-Directionnull27 function ConvertTo-Direction {
28 param($directionStr)
29
30 switch ($directionStr) {
31 "in" { return 1 }
32 "out" { return 2 }
33 default { throw "Unknown direction '$directionStr'." }
34 }
35 }
36
37 # See 'Action' constants here: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364724(v=vs.85).aspx
ConvertTo-Action()38 function ConvertTo-Action {
39 param($actionStr)
40
41 switch ($actionStr) {
42 "block" { return 0 }
43 "allow" { return 1 }
44 default { throw "Unknown action '$actionStr'." }
45 }
46 }
47
48 # Profile enum values: https://msdn.microsoft.com/en-us/library/windows/desktop/aa366303(v=vs.85).aspx
ConvertTo-Profilesnull49 function ConvertTo-Profiles
50 {
51 param($profilesList)
52
53 $profiles = ($profilesList | Select-Object -Unique | ForEach-Object {
54 switch ($_) {
55 "domain" { return 1 }
56 "private" { return 2 }
57 "public" { return 4 }
58 default { throw "Unknown profile '$_'." }
59 }
60 } | Measure-Object -Sum).Sum
61
62 if ($profiles -eq 7) { return 0x7fffffff }
63 return $profiles
64 }
65
ConvertTo-InterfaceTypes()66 function ConvertTo-InterfaceTypes
67 {
68 param($interfaceTypes)
69
70 return ($interfaceTypes | Select-Object -Unique | ForEach-Object {
71 switch ($_) {
72 "wireless" { return "Wireless" }
73 "lan" { return "Lan" }
74 "ras" { return "RemoteAccess" }
75 default { throw "Unknown interface type '$_'." }
76 }
77 }) -Join ","
78 }
79
ConvertTo-EdgeTraversalOptions()80 function ConvertTo-EdgeTraversalOptions
81 {
82 param($edgeTraversalOptionsStr)
83
84 switch ($edgeTraversalOptionsStr) {
85 "yes" { return 1 }
86 "deferapp" { return 2 }
87 "deferuser" { return 3 }
88 default { throw "Unknown edge traversal options '$edgeTraversalOptionsStr'." }
89 }
90 }
91
ConvertTo-SecureFlags()92 function ConvertTo-SecureFlags
93 {
94 param($secureFlagsStr)
95
96 switch ($secureFlagsStr) {
97 "authnoencap" { return 1 }
98 "authenticate" { return 2 }
99 "authdynenc" { return 3 }
100 "authenc" { return 4 }
101 default { throw "Unknown secure flags '$secureFlagsStr'." }
102 }
103 }
104
105 $ErrorActionPreference = "Stop"
106
107 $result = @{
108 changed = $false
109 }
110
111 $params = Parse-Args $args -supports_check_mode $true
112 $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
113 $diff_support = Get-AnsibleParam -obj $params -name "_ansible_diff" -type "bool" -default $false
114
115 $name = Get-AnsibleParam -obj $params -name "name"
116 $description = Get-AnsibleParam -obj $params -name "description" -type "str"
117 $direction = Get-AnsibleParam -obj $params -name "direction" -type "str" -validateset "in","out"
118 $action = Get-AnsibleParam -obj $params -name "action" -type "str" -validateset "allow","block"
119 $program = Get-AnsibleParam -obj $params -name "program" -type "str"
120 $group = Get-AnsibleParam -obj $params -name "group" -type "str"
121 $service = Get-AnsibleParam -obj $params -name "service" -type "str"
122 $enabled = Get-AnsibleParam -obj $params -name "enabled" -type "bool" -aliases "enable"
123 $profiles = Get-AnsibleParam -obj $params -name "profiles" -type "list" -aliases "profile"
124 $localip = Get-AnsibleParam -obj $params -name "localip" -type "str"
125 $remoteip = Get-AnsibleParam -obj $params -name "remoteip" -type "str"
126 $localport = Get-AnsibleParam -obj $params -name "localport" -type "str"
127 $remoteport = Get-AnsibleParam -obj $params -name "remoteport" -type "str"
128 $protocol = Get-AnsibleParam -obj $params -name "protocol" -type "str"
129 $interfacetypes = Get-AnsibleParam -obj $params -name "interfacetypes" -type "list"
130 $edge = Get-AnsibleParam -obj $params -name "edge" -type "str" -validateset "no","yes","deferapp","deferuser"
131 $security = Get-AnsibleParam -obj $params -name "security" -type "str" -validateset "notrequired","authnoencap","authenticate","authdynenc","authenc"
132 $icmp_type_code = Get-AnsibleParam -obj $params -name "icmp_type_code" -type "list"
133
134 $state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "present","absent"
135
136 if (-not $name -and -not $group) {
137 Fail-Json -obj $result -message "Either name or group must be specified"
138 }
139
140 if ($diff_support) {
141 $result.diff = @{}
142 $result.diff.prepared = ""
143 }
144
145 if ($null -ne $icmp_type_code) {
146 # COM representation is just "<type>:<code>,<type2>:<code>" so we just join our list
147 $icmp_type_code = $icmp_type_code -join ","
148 }
149
150 try {
151 $fw = New-Object -ComObject HNetCfg.FwPolicy2
152
153 # If name was specified, filter the rules by name, otherwise find all the rules in the group.
154 $existingRules = $fw.Rules | Where-Object {
155 if ($name) {
156 $_.Name -eq $name
157 } else {
158 $_.Grouping -eq $group
159 }
160 }
161
162 # INetFwRule interface description: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365344(v=vs.85).aspx
163 $new_rule = New-Object -ComObject HNetCfg.FWRule
164 if ($name) {
165 $new_rule.Name = $name
166 }
167 # the default for enabled in module description is "true", but the actual COM object defaults to "false" when created
168 if ($null -ne $enabled) { $new_rule.Enabled = $enabled } else { $new_rule.Enabled = $true }
169 if ($null -ne $description) { $new_rule.Description = $description }
170 if ($null -ne $group) { $new_rule.Grouping = $group }
171 if ($null -ne $program -and $program -ne "any") { $new_rule.ApplicationName = [System.Environment]::ExpandEnvironmentVariables($program) }
172 if ($null -ne $service -and $service -ne "any") { $new_rule.ServiceName = $service }
173 if ($null -ne $protocol -and $protocol -ne "any") { $new_rule.Protocol = ConvertTo-ProtocolType -protocol $protocol }
174 if ($null -ne $localport -and $localport -ne "any") { $new_rule.LocalPorts = $localport }
175 if ($null -ne $remoteport -and $remoteport -ne "any") { $new_rule.RemotePorts = $remoteport }
176 if ($null -ne $localip -and $localip -ne "any") { $new_rule.LocalAddresses = $localip }
177 if ($null -ne $remoteip -and $remoteip -ne "any") { $new_rule.RemoteAddresses = $remoteip }
178 if ($null -ne $icmp_type_code -and $icmp_type_code -ne "any") { $new_rule.IcmpTypesAndCodes = $icmp_type_code }
179 if ($null -ne $direction) { $new_rule.Direction = ConvertTo-Direction -directionStr $direction }
180 if ($null -ne $action) { $new_rule.Action = ConvertTo-Action -actionStr $action }
181 # Profiles value cannot be a uint32, but the "all profiles" value (0x7FFFFFFF) will often become a uint32, so must cast to [int]
182 if ($null -ne $profiles) { $new_rule.Profiles = [int](ConvertTo-Profiles -profilesList $profiles) }
183 if ($null -ne $interfacetypes -and @(Compare-Object -ReferenceObject $interfacetypes -DifferenceObject @("any")).Count -ne 0) { $new_rule.InterfaceTypes = ConvertTo-InterfaceTypes -interfaceTypes $interfacetypes }
184 if ($null -ne $edge -and $edge -ne "no") {
185 # EdgeTraversalOptions property exists only from Windows 7/Windows Server 2008 R2: https://msdn.microsoft.com/en-us/library/windows/desktop/dd607256(v=vs.85).aspx
186 if ($new_rule | Get-Member -Name 'EdgeTraversalOptions') {
187 $new_rule.EdgeTraversalOptions = ConvertTo-EdgeTraversalOptions -edgeTraversalOptionsStr $edge
188 }
189 }
190 if ($null -ne $security -and $security -ne "notrequired") {
191 # SecureFlags property exists only from Windows 8/Windows Server 2012: https://msdn.microsoft.com/en-us/library/windows/desktop/hh447465(v=vs.85).aspx
192 if ($new_rule | Get-Member -Name 'SecureFlags') {
193 $new_rule.SecureFlags = ConvertTo-SecureFlags -secureFlagsStr $security
194 }
195 }
196
197 $fwPropertiesToCompare = @('Description','Direction','Action','ApplicationName','Grouping','ServiceName','Enabled','Profiles','LocalAddresses','RemoteAddresses','LocalPorts','RemotePorts','Protocol','InterfaceTypes', 'EdgeTraversalOptions', 'SecureFlags','IcmpTypesAndCodes')
198 $userPassedArguments = @($description, $direction, $action, $program, $group, $service, $enabled, $profiles, $localip, $remoteip, $localport, $remoteport, $protocol, $interfacetypes, $edge, $security, $icmp_type_code)
199
200 if ($state -eq "absent") {
201 if (-not $existingRules) {
202 if ($name) {
203 $result.msg = "Firewall rule '$name' does not exist."
204 } else {
205 $result.msg = "No firewall rules in group '$group' exist."
206 }
207
208 } else {
209 $rules = foreach ($rule in $existingRules) {
210 $rule.Name # Output name for module msg string.
211
212 if ($diff_support) {
213 $result.diff.prepared += "-[$($rule.Name)]`n"
214 foreach ($prop in $fwPropertiesToCompare) {
215 $result.diff.prepared += "-$($prop)='$($rule.$prop)'`n"
216 }
217 }
218
219 if (-not $check_mode) {
220 $fw.Rules.Remove($rule.Name)
221 }
222 $result.changed = $true
223 }
224 $result.msg = "Firewall rule(s) '$($rules -join "', '")' removed."
225 }
226 } elseif ($state -eq "present") {
227 if (-not $existingRules -and $name) {
228 # name was specified and no rules were found, create the rule
229 if ($diff_support) {
230 $result.diff.prepared += "+[$($new_rule.Name)]`n"
231 foreach ($prop in $fwPropertiesToCompare) {
232 $result.diff.prepared += "+$($prop)='$($new_rule.$prop)'`n"
233 }
234 }
235
236 if (-not $check_mode) {
237 $fw.Rules.Add($new_rule)
238 }
239 $result.changed = $true
240 $result.msg = "Firewall rule '$name' created."
241 } elseif ($existingRules) {
242 # Either name or group was specified which matched existing rules, check the properties
243 $changedRules = [System.Collections.Generic.List[String]]@()
244 $unchangedRules = [System.Collections.Generic.List[String]]@()
245
246 foreach ($existingRule in $existingRules) {
247 if ($diff_support) {
248 $result.diff.prepared += "[$($existingRule.Name)]`n"
249 }
250
251 $changed = $false
252 for($i = 0; $i -lt $fwPropertiesToCompare.Length; $i++) {
253 $prop = $fwPropertiesToCompare[$i]
254 if($null -ne $userPassedArguments[$i]) { # only change values the user passes in task definition
255 if ($existingRule.$prop -ne $new_rule.$prop) {
256 if ($diff_support) {
257 $result.diff.prepared += "-$($prop)='$($existingRule.$prop)'`n"
258 $result.diff.prepared += "+$($prop)='$($new_rule.$prop)'`n"
259 }
260
261 if (-not $check_mode) {
262 # Profiles value cannot be a uint32, but the "all profiles" value (0x7FFFFFFF) will often become a uint32, so must cast to [int]
263 # to prevent InvalidCastException under PS5+
264 If($prop -eq 'Profiles') {
265 $existingRule.Profiles = [int] $new_rule.$prop
266 }
267 Else {
268 $existingRule.$prop = $new_rule.$prop
269 }
270 }
271 $changed = $true
272 }
273 }
274 }
275
276 if ($changed) {
277 $result.changed = $true
278 $changedRules.Add($existingRule.Name)
279 } else {
280 $unchangedRules.Add($existingRule.Name)
281 }
282 }
283
284 $result.msg = "Firewall rule(s) changed '$($changedRules -join "', '")' - unchanged '$($unchangedRules -join "', '")'"
285 }
286 }
287 } catch [Exception] {
288 $ex = $_
289 $result['exception'] = $($ex | Out-String)
290 Fail-Json $result $ex.Exception.Message
291 }
292
293 Exit-Json $result
294