- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# aws_waf_condition – create and delete WAF Conditions

New in version 2.5.

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## Synopsis

- Read the AWS documentation for WAF https://aws.amazon.com/documentation/waf/

## Requirements

The below requirements are needed on the host that executes this module.

- python >= 2.6

- boto

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
aws_access_key string |  | AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used. aliases: ec2_access_key, access_key
aws_secret_key string |  | AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used. aliases: ec2_secret_key, secret_key
debug_botocore_endpoint_logs boolean added in 2.8 | Choices: no ← yes | Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.
ec2_url string |  | Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.
filters - |  | A list of the filters against which to match. For type=`byte`, valid keys are `field_to_match`, `position`, `header`, `transformation`. For type=`geo`, the only valid key is `country`. For type=`ip`, the only valid key is `ip_address`. For type=`regex`, valid keys are `field_to_match`, `transformation` and `regex_pattern`. For type=`size`, valid keys are `field_to_match`, `transformation`, `comparison` and `size`. For type=`sql`, valid keys are `field_to_match` and `transformation`. For type=`xss`, valid keys are `field_to_match` and `transformation`. field_to_match can be one of `uri`, `query_string`, `header` `method` and `body`. If field_to_match is `header`, then `header` must also be specified. transformation can be one of `none`, `compress_white_space`, `html_entity_decode`, `lowercase`, `cmd_line`, `url_decode`. position, can be one of `exactly`, `starts_with`, `ends_with`, `contains`, `contains_word`. comparison can be one of `EQ`, `NE`, `LE`, `LT`, `GE`, `GT`. target_string is a maximum of 50 bytes. regex_pattern is a dict with a `name` key and `regex_strings` list of strings to match.
name - / required |  | Name of the Web Application Firewall condition to manage.
profile string |  | Uses a boto profile. Only works with boto >= 2.24.0.
purge_filters boolean | Choices: no ← yes | Whether to remove existing filters from a condition if not passed in filters.
region string |  | The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region aliases: aws_region, ec2_region
security_token string |  | AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used. aliases: access_token
state - | Choices: present ← absent | Whether the condition should be `present` or `absent`.
type - | Choices: byte geo ip regex size sql xss | the type of matching to perform.
validate_certs boolean | Choices: no yes ← | When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
waf_regional boolean added in 2.9 | Choices: no ← yes | Whether to use waf_regional module. Defaults to false.

## Notes

Note

- If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence `AWS_URL` or `EC2_URL`, `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` or `EC2_ACCESS_KEY`, `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` or `EC2_SECRET_KEY`, `AWS_SECURITY_TOKEN` or `EC2_SECURITY_TOKEN`, `AWS_REGION` or `EC2_REGION`

- Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html

- `AWS_REGION` or `EC2_REGION` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file

