community / community.aws / 5.1.0 / module / networkfirewall_rule_group create, delete and modify AWS Network Firewall rule groups | "added in version" 4.0.0 of community.aws" Authors: Mark Chappell (@tremble)community.aws.networkfirewall_rule_group (5.1.0) — module
Install with ansible-galaxy collection install community.aws:==5.1.0
collections: - name: community.aws version: 5.1.0
A 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