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:

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

Multiple transform values for the 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:

Suppression of parameters

The following sample JSON transform_rule file defines the schema for suppressing parameters:

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

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:

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