Copying a Test Run

Necessary Data

To copy a test run via an API call, the following pieces of data are required:

  • a token
  • an existing test record identifier

    To copy a test run via a web interface, a Wallarm account is required.

    You can get detailed information about token and test records here.

    The following values are used as examples in this document:

  • token_Qwe12345 as a token.
  • rec_0001 as a test record.

When a test run is being copied, an existing test record is reused.

This method of test run creation should be used if it is necessary to test a target application using already recorded baseline requests.

Rules of Test Run Copying

The things to be taken into account when copying a test run are:

  • You can specify any test policy to be used by a copied test run. This policy may differ from the policy used in the original test run.
  • You can copy test runs in the following states: failed, interrupted, passed, paused, running. Descriptions of these test run states are given here.
  • It is not possible to copy a test run using an empty test record with no baseline requests in it.
  • If some baseline requests are being recorded in a test record, this record cannot be used to copy a test run.

    If you try to copy a test run based on an unfinished test record, you will get the 400 error code (Bad Request) from the API server and an error message similar to the one below:

     {
       "status": 400,
       "body": {
         "test_record_id": {
         "error": "not_ready_for_cloning",
         "value": rec_0001
         }
       }
     }
    

    It is not possible to copy a test run from the web interface unless the recording process has been stopped.

Copying a Test Run via an API

To copy and execute a test run, issue this API call:

POST

Copy test run

https://us1.api.wallarm.com/v1/test_run
API call: POST /v1/test_run
Authorization: Required Authorization is provided by the token
HTTP header with the token: X-WallarmAPI-Token Serves to pass the token’s value to the API server
Parameters: name (required) The name of the test run
test_record_id (required) The identifier of an existing test record
desc Detailed description of the test run.
Default value: empty string
file_extensions_to_exclude This parameter allows specifying certain file types that need to be excluded from the evaluation process during testing. These file types are specified by the regular expression.
For example, if you set the ico file extension to be excluded, then the GET /favicon.ico baseline request will not be checked by FAST and will be skipped.
The regular expression has the following format:
- .: any number (zero or more) of any character
- x*: any number (zero or more) of the x character
- x?: the single x character (or none)
- any single file extension (e.g., jpg)
- several extensions delimited by the vertical bar (e.g., jpg | png)
Default value: empty string (FAST will check baseline requests with any file extension).
policy_id The identifier of the test policy.
If this parameter is missing, then the default policy takes action
stop_on_first_fail This parameter specifies FAST’s behavior when a vulnerability is detected:
true: stops the execution of the test run at the first detected vulnerability.
false: processes all the baseline requests regardless of whether any vulnerability is detected.
Default value: false
rps_per_baseline This parameter specifies a limit on the number of test requests (RPS, requests per second) to be sent to the target application (e.g., there might be 100 test requests derived from a single baseline request).
The limit is set per baseline request (no more than N test requests per second will be sent for an individual baseline request) in the test run.
Minimum value: 1.
Maximum value: 500.
Default value: null (RPS is unlimited)
rps This parameter is similar to the one described above, except that it limits the RPS globally per test run, not just for a single baseline request.
In other words, the whole number of test requests per second should not exceed the specified value regardless of how many baseline requests were recorded during the test run.
Minimum value: 1.
Maximum value: 1000.
Default value: null (RPS is unlimited)



Example of a request:

curl --request POST \
  --url https://us1.api.wallarm.com/v1/test_run \
  --header 'Content-Type: application/json' \
  --header 'Host: us1.api.wallarm.com' \
  --header 'X-WallarmAPI-Token: token_Qwe12345' \
  --data '{
    "name":"demo-testrun",
    "test_record_id":"rec_0001"
}'

Example of a response: test run copying is in progress

{
  "status": 200,
  "body": {
    "id": tr_1234,
    "name": "demo-testrun",
    ...
    "state": "cloning",
    ...
    "test_record_id": "rec_0001",
    ...
}

The cloning state means that the baseline requests are being cloned from the original test run to its copy (the test run with the tr_1234 identifier).

Example of a response: test run copying failed

{
  "status": 400,
  "body": {
    "test_record_id": {
      "error": "not_ready_for_cloning",
      "value": "rec_0001"
    }
  }
}

The not_ready_for_cloning error means that it is not possible to clone baseline requests from the original test run to its copy because the recording process is active in the original test run (involving the test record with the rec_0001 identifier).

If the request to the API server is successful, you will be presented with the server’s response. The response provides useful information, including:

  1. id: the identifier of a test run's copy (e.g., tr_1234).

    You will need the id parameter value to control the test run execution status.

  2. state: the state of the test run.

    A newly copied test run is in the running state.

    A comprehensive description of all the values of the state parameter can be found here.

Copying a Test Run via Web Interface

To copy and execute a test run via the Wallarm portal's web interface:

  1. Log in to the portal with your Wallarm account, then navigate to the “Test runs” tab.
  2. Select a test run to copy, then open the action menu on the right of the test run.
  3. Select the “Create similar test run” menu entry.

    The “Create similar test run” menu entry

  4. Select the following items in the opened sidebar:

    • the name of the test run's copy
    • the policy to use with the test run's copy
    • the node on which the test run's copy will be executed

    The “Test run” sidebar

    You may configure additional settings by selecting “Advanced settings” (if necessary):

    • The “Stop on first fail” checkbox defines whether the test run should be stopped after the first vulnerability was found.
    • The “Skip duplicated baselines” checkbox defines whether the duplicates of the baseline requests received earlier should be ignored. If the FAST node receives the same baseline request as the one received in this test run previously, then no test requests are created on its basis, and the FAST node console prints the following message: [info] The baseline #8921 is duplicated and already was processed.
    • The “Skip following files extensions” checkbox defines whether certain file types are excluded from the evaluation process during the testing. These file types are specified by the regular expression.

      For example, if you set the ico file extension to be excluded, then the GET /favicon.ico baseline request will not be checked by FAST and will be skipped.

      The regular expression can contain one of the following mutually excluding expressions:

      • .: any number of any character
      • x*: any number of the x character
      • x?: the single x character (or no character x at all)
      • any single file extension (e.g., jpg)
      • several extensions delimited by either “|” or “,” character (e.g., jpg | png or jpg, png)


      If a regular expression is not specified, then FAST will check baseline requests with any file extension.

    • The “RPS per test run” slider defines the request per second limit for the test run. This setting can take values from 1 to 1000. The default value is 1000.

    • The “RPS per baseline” slider defines the request per second limit for one baseline request. This setting can take values from 1 to 500. The default value is 500.
    • The “Stop baseline recording after” slider defines the test run time limit. This setting can take values from 5 min (5 minutes) to 1 day (24 hours). The default value is 30 min (30 minutes).

  5. Make sure that the “Use baselines from <the name of the test record to reuse>” option is checked.

    Reusing a Test Record

    Note that it is the test record name that is displayed in the option, not the test run name.

    A test record name is often omitted: for example, if a test run is created without the test_record_name parameter specified, then the name of the test record is the same as the name of the test run.

    The figure above shows the copy dialogue that mentions a test record where the name is not equivalent to the name of the test run wthat made use of this test record in the past (the MY TEST RECORD test record was used by the DEMO TEST RUN test run).

  6. Execute the test run by clicking on the “Create and run” button.

results matching ""

    No results matching ""