--- title: "Transform rules" slug: "transform-rules" updated: 2024-06-03T05:00:52Z published: 2024-06-03T05:00:52Z --- > ## 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. # Transform rules Traceable's API Security Testing (AST) provides the option to transform parameters in headers or the request body. Parameter transformation is useful when scans fail due to redacted data in the request or when you need to run the scan with OpenAPI spec. Parameter transformation also helps find more vulnerabilities because it allows for more successful test attacks. The following examples show how transforming parameters can help run more accurate scans: #### **Example - Redacted data** Your request may have sensitive data, such as, 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 `myname@mycompany.com`. 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. It was assigned a random value, for example, john.doe. The scan may not pass with this random value. You can transform this value, for example, to `https://app.traceable.ai`. Traceable also provides you the option to suppress sensitive parameters using the same `transform_rules` JSON or YAML file. This suppression is useful when sensitive data is being sent to your Traceable account, and some parts of it are still not redacted or obfuscated. See the following section for information on the steps to suppress the data. --- ## Steps to run transform or suppression Transforming or suppressing parameter values consists of two steps: 1. Create a `transform_rules` JSON or YAML file. 2. 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: ```json {  "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 in the above file, `http.request.header.host` value is modified to 13.3.2.1. The `action` is `MODIFY`. The scope defines which APIs you wish to run the transform on. If you do not provide the scope, transform is run on all the APIs. The following table explains the various keys of the above 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: - `http.request.header.<header_name>` - `http.request.body.<body_name>` | | `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: - MODIFY - Replace or set the parameter value - REGEX_MODIFY - Replace or set the parameter value based on a regex match. | | `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 the above case, it would be the name of the API. | | `transform_params[].scope.operator` | The operator can have the following values: - CONTAINS - The `scope` contains the value. - NOT_CONTAINS - The `scope` does not contain the value. | #### Multiple transform values for the parameter The following sample JSON `transform_rule` file defines the schema for transforming multiple parameters: ```json {  "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. | #### Suppression of parameters The following sample JSON `transform_rule` file defines the schema for suppressing parameters: ```json {  "transform_params": [    {      "key": "authorization",      "action": "SUPPRESS",      "suppression_type": "REDACT"    },    {      "key": "http.request.header.host",      "action": "SUPPRESS",      "suppression_type": "OBFUSCATE"      "scope": {        "key": "API_NAME",        "operator": "CONTAINS",        "value": "/post/orders"      }    }] } ``` As you can see in the above file, `http.request.header.host` value is being suppressed. The `action` is `SUPPRESS`. The scope defines on which APIs you wish to run the suppression. If you do not provide the scope, transform is run on all the APIs. The following table explains the various keys of the above file: | JSON key | Description | | --- | --- | | `transform_params[]` | Defines a list of parameters that you want to suppress. | | `transform_params[].key` | Defines the keys of the parameters that you wish to suppress. | | `transform_params[].action` | The type of action that you want to take, here, suppress or redact the parameter. It can have *SUPPRESS* as the value. | | `transform_params[].suppression_type` | The type of suppression that you want to perform on the parameter. It can have one of the following values: - RAW — Do not suppress the parameter. - REDACT — Replace each character of the sensitive parameter with a *. - OBFUSCATE — Replace the sensitive parameter with a hash-id. | | `transform_params[].scope` | Defines the APIs for which you wish to apply suppression. 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` | The API name that contains the sensitive parameter. | | `transform_params[].scope.operator` | The operator can have the following values: - CONTAINS - The `scope` contains the value. - NOT_CONTAINS - The `scope` does not contain the value. | | `transform_params[].scope.value` | Value related to the key. In the above case, it would be the name of the API. | --- ## Step 2 - Run the transform command Once you have created the `transform_rule` 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 scan policy. #### Python CLI command Enter the following command to run the transform using Python: ```actionscript ./traceable ast scan initAndRun --scan-name test-scan-1 --policy scan-policy-1 --token --transform-rules ~/.traceable/transform_rules.json ``` #### Docker CLI Enter the following command to run the transform using Docker CLI: ```actionscript 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 --transform-rules /app/userdata/transform_rules.json ```