Akto - API Security platform
Akto WebsiteStart freeBook a demoDiscordGitHub
  • Github Open Source Repo
  • What is Akto?
  • AktoGPT
  • AGENTIC AI
    • Akto MCP Server
  • Getting Started
    • Deployment Types
    • Akto Cloud
      • Connect Akto with Hybrid SaaS
      • Migrate From Self Hosted Setup To SaaS
      • Setting up proxy
    • Akto Self Hosted
      • AWS deploy
        • AWS multi-VPC deploy
        • AWS Cross-Region Cross-VPC deploy
        • Custom subdomain on Akto on AWS
      • Helm Deploy
      • Azure Deploy
      • Openshift Deploy
      • Heroku
      • GCP Deploy
    • Local Deploy
    • FAQs on data concerns
  • Traffic Connector
    • Traffic Data Sources
    • eBPF
      • Connect Akto with eBPF
      • Connect Akto with eBPF on mTLS
    • Kubernetes
      • Connect Akto with Kubernetes in AWS
      • Connect Akto eBPF with Kubernetes
    • API Gateways
      • Connect Akto with Envoy
      • Connect Akto with NGINX
      • Connect Akto with Istio
      • Connect Akto with HAProxy
      • Connect Akto with Azure API Management
      • Connect Akto with F5
      • Connect Akto with 3Scale
      • Connect Akto with Layer7 API Gateway
      • Connect Akto with Citrix
      • Connect Akto with Kong
      • Connect Akto with Kong Mesh
      • Connect Akto with Cloudflare
      • Connect Akto with IBM Connect
      • Connect Akto with Mulesoft Flex Gateway
      • Connect Akto with Apigee
    • Mirroring
      • Connect Akto with AWS Traffic Mirroring
      • Connect Akto with GCP Packet Mirroring
    • AWS Services
      • Connect Akto with AWS Beanstalk
      • Connect Akto with AWS API Gateway
      • Connect Akto with AWS Lambda
      • Connect Akto with AWS API Gateway with CloudWatch OAM
      • Connect Akto with AWS API Gateway with service account (Temporary Credentials)
      • Connect Akto with AWS Fargate
      • Connect Akto with AWS EKS
      • Connect Akto with AWS ECS
    • GCP Services
      • Connect Akto with GCP Packet Mirroring
      • Connect Akto with Apigee
      • Connect Akto with Google Cloud Run Functions
      • Connect Akto with Google Cloud Run
      • Connect Akto with GKE
    • Azure Services
      • Connect Akto with Azure App Services
      • Connect Akto with Azure API Management
      • Connect Akto with AKS
      • Connect Akto with Azure OpenShift
      • Connect Akto with Azure Container App
      • Connect Akto with Azure Functions
    • Akto SDK
    • Source Code
      • GitHub
      • Bitbucket
      • GitLab
      • API inventory from source code
      • Source code installation
    • Virtual Machines
      • Connect Akto with Docker
      • Connect Akto on TLS service
      • Connect Akto with TCP Agent
    • Manual
      • Connect Akto with Burp suite
      • Connect Akto with Postman
      • Connect Akto with OpenAPI
      • Add API traffic to Akto using HAR file upload
      • API Import: WSDL in Akto
    • Configure TLS on kafka
  • API Inventory
    • Concepts
      • API Endpoints
      • Meta Properties of API Endpoint
      • API Collection
      • API Call Stats
      • Explore mode
      • gRPC API Coverage with Akto
      • Data Types
      • API Groups
      • Environment Type
      • Protocol Support in Akto
      • API Changes
      • Third Party APIs
      • Tags
      • API Dependency Graph
      • Sensitive Data
      • Alerts
      • Shadow APIs
      • Zombie APIs
      • Risk Score
      • Auth types
      • Access Type
      • API discovery from source code
      • Advanced Filter Option
    • How-To
      • Enable Tree view for API collections
      • Export an API Collection to Postman
      • Export an API Collection to Burp
      • Create API group
      • Collection-Based RBAC
      • Descriptions for API Collections & Endpoints
      • Remove API(s) from API group
      • Deactivating and Reactivating API Collections in Akto
      • Add collection using Explore Mode
      • De-merge API
      • Create Swagger File Using Akto
      • Copy API Endpoints Data
      • Add an API Collection
      • Set environment type
      • Delete an API Collection
      • Create a Custom Data Type
      • Reset Data Types in Akto
      • Set Sensitivity of a Data Type
      • De-activate a data type
      • Add a Custom Auth Type
      • Reset an Auth Type
      • Configure Access Types
      • View New API Endpoint
      • Add Private CIDRs list
      • View New Parameters
      • Configure alerts on API changes
      • Create a custom collection
      • Redact sensitive data
      • Extract APIs from github hosted source code using our Github Action
      • Extract APIs from source code using our Docker based CLI
      • Remove Bad Endpoints
      • Create New Tags
      • Edit Tags
  • API Protection
    • Overview
    • External API Runtime Threat Notifications
    • Concepts
      • Threat Actors
      • Threat Policy
  • WAF
    • AWS WAF
    • Cloudflare WAF
  • Test Editor
    • Concepts
      • Overview
      • Test YAML
      • Test Library
      • Custom Test
      • Test YAML Syntax (Detailed)
        • ID
        • Info
        • Wordlists
        • Auth
        • API Selection Filters
        • Execute
        • Validation
        • Contexts
        • Strategy
        • Conditional flows
      • Template YAMLs
        • Local File Inclusion with Akto
      • Dynamic severity
    • How To
      • Edit Test
      • Create a Custom Test
      • Deactivate Test
      • Play in Test Editor Background
      • Copy Test Content
      • Opening Endpoint in Test Editor
      • Add a New Test Library
      • Contribute to Test Library
  • API Security Testing
    • Concepts
      • Severity Levels
      • Test
      • Result types
      • Test Role
      • User Config
      • Test Result
      • JSON Recording for Automated Auth Tokens
    • How To
      • Run Test
      • Auto-Create Jira Tickets
      • Edit Test Settings
      • Install testing module in your Cloud
        • Ephemeral Storage for Hybrid Runtime
        • gRPC Testing in Hybrid Testing Module
      • Create Custom Test Suites
      • Recalculate Issue Counts
      • Testing Module Selector in Akto
      • Run Tests by Category
      • Export Vulnerability Report from Test Results
      • Test Multiple APIs
      • Schedule Tests
      • Stop Tests
      • Run Test on Any One Endpoint
      • Configure global rate limit
      • Rescan Specific Issues Resolved
      • Configure Pre-request Script
      • Set Up JSON Recording for Auth Tokens
      • Create a Test Role
      • Edit Auth Flow in Test Roles
      • Restrict Access to a Test Role Using RBAC
      • Play in Test Editor Playground
      • Conduct Role-Based Testing
      • Run tests in CLI using Akto
      • Secure GraphQL APIs using Akto
      • Secure REST APIs using Akto
      • Secure SOAP APIs using Akto
      • Create and Edit Auth Types
  • Issues
    • Concepts
      • Overview
      • Values
      • Vulnerability Report
      • Remediation
    • How To
      • Jira Integration
      • Azure DevOps Boards Integration
      • Triage Issues
        • Review Issues Marked as False Positives
      • Export Selected Issues to Reports
      • Export Vulnerability Report
  • CI/CD
    • GitHub Actions
      • Create GitHub App
    • Jenkins
    • Azure DevOps
    • GitLab
    • Generic CI/CD
    • How To
      • Run tests in CI/CD
      • Add test to CI/CD Pipeline
      • Get API Credentials
      • Test ID from Akto test
  • Account
    • Invite User
      • Change role of a User
    • Create a New Account
    • How to Switch Between Accounts in Akto
    • Understanding Role Permissions
    • Custom roles
    • Audit Logs
    • SSO
      • Azure AD SAML
      • Okta OIDC
      • Github OIDC
      • Google Workspace SSO
      • Add Members From SSO
  • Compliance
    • Concepts
      • Overview
  • API security posture
    • Concepts
      • Overview
  • SIEM Integration
    • Splunk
  • Alerts
    • Slack Webhook
    • Microsoft Teams Webhook
    • Setup alerts for Akto test run results
  • Pricing
    • Pricing Plans
    • How To
      • Upgrade Your Plan
      • Downgrade Your Plan
      • Sync Usage Data
  • API reference
    • API reference
  • Components
    • Dashboard
    • Testing module
    • Traffic mirroring module
    • Runtime analyzer
    • Context analyzer
    • Puppeteer server
    • Other OSS
    • robots.txt
  • Troubleshooting
    • How to get logs
    • How to disable logging
    • How to update helm deployments
  • Stay Updated on New Releases
  • Support
