Understanding Conditions
Understand and compose conditions for rules associated with WAF policies.
WAF uses the JMESPath language as a rule condition language. JMESPath is a query language for JSON (see https://jmespath.org/specification.htmlJMESPath selectors) that you can use to write JMESPath expressions, where each expression takes a JSON document as an input (the input document) and returns a transformed or new JSON document (the output document).
In WAF, each rule accepts a JMESPath expression as the condition. HTTP requests or HTTP responses (depending on the type of rule) trigger WAF rules. When evaluating a rule, the WAF service evaluates the JMESPath expression (the condition) of the rule and provides an input JSON document, which includes the details of the HTTP request or HTTP response that triggered the evaluation. Then, the result of the evaluated JMESPath expression is used to determine whether or not to run the action specified in the rule.
The return value of JMESPath conditions in WAF is converted to a boolean value. The following values are converted to "false":
- Empty list: []
- Empty object: {}
- Empty string: ""
- False boolean: false
- Null value: null
You can create a JMESPath condition with up to 1,024 characters.
Example
URL path conditions
# URL path equals
http.request.url.path == '/example/path'
# URL path does not equal
http.request.url.path != '/example/path'
# URL path contains
contains(http.request.url.path, 'example')
# URL path does not contain
!contains(http.request.url.path, 'example')
# URL path starts with
starts_with(http.request.url.path, '/example/path')
# URL path ends with
ends_with(http.request.url.path, '.png')
# HTTP request method is one of
contains(['GET', 'POST'], http.request.method)
HTTP request header conditions
# HTTP request header exists
contains(keys(http.request.headers), 'example-header')
# HTTP request header has specific value
http.request.headers."example-header"[0] == 'specific-value'
# One of the HTTP request headers with the same name has a specific value
contains(http.request.headers."example-header", 'specific-value')
Multiple conditions
# HTTP request method is GET and URL path starts with /example/path
http.request.method == 'GET' && starts_with(http.request.url.path, '/example/path')
# URL path starts with /example/path_one or /example/path_two
starts_with(http.request.url.path, '/example/path_one') || starts_with(http.request.url.path, '/example/path_two')
# HTTP request method is POST and URL is either /example/path_one or /example/path_two
http.request.method == 'POST' && (http.request.url.path == '/example/path_one' || http.request.url.path == '/example/path_two')
Input JSON Document Structure
When evaluating JMESPath expressions, WAF provides an input JSON document, which includes the details of the HTTP request or HTTP response that triggered the evaluation. The input JSON document is always a JSON object.
Example
For an HTTP request with the following details:
-
Source IP address and port: 129.146.10.1:48152
-
Country code that the source IP address belongs to: US
-
ASN that the source IP address belongs to: 31898
-
Destination IP address and port: 205.147.88.0:80
-
Destination host: example.com
-
Protocol: HTTP/1.1
GET /test/path/img.jpg?param1=a&m2=b HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Cookie: cookie1=A; cookie2=B; cookie3=3C; cookie3=3D
Host: example.com
User-Agent: HTTPie/2.4.0
The following JSON input document is generated and passed to JMESPath expressions:
{
"connection": {
"source": {
"address": "129.146.10.1",
"port": 49152,
"geo": {
"countryCode": "US"
},
"routing": {
"asn": 31898
}
},
"destination": {
"address": "205.147.88.0",
"port": 80
},
"protocol": "http"
},
"http": {
"request": {
"host": "www.example.com",
"method": "GET",
"version": "1.1",
"url": {
"path": "/test/path/img.jpg",
"query": "param1=a¶m2=b",
"queryParameters": {
"param1": ["a"],
"param2": ["b"]
},
"queryPrefix": "?"
},
"headers": {
"accept": ["*/*"],
"accept-encoding": ["gzip, deflate"],
"connection": ["keep-alive"],
"cookie": [
"cookie1=A; cookie2=B; cookie3=3C; cookie3=3D"
],
"host": ["www.example.com"],
"user-agent": ["HTTPie/2.4.0"]
},
"cookies": {
"cookie1": ["A"],
"cookie2": ["B"],
"cookie3": ["3C", "3D"]
}
}
}
}
Reference
Category |
Value |
---|---|
Type |
string |
Description |
A string containing the TCP source IP address. IPv6 addresses are represented in their canonical form, according to RFC 5952. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"10.0.0.1", "1.2.3.4" |
Category |
Value |
---|---|
Type |
number |
Description |
TCP source port |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
49152 |
Category |
Value |
---|---|
Type |
string | null |
Description |
ISO 3166-1 alpha-2 country code of the country, which the source IP address belongs to. Can be null when the country isn't known. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"US" |
Category |
Value |
---|---|
Type |
number | null |
Description |
The ASN (autonomous system number) to which the source IP address belongs to. Can be null when the IP address is private. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
2122, 1278 |
Category |
Value |
---|---|
Type |
string |
Description |
A string containing the TCP destination IP address. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"10.0.0.1" |
Category |
Value |
---|---|
Type |
number |
Description |
TCP destination port |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
80 |
Category |
Value |
---|---|
Type |
string |
Description |
The protocol of the connection, either "http" or "https." |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"https" |
Category |
Value |
---|---|
Type |
string |
Description |
The value of the HTTP request "Host" header. The "Host" request header specifies the host and port number of the server to which the request is being sent. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"http://www.example.com", "api.example.com:8080" |
Category |
Value |
---|---|
Type |
string |
Description |
The HTTP request method |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"GET", "POST" |
Category |
Value |
---|---|
Type |
string |
Description |
HTTP protocol version |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"1.1", "2.0" |
Category |
Value |
---|---|
Type |
string |
Description |
The absolute path part of the HTTP request target. Doesn't include the query part. Always starts with a "/". |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"/api/v1", "/index.html", "/" |
Category |
Value |
---|---|
Type |
string |
Description |
The query parameters of the HTTP request target, without the prefix. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"foo=bar&multi=1&multi=2", "multi=one&multi=two&multi=3&encoded=two%20words", "" |
Category |
Value |
||||||
---|---|---|---|---|---|---|---|
Type |
object |
||||||
Description |
The query part of the HTTP request target, parsed into an object structure, where:
Keys and values are unescaped according to URL escaping rules. |
||||||
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
||||||
Example values |
|
Category |
Value |
---|---|
Type |
string |
Description |
The query prefix of the HTTP request target. If a query string is present, it is always "?". If no query string is present, it contains an empty string. |
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
Example values |
"?", "" |
Category |
Value |
||||
---|---|---|---|---|---|
Type |
object |
||||
Description |
The HTTP request headers parsed into an object structure, where:
|
||||
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
||||
Example values |
|
Category |
Value |
||||
---|---|---|---|---|---|
Type |
object |
||||
Description |
The HTTP cookies that were passed using the "Cookie" HTTP request header, parsed into an object structure, where:
|
||||
Available in |
requestAccessControl, requestRateLimiting, requestProtection, responseAccessControl, responseProtection |
||||
Example values |
|
Category |
Value |
---|---|
Type |
number |
Description |
HTTP response code |
Available in |
responseAccessControl, responseProtection |
Example values |
200 |
Category |
Value |
||||
---|---|---|---|---|---|
Type |
object |
||||
Description |
The HTTP response headers parsed into an object structure, where:
|
||||
Available in |
responseAccessControl, responseProtection |
||||
Example values |
|
Case-Insensitive String Matching
In addition to string matching functions supported by default in JMESPath, WAF adds support for four functions that can match strings case-insensitively:
- i_equals (case-insensitive variant of the == operator);
- i_contains (case-insensitive variant of the contains function);
- i_starts_with (case-insensitive variant of the starts_with function);
- i_ends_with (case-insensitive variant of the ends_with function).
i_equals
boolean i_equals(string $left, string $right)
Returns true if strings $left and $right are equal, when compared case-insensitively (both $left and $right strings are converted to lower case, only English letters are converted to lower case). Otherwise, returns false.Given | Expression | Result |
---|---|---|
"string" | i_equals(@, 'string') | true |
"string" | i_equals(@, 'STRING') | true |
"string" | i_equals(@, 'sTrInG') | true |
"STRING" | i_equals(@, 'string') | true |
"string" | i_equals(@, 'other_string') | false |
i_contains
boolean i_contains(array|string $subject, any $search)
Case-insensitive variant of the contains function.If the provided $subject is a string, this function returns true if the string contains the provided $search argument, when compared case-insensitively (both $left and $right strings are converted to lower case, only English letters are converted to lower case). Otherwise, this function returns false.
If $subject is an array, this function returns true if at least one of the elements in the array is equal to the provided $search value, otherwise it returns false.
If $search is a string - comparison is done using the same logic as in i_equals() function: case-insensitive comparison (both the individual $subject array element and $search strings are converted to lower case, only English letters are converted to lower case).
If $search isn't a string - comparison is done using the standard == operator.
Given | Expression | Result |
---|---|---|
"foobarbaz" | i_contains(@, 'bar') | true |
"foobarbaz" | i_contains(@, 'BAR') | true |
"foobarbaz" | i_contains(@, 'bAr') | true |
"foobarbaz" | i_contains(@, 'foo') | false |
["a", "b"] | i_contains(@, `a`) | true |
["foo", "bar"] | i_contains(@, `b`) | false |
["foo", "bar"] | i_contains(@, `BAR`) | true |
i_starts_with
boolean i_starts_with(string $subject, string $prefix)
Returns true if the $subject starts with the $prefix, when compared case-insensitively (both $left and $right strings are converted to lower case, only English letters are converted to lower case). Otherwise, this function returns false.Given | Expression | Result |
---|---|---|
"foobarbaz" | i_starts_with(@, 'foo') | true |
"foobarbaz" | i_starts_with(@, 'FOO') | true |
"foobarbaz" | i_starts_with(@, 'fOo') | true |
"foobarbaz" | i_starts_with(@, 'bar') | false |
i_ends_with
boolean i_ends_with(string $subject, string $suffix)
Returns true if the $subject ends with the $suffix, when compared case-insensitively (both $left and $right strings are converted to lower case, only English letters are converted to lower case). Otherwise, this function returns false.Given | Expression | Result |
---|---|---|
"foobarbaz" | i_ends_with(@, 'baz') | true |
"foobarbaz" | i_ends_with(@, 'BAZ') | true |
"foobarbaz" | i_ends_with(@, 'bAz') | true |
"foobarbaz" | i_ends_with(@, 'bar') | false |
IP Address Matching
WAF adds support for multiple functions that can match an IP address against a list of CIDR ranges or WAF Network Address List resources:
-
address_in (matches an IP address against a list of CIDR ranges);
-
address_in_network_address_list (matches an IP address against a WAF Network Address List resource);
-
vcn_address_in_network_address_list (matches an IP address with a VCN ID against a WAF Network Address List resource).
address_in
boolean address_in(string $ip_address, array[string] $cidr_subnets)
Returns true if the given $ip_address is contained in at least one of the CIDR subnets specified in $cidr_subnets. Otherwise, returns false.
$ip_address must be a string containing an IP address.
$cidr_subnets must be an array of strings containing one CIDR subnet each.
Given | Expression | Result |
---|---|---|
{ "connection": { "source": { "address": "1.1.1.1" } } } |
address_in(connection.source.address, ['1.1.0.0/16', '2.2.0.0/16']) | true |
address_in(connection.source.address, ['3.3.0.0/16']) | false |
address_in_network_address_list
boolean address_in_network_address_list(string $ip_address, array[string] $nal_ids)
Returns true if the given $ip_address is contained in at least one of the provided Network Address Lists (a WAF resource containing a list of CIDR subnets). Otherwise, returns false.$ip_address must be a string containing an IP address.
$nal_id arguments must be an array of strings, referencing WAF NetworkAddressList resources by ID. All referenced NetworkAddressLists must be of type: "ADDRESSES".
Example 1
Item | Details |
---|---|
Given input |
{ "connection": { "source": { "address": "1.1.1.1" } } } |
Given NALs |
ocid1.webappfirewallnetworkaddresslist...a:
|
Expression | address_in_network_address_list(connection.source.address, ['ocid1.webappfirewallnetworkaddresslist...a']) |
Result | true |
Item | Details |
---|---|
Given input |
{ "connection": { "source": { "address": "1.1.1.1" } } } |
Given NALs |
ocid1.webappfirewallnetworkaddresslist...a:
ocid1.webappfirewallnetworkaddresslist...b:
|
Expression | address_in_network_address_list(connection.source.address, ['ocid1.webappfirewallnetworkaddresslist...b']) |
Result | false |
vcn_address_in_network_address_list
boolean vcn_address_in_network_address_list(string $ip_address, string $vcn_id, array[string] $nal_ids)
Returns true if the given $ip_address in VCN $vcn_id is contained in at least one of the provided Network Address Lists (a WAF resource containing a list of CIDR subnets). Otherwise, returns false.$ip_address must be a string containing an IP address.
$vcn_id must be a string containing an OCID of a VCN.
$nal_ids must be an array of strings, referencing WAF NetworkAddressList resources by ID. All referenced NetworkAddressLists must be of type: "VCN_ADDRESSES".
Example 1Item | Details |
---|---|
Given input |
{ "connection": { "source": { "address": "10.0.0.1" } }, "paResource": { "vcnOcid": "ocid1.vcn...a" } } |
Given NALs |
ocid1.webappfirewallnetworkaddresslist...a:
|
Expression |
vcn_address_in_network_address_list( connection.source.address, connection.paResource.vcnOcid, ['ocid1.webappfirewallnetworkaddresslist...a'] ) |
Result |
true |
Item | Details |
---|---|
Given input |
{ "connection": { "source": { "address": "10.0.0.1" } }, "paResource": { "vcnOcid": "ocid1.vcn...a" } } |
Given NALs |
ocid1.webappfirewallnetworkaddresslist...b:
|
Expression | vcn_address_in_network_address_list( connection.source.address, connection.paResource.vcnOcid, ['ocid1.webappfirewallnetworkaddresslist...b'] ) |
Result | false |