Probe YAML

YAML probes are a powerful tool to identify security vulnerabilities in your AI agents, MCP endpoints, and LLM components. Using Akto YAML format, you can define probes with metadata, component filters, execution details, and validation checks. These probes can be customized to target agentic-specific vulnerabilities including prompt injections, tool abuse, and permission escalation. Akto Probe Library provides a user-friendly interface to create and edit these probes, making it easy to integrate them into your agentic security workflow.

What is YAML Probe?

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

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

6 Blocks of Probe Editor

Block 1: ID

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

Block 2: Info

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

Block 3: Agentic Component 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 probe.

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 probe.
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 Agentic Component

Example Agentic Component

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 probe
  description: ""                    # provides a detailed explanation of the probe. describes objectives, methodologies, and scope of the probe
  details: ""                        # allows inclusion of additional information and context about the probe
  impact: ""                         # describes the potential risks or consequences associated with the identified vulnerabilities
  category:                          # classifies the probe into a specific category or domain
    name: ""                          
    shortName: ""
    displayName: ""
  subCategory: ""                    # this key also specifies the name or title of the probe. 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 probe
  references: ""                     # contains a list of relevant resources, documentation, or external links related to the probe
auth:
  authenticated: true               # makes sure that only authentiated api's get considered for a probe.
api_selection_filters:  
  response_code:                    # Filters agentic component calls that return a response code between 200 and 300 (inclusive).      
    gte: 200                        
    lte: 300 
  url:
    contains_all:                   # Filters agentic component 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 agentic component calls that use either the POST, PATCH, or PUT HTTP methods
      - POST
      - PATCH
      - PUT
  request_payload:                  # Filters agentic component 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 agentic component calls whose response payload does not contain the string "user2."
    not_contains: user2
  request_headers:                  # Filters agentic component calls whose request header contains a whose value has a JWT token in it.
    for_one:
      key:
        contains_jwt: true          
  response_headers:                 # Filters agentic component 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 agentic component 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 agentic component 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 agentic component call.
validate:
  response_code:                   # Validates that the response code of the agentic component 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 probe 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 probe:

• Name: The name or title of the probe.

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

• Details: Additional context about the probe.

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

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

• SubCategory: Further categorization of the probe.

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

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

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

Agentic Component Selection Filters

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

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

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

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

• request_payload: Filters agentic component 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 agentic component calls whose response payload does not contain the string "user2."

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

• response_headers: Filters agentic component 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 agentic component calls that match the selection criteria specified above. The operations include:

• modify_url: Changes the URL of the agentic component 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 agentic component 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 agentic component call is 201.

• response_payload: Validates that the response payload is not empty and contains either a key "success". Also it checks whether probe response payload and sample response payload content are not similar(difference should be higher than 50%)