API Sessions Setup ¶

API Sessions include the built-in rules for the session identification and requires only enabled Wallarm node to start working. Optionally, you can fine-tune API Sessions under your needs as described in this article.

Session context¶

Context in API sessions is information that enriches request data by grouping them into logical sessions and adding response data and metadata to provide deeper insights into session activity. Configuring context allows you to specify which aspects or additional data should be tracked and associated with each session.

Set session context by adding extra request and response parameters, associating sessions with sensitive business flows and highlighting parameters that can be used for user and user role identification.

Extra parameters¶

In API Sessions, within session, the request details by default include:

• Parameter of request or response that worked for session grouping - yours or the one from the built-in set (highlighted in the API session ID parameters group).

• For malicious requests - full request content.

You can add any additional (context) parameters both for requests and for their related responses, that you need to understand the session content: what and in what order the actor did and what the response was. To do so, add these parameters in Wallarm Console → API Sessions → Session context parameters. Once added, Wallarm will export them to the Wallarm Cloud and display in Wallarm Console, in details of your session requests (in the API session parameters group).

Users and roles¶

You can highlight session parameters, that should be used for naming the session user and its role. To do so, in Wallarm Console → API Sessions → Session context parameters, add your parameter, then from Type, select User or Role.

Once you configured parameters to be used for user and his/her role identification, these parameters are started to be filled for the sessions. You can filter sessions by users and roles.

Session grouping¶

Wallarm groups requests of your applications' traffic into user sessions based on the equal values of the selected headers/parameters of the requests and/or responses. In configuration, these are parameters marked to be grouping keys. See how grouping keys work in the example.

By default, sessions are identified with the built-in set of such parameters (not displayed in Wallarm Console). Its logic is to try most common identification parameters, such as PHPSESSID or SESSION-ID headers, and if they do not work - form session based on the combination of request source IP and user-agent (or at least IP if user-agent is not presented).

You can add your own identification parameters based on your applications' logic. To do so, go to Wallarm Console → API Sessions → Session context parameters, add your request or response parameter and select Group sessions by this key for it.

You can add several grouping keys, they are tried in specified order - next is tried only if previous did not work. Drag to change the order. You own keys are always tried before the built-in ones.

Example of how grouping keys work

Let us say you have a route login which returns a specific <TOKEN> in response_body → json_doc → hash → token parameter of the response. In the further requests, this <TOKEN> is used somewhere in get → token or post → json_doc → hash → token.

You can configure 3 parameters to be used as grouping keys (for response body, get and post requests). They will be tried in the following order (next is tried only if previous did not work):

1. response_body → json_doc → hash → token

2. get → token

3. post → json_doc → hash → token

4. (built-in set, will be used if none of previous work)

Requests:

• curl example.com -d '{in: 'bbb'}' with response '{token: aaa}' → session "A" (grouping key #1 worked)

• curl example.com -d '{in: 'ccc'}' '{token: 'aaa'}' with response without token → session "A" (grouping key #3 worked)

The same parameter value aaa groups these requests into one session.

Data protection¶

For API Sessions, from node to the Cloud, Wallarm only exports parameters selected by you. If they contain sensitive data, be sure to hash it before exporting. Note that hashing will transform the actual value into unreadable - the presence of parameter and particular but unknown value will provide the limited information for the analysis.

To hash the sensitive parameters, once they are added in Wallarm Console → API Sessions → Session context parameters, select the Hashing (secret) option for them.

Wallarm hashes the selected parameters before export.

Analyzed traffic¶

API Sessions analyze all traffic that Wallarm node is enabled to secure to organize it into sessions. You can contact the Wallarm support team to request limiting analysis to the selected applications/hosts.

Storage period¶

The API Sessions section stores and displays sessions for the last week. The older sessions are deleted to provide an optimal performance and resource consumption.

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send