|
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2018, Kevin Breit (@kbreit) <kevin.breit@kevinbreit.net>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'
}
DOCUMENTATION = r'''
---
module: meraki_mx_l3_firewall
short_description: Manage MX appliance layer 3 firewalls in the Meraki cloud
version_added: "2.7"
description:
- Allows for creation, management, and visibility into layer 3 firewalls implemented on Meraki MX firewalls.
notes:
- Module assumes a complete list of firewall rules are passed as a parameter.
- If there is interest in this module allowing manipulation of a single firewall rule, please submit an issue against this module.
options:
state:
description:
- Create or modify an organization.
choices: ['present', 'query']
default: present
type: str
net_name:
description:
- Name of network which MX firewall is in.
type: str
net_id:
description:
- ID of network which MX firewall is in.
type: str
rules:
description:
- List of firewall rules.
type: list
suboptions:
policy:
description:
- Policy to apply if rule is hit.
choices: [allow, deny]
type: str
protocol:
description:
- Protocol to match against.
choices: [any, icmp, tcp, udp]
type: str
dest_port:
description:
- Comma separated list of destination port numbers to match against.
- C(Any) must be capitalized.
type: str
dest_cidr:
description:
- Comma separated list of CIDR notation destination networks.
- C(Any) must be capitalized.
type: str
src_port:
description:
- Comma separated list of source port numbers to match against.
- C(Any) must be capitalized.
type: str
src_cidr:
description:
- Comma separated list of CIDR notation source networks.
- C(Any) must be capitalized.
type: str
comment:
description:
- Optional comment to describe the firewall rule.
type: str
syslog_enabled:
description:
- Whether to log hints against the firewall rule.
- Only applicable if a syslog server is specified against the network.
type: bool
syslog_default_rule:
description:
- Whether to log hits against the default firewall rule.
- Only applicable if a syslog server is specified against the network.
- This is not shown in response from Meraki. Instead, refer to the C(syslog_enabled) value in the default rule.
type: bool
default: no
author:
- Kevin Breit (@kbreit)
extends_documentation_fragment: meraki
'''
EXAMPLES = r'''
- name: Query firewall rules
meraki_mx_l3_firewall:
auth_key: abc123
org_name: YourOrg
net_name: YourNet
state: query
delegate_to: localhost
- name: Set two firewall rules
meraki_mx_l3_firewall:
auth_key: abc123
org_name: YourOrg
net_name: YourNet
state: present
rules:
- comment: Block traffic to server
src_cidr: 192.0.1.0/24
src_port: any
dest_cidr: 192.0.2.2/32
dest_port: any
protocol: any
policy: deny
- comment: Allow traffic to group of servers
src_cidr: 192.0.1.0/24
src_port: any
dest_cidr: 192.0.2.0/24
dest_port: any
protocol: any
policy: permit
delegate_to: localhost
- name: Set one firewall rule and enable logging of the default rule
meraki_mx_l3_firewall:
auth_key: abc123
org_name: YourOrg
net_name: YourNet
state: present
rules:
- comment: Block traffic to server
src_cidr: 192.0.1.0/24
src_port: any
dest_cidr: 192.0.2.2/32
dest_port: any
protocol: any
policy: deny
syslog_default_rule: yes
delegate_to: localhost
'''
RETURN = r'''
data:
description: Firewall rules associated to network.
returned: success
type: complex
contains:
comment:
description: Comment to describe the firewall rule.
returned: always
type: str
sample: Block traffic to server
src_cidr:
description: Comma separated list of CIDR notation source networks.
returned: always
type: str
sample: 192.0.1.1/32,192.0.1.2/32
src_port:
description: Comma separated list of source ports.
returned: always
type: str
sample: 80,443
dest_cidr:
description: Comma separated list of CIDR notation destination networks.
returned: always
type: str
sample: 192.0.1.1/32,192.0.1.2/32
dest_port:
description: Comma separated list of destination ports.
returned: always
type: str
sample: 80,443
protocol:
description: Network protocol for which to match against.
returned: always
type: str
sample: tcp
policy:
description: Action to take when rule is matched.
returned: always
type: str
syslog_enabled:
description: Whether to log to syslog when rule is matched.
returned: always
type: bool
sample: true
'''
from ansible.module_utils.basic import AnsibleModule, json
from ansible_collections.cisco.meraki.plugins.module_utils.network.meraki.meraki import MerakiModule, meraki_argument_spec
def assemble_payload(meraki):
params_map = {'policy': 'policy',
'protocol': 'protocol',
'dest_port': 'destPort',
'dest_cidr': 'destCidr',
'src_port': 'srcPort',
'src_cidr': 'srcCidr',
'syslog_enabled': 'syslogEnabled',
'comment': 'comment',
}
rules = []
for rule in meraki.params['rules']:
proposed_rule = dict()
for k, v in rule.items():
proposed_rule[params_map[k]] = v
rules.append(proposed_rule)
payload = {'rules': rules}
return payload
def get_rules(meraki, net_id):
path = meraki.construct_path('get_all', net_id=net_id)
response = meraki.request(path, method='GET')
221 ↛ exitline 221 didn't return from function 'get_rules', because the condition on line 221 was never false if meraki.status == 200:
return response
def normalize_case(rule):
any = ['any', 'Any', 'ANY']
227 ↛ 230line 227 didn't jump to line 230, because the condition on line 227 was never false if 'srcPort' in rule:
228 ↛ 230line 228 didn't jump to line 230, because the condition on line 228 was never false if rule['srcPort'] in any:
rule['srcPort'] = 'Any'
230 ↛ 233line 230 didn't jump to line 233, because the condition on line 230 was never false if 'srcCidr' in rule:
231 ↛ 233line 231 didn't jump to line 233, because the condition on line 231 was never false if rule['srcCidr'] in any:
rule['srcCidr'] = 'Any'
233 ↛ 236line 233 didn't jump to line 236, because the condition on line 233 was never false if 'destPort' in rule:
234 ↛ 236line 234 didn't jump to line 236, because the condition on line 234 was never false if rule['destPort'] in any:
rule['destPort'] = 'Any'
236 ↛ exit, 236 ↛ 2372 missed branches: 1) line 236 didn't return from function 'normalize_case', because the condition on line 236 was never false, 2) line 236 didn't jump to line 237, because the condition on line 236 was never true if 'destCidr' in rule:
if rule['destCidr'] in any:
rule['destCidr'] = 'Any'
def main():
# define the available arguments/parameters that a user can pass to
# the module
fw_rules = dict(policy=dict(type='str', choices=['allow', 'deny']),
protocol=dict(type='str', choices=['tcp', 'udp', 'icmp', 'any']),
dest_port=dict(type='str'),
dest_cidr=dict(type='str'),
src_port=dict(type='str'),
src_cidr=dict(type='str'),
comment=dict(type='str'),
syslog_enabled=dict(type='bool', default=False),
)
argument_spec = meraki_argument_spec()
argument_spec.update(state=dict(type='str', choices=['present', 'query'], default='present'),
net_name=dict(type='str'),
net_id=dict(type='str'),
rules=dict(type='list', default=None, elements='dict', options=fw_rules),
syslog_default_rule=dict(type='bool'),
)
# the AnsibleModule object will be our abstraction working with Ansible
# this includes instantiation, a couple of common attr would be the
# args/params passed to the execution, as well as if the module
# supports check mode
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
)
meraki = MerakiModule(module, function='mx_l3_firewall')
meraki.params['follow_redirects'] = 'all'
query_urls = {'mx_l3_firewall': '/networks/{net_id}/l3FirewallRules/'}
update_urls = {'mx_l3_firewall': '/networks/{net_id}/l3FirewallRules/'}
meraki.url_catalog['get_all'].update(query_urls)
meraki.url_catalog['update'] = update_urls
payload = None
# execute checks for argument completeness
# manipulate or modify the state as needed (this is going to be the
# part where your module will do what it needs to do)
org_id = meraki.params['org_id']
287 ↛ 292line 287 didn't jump to line 292, because the condition on line 287 was never false if org_id is None:
orgs = meraki.get_orgs()
289 ↛ 292line 289 didn't jump to line 292, because the loop on line 289 didn't complete for org in orgs:
290 ↛ 289line 290 didn't jump to line 289, because the condition on line 290 was never false if org['name'] == meraki.params['org_name']:
org_id = org['id']
net_id = meraki.params['net_id']
293 ↛ 297line 293 didn't jump to line 297, because the condition on line 293 was never false if net_id is None:
net_id = meraki.get_net_id(net_name=meraki.params['net_name'],
data=meraki.get_nets(org_id=org_id))
297 ↛ 299line 297 didn't jump to line 299, because the condition on line 297 was never false if meraki.params['state'] == 'query':
meraki.result['data'] = get_rules(meraki, net_id)
299 ↛ 358line 299 didn't jump to line 358, because the condition on line 299 was never false elif meraki.params['state'] == 'present':
rules = get_rules(meraki, net_id)
path = meraki.construct_path('get_all', net_id=net_id)
if meraki.params['rules'] is not None:
payload = assemble_payload(meraki)
else:
payload = dict()
update = False
307 ↛ 309line 307 didn't jump to line 309, because the condition on line 307 was never false if meraki.params['syslog_default_rule'] is not None:
payload['syslogDefaultRule'] = meraki.params['syslog_default_rule']
try:
if meraki.params['rules'] is not None:
311 ↛ 313line 311 didn't jump to line 313, because the condition on line 311 was never false if len(rules) - 1 != len(payload['rules']): # Quick and simple check to avoid more processing
update = True
if meraki.params['syslog_default_rule'] is not None:
if rules[len(rules) - 1]['syslogEnabled'] != meraki.params['syslog_default_rule']:
update = True
if update is False:
default_rule = rules[len(rules) - 1].copy()
del rules[len(rules) - 1] # Remove default rule for comparison
319 ↛ 326line 319 didn't jump to line 326, because the condition on line 319 was never false if len(rules) - 1 == 0:
normalize_case(rules[0])
normalize_case(payload['rules'][0])
# meraki.fail_json(msg='Compare', original=rules, payload=payload)
323 ↛ 332line 323 didn't jump to line 332, because the condition on line 323 was never false if meraki.is_update_required(rules[0], payload['rules'][0]) is True:
update = True
else:
326 ↛ 332line 326 didn't jump to line 332, because the loop on line 326 didn't complete for r in range(len(rules) - 1):
normalize_case(rules[r])
normalize_case(payload['rules'][r])
# meraki.fail_json(msg='Full Compare', original=rules, payload=payload)
330 ↛ 326line 330 didn't jump to line 326, because the condition on line 330 was never false if meraki.is_update_required(rules[r], payload['rules'][r]) is True:
update = True
rules.append(default_rule)
except KeyError:
pass
335 ↛ 354line 335 didn't jump to line 354, because the condition on line 335 was never false if update is True:
336 ↛ 349line 336 didn't jump to line 349, because the condition on line 336 was never false if meraki.check_mode is True:
if meraki.params['rules'] is not None:
data = payload['rules']
data.append(rules[len(rules) - 1]) # Append the default rule
340 ↛ 346line 340 didn't jump to line 346, because the condition on line 340 was never false if meraki.params['syslog_default_rule'] is not None:
data[len(payload) - 1]['syslog_enabled'] = meraki.params['syslog_default_rule']
else:
343 ↛ 346line 343 didn't jump to line 346, because the condition on line 343 was never false if meraki.params['syslog_default_rule'] is not None:
data = rules
data[len(data) - 1]['syslogEnabled'] = meraki.params['syslog_default_rule']
meraki.result['data'] = data
meraki.result['changed'] = True
meraki.exit_json(**meraki.result)
response = meraki.request(path, method='PUT', payload=json.dumps(payload))
350 ↛ 358line 350 didn't jump to line 358, because the condition on line 350 was never false if meraki.status == 200:
meraki.result['data'] = response
meraki.result['changed'] = True
else:
meraki.result['data'] = rules
# in the event of a successful module execution, you will want to
# simple AnsibleModule.exit_json(), passing the key/value results
meraki.exit_json(**meraki.result)
361 ↛ 362line 361 didn't jump to line 362, because the condition on line 361 was never trueif __name__ == '__main__':
main()
|