Deployment and Configuration of FAST Node

Chapter Prerequisites

To follow the steps described in this chapter, you need to obtain a token.

The following values are used as example values throughout the chapter:

  • token_Qwe12345 as a token.
  • tr_1234 as an identifier of a test run.

The deployment and configuration of FAST node comproses the following steps:

  1. Deployment of the Docker Container with the FAST Node.
  2. Creation of the Test Run.

Deployment of the Docker Container with the FAST Node

Limit the Number of Requests to be Recorded

The FAST node treats all of the incoming requests as the baseline ones by default. Therefore, the node records them and creates and executes security tests on their basis. However, it is possible for the extraneous requests that should not be recognized as baseline requests to pass through the FAST node to the target application.

You can limit the number of requests to be recorded with the FAST node by filtering out all the requests that are not targeted to the application (note that the FAST node proxies the filtered requests but does not record them). This limitation reduces the load that applies to the FAST node and the target application, while boosting the testing process. To apply this limitation, you need to know the hosts the request source interacts with during the testing.

You can filter out all the non-baseline requests by configuring the ALLOWED_HOSTS environment variable.

Valid ALLOWED_HOSTS Variable Values

The ALLOWED_HOSTS variable accepts the following hosts formats:

  • fully qualified names (e.g. node.example.local)
  • a value beginning with a period (e.g. .example.local) that is recognized as a subdomain wildcard
  • a value of * that matches anything (in this case, all of the requests are recorded by the FAST node)

For more information about the ALLOWED_HOSTS variable values, proceed to this link.

The FAST node employs this environment variable in the following way:

  • If the value of the Host header of the incoming request matches the value specified in the ALLOWED_HOSTS variable, then the FAST node considers the request as a baseline one. The request is then recorded and proxied.

  • All the other requests are proxied through the FAST node but not recorded.

The “Quick Start” guide contains an example of the variable’s usage.

Run Docker Container with the FAST Node

Grant Access to Wallarm API Servers

It is crucial that the FAST node has access to the us1.api.wallarm.com Wallarm API servers using the HTTPS protocol (TCP/443) for the proper operation of the node.

Make sure that the firewall does not restrict the Docker host from accessing the Wallarm API servers.

It is required to do some configuration prior to running the Docker container with the FAST node. To configure the node, place the token into the container using the WALLARM_API_TOKEN environment variable. Additionally, you could use the ALLOWED_HOSTS variable if you need to limit the number of requests to be recorded.

Valid ALLOWED_HOSTS Variable Values

The ALLOWED_HOSTS variable accepts the following hosts formats:

  • fully qualified names (e.g. node.example.local)
  • a value beginning with a period (e.g. .example.local) that is recognized as a subdomain wildcard
  • a value of * that matches anything (in this case, all of the requests are recorded by the FAST node)

For more information about the ALLOWED_HOSTS variable values, proceed to this link.

To pass the environment variables to the container, place the variables in a text file and specify the path to the file using the --env-file parameter of the docker run command (see the instructions in the “Quick Start” guide).

Run a container with the FAST node by executing the following command:

docker run \ 
--rm \
--name <name> \
--env-file=<environment variables file> \
-p <target port>:8080 \
wallarm/fast

This guide assumes that the container runs only once for the given CI/CD job and is removed when the job ends. Therefore, the --rm parameter was added to the command listed above.

Please refer to the “Quick Start” guide for a detailed description of the command’s parameters.

Example.

This example assumes that the FAST node uses the token_Qwe12345 token and is set up to record all the incoming baseline requests which have example.local as a substring of the Host header’s value.

The content of a file with environment variables is shown in the following example:

fast.cfg
WALLARM_API_TOKEN=token_Qwe12345
ALLOWED_HOSTS=example.local

The command below runs the Docker container named fast-poc-demo with the certain behavior:

  • The container is removed after it’s job is done.
  • The environment variables are passed to the container using the fast.cfg file.
  • The container’s 8080 port is published to the Docker host’s 9090 port.
docker run --rm --name fast-poc-demo --env-file=fast.cfg -p 9090:8080  wallarm/fast

If the FAST node deployment is successful, the container’s console and log file contain the following informational messages:

