oracle.oci.oci_waas_access_rules_facts – Fetches details about one or multiple AccessRules resources in Oracle Cloud Infrastructure

Note

This plugin is part of the oracle.oci collection (version 4.14.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install oracle.oci.

To use it in a playbook, specify: oracle.oci.oci_waas_access_rules_facts.

New in version 2.9.0: of oracle.oci

Synopsis

  • Fetches details about one or multiple AccessRules resources in Oracle Cloud Infrastructure

  • Gets the currently configured access rules for the Web Application Firewall configuration of a specified WAAS policy. The order of the access rules is important. The rules will be checked in the order they are specified and the first matching rule will be used.

Requirements

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

Parameters

Parameter Choices/Defaults Comments
api_user
string
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See config_file_location). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint
string
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See config_file_location). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file
string
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See config_file_location). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided.
api_user_key_pass_phrase
string
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location).
auth_purpose
string
    Choices:
  • service_principal
The auth purpose which can be used in conjunction with 'auth_type=instance_principal'. The default auth_purpose for instance_principal is None.
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
cert_bundle
string
The full path to a CA certificate bundle to be used for SSL verification. This will override the default CA certificate bundle. If not set, then the value of the OCI_ANSIBLE_CERT_BUNDLE variable, if any, is used.
config_file_location
string
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name
string
The profile to load from the config file referenced by config_file_location. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location.
name
string
Use name along with the other options to return only resources that match the given name exactly.
region
string
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See config_file_location). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions.
tenancy
string
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See config_file_location). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
waas_policy_id
string / required
The OCID of the WAAS policy.

Examples

- name: List access_rules
  oci_waas_access_rules_facts:
    # required
    waas_policy_id: "ocid1.waaspolicy.oc1..xxxxxxEXAMPLExxxxxx"

Return Values

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

Key Returned Description
access_rules
complex
on success
List of AccessRules resources

Sample:
[{'action': 'ALLOW', 'block_action': 'SET_RESPONSE_CODE', 'block_error_page_code': 'block_error_page_code_example', 'block_error_page_description': 'block_error_page_description_example', 'block_error_page_message': 'block_error_page_message_example', 'block_response_code': 56, 'bypass_challenges': [], 'captcha_footer': 'captcha_footer_example', 'captcha_header': 'captcha_header_example', 'captcha_submit_label': 'captcha_submit_label_example', 'captcha_title': 'captcha_title_example', 'criteria': [{'condition': 'URL_IS', 'is_case_sensitive': True, 'value': 'value_example'}], 'name': 'name_example', 'redirect_response_code': 'MOVED_PERMANENTLY', 'redirect_url': 'redirect_url_example', 'response_header_manipulation': [{'action': 'EXTEND_HTTP_RESPONSE_HEADER', 'header': 'header_example', 'value': 'value_example'}]}]
 
action
string
on success
The action to take when the access criteria are met for a rule. If unspecified, defaults to `ALLOW`.
- **ALLOW:** Takes no action, just logs the request.
- **DETECT:** Takes no action, but creates an alert for the request.
- **BLOCK:** Blocks the request by returning specified response code or showing error page.
- **BYPASS:** Bypasses some or all challenges.
- **REDIRECT:** Redirects the request to the specified URL. These fields are required when `REDIRECT` is selected: `redirectUrl`, `redirectResponseCode`.
- **SHOW_CAPTCHA:** Show a CAPTCHA Challenge page instead of the requested page.
Regardless of action, no further rules are processed once a rule is matched.

Sample:
ALLOW
 
block_action
string
on success
The method used to block requests if `action` is set to `BLOCK` and the access criteria are met. If unspecified, defaults to `SET_RESPONSE_CODE`.

Sample:
SET_RESPONSE_CODE
 
block_error_page_code
string
on success
The error code to show on the error page when `action` is set to `BLOCK`, `blockAction` is set to `SHOW_ERROR_PAGE`, and the access criteria are met. If unspecified, defaults to 'Access rules'.

Sample:
block_error_page_code_example
 
