API Selection Filters
This section describes the conditions
that act as selection criteria for choosing APIs that are eligible for a particular test. It also filters out APIs that are not eligible.
Example:
Syntax
Parent Operators
Data Operators
Collection Operators
Combining Conditions using Boolean Operators
Parent Operators
Each condition
block begins with a parent operator. Parent Operators indicate the property of the API
you are testing. All the conditions will apply to these parent operators. Parent Operators can have the following values:
response_code
This denotes that the conditions will be applied on response code of the api
method
This denotes that the conditions will be applied on http method of the api
url
This denotes that the conditions will be applied on http url of the api
request_payload
This denotes that the conditions will be applied on request payload of the api
response_payload
This denotes that the conditions will be applied on response payload of the api
request_headers
This denotes that the condition will be applied on request headers of the api
response_headers
This denotes that the condition will be applied on response headers of the api
query_param
This denotes that the condition will be applied on query params of the api
Data Operators
Each Parent Operator should contain one or more Data Operators
that describe the exact condition to be applied to the Parent Property. Data Operators can have the following values:
contains_either
List/Non List
Checks whether the parent property contains the specified input. If input is an array, any one of the input element should satisfy this condition.
contains_all
List/Non List
Checks whether the parent property contains the specified input. If input is an array, all of the input element should satisfy this condition.
regex
List/Non List
Checks whether the parent property contains a match for the regex specified in the specified input. If input is an array, one of the regex input should have a match
eq
Non List
Checks whether the parent property is equal to the specified input.
neq
Non List
Checks whether the parent property is not equal equal to the specified input.
gt
Non List
Checks whether the parent property is greater than to the specified input.
gte
Non List
Checks whether the parent property is greater than equal to the specified input.
lt
Non List
Checks whether the parent property is lesser than the specified input.
lte
Non List
Checks whether the parent property is lesser than equal to to the specified input.
not_contains
List/Non List
Checks whether the parent property does not contain the specified input. If input is an array, all of the input element should satisfy this condition.
not_contains_either
List/Non List
Checks whether the parent property does not contain the specified input. If input is an array, any one of the input element should satisfy this condition.
contains_jwt
boolean
Checks whether the parent property contains/not contains a jwt token
cookie_expire_filter
boolean
Checks if the cookie expires in next 30 days
contains_either
contains_either
Checks whether the parent property contains the specified input. If input is an array, any one
of the input element should satisfy this condition.
Example 1
Example 2
👉🏻 In simple language: The above yaml syntax is filtering APIs with url containing the keywords ‘https’ or ‘login’
contains_all
contains_all
Checks whether the parent property contains the specified input. If input is an array, all
of the input mlelement should satisfy this condition.
Example 1
Example 2
👉🏻 In simple language: The above yaml syntax is filtering APIs with url containing the keywords ‘https’ and ‘login’
regex
regex
Checks whether the parent property contains a match for the regex
specified in the specified input. If input is an array, one of the regex input should have a match.
Example 1
eq
eq
Checks whether the parent property is equal to the specified input.
Example 1
gt
gt
Checks whether the parent property is greater than the specified input.
Example 1
gte
gte
Checks whether the parent property is greater than or equal to the specified input.
Example 1
lt
lt
Checks whether the parent property is lesser than the specified input.
Example 1
lte
lte
Checks whether the parent property is lesser than or equal to the specified input.
Example 1
not_contains
not_contains
Checks whether the parent property does not contain the specified input. If input is an array, all of the input element should satisfy this condition.
Example 1
Match Example for above
Invalid Example for above
not_contains_either
not_contains_either
Checks whether the parent property does not contain the specified input. If input is an array, any one of the input element should satisfy this condition.
Example 1
contains_jwt
contains_jwt
Checks whether the parent property contains/not contains a JWT token.
Example 1
Collection Operators
These operators are useful for queries that involve individual keys and values in payloads and headers, rather than applying the condition to the entire payload as a string. To achieve the desired result, they must be combined with a data operator.
for_one
for_one
This collection operator is used to imply that either of key
or value
in the entire payload should satisfy the condition.
Example 1
Request Payload {”id”: 123, “data”:{”Username”: “abc”}}
Let’s say we want to check if there is a key present in request payload which contains name. We can represent that in the following yaml syntax -
👉🏻 In simple language: The above yaml syntax is filtering APIs with any key of the request payload containing the keyword ‘name’
Example 2
Request Payload {”id”: 123, ”status”: “admin”, “createdAt”: 1688364964}
Let’s say we want to check if there is a key
present in request payload which is equal to status
, and contains a value
like (admin
). We can represent that in the following yaml syntax -
👉🏻 In simple language: The above yaml syntax is filtering APIs with any key of the request payload equal to ‘status’ and the same key having value which matches specified regex.
Matching Payloads
{”id”: 123, ”status”: “admin”, “createdAt”: 1688364964}
{”status”: “administrator”, “active”: true}
{”userInfo”: {”name”: “testUser”, “status”: “admin”}, “lastLoginTs”: 1688364964}
Invalid Examples
{”id”: 123, “createdAt”: 1688364964}
{”id”: 123, ”status”: “normal”, “createdAt”: 1688364964}
{”id”: 123, ”access”: “admin”, “status”: “active”}
Here key is named status, and a value matches regex .*admin*., but there is no single key value pair which satisfies both conditions.
Body Operators
These operators are useful for applying conditions specifically on request payload, response payload strings. To achieve the desired result, they must be combined with a data operator. Currently there are 2 types of body operators -
length
length
Length operator is used for applying conditions on the request/response payload length. Let’s explore this more through the below example
Extract Operators
extract
extract
These operators can be used to save parent entity’s value into a variable at any point during the api_selection_filters phase, which can be used later on in the test template yaml using ${}
notation. Let’s see it in action in the below example -
We can also extract an individual key/value inside the parent entities like (request_payload, response_payload, request_headers, response_headers, query_params).
How to use extracted variables in YAML
You can use ${<VAR_NAME>}
to refer the extracted value. Eg. you can use extracted urlVar
do the following -
extractMultiple
extractMultiple
This is similar to extract
, except it can extract a list of values. For example, if you need a list of all keys in the API request JSON, you can use extractMultiple
operator. Using extract
will just extract the first key. #Example 1
Combining conditions using Boolean Operators
Security tests can be complex in nature. Often, a specific test requires multiple filter conditions to evaluate whether a given endpoint is eligible for the test.
Default Behavior
For a test to consider an endpoint valid, all conditions
specified in the YAML template must be satisfied. By default, yaml considers and
operator for all conditions. However, you can easily override this behavior using other boolean operators.
Boolean Operators
Boolean operators are of 2 types:
and
and
The and
operator requires all of the specified conditions to be satisfied, which is also the default
behavior. It can be applied on top of any operator, including data
, collection
, and parent
operands.
Example 1
Since applying and
operator is default behaviour, we don’t need to explicitly write and
operator. See below
or
or
The OR operator requires that at least one of the specified conditions is satisfied. It can be applied to any operator, including data, collection, and parent operands.
Example 1
Last updated