Test YAML

YAML tests are a powerful tool to identify security vulnerabilities in your APIs. Using Akto YAML format, you can define tests with metadata, API filters, execution details, and validation checks. These tests can be customized to target specific vulnerabilities and run against your APIs to ensure they are secure. Akto Test Editor provides a user-friendly interface to create and edit these tests, making it easy to integrate them into your security workflow.

What is YAML Test?

A YAML test in Akto is a configuration file written in YAML (YAML Ain't Markup Language) that defines a set of instructions for testing APIs to find security vulnerabilities. It includes details about the test, how to select which APIs to test, how to execute the test, and how to validate the results. The test is executed against APIs, and the results are used to identify any issues with the API's security.

You can create and run tests to detect vulnerabilities in your APIs. Tests are written in Akto's YAML format, which includes sections for metadata, selection filters, execution details, and validation checks.

6 Blocks of Test Editor

Block 1: ID

Name	Desciption
id	The ID field serves as a unique, descriptive identifier for a particular test YAML file.

Block 2: Info

Name	Desciption
info	Name, Description, Details, Impact, Category, SubCategory, Severity, Tags, Reference

Block 3: API Selection Filters

Name	Desciption
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.
Parent Operators	response_code, method, url, request_payload, response_payload, request_headers, response_headers, query_param
Data Operators	regex, eq, neq, gt, gte, lt, lte not_contains, not_contains_either, contains_jwt, contains_all, contains_either
Collection Operators	for_one
Combining Conditions using Boolean Operators	or, and

Block 4: Execute

Name	Desciption
execute	add_body_param, modify_body_param, delete_body_param, add_query_param, modify_query_param, delete_query_param modify_url, modify_method, replace_body, add_header, modify_header, delete_header, remove_auth_header, follow_redirect
Combining Conditions using Boolean Operators	or, and

Block 5: Auth [Optional block]

Name	Desciption
auth	This section describes the conditions that serve as validation criteria for determining whether a particular endpoint is vulnerable to a given test.

Block 6: Validate

Name	Description
validate	This section describes the conditions that serve as validation criteria for determining whether a particular endpoint is vulnerable to a given test.
Parent Operators	response_code, method, url, request_payload, response_payload, request_headers, response_headers, query_param
Data Operators	regex, eq, neq, gt, gte, lt, lte not_contains, not_contains_either, contains_jwt, contains_all, contains_either
Collection Operators	for_one
Combining Conditions using Boolean Operators	or, and

Learn with Example

Example API

Example API

POST https://xyz.abc.com/api/v1/users?userId=500&creationFlow=true
Request Payload

{
  "userData": {
      "name": "user1"
      "status": "normalUser"
      "age": 20
  },
  "profileData": {
      "isActive": true,
      "createdAt": 1254345343
  }
}

Response Payload
{
  "id": 500,
  "created": true,
  "username": "user1", 
}

Request Headers

Content-Type: application/json
Authorization: <Bearer-Token>
Host: https://xyz.abc.com

Response Headers

access-control-allow-origin: "*"
date: "Wed, 05 Jul 2023 09:53:32 GMT"
content-length: "14871"
server: "uvicorn"
access-control-allow-credentials: "true"
content-type: "application/json"

Let’s have a comprehensive look at all the possible operators in 1 single yaml.

Example Yaml with all possible operators

YAML with all operators

id: Vulnerable_Test
info:
  name: ""                           # specifies the name or title of the test
  description: ""                    # provides a detailed explanation of the test. describes objectives, methodologies, and scope of the test
  details: ""                        # allows inclusion of additional information and context about the test
  impact: ""                         # describes the potential risks or consequences associated with the identified vulnerabilities
  category:                          # classifies the test into a specific category or domain
    name: ""                          
    shortName: ""
    displayName: ""
  subCategory: ""                    # this key also specifies the name or title of the test. should always contain the same value as id key
  severity: ""                       # indicates the severity level assigned to the identified vulnerabilities
  tags: ""                           # provides descriptive labels or keywords associated with the test
  references: ""                     # contains a list of relevant resources, documentation, or external links related to the test
auth:
  authenticated: true               # makes sure that only authentiated api's get considered for a test.
api_selection_filters:  
  response_code:                    # Filters API calls that return a response code between 200 and 300 (inclusive).      
    gte: 200                        
    lte: 300 
  url:       
    contains_all:                   # Filters API calls that contain the word "user" in the URL.
      - user
    extract: urlVar                 # extracts the url value into a variable named urlVar
  method:    
    contains_either:                # Filters API calls that use either the POST, PATCH, or PUT HTTP methods
      - POST
      - PATCH
      - PUT
  request_payload:                  # Filters API calls whose request payload contains a key-value pair where the key matches the regex ".*age*." and the value is between 15 and 40 (inclusive)
    for_one:      
      key:
        regex: .*age*. 
        extract: ageVar             # extracts the matching key value into a variable named ageVar
      value:
        gt: 15  
        lt: 40  
  response_payload:                 # Filters API calls whose response payload does not contain the string "user2."
    not_contains: user2
  request_headers:                  # Filters API calls whose request header contains a whose value has a JWT token in it.
    for_one:
      key:
        contains_jwt: true          
  response_headers:                 # Filters API calls whose response header contains a key that exactly matches "server" and a value that matches the regex "nginx/1.8.0."
    for_one:
      key:
        eq: server
      value:
        regex: nginx/1.8.0
execute: 
  type: single
  requests:
    - req:
      - modify_url: https://xyz.abc.com/api/v2/users    # Changes the URL of the API call to "[https://xyz.abc.com/api/v2/users."](https://xyz.abc.com/api/v2/users.%22)
      - modify_method: PATCH        # Changes the HTTP method of the API call to PATCH.
      - add_body_param:             # Adds a key-value pair "k1: v1" to the request body.
          k1: v1
      - modify_body_param:          # Changes the value of the "status" key in the request body to "admin."
          status: admin
      - delete_body_param: age      # Deletes the "age" key-value pair from the request body.
      - add_header:                 # Adds a "h1: v2" key-value pair to the request header.
          h1: v2
      - modify_header:              # Changes the value of the "host" key in the request header to "[https://xyz.evil.com](https://xyz.evil.com/)."
          host: https://xyz.evil.com
      - delete_header: authorization # Deletes the "authorization" key-value pair from the request header.
      - add_query_param:            # Adds a "q1: v3" key-value pair to the query string.
          q1: v3
      - modify_query_param:         # Changes the value of the "userId" key in the query string to "501."
          userId: 501
      - delete_query_param: creationFlow # Deletes the "creationFlow" key-value pair from the query string.
      - replace_body: '{"user": "newUser", "status": "admin"}'
      - remove_auth_header: true   # Replaces the entire request body with the JSON object 
      - follow_redirect: true      # Follows any HTTP redirects returned by the API call.
validate:
  response_code:                   # Validates that the response code of the API call is 201.
    eq: 201
  response_payload:                # Validates that the response payload is not empty and contains atleast one key named "success". Also it checks whether test response payload and sample response payload content are not similar(difference should be higher than 50%)
    length:
      gt: 0
    percentage_match:
      lt: 50
    contains_either:
      for_one:
        key: success

Explanation of the above yaml

Info

The Info section contains metadata about the test:

• Name: The name or title of the test.

• Description: A detailed explanation of the test, including objectives, methodologies, and scope.

• Details: Additional context about the test.

• Impact: The potential risks or consequences associated with the identified vulnerabilities.

• Category: The category or domain the test falls into.

• SubCategory: Further categorization of the test.

• Severity: The severity level assigned to the identified vulnerabilities.

• Tags: Descriptive labels or keywords associated with the test.

• Reference: A list of relevant resources, documentation, or external links related to the test.

API Selection Filters

This section contains a set of filters that can be used to select specific API calls based on various criteria. The filters include:

• response_code: Filters API calls that return a response code between 200 and 300 (inclusive).

• url: Filters API calls that contain the word "user" in the URL.

• method: Filters API calls that use either the POST, PATCH, or PUT HTTP methods.

• request_payload: Filters API calls whose request payload contains a key-value pair where the key matches the regex ".age." and the value is between 15 and 40 (inclusive).

• response_payload: Filters API calls whose response payload does not contain the string "user2."

• request_headers: Filters API calls whose request header contains a key that matches "contains_jwt."

• response_headers: Filters API calls whose response header contains a key that exactly matches "server" and a value that matches the regex "nginx/1.8.0."

Execute

This section contains a set of operations that can be performed on API calls that match the selection criteria specified above. The operations include:

• modify_url: Changes the URL of the API call to "https://xyz.abc.com/api/v2/users."

• modify_method: Changes the HTTP method of the API call to PATCH.

• add_body_param: Adds a key-value pair "k1: v1" to the request body.

• modify_body_param: Changes the value of the "status" key in the request body to "admin."

• delete_body_param: Deletes the "age" key-value pair from the request body.

• add_header: Adds a "h1: v2" key-value pair to the request header.

• modify_header: Changes the value of the "host" key in the request header to "https://xyz.evil.com."

• delete_header: Deletes the "authorization" key-value pair from the request header.

• add_query_param: Adds a "q1: v3" key-value pair to the query string.

• modify_query_param: Changes the value of the "userId" key in the query string to "501."

• delete_query_param: Deletes the "creationFlow" key-value pair from the query string.

• replace_body: Replaces the entire request body with the JSON object {"user": "newUser", "status": "admin"}.

• remove_auth_header: Removes the "authorization" header from the request.

• follow_redirect: Follows any HTTP redirects returned by the API call.

Validate

This section contains a set of validation criteria that can be used to validate the response of the API call after it has been modified by the operations specified in the "Execute" section. The validation criteria include:

• response_code: Validates that the response code of the API call is 201.

• response_payload: Validates that the response payload is not empty and contains either a key "success".