## Examples

    - name: create WAF byte condition
      aws_waf_condition:
        name: my_byte_condition
        filters:
        - field_to_match: header
          position: STARTS_WITH
          target_string: Hello
          header: Content-type
        type: byte

    - name: create WAF geo condition
      aws_waf_condition:
        name: my_geo_condition
        filters:
          - country: US
          - country: AU
          - country: AT
        type: geo

    - name: create IP address condition
      aws_waf_condition:
        name: "{{ resource_prefix }}_ip_condition"
        filters:
          - ip_address: "10.0.0.0/8"
          - ip_address: "192.168.0.0/24"
        type: ip

    - name: create WAF regex condition
      aws_waf_condition:
        name: my_regex_condition
        filters:
          - field_to_match: query_string
            regex_pattern:
              name: greetings
              regex_strings:
                - '[hH]ello'
                - '^Hi there'
                - '.*Good Day to You'
        type: regex

    - name: create WAF size condition
      aws_waf_condition:
        name: my_size_condition
        filters:
          - field_to_match: query_string
            size: 300
            comparison: GT
        type: size

    - name: create WAF sql injection condition
      aws_waf_condition:
        name: my_sql_condition
        filters:
          - field_to_match: query_string
            transformation: url_decode
        type: sql

    - name: create WAF xss condition
      aws_waf_condition:
        name: my_xss_condition
        filters:
          - field_to_match: query_string
            transformation: url_decode
        type: xss

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
condition complex | always | condition returned by operation
| byte_match_set_id string | always | ID for byte match set Sample: c4882c96-837b-44a2-a762-4ea87dbf812b
| byte_match_tuples complex | always | list of byte match tuples
|  | field_to_match complex | always | Field to match
|  |  | data string |  | Which specific header (if type is header) Sample: content-type
|  |  | type string |  | Type of field Sample: HEADER
|  | positional_constraint string |  | Position in the field to match Sample: STARTS_WITH
|  | target_string string |  | String to look for Sample: Hello
|  | text_transformation string |  | Transformation to apply to the field before matching Sample: NONE
| condition_id string | when state is present | type-agnostic ID for the condition Sample: dd74b1ff-8c06-4a4f-897a-6b23605de413
| geo_match_constraints complex | when type is geo and state is present | List of geographical constraints
|  | type string |  | Type of geo constraint Sample: Country
|  | value string |  | Value of geo constraint (typically a country code) Sample: AT
| geo_match_set_id string | when type is geo and state is present | ID of the geo match set Sample: dd74b1ff-8c06-4a4f-897a-6b23605de413
| ip_set_descriptors complex | when type is ip and state is present | list of IP address filters
|  | type string | always | Type of IP address (IPV4 or IPV6) Sample: IPV4
|  | value string | always | IP address Sample: 10.0.0.0/8
| ip_set_id string | when type is ip and state is present | ID of condition Sample: 78ad334a-3535-4036-85e6-8e11e745217b
| name string | when state is present | Name of condition Sample: my_waf_condition
| regex_match_set_id string | when type is regex and state is present | ID of the regex match set Sample: 5ea3f6a8-3cd3-488b-b637-17b79ce7089c
| regex_match_tuples complex | when type is regex and state is present | List of regex matches
|  | field_to_match complex |  | Field on which the regex match is applied
|  |  | type string | when type is regex and state is present | The field name Sample: QUERY_STRING
|  | regex_pattern_set_id string |  | ID of the regex pattern Sample: 6fdf7f2d-9091-445c-aef2-98f3c051ac9e
|  | text_transformation string |  | transformation applied to the text before matching Sample: NONE
| size_constraint_set_id string | when type is size and state is present | ID of the size constraint set Sample: de84b4b3-578b-447e-a9a0-0db35c995656
| size_constraints complex | when type is size and state is present | List of size constraints to apply
|  | comparison_operator string |  | Comparison operator to apply Sample: GT
|  | field_to_match complex |  | Field on which the size constraint is applied
|  |  | type string |  | Field name Sample: QUERY_STRING
|  | size integer |  | size to compare against the field Sample: 300
|  | text_transformation string |  | transformation applied to the text before matching Sample: NONE
| sql_injection_match_set_id string | when type is sql and state is present | ID of the SQL injection match set Sample: de84b4b3-578b-447e-a9a0-0db35c995656
| sql_injection_match_tuples complex | when type is sql and state is present | List of SQL injection match sets
|  | field_to_match complex |  | Field on which the SQL injection match is applied
|  |  | type string |  | Field name Sample: QUERY_STRING
|  | text_transformation string |  | transformation applied to the text before matching Sample: URL_DECODE
| xss_match_set_id string | when type is xss and state is present | ID of the XSS match set Sample: de84b4b3-578b-447e-a9a0-0db35c995656
| xss_match_tuples complex | when type is xss and state is present | List of XSS match sets
|  | field_to_match complex |  | Field on which the XSS match is applied
|  |  | type string |  | Field name Sample: QUERY_STRING
|  | text_transformation string |  | transformation applied to the text before matching Sample: URL_DECODE

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Will Thames (@willthames)

- Mike Mochan (@mmochan)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.