Test and Custom Plugins

config.yaml

$TRACEABLE_HOME`

Contains the configuration for AST, such as pre-hooks, post-hooks, and custom plugin definitions.

custom

$TRACEABLE_HOME/plugins/custom

Contains the custom plugin implementations.

hooks

$TRACEABLE_HOME/hooks

Contains the pre and post-hooks.

testsuite (per API)

$TRACEABLE_HOME/data/<scan_id>/*.json

Contains the JSON files that represent test suites. Each file is a suite of tests generated at the moment for a specific API.

category

For a custom plugin, the value of this field should always be “custom”.

name

The name of the custom plugin. The name you specify here should match the one in the config.yaml file.

For example, in the above code:

name = "SamplePlugin"

Similarly, in the config.yaml file:

name = "SamplePlugin"
scan:
   plugins:
.....
      custom:
         SamplePlugin: {}

title

The plugin title you want to display in the vulnerability.

description

The description of the vulnerability identified using the plugin.

mitigation

The steps for mitigating the vulnerability that the plugin finds.

severity

The severity of the vulnerability that the plugin finds. The severity can be either Unspecified, Critical, High, Medium, or Low.

cvss_vector_string

The string specifies the attributes of the vulnerability, along with the attack vector, complexity, privileges required, and impact. These values are used to calculate the severity score. For more information, see CVSS Vector Strings.

displayName

The name of the plugin should be visible in the Traceable platform user interface.

affectedEntityType

This field should have the value “Custom”.

impact

A description of the impact of the vulnerability that the plugin finds.

references

The list of references for the vulnerability generated by the plugin.

estimated_fix_time

The estimated fix time for the vulnerability that the plugin finds.

estimated_bounty_value

The estimated bounty value in case the vulnerability is exploited.

tags

The tags associated with the plugin.

attributes.add_attributes(attributeList, prefix: str = "")

This operator is used to add attributes from another attribute list. It adds new values without modifying the existing ones.

attributes.set_attributes(attributeList, prefix: str = "")

This operator is used to set attributes from another attribute list. It modifies any existing values or creates them if they don’t exist.

attributes.get_one(key, , default: any = None, use_prefix: bool = False, regex: bool = False)

This operator is used to fetch one value from the attribute.

attributes.get(key, : str, default: any = None, use_prefix: bool = False, regex: bool = False)

This operator is used to fetch values from the attribute.

attributes.get_one_attr(key, , default: any = None, use_prefix: bool = False, regex: bool = False)

This operator is used to fetch one attribute.

attributes.get_original(key, , default: any = None, use_prefix: bool = False, regex: bool = False)

This operator is used to fetch the original value from the attribute.

attributes.items(self)

This operator is used to fetch the attribute list iterator.

attributes.add(key, : str, value: any, original_and_mutated: bool = False, is_dirty: bool = False, force: bool = False)

This operator is used to add 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.

attributes.modify(key, : str, value: any, first_only: bool = False, regex: bool = False)

This operator is used to update 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.

attributes.set(key, : str, value: any, original_and_mutated: bool = False, regex: bool = False, is_dirty: bool = False, force: bool = True)

This operator is used to set 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.

attributes.expand_attributes(self, data, regex: bool = False, user_prefix: bool = False)

This operator is used to expand templated variables to fetch the attribute value.

attributes.expand(self, data, regex: bool = False, use_prefix: bool = False)

This operator is used to expand 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.

attributes.delete(key, value, regex: bool = False)

This operator is used to delete attributes from the attribute list.

MUTATION_ADD

This operator adds a new key attribute with the specified value. If the key attribute already exists, it duplicates it.

Example:

test.mutaions = [

  Mutation.create("MUTATION_ADD", “mutated.http.query.param.id”, "100”)
  Mutation.create("MUTATION_ADD", “mutated.http.query.param.id”, "50”)
]

This adds two query params in the url resulting in ?id=100&id=50. This is typically used to test parameter pollution.

MUTATION_DELETE

This operator deletes an existing key attribute.

Example:

test.mutaions = [
  Mutation.create("MUTATION_DELETE", “mutated.http.query.param.id”, "”)
]

This removes the query param id from the API request.

MUTATION_MODIFY

This operator modifies a key attribute if it exists; otherwise, it does nothing.

Example:

test.mutaions = [
  Mutation.create("MUTATION_MODIFY", “mutated.http.query.param.id”, "100”)
]

This updates the query param id with value 100 if it exists; otherwise, it ignores the instruction.

MUTATION_SET

This operator sets the value of an existing key attribute or adds it if it does not exist.

Example:

test.mutaions = [
  Mutation.create("MUTATION_SET", “mutated.http.query.param.id”, "100”)
]

This sets the query param id to 100 if it already exists; otherwise, it creates a query param id with the same value.

MUTATION_REGEX_DELETE

This operator deletes all attributes that match the key/regular expression with value.

Example:

test.mutaions = [
  Mutation.create("MUTATION_REGEX_DELETE", r“mutated\.http\.query\.param.*amount”, "”)
]

This deletes all query params ending with the string “amount”.

MUTATION_REGEX_MODIFY

This operator modifies all attributes that match the key/regular expression with value.

Example:

test.mutaions = [
  Mutation.create("MUTATION_REGEX_MODIFY", r“mutated\.http\.query\.param.*amount”, "100”)
]

This modifies the query param ending with the string “amount” with value 100, if it exists; otherwise, it ignores the instruction.

MUTATION_REGEX_SET

This operator sets all attributes that match the key/regular expression with value.

Example:

test.mutaions = [
  Mutation.create("MUTATION_REGEX_SET", r“mutated\.http\.query\.param.*amount”, "100”)
]

This sets the query param ending with the string “amount” with a value of 100, if it exists; otherwise, it ignores the instruction.

LOGICAL_OPERATOR_AND

All assertion items in the assertion list need to be VULN(True) for the return value to be VULN(True).

LOGICAL_OPERATOR_OR

Any assertion item in the assertion list needs to be VULN(True) for the return value to be VULN(True).

MATCH_OPERATOR_EQUALS

This operator checks whether the mutated value matches the original value. If it does, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.code", “MATCH_OPERATOR_EQUALS”, "${mutated.http.response.code}", “${original.http.response.code}”)

This evaluates to True if the response code received from the mutated request matches the response code received from the original request.

MATCH_OPERATOR_NOT_EQUALS

This operator checks whether the mutated value does not match the original value. If it does not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body.param1", “MATCH_OPERATOR_NOT_EQUALS”, "${mutated.http.response.body.param1}", “${original.http.response.body.param1}”)

This 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.

MATCH_OPERATOR_MATCHES_REGEX

This operator checks whether the mutated value matches the regex. If it does, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.duration", “MATCH_OPERATOR_MATCHES_REGEX”, "${mutated.http.response.code}", r"^5\d\d")

This evaluates to True if the response code received for the mutated request matches the specified regular expression.

MATCH_OPERATOR_NOT_MATCHES_REGEX

This operator checks whether the 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:

Assertion.create("http.response.duration", “MATCH_OPERATOR_NOT_MATCHES_REGEX”, "${mutated.http.response.code}", r"^4\d\d")

This evaluates to True if the response code received for the mutated request does not match the specified regular expression.

MATCH_OPERATOR_GREATER_THAN

This operator checks whether the mutated value is greater than the original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.duration", “MATCH_OPERATOR_GREATER_THAN”, "${mutated.http.response.duration}", "100")

This evaluates to True if the time taken to receive a response to the mutated request takes longer than 100 ms.

MATCH_OPERATOR_GREATER_THAN_EQUALS

This operator checks whether the mutated value is greater than or equal to the original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body.param1", "MATCH_OPERATOR_GREATER_THAN_EQUALS", "${mutated.http.response.body.param1}", "100")

This 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.

MATCH_OPERATOR_LESS_THAN

This operator checks whether the mutated value is less than the original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body.param1", "MATCH_OPERATOR_LESS_THAN", "${mutated.http.response.body.param1}", "100")

This evaluates to True if param1 in the body of the response received for the mutated request has a value less than 100.

MATCH_OPERATOR_LESS_THAN_EQUALS

This operator checks whether the mutated value is less than or equal to the original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body.param1", "MATCH_OPERATOR_LESS_THAN_EQUALS", "${mutated.http.response.body.param1}", "100")

This 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.

MATCH_OPERATOR_CONTAINS

This operator checks whether the mutated value contains the 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 list, set, and string.

Example:

Assertion.create("http.response.body.param1", "MATCH_OPERATOR_NOT_CONTAINS", "${mutated.http.response.body.param1}", "Unauthorized")

This evaluates to True if param1 in the body of the response received for the mutated request contains the key word “Unauthorized”.

MATCH_OPERATOR_NOT_CONTAINS

This operator checks whether the mutated value does not contain the original value. If it does not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

It also supports various python data structures, such as list, set, and string.

Example:

Assertion.create("http.response.body", "MATCH_OPERATOR_NOT_CONTAINS", "${mutated.http.response.body}", "Bad request")

This evaluates to True if the body of the response received for the mutated request does not contain the key word “Bad request”.

MATCH_OPERATOR_IN

This operator checks whether the mutated value is present in the original value. If it is, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body", "MATCH_OPERATOR_IN", "${mutated.http.response.body.message}", "[\”FAILED\”,\”ERRORED\”]")

This evaluates to True if the message in the body of the response received for the mutated request includes either “Failed” or “Errored”.

MATCH_OPERATOR_NOT_IN

This operator checks whether the mutated value is not present in the original value. If it is not, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body", "MATCH_OPERATOR_NOT_IN",  "${mutated.http.response.body.message}", "[\”FAILED\”,\”ERRORED\”]")

This evaluates to True if the message in the body of the response received for the mutated request does not include either “Failed” or “Errored”.

MATCH_OPERATOR_KEYS_EQUALS

This operator checks whether the mutated and original values are JSON/URL-encoded parseable and have the same keys. If they do, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.response.body", "MATCH_OPERATOR_KEYS_EQUALS",  "${mutated.http.response.body}", "${original.http.response.body}",  data={“level”:5,“content-type”: “application/json”})

This 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.

MATCH_OPERATOR_KEYS_NOT_EQUALS

This operator checks whether the mutated and original values are JSON/URL-encoded parseable and have the same keys. If they do, the assertion evaluates to False/Not Vulnerable; otherwise, it evaluates to True/Vulnerable.

Example:

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”})

This 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.

MATCH_OPERATOR_FUZZY_EQUALS

This operator checks whether the mutated and 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:

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})

This 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.

MATCH_OPERATOR_FUZZY_NOT_EQUALS

This operator checks whether the mutated and 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:

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})

This 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.

MATCH_OPERATOR_FUZZY_KEYS_EQUALS

This operator checks whether the mutated and 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:

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})

This 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.

MATCH_OPERATOR_FUZZY_KEYS_NOT_EQUALS

This operator checks whether the mutated and 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:

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})

This 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.

MATCH_OPERATOR_VALUES_DIFFERENCE

This operator checks if the absolute difference between the mutated and original value is a certain amount.

Example:

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})

This evaluates to True if the query param id of the mutated request differs from the response parameter id by a value of 100.

MATCH_OPERATOR_VALUES_SEARCH

This operator searches for the original value in the mutated value. The mutated 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 original value is found in the mutated one, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

Assertion.create("http.request.query.param.id",  "MATCH_OPERATOR_VALUES_SEARCH", "${mutated.http.response.body}", "15",  data={“level”:5,“content-type”: “application/json”})

This evaluates to True if the body of the response received for the mutated request contains the value 15 - up to the depth 5 for the JSON encoded tree.

MATCH_OPERATOR_VALUES_NOT_SEARCH

This operator searches for the original value in the mutated value. The mutated 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 original value is not found in the mutated one, the assertion evaluates to True/Vulnerable; otherwise, it evaluates to False/Not Vulnerable.

Example:

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”})

This 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.

MATCH_OPERATOR_REGEXLOOKUP_EQUALS

This operator works in two steps:

1. Lookup for all attributes matching the mutated regex and use them in step 2.

2. If all attributes matched in step 1, match the original value, return True/Vulnerable; otherwise, return False/Not Vulnerable.

Example:

Assertion.create("http.response.body", "MATCH_OPERATOR_REGEXLOOKUP_EQUALS",  "mutated.http.response.body.*.carid", "15")

This evaluates to True if all parameters that match the specified regex in response to the mutated request contains the value 15.

MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS

This operator works in two steps:

1. Lookup for all attributes matching the mutated regex and use them in step 2.

2. If all attributes matched in step 1, do not match the original value, return True/Vulnerable; otherwise, return False/Not Vulnerable.

Example:

Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_NOT_EQUALS",  "mutated.http.response.body.*.carid", "15")

This evaluates to True if all parameters that match the specified regex in response to the mutated request does not contain the value 15.

MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX

This operator works in two steps:

1. Lookup for all attributes matching the mutated regex and use them in step 2.

2. If all attributes matched in step 1, match the original regex, return True/Vulnerable; otherwise, return False/Not Vulnerable.

Example:

Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_MATCHES_REGEX",  "mutated.http.response.body.*.carid", "141[a-z0-9]{1,10}411")

This evaluates to True if all parameters that match the specified regex in response to the mutated request contains a value of that matches the regex ("141[a-z0-9]{1,10}411").

MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX

This operator works in two steps:

1. Lookup for all attributes matching the mutated regex and use them in step 2.

2. If all attributes matched in step 1, do not match the original regex, return True/Vulnerable; otherwise, return False/Not Vulnerable.

Example:

Assertion.create("http.response.body",  "MATCH_OPERATOR_REGEXLOOKUP_NOT_MATCHES_REGEX",  "mutated.http.response.body.*.carid", "141[a-z0-9]{1,10}411")

This evaluates to True if all parameters that match the specified regex in response to the mutated request does not contain a value of that matches the regex ("141[a-z0-9]{1,10}411").

MATCH_OPERATOR_ALWAYS_TRUE

This operator always returns True/Vulnerable. It is mostly useful when you are writing plugins and want to test dummy assertions.

Example:

Assertion.create("test.true", "MATCH_OPERATOR_ALWAYS_TRUE", "xyz", "abc")

MATCH_OPERATOR_ALWAYS_FALSE

This operator always returns False/Not Vulnerable. It is mostly useful when you are writing plugins and want to test dummy assertions.

Example:

Assertion.create("test.false", "MATCH_OPERATOR_ALWAYS_FALSE", "xyz", "abc")

MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS

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:

Assertion.create("http.response.body",  "MATCH_OPERATOR_COLLABORATOR_LOOKUP_CONTAINS", "${mutated.test.id}", "${mutated.test.id}")

This evaluates to True if the payload (from the application) received by the collaborator contains the test id.

MATCH_OPERATOR_RAW

This operator executes raw lambda code supplying it with mutated and original values. If lambda returns True, it is marked as Vulnerable, else Not Vulnerable.

Example:

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(" ")])' })