Powered by GitBook
On this page
  • Syntax
  • Parent Operators
  • Data Operators
  • belongs_to_collections
  • contains_either
  • contains_all
  • regex
  • eq
  • gt
  • gte
  • lt
  • lte
  • not_contains
  • not_contains_either
  • contains_jwt
  • Collection Operators
  • for_one
  • Body Operators
  • length
  • Extract Operators
  • extract
  • extractMultiple
  • Combining conditions using Boolean Operators
  • and
  • or

Was this helpful?

  1. Test Editor
  2. Concepts
  3. Test YAML Syntax (Detailed)

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:

Example of API Selection filter
# THIS IS API SELECTION FILTER
api_selection_filters:
  response_code:
    gte: 200
    lt: 300
  url:
    belongs_to_collections:
      - payment
      - checkout
      - juiceshop.akto.io
    contains_either:
      - login
      - signin
      - sign-in
      - log-in
  request_payload:
    for_one:
      key: 
        contains_either:
          - password
          - pwd
          - pass
          - passwd
  request_headers:
    for_one:
      key:
        contains_either: cookie
        extract: header_key

Syntax

  1. Parent Operators

  2. Data Operators

  3. Collection Operators

  4. 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:

Parent Operator
Description

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:

Data Operator
Expected Arguments
Description

