You are here

Dynamic Value Endorsement (DyVE)

Affects product: 
Airlock WAF
Affects version(s): 

Airlock WAF has a longstanding tradition of promoting dynamic whitelisting technologies, including URL encryption, the cookie store, smart HTML form protection, or ADAPS. The common goal behind these approaches is to infer implicit application APIs and to automatically enforce proper usage by clients, without the need for cumbersome manual WAF configuration.

With the shift towards less standardized technologies, such as JSON or REST, implicit APIs get rare. To overcome these limitations, Airlock WAF 6 offers a new feature called Dynamic Value Endorsement (DyVE). Using DyVE, it is possible to scan JSON objects delivered by back-ends and to dynamically endorse values of selected attributes within a session's scope. Parameters or JSON attributes of subsequent requests (e.g., REST API calls) can then be matched against previously endorsed values.

The feature is currently in prototype status. The functionality and configuration directives may change in future and are not update resistant.

How DyVE Works

DyVE can be enabled globally or per mapping on Airlock WAF. No changes on application side are necessary to protect the application. DyVE extracts a dynamic set of JSON parameter values from HTTP responses and stores hashes of these values in the local session store. Parameters reflected from the client back to the application which must not be modified by the user are identified using pre-defined rule set. If the value of a protected parameter is missing in the local session store the request is blocked. Request parameters are validated independently whether they are sent in a HTTP form POST (x-www-form-urlencoded or multipart), as HTTP query parameters or in a JSON structure.

In a cluster setup all DyVE session information is synched to the partner node to provide high availability in case of failure.


Consider the following balance transfer example in a online banking application:

DyVE Account Transfer Example

Step 1: The application sends one or multiple JSON requests containing account numbers the client can use for a balance transfer.
Step 2: Airlock WAF extracts the account numbers from the JSON structure and stores the values in the session store.
Step 3: The browser renders the account numbers into a drop down list. The client select the beneficiary account.
Step 4: The browser creates a JSON structure with all data describing the balance transfer and submits the JSON structure.
Step 5: Airlock WAF validates the "target_account_id" field using the previously remembered account ids and forwards the request to the server.
Step 6: Now the client (e.g., an attacker) manipulates the JSON structure and changes the "target_account_id" to a new value that was never sent from the server to the client.
Step 7: Airlock WAF blocks this request because the new account id "177-002-99" can not be found in the session store.

DyVE vs. Static White- or Blacklisting

In contrast to static black- or whitelisting DyVE does not only validate the syntax and format of a value but also the concrete value within the context of the current user session. This prevents any kind of injection attacks on protected parameters but also prevents business logic attacks.

Applications Suitable for DyVE

If your application fulfills the following criteria it can be protected by DyVE.

  • Data is transferred from server to client in pure JSON format, i.e. with content type "application/json"
  • Client sends unmodified parameter values from previously received JSON responses back to the server. Such reflected values often appear in drop down lists, check boxes, radio buttons or in hidden fields.


The following configuration steps must be performed to configure DyVE.

  • Enable DyVE on a mapping or globally
  • Configure the JSON parser for HTTP responses
  • Define rules to endorse parameter values from JSON responses
  • Define protected request parameters


DyVE is configured using Security Gate expert settings globally or per mapping context. In this example, DyVE is configured on a specific mapping (tab "Expert Settings").

Enable DyVE

The following SG expert settings enable DyVE on the request and response way respectively.

Response.DynamicValueEndorsement.Enable "TRUE"
Request.DynamicValueEndorsement.Enable "TRUE"

There are two different resources to enable DyVE for the request and response way independently in case values are endorsed on one mapping but enforced on a different one.
Configure the JSON parser for HTTP responses

By default the JSON parser only considers responses with content-type header "application/json". If necessary, this can be changed with the following setting. Note that only valid and pure JSON responses can be handled by the JSON parser.

Response.Json.Parser.ContentType.Pattern       "^application/json$"

Define rules to endorse parameter values from JSON responses

The following rule collects all JSON parameters containing the word "account" in all JSON responses matching the path pattern "/invoice_data". These values are endorsed (dynamic whitelisted) by Airlock WAF and can be used by the client in protected request parameters.

Response.DynamicValueEndorsement.Rule.0.Path.Pattern   "/invoice_data"
Response.DynamicValueEndorsement.Rule.0.Parameter.Name.Pattern "account"
Response.DynamicValueEndorsement.Rule.0.ValueSet 0

It is possible to collect and endorse all JSON values from all JSON responses for testing purposes by defining a wildcard pattern.

Response.DynamicValueEndorsement.Rule.0.Path.Pattern   ".*"
Response.DynamicValueEndorsement.Rule.0.Parameter.Name.Pattern ".*"
Response.DynamicValueEndorsement.Rule.0.ValueSet 0

Note that the format of the JSON parameter names follow the Airlock WAF standard parameter syntax for JSON objects.


The values "Simon" and "Smith" in the following JSON structure can be referenced using the parameter names "#json#name#first" and "#json#name#last".

{ "name" : { "first": "Simon", "last" : "Smith" } }

A detailed description of the Airlock WAF parameter syntax for JSON objects can be found in the section "JSON Filtering" in the Airlock WAF online manual.

Define protected request parameters

The following rule validates all parameters with a name matching the pattern "target_account_id" in all HTTP requests matching the path pattern "/transfer". If the protected parameter value is not found within the value store on Airlock WAF the request will be blocked.

Request.DynamicValueEndorsement.Rule.0.Path.Pattern   "/transfer"
Request.DynamicValueEndorsement.Rule.0.Parameter.Name.Pattern "^target_account_id$"
Request.DynamicValueEndorsement.Rule.0.ValueSet 0

Multiple Rules and Multiple Value Sets

Multiple DyVE rules can be defined by incrementing the rule index (Rule.0, Rule.1, ..., Rule.<N>). The index must be ascending without gaps.

For each DyVe rule a value set is defined which defines where to store endorsed values and lookup values of protected parameters respectively. Multiple value sets can be useful to implement a more fine-grained policy. Assume you want to limit the allowed values for a drop down list to the precise set of values received in a certain JSON response. This can be done by defining a dedicated value set for the corresponding request and response rule.

Logging and Debugging

Blocked requests due to a DyVE rule violation will cause a production log message of the following form.

m:WR-SG-BLOCK-125 c:Y th:BLOCK , parameter "account" with value "01-1234-4" is illegal according to dynamic value endorsementBy setting the log level to "Trace" a log messages for all extracted JSON values is logged.

m:WR-SG-RESP-130 c:Y Value "val9" added to value set 2 due to DyVE rule 2 matching path "/dyve_res/asis/dyve.asis" and parameter name "#json#obj3#arr3#2" on mapping:DynamicValueEndorsement with audit token "-"

Session Size Limit

The maximal size of all collected values per session can be restricted with the following expert setting (value in bytes)

SecurityGateway * DynamicValueEndorsementStoreSize "32768"

Each collected value (hash) occupies 4 bytes in the value store. If the maximal size is reached no further values are saved into the value store and a corresponding production log message is logged. Further requests may be blocked because the protected parameter value is is missing in the value store.

Custom Parameter Naming Scheme

If the parameter naming scheme of your application can be modified, custom pre- or suffixes for parameters to be endorsed and protected by Airlock WAF can be used to reduce the size and complexity of the DyVE rule set. Further the rules must not be modified if the application changes. As a consequence responsibility for a correct policy definition is shifted to the application side.

Knowledge Base Categories: