nevisProxy
As shown in Technical architecture, it is the ICAPFilter that sends the HTTP request of the user to nevisDetect. For a detailed description of the ICAPFilter, see the nevisProxy Reference Guide. The following text discusses different configuration options of the ICAPFilter and its consequences for nevisDetect.
ICAP protocol
ICAP is a lightweight HTTP-like protocol and stands for Internet Content Adaption Protocol (ICAP). The ICAP protocol is generally used to modify an HTTP request or an HTTP response (see the RFC3507 for more details). The following aspects of the ICAP protocol are relevant for the modification of an HTTP request.
- The ICAP client sends an ICAP request containing the encapsulated HTTP request.
- The ICAP server has different options:
- The server modifies the HTTP request. In this case, the server sends back an ICAP response containing the modified HTTP request. The ICAP client uses this modified HTTP request for its further processing. This situation is called ICAP request modification.
- The server returns an HTTP response as reaction to the HTTP request. In this case, the server sends an ICAP response containing the HTTP response. The ICAP client stops processing the HTTP request and sends back the HTTP response. This situation is called ICAP response modification.
- The server does neither modify the HTTP request nor return an HTTP response. In this case, the server sends back an ICAP response with an appropriate status code. This situation is called ICAP no modification.
In the context of nevisDetect, the ICAPFilter of nevisProxy acts as the ICAP client and the FeatureCorrelator component of nevisDetect acts as the ICAP server.
The following sequence diagram shows the propagation of the risk scores from an ICAP point of view:
The diagram below shows the blocking of the HTTP request from a certain user due to a matching policy, again from an ICAP point of view:
The next table lists the possible scenarios:
| nevisDetect scenario | ICAP response |
|---|---|
| Risk score propagation | ICAP request modification |
Matching policy with the NevisProxyActionPlugin and the action PASSTHROUGH | ICAP request modification |
Matching policy with the NevisProxyActionPlugin and the action AUTHENTICATE or BLOCK | ICAP response modification |
| An error in nevisDetect during processing; failopen is "false" | ICAP response modification |
ICAPFilter
In the following table we discuss the configurations attributes of the ICAPFilter and its required values in the context of nevisDetect:
| Configuration attribute | Value | Description |
|---|---|---|
| ScanRequest | true | Only the HTTP request must be passed to nevisDetect. |
| ScanResponse | false | |
| BodyRequired | false | Ensures that also HTTP requests without a body are passed to nevisDetect. |
| BufferRequest | true | Required for the ICAP response modification scenario. |
| RequestBufferSize | Defines the buffer size aligned with the maximum allowed request size of your nevisProxy configuration. | |
| AllowRequestModification | true | See discussion below |
| AllowResponseModification | true | See discussion below |
| PreviewSize | 0 | See discussion below |
| RequestTimeout | Defines how long nevisProxy will wait for an ICAP response from the FeatureCorrelator. The configured value should be greater then the value set in the nevisDetect configuration attribute jms.receiveTimeout, see Common attributes. | |
| PropagateFromEnv | nevisDetect needs information that is not part of the pure HTTP request. A LUA script will collect this information and stores it in the environment of nevisProxy.The configuration below will add the information to the HTTP request headers, which in turn will pass it to the FeatureCorrelator, see example below. | |
| TargetURI | /nevisDetect? AllowResponseModification= true&AllowRequest Modification=true | That values for the query attributes AllowResponseModification and AllowRequestModification must be consistent with the configuration attributes AllowResponseModification and AllowRequestModification. |
| SplittMultipartBody | false | Disables the splitting of multi-part bodies. |
| VerificationMode | optional | Depending on your security requirements, set to "optional" to ensure the transparency of nevisDefect also in case of a disaster. |
| InetAddress | The TCP listener address of the FeatureCorrelator component of nevisDetect, see also: nevisDetect Feature Correlator. |
<init-param>
<param-name>PropagateFromEnv</param-name>
<param-value>
REMOTE_ADDR:X-Client-IP
REMOTE_PORT:X-Client-Port
SERVER_ADDR:X-Server-IP
SERVER_PORT:X-Server-Port
ENTRYPOINTID:X-EntryPointId
RDF_KILL_SESSION:X-KillSession
RDF_REQUESTCOUNT:X-RequestCount
RDF_SESSION_ID:X-HttpSessionId
RDF_SESSION_LASTACCESS_TIME:X-SessionLastAccess
RDF_SESSION_MAX_INACTIVE_INTERVAL:X-SessionMaxInactiveInterval
SSL_SESSION_ID:X-SSLId
bcx.servlet.connection.SSLCiphersUsed:X-SSLCiphersUsed
bcx.servlet.request.TransferID:X-TransferId
REMOTE_USER:X-LoginId
LOGIN_REALM:X-LoginRealm
</param-value>
</init-param>
If the values for the query attributes AllowResponseModification and AllowRequestModification of the TargetURI configuration attribute are not consistent with the configuration attributes AllowResponseModification and AllowRequestModification it can happen that the ICAPFilter unintentionally blocks the HTTP request of a user (for example in case of risk score propagation).
If one of the PropagateFromEnv attributes is missing, the FeatureCorrelator component of nevisDetect stops processing the ICAP request. Depending on the setting for Failopen the HTTP request will be blocked. See also the Status section of the GUI.
Optimizing the ICAPFilter configuration
The configuration of an ICAP filter supports all possible scenarios of nevisDetect. You can either configure a single ICAP and map it to the desired URL name space. In a more advanced setup, several ICAPFilters can be configured and mapped to different URL name subspaces.
In the following we illustrate three typical situations by an example:
Lets consider the following name space of an hypothetical web application:
- /app/images/
- static content like style sheets, images etc.
- no need to mitigate fraudulent HTTP requests
- /app/readonly/
- part of the web application where no transactions can be executed
- no need to mitigate fraudulent HTTP requests
- /app/read-write/
- part of the web application where no transactions can be executed
- need to block fraudulent HTTP requests
We cover that situation by two ICAPFilters, lets call them LowSecurityICAPFilter and HighSecurityICAPFilter:
For the LowSecurityICAPFilter we set the configuration attributes AllowRequestModification and AllowResponseModification to "false". Accordingly, for the configuration attribute TargetURI we set the value /nevisDetect?AllowResponseModification=false&AllowRequestModification=false. Thus, nevisDetect knows that it should act in a read-only mode and can optimize its processing. Additionally, we use the value 0 for the configuration attribute PreviewSize with the effect that only the HTTP headers are passed to nevisDetect. Additional we use a low value like 50 milliseconds for the configuration attribute RequestTimeout.
For the HighSecurityICAPFilter we use a different configuration. We set AllowResponseModification to "true" and AllowRequestModification again to "false" (since we want to block HTTP requests but we do not want to propagate any risk scores). As in the previous example, the TargetURI must be consistent. So we use the value /nevisDetect?AllowResponseModification=true&AllowRequestModification=false. The value of PreviewSize is 0 since the complete HTTP request should be captured. For the RequestTimeout we may use a higher value like 150 milliseconds.
In case of several ICAP filters it must be ensured that only one ICAPFilter is sending an ICAP request to the FeatureCorrelator component of nevisDetect. Otherwise, the same HTTP request of the user will be processed several times, which causes an error within nevisDetect.