Transform rules

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

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:

{
  "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.

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:

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