--- title: "Plugin Functions and Operators" slug: "functions-operators-custom-plugin" description: "Understand the different mutation and assertion functions supported in custom plugins, and explore a comprehensive list of attribute operators for Python and YAML plugins. This document is essential for writing precise and effective API security tests." tags: ["API Security Testing", "AST Plugins", "Custom Plugins", "Plugin Configuration", "Plugin Operators"] updated: 2025-04-30T05:49:31Z published: 2025-04-30T05:49:31Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Plugin Functions and Operators Custom plugins support the mutation and assertion functions and a wide range of operators within each of them. These functions allow you to define how Traceable should inspect the APIs for vulnerabilities. The attributes in these functions refer to the specific elements in the request or response, such as headers, body, and query parameters, while the operators specify the comparison type to perform. This document highlights details about attributes and operators, along with descriptions and examples of how to use them in the mutation and assertion functions. ## Attributes and their Convention Attributes are the elements in the API requests and responses. While writing custom plugins, you must refer to these attributes as part of the mutation and assertion functions. As mentioned in the [Working of a Plugin](/docs/plugins-introduction#working-of-a-plugin), Traceable creates a clone of the original request to create a mutated one. The attributes in these requests are represented in the following manner: - The attributes prefixed with `original.` correspond to the traffic being received or generated in the original request. - The attributes prefixed with `mutated.` correspond to the modified request For example, the authorization header is represented as `original.header.request.header.authorization` in the original request and `mutated.header.request.header.authorization` in the mutated request. The following is the common list of attributes that you can use while writing a custom plugin: ##### **Common List of Attributes** ##### Request URL - (original/mutated).http.request.method: "POST" - (original/mutated).http.request.url: "http://example.com?arg=val1&arg2=val2" - (original/mutated).http.request.url: "HTTP://example.com/order/{orderId}?arg=val1&arg2=val2" - (original/mutated).http.request.path.param.2: "1234" - (original/mutated).http.request.query.param.limit: 100 - (original/mutated).net.host.scheme: https - (original/mutated).net.host.name: "example.com" - (original/mutated).net.host.port: 443 - (original/mutated).http.request.header.content-type: "application/json" ##### Request Header - (original/mutated).http.request.header.*: - (original/mutated).http.request.header.user-agent: "curl/1.1" - (original/mutated).http.request.header.accept: "application/json" - (original/mutated).http.request.header.content-type: "application/json" ##### Request Cookie - (original/mutated).http.request.cookie.PHPSESSID: "064d213baaef028e724b06042a69561dceb256f3119721b846234d72dcc35134" ##### Request Body - (original/mutated).http.request.body: '{"username": "user1", "password": "p4s1d135DDg4"}' - (original/mutated).http.request.body.username: "user1" - (original/mutated).http.request.body.password: "user1" - (original/mutated).http.response.body: '{"token": "jshdlahflafnfbdfbkfnalfja", "msg": "Success"}' - (original/mutated).http.response.body.token: "jshdlahflafnfbdfbkfnalfja" - (original/mutated).http.response.body.msg: "Success" ##### Response - (original/mutated).http.response.code' - (original/mutated).http.response.duration - (original/mutated).http.response.header.*: - (original/mutated).http.response.cookie.PHPSESSID: "064d213baaef028e724b06042a69561dceb256f3119721b846234d72dcc35134" --- ## Attribute Operators (Python Plugins only) In Python-based custom plugins, attribute operators provide a way to interact with your API request and response. Using these operators, you can fetch, modify, or add attributes according to your requirements. Whether you are retrieving a value for comparison or injecting a mutated field, these operators act as the building block for creating an accurate and adaptive plugin logic. The following are the supported operators that you can use while writing a Custom Python Plugin: #### Add Attributes from Another List ##### Description This operator adds attributes from another attribute list. It adds new values without modifying the existing ones. ##### Syntax ```python attributes.add_attributes(attributeList, prefix: str = "") ``` #### Set Attributes from Another List ##### Description This operator sets attributes from another attribute list. It modifies any existing values or creates them if they don’t exist. ##### Syntax ```python attributes.set_attributes(attributeList, prefix: str = "") ``` #### Get One Value ##### Description This operator fetches one value from the attribute. ##### Syntax ```python attributes.get_one(key, , default: any = None, use_prefix: bool = False, regex: bool = False) ``` #### Get Values ##### Description This operator fetches values from the attribute. ##### Syntax ```python attributes.get(key, : str, default: any = None, use_prefix: bool = False, regex: bool = False) ``` #### Get One Attribute ##### Description This operator fetches one attribute. ##### Syntax ```python attributes.get_one_attr(key, , default: any = None, use_prefix: bool = False, regex: bool = False) ``` #### Get Original Value ##### Description This operator fetches the original value from the attribute. ##### Syntax ```python attributes.get_original(key, , default: any = None, use_prefix: bool = False, regex: bool = False) ``` #### Get Attribute List ##### Description This operator fetches the attribute list iterator. ##### Syntax ```python attributes.items(self) ``` #### Add Attributes ##### Description This operator adds attributes to the list. If *original_and_mutated* is *True*, both original and mutated keys are added; otherwise, only one copy without a prefix is added. ##### Syntax ```python attributes.add(key, : str, value: any, original_and_mutated: bool = False, is_dirty: bool = False, force: bool = False) ``` #### Modify Attributes ##### Description This operator updates all attributes with the specified key. If first_only is True, only the first attribute is updated. If the key is not found, the instruction is ignored. ##### Syntax ```python attributes.modify(key, : str, value: any, first_only: bool = False, regex: bool = False) ``` #### Set Attributes ##### Description This operator sets attributes to the list. If *original_and_mutated* is *True*, both original and mutated keys are modified or are created if they don’t exist; otherwise, only one copy without a prefix is modified or created. ##### Syntax ```python attributes.set(key, : str, value: any, original_and_mutated: bool = False, regex: bool = False, is_dirty: bool = False, force: bool = True) ``` #### Expand Attributes ##### Description This operator expands attributes to fetch values of the sub-attributes. ##### Syntax ```python attributes.expand_attributes(self, data, regex: bool = False, user_prefix: bool = False) ``` #### Expand Templated Variables ##### Description This operator expands templated variables to fetch the attribute value. For example, if the input is *mutated.${authorization_header}* and the *authorization_header* is *request.header.jwt*, then the output is *mutated.request.header.jwt*. ##### Syntax ```python attributes.expand(self, data, regex: bool = False, use_prefix: bool = False) ``` #### Delete Attributes ##### Description This operator deletes attributes from the attribute list. ##### Syntax ```python attributes.delete(key, value, regex: bool = False) ``` --- ## Mutation Function The mutation function adds, modifies, and deletes specific parameters within API requests. While Traceable specifies this function by default in test plugins, you can define it according to your requirements in custom plugins. ### Mutation Parameters and Syntax The parameters within a custom plugin mutation function vary depending on the plugin type you are configuring. To learn about these parameters, click the tabs below according to your requirements. YAMLPython A mutation function in a YAML-based plugin contains the following parameters: | Parameter | Description | | --- | --- | | **action (String)** | The type of operation that Traceable should perform. For more information, see Mutation Operators. | | **description** | A description of what the mutation does. | | **key (String)** | The query parameter on which Traceable should perform the operation. | | **kind** | The data type of the value being specified below. | | **value** | The value you wish to mutate on the above key. | After combining the parameters within a plugin, the syntax is: ```python - action: MUTATION_OPERATOR  description: "Mutate the value to the specified key"  key: "${http.query.param.id}"  field:    kind: STRING    value: "50" ``` A mutation function in a Python-based plugin contains the following parameters: | Parameters | Description | | --- | --- | | **operator (String)** | The type of operation that Traceable should perform. For more information, see Mutation Operators. | | **key (String)** | The key or attribute that Traceable should mutate. The attributes are updated in Traceable's mutated request in the Cloning step. | | **value (Any)** | The new value to replace the existing value. This parameter can contain any value, for example, *none* or an empty string (““). This value is stored in the mutated request. | After combining the parameters within a plugin, the syntax is: ```python Mutation.create(operator: str, key: str, value: any = ””) ``` ### Mutation Operators The following are the supported operators that you can use along with the mutation function while writing a custom plugin: > [!NOTE] > Note > > While the operators remain the same for both YAML and Python-based custom plugins, the syntax may vary as shown in the examples of the respective operators. #### MUTATION_ADD ##### **Operator Tag** `MUTATION_ADD` ##### **Description** This operator adds a new key attribute with the specified value. If the key attribute already exists, it duplicates it. ##### **Example** The below example suffixes the URL with two query params *?id=100& id=50* to check parameter pollution. **YAML** ```yaml - action: MUTATION_ADD  description: "Add a query parameter to the HTTP request"  key: "${mutated.http.query.param.id}"  field:    kind: STRING    value: "50" - action: MUTATION_ADD  description: "Add a query parameter to the HTTP request"  key: "${mutated.http.query.param.id}"  field:    kind: STRING    value: "100" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_ADD", "${mutated.http.query.param.id}", "100")  Mutation.create("MUTATION_ADD", "${mutated.http.query.param.id}", "50") ] ``` #### MUTATION_DELETE ##### **Operator Tag** `MUTATION_DELETE` ##### **Description** This operator deletes an existing key attribute. ##### **Example** The below example removes the query param *id* from the API request. **YAML** ```yaml - action: MUTATION_DELETE  description: "Delete the HTTP query parameter"  key: "${mutated.http.query.param.id}"  field:    kind: STRING    value: "" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_DELETE", "${mutated.http.query.param.id}", "") ] ``` #### MUTATION_MODIFY ##### Operator Tag `MUTATION_MODIFY` ##### **Description** This operator modifies a key attribute if it exists; otherwise, it does nothing. ##### **Example** The below example updates the query param *id* with the value *100* if it exists; otherwise, it ignores the instruction. **YAML** ```yaml - action: MUTATION_MODIFY  description: "Modify the HTTP query parameter"  key: "${mutated.http.query.param.id}"  field:    kind: STRING    value: "100" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_MODIFY", "${mutated.http.query.param.id}", "100") ] ``` #### MUTATION_SET ##### Operator Tag `MUTATION_SET` ##### **Description** This operator sets the value of an existing key attribute or adds it if it does not exist. ##### **Example** The below example sets the query param *id* to *100* if it exists; otherwise, it creates a query param *id* with the same value. **YAML** ```yaml - action: MUTATION_SET  description: "Set the HTTP query parameter"  key: "${mutated.http.query.param.id}"  field:    kind: STRING    value: "100" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_SET", "${mutated.http.query.param.id}", "100") ] ``` #### MUTATION_REGEX_DELETE ##### Operator Tag `MUTATION_REGEX_DELETE` ##### **Description** This operator deletes all attributes that match the key/regular expression with the value. ##### **Example** The below example deletes all query params ending with the string “*amount*”. **YAML** ```yaml - action: MUTATION_REGEX_DELETE  description: "Delete HTTP query parameters matching the regex pattern"  key: "${mutated\.http\.query\.param.*amount}"  field:    kind: STRING    value: "" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_REGEX_DELETE", "${mutated\.http\.query\.param.*amount}", "") ] ``` #### MUTATION_REGEX_MODIFY ##### Operator Tag `MUTATION_REGEX_MODIFY` ##### **Description** This operator modifies all attributes that match the key/regular expression with the value. ##### **Example** The below example modifies the query params ending with the string “*amount*” with the value *100* if it exists; otherwise, it ignores the instruction. **YAML** ```yaml - action: MUTATION_REGEX_MODIFY  description: "Modify HTTP query parameters matching the regex pattern"  key: "${mutated\.http\.query\.param.*amount}"  field:    kind: STRING    value: "100" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_REGEX_MODIFY", "r${mutated\.http\.query\.param.*amount}", "100") ] ``` #### MUTATION_REGEX_SET ##### Operator Tag `MUTATION_REGEX_SET` ##### **Description** This operator sets all attributes that match the key/regular expression with the value. ##### **Example** The below example sets the query params ending with the string “*amount*” with the value *100* if it exists; otherwise, it ignores the instruction. **YAML** ```yaml - action: MUTATION_REGEX_SET  description: "Set HTTP query parameters matching the regex pattern"  key: "${mutated\.http\.query\.param.*amount}"  field:    kind: STRING    value: "100" ``` **Python** ```python test.mutations = [  Mutation.create("MUTATION_REGEX_SET", "r${mutated\.http\.query\.param.*amount}", "100") ] ``` --- ## Assertion Function The **Assertion Function** in custom plugins is used to evaluate API responses for vulnerabilities by comparing specific values in the response to expected outcomes, with various operators available to define the conditions for a successful match. The following sections explain the various subfunctions and operators. ### Assertion Types Assertion functions can be of two types: | Assertion Type | Description | | --- | --- | | **IMMEDIATE** | These assertions execute immediately after Traceable encounters them in the plugin definition. If the condition fails, Traceable stops further execution based on the logic. For example, verify whether the response code of the mutated request is *200*. | | **LOGICAL** | These assertions evaluate conditions at the end of the scan or execution rather than immediately. This allows for the aggregation of multiple results before making a final decision. For example, verify if at least one of the multiple mutated requests can access sensitive data. For more information on this function, see the sections below. | ### Assertion Parameters and Syntax The parameters within a custom plugin assertion function vary depending on the plugin type you are configuring. To know about these parameters, click the below tabs according to your requirements. YAMLPython An assertion function in a YAML-based plugin contains the following parameters: | Parameters | Description | | --- | --- | | **lhs (String)** | The mutated value for comparison. | | **rhs (String)** | The original value for comparison. | | **operator (String)** | The match operator used for comparison. | | **key (String)** | Used for display purposes as part of visualization on the UI. It is not used for any processing. | | **description** | A description of what the assertion does. | | **assertionType** | The type of assertion Traceable should execute on the above parameters. | After combining the parameters within a plugin, the syntax is: ```python - lhs: "${mutated.request.param}"  rhs: "${original.request.param}"  operator: MATCH_OPERATOR_NAME  key: "http.request.cookie"  description: "Compares the lhs value compares to the rhs value based on the operator"  assertionType: IMMEDIATE/LOGICAL ``` An **Assertion Function** in a Python-based plugin contains the following parameters: | Parameters | Description | | --- | --- | | **key (String)** | Used for display purposes as part of visualization on the UI. It is not used for any processing. | | **operator (String)** | The match operator used for comparison. | | **mutated (String)** | The mutated value for comparison. | | **original (String)** | The original value for comparison. | | ****kwargs** (optional) | Additional parameters used to provide metadata for the assertion. These parameters can vary depending on the match operator used. | After combining the parameters within a plugin, the **Assertion Function syntax** is: ```python Assertion.create(key: str, operator: str, mutated: str, original: str, **kwargs) ``` A **Logical Assertion** function in a Python-based plugin contains the following parameters: | Parameters | Description | | --- | --- | | **operator (String)** | The operator for evaluation between assertion functions. | | **Assertion function** | The assertion functions for evaluation based on the above operator. | After combining the parameters within a plugin, the **Logical Assertion** **Function** **syntax** is: ```python Assertion.create_logical_assertion("LOGICAL_OPERATOR_AND/OR", [                    Assertion.create(key: str, operator: str, mutated: str, original: str, **kwargs),                    Assertion.create(key: str, operator: str, mutated: str, original: str, **kwargs)                ]) ``` ### Assertion Operators Assertion operators are divided based on the assertion types. While the assertion operators can be used individually, the logical assertion operators are used in combination with the assertion functions and operators to write a custom plugin. The following sections explain these operators along with an example. #### Logical Assertion Operators The following are the supported logical operators that you can use in combination with the assertion functions while writing a custom plugin: > [!NOTE] > Note > > While the operators remain the same for both YAML and Python-based custom plugins, the syntax may vary as shown in the examples of the respective operators. #### LOGICAL_OPERATOR_AND ##### Operator Tag `LOGICAL_OPERATOR_AND` ##### Description This operator returns VULN(True) if all the assertion functions within the assertion list are VULN(True). ##### Example The below example evaluates to *True* if both the: - Mutated response body matches the Original response body. - Mutated response code matches the Original response code. **YAML** ```yaml assertions:  - assertionType: LOGICAL    operator: LOGICAL_OPERATOR_AND    description: "The mutated response body and code should match the original"    assertions:      - lhs: "${http.response.body}"        rhs: "${original.http.response.body}"        operator: MATCH_OPERATOR_KEYS_EQUALS        key: "mutated.http.response.body"        description: "The mutated response body should match original"        assertionType: IMMEDIATE      - lhs: "${http.response.code}"        rhs: "${original.http.response.code}"        operator: MATCH_OPERATOR_EQUALS        key: "http.response.code"        description: "The mutated response code should match original"        assertionType: IMMEDIATE ``` **Python** ```python assertions_group = Assertion.create_logical_assertion("LOGICAL_OPERATOR_AND", [                    Assertion.create("http.response.body", "MATCH_OPERATOR_KEYS_EQUALS", "${mutated.http.response.body}", "${original.http.response.body}"),                    Assertion.create("http.response.code", "MATCH_OPERATOR_EQUALS", "${mutated.http.response.code}", "${original.http.response.code}"),                ]) ``` #### LOGICAL_OPERATOR_OR ##### Operator Tag `LOGICAL_OPERATOR_OR` ##### Description This operator returns VULN(True) if either of the assertion functions within the assertion list are VULN(True). ##### Example The below example evaluates to *True* if either the: - Mutated response body matches the Original response body - Mutated response code matches the Original response code. **YAML** ```yaml assertions:  - assertionType: LOGICAL    operator: LOGICAL_OPERATOR_OR    description: "The mutated response body or code should match the original"    assertions:      - lhs: "${mutated.http.response.body}"        rhs: "${original.http.response.body}"        operator: MATCH_OPERATOR_KEYS_EQUALS        key: "mutated.http.response.body"        description: "The mutated response body should match original"        assertionType: IMMEDIATE      - lhs: "${http.response.code}"        rhs: "${original.http.response.code}"        operator: MATCH_OPERATOR_EQUALS        key: "http.response.code"        description: "The mutated response code should match original"        assertionType: IMMEDIATE ``` **Python** ```python assertions_group = Assertion.create_logical_assertion("LOGICAL_OPERATOR_OR", [                    Assertion.create("http.response.body", "MATCH_OPERATOR_KEYS_EQUALS", "${mutated.http.response.body}", "${original.http.response.body}"),                    Assertion.create("http.response.code", "MATCH_OPERATOR_EQUALS", "${mutated.http.response.code}", "${original.http.response.code}"),                ]) ``` #### Assertion Operators The following are the supported operators that you can use along with the assertion function while writing a custom plugin: > [!NOTE] > Note > > While the operators remain the same for both YAML and Python-based custom plugins, the syntax may vary as shown in the examples of the respective operators. #### MATCH_OPERATOR_EQUALS ##### Operator Tag `MATCH_OPERATOR_EQUALS` ##### Description This operator checks whether the LHS/mutated value matches the RHS/original value. If it does, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the response code received from the mutated request matches the response code received from the original request. **YAML** ```yaml - lhs: "${mutated.http.response.code}"  rhs: "${original.http.response.code}"  operator: MATCH_OPERATOR_EQUALS  key: "http.response.code"  description: "Check if mutated HTTP response code equals the original HTTP response code"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.code", "MATCH_OPERATOR_EQUALS", "${mutated.http.response.code}", "${original.http.response.code}") ``` #### MATCH_OPERATOR_NOT_EQUALS ##### Operator Tag `MATCH_OPERATOR_NOT_EQUALS` ##### Description This operator checks whether the LHS/mutated value does not match the RHS/original value. If it does not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if *param1* received in the body of the response received for the mutated request does not match *param1* in the body of the response received from the original request. **YAML** ```yaml - lhs: "${mutated.http.response.body.param1}"  rhs: "${original.http.response.body.param1}"  operator: MATCH_OPERATOR_NOT_EQUALS  key: "http.response.body.param1"  description: "Check if mutated HTTP response body param1 does not equal the original HTTP response body param1"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body.param1", "MATCH_OPERATOR_NOT_EQUALS", "${mutated.http.response.body.param1}", "${original.http.response.body.param1}") ``` #### MATCH_OPERATOR_MATCHES_REGEX ##### Operator Tag `MATCH_OPERATOR_MATCHES_REGEX` ##### Description This operator checks whether the LHS/mutated value matches the regex. If it does, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the response code received for the mutated request matches the specified regular expression. **YAML** ```yaml - lhs: "${mutated.http.response.code}"  rhs: "^5\d\d"  operator: MATCH_OPERATOR_MATCHES_REGEX  key: "http.response.duration"  description: "Check if mutated HTTP response code matches the regex pattern for 5xx status codes"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.duration", "MATCH_OPERATOR_MATCHES_REGEX", "${mutated.http.response.code}", r"^5\d\d") ``` #### MATCH_OPERATOR_NOT_MATCHES_REGEX ##### Operator Tag `MATCH_OPERATOR_NOT_MATCHES_REGEX` ##### Description This operator checks whether the LHS/mutated value does not match the regex. If it does not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the response code received for the mutated request does not match the specified regular expression. **YAML** ```yaml - lhs: "${mutated.http.response.code}"  rhs: "^5\d\d"  operator: MATCH_OPERATOR_NOT_MATCHES_REGEX  key: "http.response.duration"  description: "Check if mutated HTTP response code matches the regex pattern for 5xx status codes"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.duration", "MATCH_OPERATOR_NOT_MATCHES_REGEX", "${mutated.http.response.code}", r"^4\d\d") ``` #### MATCH_OPERATOR_GREATER_THAN ##### Operator Tag `MATCH_OPERATOR_GREATER_THAN` ##### Description This operator checks whether the LHS/mutated value is greater than the RHS/original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the time taken to receive a response to the mutated request takes longer than *100 ms*. **YAML** ```yaml - lhs: "${mutated.http.response.duration}"  rhs: "100"  operator: MATCH_OPERATOR_GREATER_THAN  key: "http.response.duration"  description: "Check if mutated HTTP response duration is greater than 100ms"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.duration", "MATCH_OPERATOR_GREATER_THAN", "${mutated.http.response.duration}", "100") ``` #### MATCH_OPERATOR_GREATER_THAN_EQUALS ##### Operator Tag `MATCH_OPERATOR_GREATER_THAN_EQUALS` ##### Description This operator checks whether the LHS/mutated value is greater than or equal to the RHS/original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if *param1* in the body of the response received for the mutated request has a value greater than or equal to *100*. **YAML** ```yaml - lhs: "${mutated.http.response.body.param1}"  rhs: "100"  operator: MATCH_OPERATOR_GREATER_THAN_EQUALS  key: "http.response.body.param1"  description: "Check if mutated HTTP response body param1 is greater than or equal to 100"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body.param1", "MATCH_OPERATOR_GREATER_THAN_EQUALS", "${mutated.http.response.body.param1}", "100") ``` #### MATCH_OPERATOR_LESS_THAN ##### Operator Tag `MATCH_OPERATOR_LESS_THAN` ##### Description This operator checks whether the LHS/mutated value is less than the RHS/original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if *param1* in the body of the response received for the mutated request has a value less than *100*. **YAML** ```yaml - lhs: "${mutated.http.response.body.param1}"  rhs: "100"  operator: MATCH_OPERATOR_LESS_THAN  key: "http.response.body.param1"  description: "Check if mutated HTTP response body param1 is less than 100"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body.param1", "MATCH_OPERATOR_LESS_THAN", "${mutated.http.response.body.param1}", "100") ``` #### MATCH_OPERATOR_LESS_THAN_EQUALS ##### Operator Tag `MATCH_OPERATOR_LESS_THAN_EQUALS` ##### Description This operator checks whether the LHS/mutated value is less than or equal to the RHS/original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if *param1* in the body of the response received for the mutated request has a value less than or equal to *100*. **YAML** ```yaml - lhs: "${mutated.http.response.body.param1}"  rhs: "100"  operator: MATCH_OPERATOR_LESS_THAN_EQUALS  key: "http.response.body.param1"  description: "Check if mutated HTTP response body param1 is less than or equal to 100"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body.param1", "MATCH_OPERATOR_LESS_THAN_EQUALS", "${mutated.http.response.body.param1}", "100") ``` #### MATCH_OPERATOR_CONTAINS ##### Operator Tag `MATCH_OPERATOR_CONTAINS` ##### Description This operator checks whether the LHS/mutated value contains the LHS/original value. If it does, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. It also supports various Python data structures, such as lists, sets, and strings. ##### Example The below example evaluates to *True* if *param1* in the body of the response received for the mutated request contains the key word “*Unauthorized*”. **YAML** ```yaml - lhs: "${mutated.http.response.body.param1}"  rhs: "Unauthorized"  operator: MATCH_OPERATOR_CONTAINS  key: "http.response.body.param1"  description: "Check if mutated HTTP response body param1 does not contain the substring 'Unauthorized'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body.param1", "MATCH_OPERATOR_CONTAINS", "${mutated.http.response.body.param1}", "Unauthorized") ``` #### MATCH_OPERATOR_IN ##### Operator Tag `MATCH_OPERATOR_IN` ##### Description This operator checks whether the LHS/mutated value is present in the RHS/original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the message in the body of the response received for the mutated request includes either “Failed” or “Errored”. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "Bad request"  operator: MATCH_OPERATOR_IN  key: "http.response.body"  description: "Check if mutated HTTP response body message is one of the values in the list ['FAILED', 'ERRORED']"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_IN", "${mutated.http.response.body.message}", "[\”FAILED\”,\”ERRORED\”]") ``` #### MATCH_OPERATOR_NOT_IN ##### Operator Tag `MATCH_OPERATOR_NOT_IN` ##### Description This operator checks whether the LHS/mutated value is not present in the RHS/original value. If it is not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the message in the body of the response received for the mutated request does not include either “Failed” or “Errored”. **YAML** ```yaml - lhs: "${mutated.http.response.body.message}"  rhs: ["FAILED", "ERRORED"]  operator: MATCH_OPERATOR_NOT_IN  key: "http.response.body"  description: "Check if mutated HTTP response body message is not one of the values in the list ['FAILED', 'ERRORED']"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_NOT_IN",  "${mutated.http.response.body.message}", "[\”FAILED\”,\”ERRORED\”]") ``` #### MATCH_OPERATOR_KEYS_EQUALS ##### Operator Tag `MATCH_OPERATOR_KEYS_EQUALS` ##### Description This operator checks whether the LHS/mutated value is not present in the RHS/original value. If it is not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the keys in the body of the response received for the mutated request has the same set of keys in the body of the response received for the original request - up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_KEYS_EQUALS  key: "http.response.body"  description: "Check if the keys of the mutated HTTP response body are equal to those of the original HTTP response body,                with additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_KEYS_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”}) ``` #### MATCH_OPERATOR_KEYS_NOT_EQUALS ##### Operator Tag `MATCH_OPERATOR_KEYS_NOT_EQUALS` ##### Description This operator checks whether the LHS/mutated value is not present in the RHS/original value. If it is not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the keys in the body of the response received for the mutated request does not have the same set of keys in the body of the response received for the original request - up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_KEYS_NOT_EQUALS  key: "http.response.body"  description: "Check if the keys of the mutated HTTP response body are not equal to those of the original HTTP response body,                with additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_KEYS_NOT_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”}) ``` #### MATCH_OPERATOR_FUZZY_EQUALS ##### Operator Tag `MATCH_OPERATOR_FUZZY_EQUALS` ##### Description This operator checks whether the LHS/mutated and RHS/original values match up to the specified threshold. If they do, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the body of the response received for the mutated request matches (at least up to the threshold value of 80%) with the response received for the original request, up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_FUZZY_EQUALS  key: "http.response.body"  description: "Check if the mutated HTTP response body is approximately equal to the original HTTP response body with a fuzzy matching threshold of 0.8,                and additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_FUZZY_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”, “threshold”: 0.8}) ``` #### MATCH_OPERATOR_FUZZY_NOT_EQUALS ##### Operator Tag `MATCH_OPERATOR_FUZZY_NOT_EQUALS` ##### Description This operator checks whether the LHS/mutated and RHS/original values do not match up to the specified threshold. If they do not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the body of the response received for the mutated request does not match (at least up to the threshold value of 80%) with the response received for the original request, up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_FUZZY_NOT_EQUALS  key: "http.response.body"  description: "Check if the mutated HTTP response body is not approximately equal to the original HTTP response body with a fuzzy matching threshold of 0.8,                and additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_FUZZY_NOT_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”, “threshold”: 0.8}) ``` #### MATCH_OPERATOR_FUZZY_KEYS_EQUALS ##### Operator Tag `MATCH_OPERATOR_FUZZY_KEYS_EQUALS` ##### Description This operator checks whether the LHS/mutated and RHS/original values are JSON/URL-encoded parseable and the keys match up to the specified threshold. If they do, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the keys in the body of the response received for the mutated request matches (at least up to the threshold value of 80%) with the keys in the body of the response received for the original request - up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_FUZZY_KEYS_EQUALS  key: "http.response.body"  description: "Check if the keys of the mutated HTTP response body are approximately equal to those of the original HTTP response body with a fuzzy matching threshold of 0.8,                and additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_FUZZY_KEYS_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”, “threshold”: 0.8}) ``` #### MATCH_OPERATOR_FUZZY_KEYS_NOT_EQUALS ##### Operator Tag `MATCH_OPERATOR_FUZZY_KEYS_NOT_EQUALS` ##### Description This operator checks whether the LHS/mutated and RHS/original values are JSON/URL-encoded parseable and the keys match up to the specified threshold. If they do, the assertion evaluates to False/Not Vulnerable; otherwise, it evaluates to True/Vulnerable. ##### Example The below example evaluates to *True* if the keys in the body of the response received for the mutated request does not match (at least up to the threshold value of 80%) with the keys in the body of the response received for the original request - up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${original.http.response.body}"  operator: MATCH_OPERATOR_FUZZY_KEYS_NOT_EQUALS  key: "http.response.body"  description: "Check if the keys of the mutated HTTP response body are not approximately equal to those of the original HTTP response body with a fuzzy matching threshold of 0.8,                and additional data, level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body",  "MATCH_OPERATOR_FUZZY_KEYS_NOT_EQUALS", "${mutated.http.response.body}",  "${original.http.response.body}", data={“level”:5,“content-type”: “application/json”, “threshold”: 0.8}) ``` #### MATCH_OPERATOR_VALUES_DIFFERENCE ##### Operator Tag `MATCH_OPERATOR_VALUES_DIFFERENCE` ##### Description This operator checks if the absolute difference between the LHS/mutated and RHS/original value is a certain amount. ##### Example The below example evaluates to *True* if the query param *id* of the mutated request differs from the response parameter *id* by a value of *100.* **YAML** ```yaml - lhs: "${mutated.http.request.query.param.id}"  rhs: "${mutated.http.response.param.id}"  operator: MATCH_OPERATOR_VALUES_DIFFERENCE  key: "http.request.query.param.id"  description: "Check the difference between the mutated HTTP request query param id and the mutated HTTP response param id,                with additional data, level=5, content-type=application/json, amount=100"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.request.query.param.id",  "MATCH_OPERATOR_VALUES_DIFFERENCE", "${mutated.http.request.query.param.id}",  "${mutated.http.respose.param.id}", data={“level”:5,“content-type”: “application/json”, “amount”: 100}) ``` #### MATCH_OPERATOR_VALUES_SEARCH ##### Operator Tag `MATCH_OPERATOR_VALUES_SEARCH` ##### Description This operator searches for the RHS/original value in the LHS/mutated value. The LHS value can be a dictionary or a URL-encoded payload. The level specified in this operator signifies the max depth till which Traceable should look at in the tree structure like JSON. If the RHS value is found in the LHS one, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the body of the response received for the mutated request contains the value *15*, up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "15"  operator: MATCH_OPERATOR_VALUES_SEARCH  key: "http.request.query.param.id"  description: "Check if the value '15' is present in the mutated HTTP response body, with additional data: level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.request.query.param.id",  "MATCH_OPERATOR_VALUES_SEARCH", "${mutated.http.response.body}", "15",  data={“level”:5,“content-type”: “application/json”}) ``` #### MATCH_OPERATOR_VALUES_NOT_SEARCH ##### Operator Tag `MATCH_OPERATOR_VALUES_NOT_SEARCH` ##### Description This operator searches for the RHS/original value in the LHS/mutated value. The LHS value can be a dictionary or a URL-encoded payload. The level specified in this operator signifies the maximum depth at which Traceable should look in the tree structure, like JSON. If the RHS value is not found in the LHS one, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable. ##### Example The below example evaluates to *True* if the body of the response received for the mutated request does not contain the query param *id* of the original request, up to a depth of 5 for the JSON encoded tree. **YAML** ```yaml - lhs: "${mutated.http.response.body}"  rhs: "${mutated.http.request.query.param.id}"  operator: MATCH_OPERATOR_VALUES_NOT_SEARCH  key: "http.response.body"  description: "Check if the mutated HTTP request query param id is not present in the mutated HTTP response body, with additional data: level=5, content-type=application/json"  assertionType: IMMEDIATE  data:    level: 5    content-type: "application/json" ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_VALUES_NOT_SEARCH",  "${mutated.http.response.body}", "${mutated.http.request.query.param.id}",  data={“level”:5,“content-type”: “application/json”}) ``` #### MATCH_OPERATOR_REGEXLOOKUP_EQUALS ##### Operator Tag `MATCH_OPERATOR_REGEXLOOKUP_EQUALS` ##### Description This operator works in two steps: 1. Lookup for all attributes matching the LHS/mutated regex and use them in step 2. 2. If all attributes matched in step 1, match the RHS/original value, return True/Vulnerable; otherwise, return False/Not Vulnerable. ##### Example The below example evaluates to *True* if all parameters that match the specified regex in response to the mutated request contain the value *15*. **YAML** ```yaml - lhs: "mutated.http.response.body.*.carid"  rhs: "15"  operator: MATCH_OPERATOR_REGEXLOOKUP_EQUALS  key: "http.response.body"  description: "Check if the value '15' is equal to any value found in 'mutated.http.response.body' that matches the regex pattern for 'carid'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body", "MATCH_OPERATOR_REGEXLOOKUP_EQUALS",  "mutated.http.response.body.*.carid", "15") ``` #### MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS ##### Operator Tag `MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS` ##### Description This operator works in two steps: 1. Lookup for all attributes matching the LHS/mutated regex and use them in step 2. 2. If all attributes matched in step 1, do not match the RHS/original value, return True/Vulnerable; otherwise, return False/Not Vulnerable. ##### Example The below example evaluates to *True* if all parameters that match the specified regex in response to the mutated request do not contain the value *15*. **YAML** ```yaml - lhs: "mutated.http.response.body.*.carid"  rhs: "15"  operator: MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS  key: "http.response.body"  description: "Check if the value '15' is not equal to any value found in 'mutated.http.response.body' that matches the regex pattern for 'carid'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS",  "mutated.http.response.body.*.carid", "15") ``` #### MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX ##### Operator Tag `MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX` ##### Description This operator works in two steps: 1. Lookup for all attributes matching the LHS/mutated regex and use them in step 2. 2. If all attributes matched in step 1, match the RHS/original regex, return True/Vulnerable; otherwise, return False/Not Vulnerable. ##### Example The below example evaluates to True if all parameters that match the specified regex in the response to the mutated request contain a value that matches the regex `141[a-z0-9]{1,10}411`. **YAML** ```yaml - lhs: "mutated.http.response.body.*.carid"  rhs: "141[a-z0-9]{1,10}411"  operator: MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX  key: "http.response.body"  description: "Check if any value found in 'mutated.http.response.body' that matches the regex pattern for 'carid' matches the regex pattern '141[a-z0-9]{1,10}411'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX",  "mutated.http.response.body.*.carid", "141[a-z0-9]{1,10}411") ``` #### MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX ##### Operator Tag `MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX` ##### Description This operator works in two steps: 1. Lookup for all attributes matching the LHS/mutated regex and use them in step 2. 2. If all attributes matched in step 1, do not match the RHS/original regex, return True/Vulnerable; otherwise, return False/Not Vulnerable. ##### Example The below example evaluates to True if all parameters that match the specified regex in the response to the mutated request do not contain a value that matches the regex `141[a-z0-9]{1,10}411`. **YAML** ```yaml - lhs: "mutated.http.response.body.*.carid"  rhs: "141[a-z0-9]{1,10}411"  operator: MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX  key: "http.response.body"  description: "Check if no value found in 'mutated.http.response.body' that matches the regex pattern for 'carid' matches the regex '141[a-z0-9]{1,10}411'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX",  "mutated.http.response.body.*.carid", "141[a-z0-9]{1,10}411") ``` #### MATCH_OPERATOR_ALWAYS_TRUE ##### Operator Tag `MATCH_OPERATOR_ALWAYS_TRUE` ##### Description This operator always returns True/Vulnerable. It is mostly useful when you are writing plugins and want to test dummy assertions. ##### Example The below example evaluates to True every time. **YAML** ```yaml - lhs: "xyz"  rhs: "abc"  operator: MATCH_OPERATOR_ALWAYS_TRUE  key: "test.true"  description: "Assertion that always evaluates to true, regardless of the values of lhs and rhs."  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("test.true", "MATCH_OPERATOR_ALWAYS_TRUE", "xyz", "abc") ``` #### MATCH_OPERATOR_ALWAYS_FALSE ##### Operator Tag `MATCH_OPERATOR_ALWAYS_FALSE` ##### Description This operator always returns False/Not Vulnerable. It is mostly useful when you are writing plugins and want to test dummy assertions. ##### Example The below example evaluates to False every time. **YAML** ```yaml - lhs: "xyz"  rhs: "abc"  operator: MATCH_OPERATOR_ALWAYS_FALSE  key: "test.false"  description: "Assertion that always evaluates to false, regardless of the values of lhs and rhs."  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("test.false", "MATCH_OPERATOR_ALWAYS_FALSE", "xyz", "abc") ``` #### MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS ##### Operator Tag `MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS` ##### Description This operator is used for SSRF-based scans, where if the application reaches out to Traceable collaborator, it looks out for the presence of *test id* in the payload received by the collaborator. ##### Example The below example evaluates to True if the payload (from the application) received by the collaborator contains the *test id*. **YAML** ```yaml - lhs: "${mutated.test.id}"  rhs: "${mutated.test.id}"  operator: MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS  key: "http.response.body"  description: "Check if the value '${mutated.test.id}' is contained within the value '${mutated.test.id}'"  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("http.response.body",  "MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS", "${mutated.test.id}", "${mutated.test.id}") ``` #### MATCH_OPERATOR_RAW ##### Operator Tag `MATCH_OPERATOR_RAW` ##### Description This operator executes raw lambda code supplying it with LHS/mutated and RHS/original values. If lambda returns *True*, it is marked as Vulnerable, else Not Vulnerable. ##### Example The below example evaluates to TRUE if the value `RSA` is present in the mutual TLS protocol ciphers. **YAML** ```yaml - lhs: "${mutated.tls.protocol.ciphers}"  rhs: "RSA"  operator: MATCH_OPERATOR_RAW  key: "tls.protocol.ciphers"  description: "Check if the value 'RSA' is present in the mutated TLS protocol ciphers, using a custom lambda function for validation."  assertionType: IMMEDIATE ``` **Python** ```python Assertion.create("tls.protocol.ciphers", "MATCH_OPERATOR_RAW", "${mutated.tls.protocol.ciphers}", "RSA", data={ "code": 'lambda x,y: any([y in n for n in x.split(" ")])' }) ``` ## Related - [Getting Started with AST Plugins](/plugins-introduction.md) - [Configuring and Writing Custom Plugins](/configuring-custom-plugins.md)