block_error_page_description
string
on success
The description text to show on the error page when `action` is set to `BLOCK`, `blockAction` is set to `SHOW_ERROR_PAGE`, and the access criteria are met. If unspecified, defaults to 'Access blocked by website owner. Please contact support.'

Sample:
block_error_page_description_example
 
block_error_page_message
string
on success
The message to show on the error page when `action` is set to `BLOCK`, `blockAction` is set to `SHOW_ERROR_PAGE`, and the access criteria are met. If unspecified, defaults to 'Access to the website is blocked.'

Sample:
block_error_page_message_example
 
block_response_code
integer
on success
The response status code to return when `action` is set to `BLOCK`, `blockAction` is set to `SET_RESPONSE_CODE`, and the access criteria are met. If unspecified, defaults to `403`. The list of available response codes: `200`, `201`, `202`, `204`, `206`, `300`, `301`, `302`, `303`, `304`, `307`, `400`, `401`, `403`, `404`, `405`, `408`, `409`, `411`, `412`, `413`, `414`, `415`, `416`, `422`, `444`, `494`, `495`, `496`, `497`, `499`, `500`, `501`, `502`, `503`, `504`, `507`.

Sample:
56
 
bypass_challenges
list / elements=string
on success
The list of challenges to bypass when `action` is set to `BYPASS`. If unspecified or empty, all challenges are bypassed.
- **JS_CHALLENGE:** Bypasses JavaScript Challenge.
- **DEVICE_FINGERPRINT_CHALLENGE:** Bypasses Device Fingerprint Challenge.
- **HUMAN_INTERACTION_CHALLENGE:** Bypasses Human Interaction Challenge.
- **CAPTCHA:** Bypasses CAPTCHA Challenge.

  captcha_footer
string
on success
The text to show in the footer when showing a CAPTCHA challenge when `action` is set to `SHOW_CAPTCHA` and the request is challenged.

Sample:
captcha_footer_example
 
captcha_header
string
on success
The text to show in the header when showing a CAPTCHA challenge when `action` is set to `SHOW_CAPTCHA` and the request is challenged.

Sample:
captcha_header_example
 
captcha_submit_label
string
on success
The text to show on the label of the CAPTCHA challenge submit button when `action` is set to `SHOW_CAPTCHA` and the request is challenged.

Sample:
captcha_submit_label_example
 
captcha_title
string
on success
The title used when showing a CAPTCHA challenge when `action` is set to `SHOW_CAPTCHA` and the request is challenged.

Sample:
captcha_title_example
 
