1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2014, Timothy Vandenbrande <timothy.vandenbrande@gmail.com>
5# Copyright: (c) 2017, Artem Zinenko <zinenkoartem@gmail.com>
6# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
7
8DOCUMENTATION = r'''
9---
10module: win_firewall_rule
11short_description: Windows firewall automation
12description:
13  - Allows you to create/remove/update firewall rules.
14options:
15  enabled:
16    description:
17      - Whether this firewall rule is enabled or disabled.
18      - Defaults to C(true) when creating a new rule.
19    type: bool
20    aliases: [ enable ]
21  state:
22    description:
23      - Should this rule be added or removed.
24    type: str
25    choices: [ absent, present ]
26    default: present
27  name:
28    description:
29      - The rule's display name.
30      - This is required unless I(group) is specified.
31    type: str
32  group:
33    description:
34      - The group name for the rule.
35      - If I(name) is not specified then the module will set the firewall options for all the rules in this group.
36    type: str
37  direction:
38    description:
39      - Whether this rule is for inbound or outbound traffic.
40      - Defaults to C(in) when creating a new rule.
41    type: str
42    choices: [ in, out ]
43  action:
44    description:
45      - What to do with the items this rule is for.
46      - Defaults to C(allow) when creating a new rule.
47    type: str
48    choices: [ allow, block ]
49  description:
50    description:
51      - Description for the firewall rule.
52    type: str
53  localip:
54    description:
55      - The local ip address this rule applies to.
56      - Set to C(any) to apply to all local ip addresses.
57      - Defaults to C(any) when creating a new rule.
58    type: str
59  remoteip:
60    description:
61      - The remote ip address/range this rule applies to.
62      - Set to C(any) to apply to all remote ip addresses.
63      - Defaults to C(any) when creating a new rule.
64    type: str
65  localport:
66    description:
67      - The local port this rule applies to.
68      - Set to C(any) to apply to all local ports.
69      - Defaults to C(any) when creating a new rule.
70      - Must have I(protocol) set
71    type: str
72  remoteport:
73    description:
74      - The remote port this rule applies to.
75      - Set to C(any) to apply to all remote ports.
76      - Defaults to C(any) when creating a new rule.
77      - Must have I(protocol) set
78    type: str
79  program:
80    description:
81      - The program this rule applies to.
82      - Set to C(any) to apply to all programs.
83      - Defaults to C(any) when creating a new rule.
84    type: str
85  service:
86    description:
87      - The service this rule applies to.
88      - Set to C(any) to apply to all services.
89      - Defaults to C(any) when creating a new rule.
90    type: str
91  protocol:
92    description:
93      - The protocol this rule applies to.
94      - Set to C(any) to apply to all services.
95      - Defaults to C(any) when creating a new rule.
96    type: str
97  profiles:
98    description:
99      - The profile this rule applies to.
100      - Defaults to C(domain,private,public) when creating a new rule.
101    type: list
102    aliases: [ profile ]
103  icmp_type_code:
104    description:
105      - The ICMP types and codes for the rule.
106      - This is only valid when I(protocol) is C(icmpv4) or C(icmpv6).
107      - Each entry follows the format C(type:code) where C(type) is the type
108        number and C(code) is the code number for that type or C(*) for all
109        codes.
110      - Set the value to just C(*) to apply the rule for all ICMP type codes.
111      - See U(https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml)
112        for a list of ICMP types and the codes that apply to them.
113    type: list
114notes:
115- Multiple firewall rules can share the same I(name), if there are multiple matches then the module will set the user
116  defined options for each matching rule.
117seealso:
118- module: community.windows.win_firewall
119author:
120  - Artem Zinenko (@ar7z1)
121  - Timothy Vandenbrande (@TimothyVandenbrande)
122'''
123
124EXAMPLES = r'''
125- name: Firewall rule to allow SMTP on TCP port 25
126  community.windows.win_firewall_rule:
127    name: SMTP
128    localport: 25
129    action: allow
130    direction: in
131    protocol: tcp
132    state: present
133    enabled: yes
134
135- name: Firewall rule to allow RDP on TCP port 3389
136  community.windows.win_firewall_rule:
137    name: Remote Desktop
138    localport: 3389
139    action: allow
140    direction: in
141    protocol: tcp
142    profiles: private
143    state: present
144    enabled: yes
145
146- name: Firewall rule to be created for application group
147  community.windows.win_firewall_rule:
148    name: SMTP
149    group: application
150    localport: 25
151    action: allow
152    direction: in
153    protocol: tcp
154    state: present
155    enabled: yes
156
157- name: Enable all the Firewall rules in application group
158  win_firewall_rule:
159    group: application
160    enabled: yes
161
162- name: Firewall rule to allow port range
163  community.windows.win_firewall_rule:
164    name: Sample port range
165    localport: 5000-5010
166    action: allow
167    direction: in
168    protocol: tcp
169    state: present
170    enabled: yes
171
172- name: Firewall rule to allow ICMP v4 echo (ping)
173  community.windows.win_firewall_rule:
174    name: ICMP Allow incoming V4 echo request
175    enabled: yes
176    state: present
177    profiles: private
178    action: allow
179    direction: in
180    protocol: icmpv4
181    icmp_type_code:
182    - '8:*'
183
184- name: Firewall rule to alloc ICMP v4 on all type codes
185  community.windows.win_firewall_rule:
186    name: ICMP Allow incoming V4 echo request
187    enabled: yes
188    state: present
189    profiles: private
190    action: allow
191    direction: in
192    protocol: icmpv4
193    icmp_type_code: '*'
194'''
195