Try Spottercreate, delete and modify AWS Network Firewall rule groups
| "added in version" 4.0.0 of community.aws"
Authors: Mark Chappell (@tremble)
Install with ansible-galaxy collection install community.aws:==5.1.0
collections:
- name: community.aws
version: 5.1.0A module for managing AWS Network Firewall rule groups.
U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/index.html)
Currently only supports C(stateful) firewall groups.
# Create a rule group
- name: Create a minimal AWS Network Firewall Rule Group
community.aws.networkfirewall_rule_group:
name: 'MinimalGroup'
type: 'stateful'
capacity: 200
rule_strings:
- 'pass tcp any any -> any any (sid:1000001;)'
# Create an example rule group using rule_list
- name: Create 5-tuple Rule List based rule group
community.aws.networkfirewall_rule_group:
name: 'ExampleGroup'
type: 'stateful'
description: 'My description'
rule_order: default
capacity: 100
rule_list:
- sid: 1
direction: forward
action: pass
protocol: IP
source: any
source_port: any
destination: any
destination_port: any
# Create an example rule group using rule_list
- name: Create 5-tuple Rule List based rule group
community.aws.networkfirewall_rule_group:
name: 'ExampleGroup'
type: 'stateful'
description: 'My description'
ip_variables:
SOURCE_IPS: ['203.0.113.0/24', '198.51.100.42']
DESTINATION_IPS: ['192.0.2.0/24', '198.51.100.48']
port_variables:
HTTP_PORTS: [80, 8080]
rule_order: default
capacity: 100
rule_list:
# Allow 'Destination Unreachable' traffic
- sid: 1
action: pass
protocol: icmp
source: any
source_port: any
destination: any
destination_port: any
rule_options:
itype: 3
- sid: 2
action: drop
protocol: tcp
source: "$SOURCE_IPS"
source_port: any
destination: "$DESTINATION_IPS"
destination_port: "$HTTP_PORTS"
rule_options:
urilen: ["20<>40"]
# Where only a keyword is needed, add the keword, but no value
http_uri:
# Settings where Suricata expects raw strings (like the content
# keyword) will need to have the double-quotes explicitly escaped and
# passed because there's no practical way to distinguish between them
# and flags.
content: '"index.php"'
# Create an example rule group using Suricata rule strings
- name: Create Suricata rule string based rule group
community.aws.networkfirewall_rule_group:
name: 'ExampleSuricata'
type: 'stateful'
description: 'My description'
capacity: 200
ip_variables:
EXAMPLE_IP: ['203.0.113.0/24', '198.51.100.42']
ANOTHER_EXAMPLE: ['192.0.2.0/24', '198.51.100.48']
port_variables:
EXAMPLE_PORT: [443, 22]
rule_strings:
- 'pass tcp any any -> $EXAMPLE_IP $EXAMPLE_PORT (sid:1000001;)'
- 'pass udp any any -> $ANOTHER_EXAMPLE any (sid:1000002;)'
# Create an example Domain List based rule group
- name: Create Domain List based rule group
community.aws.networkfirewall_rule_group:
name: 'ExampleDomainList'
type: 'stateful'
description: 'My description'
capacity: 100
domain_list:
domain_names:
- 'example.com'
- '.example.net'
filter_https: True
filter_http: True
action: allow
source_ips: '192.0.2.0/24'
# Update the description of a rule group
- name: Update the description of a rule group
community.aws.networkfirewall_rule_group:
name: 'MinimalGroup'
type: 'stateful'
description: 'Another description'
# Update IP Variables for a rule group
- name: Update IP Variables
community.aws.networkfirewall_rule_group:
name: 'ExampleGroup'
type: 'stateful'
ip_variables:
EXAMPLE_IP: ['192.0.2.0/24', '203.0.113.0/24', '198.51.100.42']
purge_ip_variables: false
# Delete a rule group
- name: Delete a rule group
community.aws.networkfirewall_rule_group:
name: 'MinimalGroup'
type: 'stateful'
state: absent
arn:
description:
- The ARN of the Network Firewall rule group.
- Exactly one of I(arn) and I(name) must be provided.
required: false
type: str
name:
description:
- The name of the Network Firewall rule group.
- When I(name) is set, I(rule_type) must also be set.
required: false
type: str
tags:
aliases:
- resource_tags
description:
- A dictionary representing the tags to be applied to the resource.
- If the I(tags) parameter is not set then tags will not be modified.
required: false
type: dict
wait:
default: true
description:
- Whether to wait for the firewall rule group to reach the C(ACTIVE) or C(DELETED)
state before the module returns.
required: false
type: bool
state:
choices:
- present
- absent
default: present
description:
- Create or remove the Network Firewall rule group.
required: false
type: str
region:
aliases:
- aws_region
- ec2_region
description:
- The AWS region to use.
- For global services such as IAM, Route53 and CloudFront, I(region) is ignored.
- The C(AWS_REGION) or C(EC2_REGION) environment variables may also be used.
- See the Amazon AWS documentation for more information U(http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region).
- The C(ec2_region) alias has been deprecated and will be removed in a release after
2024-12-01
- Support for the C(EC2_REGION) environment variable has been deprecated and will
be removed in a release after 2024-12-01.
type: str
profile:
aliases:
- aws_profile
description:
- A named AWS profile to use for authentication.
- See the AWS documentation for more information about named profiles U(https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
- The C(AWS_PROFILE) environment variable may also be used.
- The I(profile) option is mutually exclusive with the I(aws_access_key), I(aws_secret_key)
and I(security_token) options.
type: str
capacity:
description:
- The maximum operating resources that this rule group can use.
- Once a rule group is created this parameter is immutable.
- See also the AWS documentation about how capacityis calculated U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/nwfw-rule-group-capacity.html)
- This option is mandatory when creating a new rule group.
required: false
type: int
rule_list:
aliases:
- stateful_rule_list
description:
- Inspection criteria to be used for a 5-tuple based rule group.
- When set overwrites all existing 5-tuple rules with the new configuration.
- Mutually exclusive with I(domain_list) and I(rule_strings).
- Mutually exclusive with I(rule_type=stateless).
- Exactly one of I(rule_strings), I(domain_list) or I(rule_list) must be specified
at creation time.
- For more information about valid values see the AWS documentation U(https://docs.aws.amazon.com/network-firewall/latest/APIReference/API_StatefulRule.html)
and U(https://docs.aws.amazon.com/network-firewall/latest/APIReference/API_Header.html).
- 'Note: Idempotency when comparing AWS Web UI and Ansiible managed rules can not
be guaranteed'
elements: dict
required: false
suboptions:
action:
choices:
- pass
- drop
- alert
description:
- What Network Firewall should do with the packets in a traffic flow when the
flow matches.
required: true
type: str
destination:
description:
- The destination IP address or address range to inspect for, in CIDR notation.
- To match with any address, specify C(ANY).
required: true
type: str
destination_port:
description:
- The source port to inspect for.
- To match with any port, specify C(ANY).
required: true
type: str
direction:
choices:
- forward
- any
default: forward
description:
- The direction of traffic flow to inspect.
- If set to C(any), the inspection matches both traffic going from the I(source)
to the I(destination) and from the I(destination) to the I(source).
- If set to C(forward), the inspection only matches traffic going from the I(source)
to the I(destination).
required: false
type: str
protocol:
description:
- The protocol to inspect for. To specify all, you can use C(IP), because all
traffic on AWS is C(IP).
required: true
type: str
rule_options:
description:
- Additional options for the rule.
- 5-tuple based rules are converted by AWS into Suricata rules, for more complex
options requirements where order matters consider using I(rule_strings).
- A dictionary mapping Suricata RuleOptions names to a list of values.
- The examples section contains some examples of using rule_options.
- For more information read the AWS documentation U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/suricata-limitations-caveats.html)
and the Suricata documentation U(https://suricata.readthedocs.io/en/suricata-6.0.0/rules/intro.html).
required: false
type: dict
sid:
description:
- The signature ID of the rule.
- A unique I(sid) must be passed for all rules.
required: true
type: int
source:
description:
- The source IP address or address range to inspect for, in CIDR notation.
- To match with any address, specify C(ANY).
required: true
type: str
source_port:
description:
- The source port to inspect for.
- To match with any port, specify C(ANY).
required: true
type: str
type: list
rule_type:
aliases:
- type
choices:
- stateful
description:
- Indicates whether the rule group is stateless or stateful.
- Stateless rulesets are currently not supported.
- Required if I(name) is set.
required: false
type: str
access_key:
aliases:
- aws_access_key_id
- aws_access_key
- ec2_access_key
description:
- AWS access key ID.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY) environment variables
may also be used in decreasing order of preference.
- The I(aws_access_key) and I(profile) options are mutually exclusive.
- The I(aws_access_key_id) alias was added in release 5.1.0 for consistency with the
AWS botocore SDK.
- The I(ec2_access_key) alias has been deprecated and will be removed in a release
after 2024-12-01.
- Support for the C(EC2_ACCESS_KEY) environment variable has been deprecated and will
be removed in a release after 2024-12-01.
type: str
aws_config:
description:
- A dictionary to modify the botocore configuration.
- Parameters can be found in the AWS documentation U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config).
type: dict
purge_tags:
default: true
description:
- If I(purge_tags=true) and I(tags) is set, existing tags will be purged from the
resource to match exactly what is defined by I(tags) parameter.
- If the I(tags) parameter is not set then tags will not be modified, even if I(purge_tags=True).
- Tag keys beginning with C(aws:) are reserved by Amazon and can not be modified. As
such they will be ignored for the purposes of the I(purge_tags) parameter. See
the Amazon documentation for more information U(https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions).
required: false
type: bool
rule_order:
aliases:
- stateful_rule_order
choices:
- default
- strict
description:
- Indicates how to manage the order of the rule evaluation for the rule group.
- Once a rule group is created this parameter is immutable.
- Mutually exclusive with I(rule_type=stateless).
- For more information on how rules are evaluated read the AWS documentation U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/suricata-rule-evaluation-order.html).
- I(rule_order) requires botocore>=1.23.23.
required: false
type: str
secret_key:
aliases:
- aws_secret_access_key
- aws_secret_key
- ec2_secret_key
description:
- AWS secret access key.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY) environment
variables may also be used in decreasing order of preference.
- The I(secret_key) and I(profile) options are mutually exclusive.
- The I(aws_secret_access_key) alias was added in release 5.1.0 for consistency with
the AWS botocore SDK.
- The I(ec2_secret_key) alias has been deprecated and will be removed in a release
after 2024-12-01.
- Support for the C(EC2_SECRET_KEY) environment variable has been deprecated and will
be removed in a release after 2024-12-01.
type: str
description:
description:
- A description of the AWS Network Firewall rule group.
type: str
domain_list:
description:
- Inspection criteria for a domain list rule group.
- When set overwrites all Domain List settings with the new configuration.
- For more information about domain name based filtering read the AWS documentation
U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/stateful-rule-groups-domain-names.html).
- Mutually exclusive with I(rule_type=stateless).
- Mutually exclusive with I(ip_variables), I(rule_list) and I(rule_strings).
- Exactly one of I(rule_strings), I(domain_list) or I(rule_list) must be specified
at creation time.
required: false
suboptions:
action:
choices:
- allow
- deny
description:
- Action to perform on traffic that matches the rule match settings.
required: true
type: str
domain_names:
description:
- A list of domain names to look for in the traffic flow.
elements: str
required: true
type: list
filter_http:
default: false
description:
- Whether HTTP traffic should be inspected (uses the host header).
required: false
type: bool
filter_https:
default: false
description:
- Whether HTTPS traffic should be inspected (uses the SNI).
required: false
type: bool
source_ips:
description:
- Used to expand the local network definition beyond the CIDR range of the VPC
where you deploy Network Firewall.
elements: str
required: false
type: list
type: dict
endpoint_url:
aliases:
- ec2_url
- aws_endpoint_url
- s3_url
description:
- URL to connect to instead of the default AWS endpoints. While this can be used
to connection to other AWS-compatible services the amazon.aws and community.aws
collections are only tested against AWS.
- The C(AWS_URL) or C(EC2_URL) environment variables may also be used, in decreasing
order of preference.
- The I(ec2_url) and I(s3_url) aliases have been deprecated and will be removed in
a release after 2024-12-01.
- Support for the C(EC2_URL) environment variable has been deprecated and will be
removed in a release after 2024-12-01.
type: str
ip_variables:
aliases:
- ip_set_variables
description:
- A dictionary mapping variable names to a list of IP addresses and address ranges,
in CIDR notation.
- For example C({EXAMPLE_HOSTS:["192.0.2.0/24", "203.0.113.42"]}).
- Mutually exclusive with I(domain_list).
required: false
type: dict
rule_strings:
description:
- Rules in Suricata format.
- If I(rule_strings) is specified, it must include at least one entry.
- For more information read the AWS documentation U(https://docs.aws.amazon.com/network-firewall/latest/developerguide/suricata-limitations-caveats.html)
and the Suricata documentation U(https://suricata.readthedocs.io/en/suricata-6.0.0/rules/intro.html).
- Mutually exclusive with I(rule_type=stateless).
- Mutually exclusive with I(domain_list) and I(rule_list).
- Exactly one of I(rule_strings), I(domain_list) or I(rule_list) must be specified
at creation time.
elements: str
required: false
type: list
wait_timeout:
description:
- Maximum time, in seconds, to wait for the firewall rule group to reach the expected
state.
- Defaults to 600 seconds.
required: false
type: int
aws_ca_bundle:
description:
- The location of a CA Bundle to use when validating SSL certificates.
- The C(AWS_CA_BUNDLE) environment variable may also be used.
type: path
session_token:
aliases:
- aws_session_token
- security_token
- aws_security_token
- access_token
description:
- AWS STS session token for use with temporary credentials.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_SESSION_TOKEN), C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment
variables may also be used in decreasing order of preference.
- The I(security_token) and I(profile) options are mutually exclusive.
- Aliases I(aws_session_token) and I(session_token) were added in release 3.2.0, with
the parameter being renamed from I(security_token) to I(session_token) in release
6.0.0.
- The I(security_token), I(aws_security_token), and I(access_token) aliases have been
deprecated and will be removed in a release after 2024-12-01.
- Support for the C(EC2_SECRET_KEY) and C(AWS_SECURITY_TOKEN) environment variables
has been deprecated and will be removed in a release after 2024-12-01.
type: str
port_variables:
aliases:
- port_set_variables
description:
- A dictionary mapping variable names to a list of ports.
- For example C({SECURE_PORTS:["22", "443"]}).
required: false
type: dict
validate_certs:
default: true
description:
- When set to C(false), SSL certificates will not be validated for communication with
the AWS APIs.
- Setting I(validate_certs=false) is strongly discouraged, as an alternative, consider
setting I(aws_ca_bundle) instead.
type: bool
purge_ip_variables:
aliases:
- purge_ip_set_variables
default: true
description:
- Whether to purge variable names not mentioned in the I(ip_variables) dictionary.
- To remove all IP Set Variables it is necessary to explicitly set I(ip_variables={})
and I(purge_port_variables=true).
required: false
type: bool
purge_port_variables:
aliases:
- purge_port_set_variables
default: true
description:
- Whether to purge variable names not mentioned in the I(port_variables) dictionary.
- To remove all Port Set Variables it is necessary to explicitly set I(port_variables={})
and I(purge_port_variables=true).
required: false
type: bool
debug_botocore_endpoint_logs:
default: false
description:
- Use a C(botocore.endpoint) logger to parse the unique (rather than total) C("resource:action")
API calls made during a task, outputing the set to the resource_actions key in the
task results. Use the C(aws_resource_action) callback to output to total list made
during a playbook.
- The C(ANSIBLE_DEBUG_BOTOCORE_LOGS) environment variable may also be used.
type: bool
rule_group:
contains:
rule_group:
contains:
rule_variables:
contains:
ip_sets:
description: A dictionary mapping variable names to IP addresses in
CIDR format.
example:
- 192.0.2.0/24
returned: success
type: dict
port_sets:
description: A dictionary mapping variable names to ports
example:
- '42'
returned: success
type: dict
description: Settings that are available for use in the rules in the rule
group.
returned: When rule variables are attached to the rule group.
type: complex
rules_source:
contains:
rules_source_list:
contains:
generated_rules_type:
description: Whether the rule group allows or denies access to the
domains in the list.
example: ALLOWLIST
returned: success
type: str
target_types:
description: The protocols to be inspected by the rule group.
elements: str
example:
- TLS_SNI
- HTTP_HOST
returned: success
type: list
targets:
description: A list of domain names to be inspected for.
elements: str
example:
- abc.example.com
- .example.net
returned: success
type: list
description: A description of the criteria for a domain list rule group.
returned: When the rule group is "domain list" based.
type: dict
rules_string:
description: A string describing the rules that the rule group is comprised
of.
returned: When the rule group is "rules string" based.
type: str
stateful_rules:
contains:
action:
description: What action to perform when a flow matches the rule
criteria.
example: PASS
returned: success
type: str
header:
contains:
destination:
description: The destination address or range of addresses to
inspect for.
example: 198.51.100.0/24
returned: success
type: str
destination_port:
description: The destination port to inspect for.
example: 6666:6667
returned: success
type: str
direction:
description: The direction of traffic flow to inspect.
example: FORWARD
returned: success
type: str
protocol:
description: The protocol to inspect for.
example: IP
returned: success
type: str
source:
description: The source address or range of addresses to inspect
for.
example: 203.0.113.98
returned: success
type: str
source_port:
description: The source port to inspect for.
example: '42'
returned: success
type: str
description: A description of the criteria used for the rule.
returned: success
type: dict
rule_options:
contains:
keyword:
description: The keyword for the setting.
example: sid:1
returned: success
type: str
settings:
description: A list of values passed to the setting.
elements: str
returned: When values are available
type: list
description: Additional Suricata RuleOptions settings for the rule.
elements: dict
returned: success
type: list
description: A list of dictionaries describing the rules that the rule
group is comprised of.
elements: dict
returned: When the rule group is "rules list" based.
type: list
stateless_rules_and_custom_actions:
contains:
custom_actions:
contains:
action_definition:
contains:
publish_metric_action:
contains:
dimensions:
contains:
value:
description: The value to use in the custom metric
dimension.
returned: success
type: str
description: The value to use in an Amazon CloudWatch
custom metric dimension.
elements: dict
returned: success
type: list
description: The description of an action which publishes
to CloudWatch.
returned: When the action publishes to CloudWatch.
type: dict
description: The custom action associated with the action name.
returned: success
type: dict
action_name:
description: The name for the custom action.
returned: success
type: str
description: A list of individual custom action definitions that
are available for use in stateless rules.
elements: dict
type: list
stateless_rules:
contains:
priority:
description: Indicates the order in which to run this rule relative
to all of the rules that are defined for a stateless rule
group.
returned: success
type: int
rule_definition:
contains:
actions:
description: The actions to take when a flow matches the
rule.
elements: str
example:
- aws:pass
- CustomActionName
returned: success
type: list
match_attributes:
contains:
destination_ports:
contains:
from_port:
description: The lower limit of the port range.
returned: success
type: int
to_port:
description: The upper limit of the port range.
returned: success
type: int
description: The destination port ranges to inspect
for.
elements: dict
returned: success
type: list
destinations:
contains:
address_definition:
description: An IP address or a block of IP addresses
in CIDR notation.
example: 192.0.2.3
returned: success
type: str
description: The destination IP addresses and address
ranges to inspect for.
elements: dict
returned: success
type: list
protocols:
description: The IANA protocol numbers of the protocols
to inspect for.
elements: int
example:
- 6
returned: success
type: list
source_ports:
contains:
from_port:
description: The lower limit of the port range.
returned: success
type: int
to_port:
description: The upper limit of the port range.
returned: success
type: int
description: The source port ranges to inspect for.
elements: dict
returned: success
type: list
sources:
contains:
address_definition:
description: An IP address or a block of IP addresses
in CIDR notation.
example: 192.0.2.3
returned: success
type: str
description: The source IP addresses and address ranges
to inspect for.
elements: dict
returned: success
type: list
tcp_flags:
contains:
flags:
description: Used with masks to define the TCP flags
that flows are inspected for.
elements: str
returned: success
type: list
masks:
description: The set of flags considered during
inspection.
elements: str
returned: success
type: list
description: The TCP flags and masks to inspect for.
elements: dict
returned: success
type: list
description: Describes the stateless 5-tuple inspection
criteria for the rule.
returned: success
type: dict
description: Describes the stateless 5-tuple inspection criteria
and actions for the rule.
returned: success
type: dict
description: A list of stateless rules for use in a stateless rule
group.
elements: dict
type: list
description: A description of the criteria for a stateless rule group.
returned: When the rule group is a stateless rule group.
type: dict
description: Inspection criteria used for a 5-tuple based rule group.
returned: success
type: dict
stateful_rule_options:
contains:
rule_order:
description: The order in which rules will be evaluated.
example: DEFAULT_ACTION_ORDER
returned: success
type: str
description: Additional options governing how Network Firewall handles stateful
rules.
returned: When the rule group is either "rules string" or "rules list" based.
type: dict
description: Details of the rules in the rule group
returned: success
type: dict
rule_group_metadata:
contains:
capacity:
description: The maximum operating resources that this rule group can use.
returned: success
type: int
consumed_capacity:
description: The number of capacity units currently consumed by the rule
group rules.
returned: success
type: int
description:
description: A description of the rule group.
returned: success
type: str
number_of_associations:
description: The number of firewall policies that use this rule group.
returned: success
type: int
rule_group_arn:
description: The ARN for the rule group
example: arn:aws:network-firewall:us-east-1:123456789012:stateful-rulegroup/ExampleGroup
returned: success
type: int
rule_group_id:
description: A unique identifier for the rule group.
example: 12345678-abcd-1234-abcd-123456789abc
returned: success
type: int
rule_group_name:
description: The name of the rule group.
returned: success
type: str
rule_group_status:
description: The current status of a rule group.
example: DELETING
returned: success
type: str
tags:
description: A dictionary representing the tags associated with the rule
group.
returned: success
type: dict
type:
description: Whether the rule group is stateless or stateful.
example: STATEFUL
returned: success
type: str
description: Details of the rules in the rule group
returned: success
type: dict
description: Details of the rules in the rule group
returned: success
type: dict