criteria
complex
on success
The list of access rule criteria. The rule would be applied only for the requests that matched all the listed conditions.

   
condition
string
on success
The criteria the access rule and JavaScript Challenge uses to determine if action should be taken on a request. - **URL_IS:** Matches if the concatenation of request URL path and query is identical to the contents of the `value` field. URL must start with a `/`. - **URL_IS_NOT:** Matches if the concatenation of request URL path and query is not identical to the contents of the `value` field. URL must start with a `/`. - **URL_STARTS_WITH:** Matches if the concatenation of request URL path and query starts with the contents of the `value` field. URL must start with a `/`. - **URL_PART_ENDS_WITH:** Matches if the concatenation of request URL path and query ends with the contents of the `value` field. - **URL_PART_CONTAINS:** Matches if the concatenation of request URL path and query contains the contents of the `value` field. - **URL_REGEX:** Matches if the concatenation of request URL path and query is described by the regular expression in the value field. The value must be a valid regular expression recognized by the PCRE library in Nginx (https://www.pcre.org). - **URL_DOES_NOT_MATCH_REGEX:** Matches if the concatenation of request URL path and query is not described by the regular expression in the `value` field. The value must be a valid regular expression recognized by the PCRE library in Nginx (https://www.pcre.org). - **URL_DOES_NOT_START_WITH:** Matches if the concatenation of request URL path and query does not start with the contents of the `value` field. - **URL_PART_DOES_NOT_CONTAIN:** Matches if the concatenation of request URL path and query does not contain the contents of the `value` field. - **URL_PART_DOES_NOT_END_WITH:** Matches if the concatenation of request URL path and query does not end with the contents of the `value` field. - **IP_IS:** Matches if the request originates from one of the IP addresses contained in the defined address list. The `value` in this case is string with one or multiple IPs or CIDR notations separated by new line symbol \n *Example:* "1.1.1.1\n1.1.1.2\n1.2.2.1/30" - **IP_IS_NOT:** Matches if the request does not originate from any of the IP addresses contained in the defined address list. The `value` in this case is string with one or multiple IPs or CIDR notations separated by new line symbol \n *Example:* "1.1.1.1\n1.1.1.2\n1.2.2.1/30" - **IP_IN_LIST:** Matches if the request originates from one of the IP addresses contained in the referenced address list. The `value` in this case is OCID of the address list. - **IP_NOT_IN_LIST:** Matches if the request does not originate from any IP address contained in the referenced address list. The `value` field in this case is OCID of the address list. - **HTTP_HEADER_CONTAINS:** The HTTP_HEADER_CONTAINS criteria is defined using a compound value separated by a colon: a header field name and a header field value. `host:test.example.com` is an example of a criteria value where `host` is the header field name and `test.example.com` is the header field value. A request matches when the header field name is a case insensitive match and the header field value is a case insensitive, substring match. *Example:* With a criteria value of `host:test.example.com`, where `host` is the name of the field and `test.example.com` is the value of the host field, a request with the header values, `Host: www.test.example.com` will match, where as a request with header values of `host: www.example.com` or `host: test.sub.example.com` will not match. - **HTTP_METHOD_IS:** Matches if the request method is identical to one of the values listed in field. The `value` in this case is string with one or multiple HTTP methods separated by new line symbol \n The list of available methods: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`
*Example:* "GET\nPOST"
- **HTTP_METHOD_IS_NOT:** Matches if the request is not identical to any of the contents of the `value` field. The `value` in this case is string with one or multiple HTTP methods separated by new line symbol \n The list of available methods: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`
*Example:* "GET\nPOST"
- **COUNTRY_IS:** Matches if the request originates from one of countries in the `value` field. The `value` in this case is string with one or multiple countries separated by new line symbol \n Country codes are in ISO 3166-1 alpha-2 format. For a list of codes, see ISO's website. *Example:* "AL\nDZ\nAM" - **COUNTRY_IS_NOT:** Matches if the request does not originate from any of countries in the `value` field. The `value` in this case is string with one or multiple countries separated by new line symbol \n Country codes are in ISO 3166-1 alpha-2 format. For a list of codes, see ISO's website. *Example:* "AL\nDZ\nAM" - **USER_AGENT_IS:** Matches if the requesting user agent is identical to the contents of the `value` field. *Example:* `Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0` - **USER_AGENT_IS_NOT:** Matches if the requesting user agent is not identical to the contents of the `value` field. *Example:* `Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0`

Sample:
URL_IS
   
is_case_sensitive
boolean
on success
When enabled, the condition will be matched with case-sensitive rules.

Sample:
True
   
value
string
on success
The criteria value.

Sample:
value_example
 
name
string
on success
The unique name of the access rule.

Sample:
name_example
 
redirect_response_code
string
on success
The response status code to return when `action` is set to `REDIRECT`.
- **MOVED_PERMANENTLY:** Used for designating the permanent movement of a page (numerical code - 301).
- **FOUND:** Used for designating the temporary movement of a page (numerical code - 302).

Sample:
MOVED_PERMANENTLY
 
redirect_url
string
on success
The target to which the request should be redirected, represented as a URI reference. Required when `action` is `REDIRECT`.

Sample:
redirect_url_example
 
response_header_manipulation
complex
on success
An object that represents an action to apply to an HTTP response headers if all rule criteria will be matched regardless of `action` value.

   
action
string
on success

Sample:
EXTEND_HTTP_RESPONSE_HEADER
   
header
string
on success
A header field name that conforms to RFC 7230.
Example: `example_header_name`

Sample:
header_example
   
value
string
on success
A header field value that conforms to RFC 7230.
Example: `example_value`

Sample:
value_example


Authors

  • Oracle (@oracle)