[info] Node connected to Wallarm Cloud
[info] Waiting for TestRun to check…

Now the FAST node is listening on the Docker host’s IP address, and the port you have specified earlier with the -p parameter of the docker run command.

Create Test Run

If you plan to employ your own test policy, then create one and get the policy’s identifier. Later, pass the identifier into the policy_id parameter when doing an API call to create a test run.

Example of Test Policy

The “Quick Start” guide contains step-by-step instructions on how to create a sample test policy.

Otherwise, if you choose to use the default test policy, then the policy_id parameter should be omitted from the API call.

Create a test run by issuing the following API call:

POST

Create New Test Run

https://us1.api.wallarm.com/v1/test_run
API call: POST /v1/test_run
Authorization: Required With the token
HTTP header with the token: X-WallarmAPI-Token Serves to pass the token’s value to the API server
Parameters: name (required) Name of the test run
desc Detailed description of the test run.
Default value: empty string
policy_id The identifier of the test policy.
If the parameter is missing, then the default policy takes action
stop_on_first_fail The parameter specifies FAST’s behavior when a vulnerability has been detected:

true: stop the execution of the test run on the first detected vulnerability.
false: process all the baseline requests no matter if any vulnerability is detected or not.

Default value: false
skip_duplicated_baselines The parameter specifies FAST’s behavior when a duplicated baseline request has been encountered:

true: skip duplicated baseline requests (if there are a few identical baseline requests, then the test requests are generated for the first baseline request only).
false: the test requests are generated for each incoming baseline request.

Default value: true
rps_per_baseline The 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 The parameter is similar to the one described above, except that it limits the RPS globally, per test run, not just a single baseline request.
In other words, the whole number of test requests per second should not exceed the specified value no matter how many baseline requests were recorded during the test run.

Minimum value: 1.
Maximum value: 1000.

Default value: null (RPS is unlimited)
inactivity_timeout The parameter specifies the time interval in seconds during which the FAST node waits for a new baseline request to arrive.
This behavior is described here in detail.
The timeout has no influence on the processes of creation and execution of security tests for baseline requests that has been recorded.

Minimum value: 300 (300 seconds or 5 minutes).
Maximum value: 86400 (86400 seconds or 1 day).

Default value: 1800 (1800 seconds or 30 minutes)



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"
}'

Example of a response:

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

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

  1. id: the identifier of a newly created test run (e.g. tr_1234).

    You will need the id parameter value to perform the following actions, required to integrate FAST into CI/CD:

    1. Checking for the FAST node to start the recording process.
    2. Stopping the baseline requests recording process.
    3. Waiting for the FAST security tests to finish.


  2. state: the state of the test run.

    A newly created test run is in the running state. A comprehensive description of all the values of the state parameter can be found here.

The FAST node needs a certain amount of time to pass after the creation of the test run to be ready to record requests.

Make sure that the FAST node is ready to record requests before you send any requests to the target application using the test tool.

To do that, check the test run status periodically by issuing the following API call:

GET

Do One-Time Check of Test Run State

https://us1.api.wallarm.com/v1/test_run/test_run_id
API call: GET /v1/test_run/test_run_id
Authorization: Required With the token
HTTP header with the token: X-WallarmAPI-Token Serves to pass the token’s value to the API server
Parameters: test_run_id (required) The identifier of the test run whose state to obtain



Example of a request:

curl --request GET \
  --url https://us1.api.wallarm.com/v1/test_run/tr_1234 \
  --header 'Host: us1.api.wallarm.com' \
  --header 'X-WallarmAPI-Token: token_Qwe12345'

Example of a response:

{
  "status": 200,
  "body": {
    "id": tr_1234,
    "name": "demo-testrun",
    ...
    "ready_for_recording": true,
    ...
  }
}

If the request to the API server is successful, you are presented with the server’s response. The response provides useful information, including the state of the recording process (the ready_for_recording parameter’s value).

If the parameter’s value is true, then the FAST node is ready for recording and you could fire up your test tool to start sending requests to the target application.

Otherwise, issue the same API call repeatedly until the node is ready.

The next chapter describes how to configure HTTP traffic proxying through the FAST node.

You could go back to the list of FAST integration's steps if necessary.

results matching ""

    No results matching ""