- 25 Aug 2023
- 4 Minutes to read
- PDF
Transform rules
- Updated on 25 Aug 2023
- 4 Minutes to read
- PDF
Traceable's API Security Testing (AST) provides you with an option to transform parameters in headers or request body. Transforming of parameters is useful when scans fail due to redacted data in the request, or you need to run the scan with OpenAPI spec. Parameter transformation also helps in finding more vulnerabilities because more successful test attacks are possible.
The following examples explain show how transforming parameters can be helpful in running more accurate scans:
Example - Redacted data
Your request may have sensitive data, for example, email ID, name, and so on, which may be redacted due to configurations. You can transform such a redacted parameter to a value that you define in transform_rules JSON or YAML file. For example, you may have email
as a sensitive data key, the value of which was redacted (*******
). You can transform this, for example, to [email protected]
. With this transformation, the test attack to scan for vulnerabilities that earlier failed because of redacted data will now pass.
Example - OpenAPI spec
You can run an OpenAPI spec scan in which a parameter name
did not have an example value. A random value was assigned to it, for example, john.doe. Scan may not pass with this random value. You can transform this value, for example, to https://app.traceable.ai
.
Steps to run transform
Transforming parameter values consists of two simple steps:
- Create a transform_rules JSON or YAML file.
- Run the transform command, either using python or docker CLI.
Step 1 - Create the transform file
Single transform value for a parameter
The following sample JSON transform_rule file defines the schema for transforming single parameters:
{
"transform_params": [
{
"key": "http.request.header.host",
"value": "13.3.2.1",
"action": "MODIFY",
"scope": {
"key": "API_NAME",
"operator": "CONTAINS",
"value": "/post/orders"
}
},
{
"key": "authorization",
"value": "Bearer token",
"action": "REGEX_MODIFY",
"scope": {
"key": "API_NAME",
"operator": "NOT_CONTAINS",
"value": "/get/payments"
}
}
]
}
As you can see that in the above transform_rule file, http.request.header.host
value is modified to 13.3.2.1. The action
is MODIFY
. The scope defines on which APIs you wish to run the transform. If you do not provide the scope, transform is run on all the APIs. The following table explains the various keys of the transform_rule file.
JSON key | Description |
---|---|
transform_params[] | Defines a list of parameters that you wish to transform. |
transform_params[].key | Defines the keys of the parameters that you wish to transform. The following is the format:
|
transform_params[].value | Defines the value that would replace the original value. |
transform_params[].action | The type of action that you wish to take. It can have one of the following values:
|
transform_params[].scope | Defines the APIs for which you wish to apply transformation rules. This is an optional key. If you do not define the scope, then the transformation is applied to all the APIs. |
transform_params[].scope.key | API_NAME |
transform_params[].scope.value | Value related to the key. In above case, it would be the name of the API. |
transform_params[].scope.operator | The operator can have the following values:
|
Multiple transform value for parameter
The following sample JSON transform_rule file defines the schema for transforming multiple parameters:
{
"transform_params": [
{
"key": "http.request.body.fruit",
"value": "$SINGLE_FRUIT_VALUE",
"action": "MODIFY"
},
{
"key": "http.request.body.firstName",
"value": "$GROUP_NAME_VALUE",
"action": "MODIFY"
},
{
"key": "http.request.body.lastName",
"value": "$GROUP_NAME_VALUE",
"action": "MODIFY"
},
{
"key": "http.request.body.age",
"value": "$GROUP_NAME_VALUE",
"action": "MODIFY"
}
],
"values_store": {
"single_choice_store": {
"$SINGLE_FRUIT_VALUE": ["apple", "mango", "banana", "watermelon"]
},
"group_choice_store": {
"$GROUP_NAME_VALUE": [{
"http.request.body.firstName": "John",
"http.request.body.lastName": "Doe",
"http.request.body.age": 25
},
{
"http.request.body.firstName": "Kevin",
"http.request.body.lastName": "Smith",
"http.request.body.age": 35
}
]
}
}
}
Note the following points:
$SINGLE
- A random single value is selected from the choices you provide.$GROUP
- A random group of parameters is selected from the choices you provide.
For example, in the above sample schema, a random fruit value is chosen from the given choices (apple, mango, banana, and watermelon). Similarly, a group is picked from the choices you have provided.
The following table explains the various JSON keys:
JSON key | Description |
---|---|
values_store.single_choice_store | Defines the set of values that are possible for any parameter. |
values_store.single_choice_store.<key_name> | Key is the variable that is used in transform_params[].value field. Value is a list of possible values for that variable. |
values_store.group_choice_store.<key_name> | Key is the variable that is used in transform_params[].value field. Value is a list of possible objects with key-value pairs (transform_params[].key transform_params[].value ) that are possible for that variable. |
Step 2 - Run the transform command
Once you have created the transform_rule JSON file, run the transform command. You can run it either using python or docker CLI. Make a note of the following before running the transform command:
- Keep the Platform token handy. In Traceable Platform, navigate to My Preferences → API Token → Generate API Token button.
- Decide the name of the scan and the scan policy.
Python CLI command
Enter the following command to run the transform using python:
./traceable ast scan initAndRun --scan-name test-scan-1 --policy scan-policy-1 --token <platform_token> --transform-rules ~/.traceable/transform_rules.json
Docker CLI
Enter the following command to run the transform using Docker CLI:
docker run --rm -v /localmount_folder_path:/app/userdata traceable-data -it traceableai/traceable-cli ast scan initAndRun --scan-name test-scan-1 --policy scan-policy-1 --token <platform_token> --transform-rules /app/userdata/transform_rules.json