belongs_to_collections

List

Checks whether the parent property belongs to one of the specified collections in the list. The API must be part of at least one of the collections specified to satisfy this condition.

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

belongs_to_collections

Checks whether the parent property belongs to one of the specified collections in the list. The API must be part of at least one of the collections specified to satisfy this condition.

Example 1

Example of belongs_to_collections
url:
  belongs_to_collections:
    - payment
    - checkout

# APIs that belong to either the payment or checkout collection would match the above condition.
# Match Example - An API categorized as part of the payment collection
# Invalid Example - An API that belongs only to the auth collection

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 of contains_either
url:
	contains_either: login
# Endpoints that contain login substring would match the above condition.
# Match Example - https://xyz.com/user/login
# Invalid Example - https://xyz.com/user/register

Example 2

Example of contains_either
url:
	contains_either:
			- https
			- login
# Endpoints that contain either https or login substring would match the above condition.
# Match Examples - https://xyz.com/user/login | https://xyz.com/user/register
# Invalid Example - http://xyz.com/user/data

👉🏻 In simple language: The above yaml syntax is filtering APIs with url containing the keywords ‘https’ or ‘login’

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 1
url:
	contains_all: login
# Endpoints that contain login substring would match the above condition.
# Match Example - https://xyz.com/user/login 
# Invalid Example - https://xyz.com/user/register

Example 2

Example for contains_all
url:
	contains_all:
			- https
			- login
# Endpoints that contain both https and login substring would match the above condition.
# Match Example - https://xyz.com/user/login 
# Invalid Example - http://xyz.com/user/login | https://xyz.com/user/register

👉🏻 In simple language: The above yaml syntax is filtering APIs with url containing the keywords ‘https’ and ‘login’

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

Example for regex
request_payload:
	contains_either: .*user*.
# If any part of request payload matches the above regex, it would be considered a match.
# Match Example - {”id”: 123, “data”:{”userName”: “abc”}} - userName is a valid match for above regex
# Invalid Example - {”id”: 123, “data”:{”name”: “abc”}} - no part of the request payload matches the above regex

