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, send the POST request to the URL 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:
-
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. -
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:
-
Log in to the portal with your Wallarm account, then navigate to the “Test runs” tab.
-
Select a test run to copy, then open the action menu on the right of the test run.
-
Select the “Create similar testrun” menu entry.
-
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
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 testing. These file types are specified by the regular expression.
For example, if you set the
ico
file extension to be excluded, then theGET /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 characterx*
: any number of thex
characterx?
: the singlex
character (or no characterx
at all)- any single file extension (e.g.,
jpg
) - several extensions delimited by either “|” or “,” character (e.g.,
jpg | png
orjpg, 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
to1000
. The default value is1000
. - The “RPS per baseline” slider defines the request per second limit for one baseline request. This setting can take values from
1
to500
. The default value is500
. - The “Stop baseline recording after” slider defines the test run time limit. This setting can take values from
5 min
(5 minutes) to1 day
(24 hours). The default value is30 min
(30 minutes).
-
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 theDEMO TEST RUN
test run). -
Execute the test run by clicking on the “Create and run” button.