eq

Checks whether the parent property is equal to the specified input.

Example 1

Example for eq
method:
	eq: POST
# All the Post Endpoints will match the above condition.
# Match Example - POST https://xyz.com/getById
# Invalid Example - GET https://xyz.com/getById

gt

Checks whether the parent property is greater than the specified input.

Example 1

Example for gt
response_code:
	gt: 204
# Endpoints with response greater than 204 will match the above condition.
# Match Example - Response codes like 205, 302
# Invalid Example - Response codes like 200, 201

gte

Checks whether the parent property is greater than or equal to the specified input.

Example 1

Example for gte
response_code:
	gte: 204
# Endpoints with response greater than or equal to 204 will match the above condition.
# Match Example - Response codes like 204, 302
# Invalid Example - Response codes like 200, 201

lt

Checks whether the parent property is lesser than the specified input.

Example 1

Example for lt
response_code:
	lt: 204
# Endpoints with response less than 204 will match the above condition.
# Match Example - Response codes like 200, 201
# Invalid Example - Response codes like 204, 205

lte

Checks whether the parent property is lesser than or equal to the specified input.

Example 1

response_code:
	lte: 204
# Endpoints with response less than or equal to 204 will match the above condition.
# Match Example - Response codes like 200, 204
# Invalid Example - Response codes like 205, 302

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

Example of not_contains
response_payload:
	not_contains: 
		- "normal_user"
		- "new"
# Response Payloads not containing strings ("normal_user", "new") will match the above condition.

Match Example for above

{"id": 100, "userdata": {"name": "xyz", "status": "admin", "identifier": "old"}}

Invalid Example for above

1. {"id": 100, "userdata": {"name": "xyz", "status": "normal_user", "identifier": "old"}}
2. {"id": 100, "userdata": {"name": "xyz", "status": "admin", "identifier": "new"}}
3. {"id": 100, "userdata": {"name": "xyz", "status": "normal_user", "identifier": "new"}}

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

Example of not_contains_either
response_payload:
	not_contains_either: 
		- "normal_user"
		- "new"
# Response Payloads which does not contain either ("normal_user") or ("new") will match the above condition.


# Match Example - 
1. {"id": 100, "userdata": {"name": "xyz", "status": "admin",
	    "identifier": "old"}}
2. {"id": 100, "userdata": {"name": "xyz", "status": "normal_user",
	    "identifier": "old"}}
3. {"id": 100, "userdata": {"name": "xyz", "status": "admin",
	    "identifier": "new"}}
# Invalid Example - 
1. {"id": 100, "userdata": {"name": "xyz", "status": "normal_user",
	    "identifier": "new"}}

contains_jwt

Checks whether the parent property contains/not contains a JWT token.

Example 1

Example of contains_jwt
request_headers:
	for_one:
		value:
			contains_jwt: true 

# Request Headers which contain jwt token will match the above condition.
# Match Example - 
	1. Headers - 
			Content-Type: application/json
			Authorization: <Bearer-Token>
# Invalid Example - 
	1. Headers -
			Content-Type: application/json
			Authorization: 23sdf234r3aaa

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

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 -

Example of for_one
api_selection_filters:
	request_payload:
		for_one:
			key:
				contains_either: name

# ”for_one” here specified that the condition is applied on key. 
# Data operand 'contains_either' checks whether any key in the request payload contains string (”name”)

👉🏻 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 -

Example of for_one
api_selection_filters:
	request_payload:
		for_one:
			key:
				eq: status
			value:
				regex: .*admin.*
# ”for_one” here specified that the condition is applied on both key and value. 
# Data operand 'eq' checks whether any key in the request payload is exactly equalt to (”status”).
# Data operand 'regex' checks whether any value in the status key matches the provided regex.

👉🏻 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

  1. {”id”: 123, ”status”: “admin”, “createdAt”: 1688364964}

  2. {”status”: “administrator”, “active”: true}

  3. {”userInfo”: {”name”: “testUser”, “status”: “admin”}, “lastLoginTs”: 1688364964}

Invalid Examples

  1. {”id”: 123, “createdAt”: 1688364964}

  2. {”id”: 123, ”status”: “normal”, “createdAt”: 1688364964}

  3. {”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 operator is used for applying conditions on the request/response payload length. Let’s explore this more through the below example

Examples of length
#Example 1
request_payload:
	length:
		gt: 0

# Here we want to apply a condition, where api's should have a non-empty request payload.
# We use length operator, and combine it with data operator(gt), where we specify length to be greater than 0
 
#Example 2
response_payload:
	length:
		gte: 10

# Here we want to apply a condition, where api's should have a non-empty response payload.
# We use length operator, and combine it with data operator(gt), where we specify length to be greater than equal to 10 

Extract Operators

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 -

Example of extract
#Example 1
url:
  contains_either: https
  extract: urlVar

# Here we have defined an extract operator, which will copy the complete url into a new variable named urlVar, in case the contains_either operand satisfies the condition

#Example 2
method:
  extract: methodVar
  

# Here we have defined an extract operator, which will copy the http method values into a new variable named methodVar

We can also extract an individual key/value inside the parent entities like (request_payload, response_payload, request_headers, response_headers, query_params).

Example 1:
Request Payload** {”id”: 123, “data”:{”Username”: “abc”, "userStatus": "admin"}}
Example of extract
#request_payload:
  for_one;
    key:
      contains_either: status
      extract: keyVar

# Here we have defined an extract operator, which will copy the key("userStatus") into a new variable named keyVar, since ("userStatus") satisfies the contains_either operand. In simple words - keyVar = userStatus
Example 2
Request Payload** {”id”: 123, “data”:{”Username”: “abc”, "userStatus": "admin"}}
Example of extract
request_payload:
  for_one;
    key:
      contains_either: status
      extract: keyVar
    value:
      extract: valVar

# Here we have defined an extract operator, which will copy the key("userStatus") into a new variable named keyVar, since ("userStatus") satisfies the contains_either operand.
# We also defined a second extract operator inside value operand, which will copy the value associated with the matching key("userStatus") into the variable, i.e. ("admin").
# In other words - keyVar = userStatus, valVar = admin  

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 -

#Here we append /debug/vars to the URL to check if debug variables are exposed. 

api_selection_filters:
  url:
    extract: urlVar

execute:
  type: single
  requests:
    - req:
      - modify_url: ${urlVar}/debug/vars

validate:
  ...

extractMultiple

#Example of extractMultiple

api_selection_filters:
  request_payload:
    for_one:
      key:
        regex: .*
        extractMultiple: payloadKeys # Here we extract list of all keys in the payload

execute:
  type: single
  requests:
  - req:
    - add_body_param:
      ${payloadKeys}: '\0' #Here we replace all values by null terminated string

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

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

Example of and
#Test Description - 
# condition 1: Consider only post endpoints.
# condition 2: Status code must be between 200-205(including both)
# condition 3: Request Headers should contain a header named origin.
# All conditions are mandatory.

api_selection_filters:
  and:
    - method:
        eq: POST
    - response_code:
        and:
          - gte: 200
          - lte: 205
    - request_headers:
        for_one:
          key:
            eq: origin 

Since applying and operator is default behaviour, we don’t need to explicitly write and operator. See below

Example of and
# removed 'AND' as it is default behavior

api_selection_filters:
  method:
    eq: POST
  response_code:
    gte: 200
    lte: 205
  request_headers:
    for_one:
      key:
        eq: origin

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

Example of or
# Test Description 
# condition 1: Status code must be equal to either 200 or 302
# condition 2: Request Headers should contain a header named origin.
# An endpoint should either satisfy either of the above two conditions

api_selection_filters:
  or:
    - response_code:
        or:
          - eq: 200
          - eq: 302
    - request_headers:
        for_one:
          key:
            eq: origin 
PreviousAuthNextExecute

Last updated 2 months ago

Was this helpful?

This is similar to , 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

extract