Content inspection callout

When a Citrix ADC appliance sends an ICAP request, the ICAP server uses a status code to specify the response status and the action to be taken by the ICAP client (Citrix ADC appliance). For example, if the status code in an ICAP response is 200 OK for a REQMOD ICAP request and if res-hdr is set, then the ICAP client can send the received response from the ICAP server to the user. But, if the res-hdr is not set, then the ICAP client (Citrix ADC appliance) can forward the original or adapted request to the origin back-end server.

But in certain scenarios, the ICAP server cannot take the final decision. Instead it only provides the requested information to the appliance and the appliance can decide based on policy evaluation. In this case, ICAP client cannot depend only on the ICAP response status code, instead it looks at the received ICAP headers and evaluates the policy expression on the headers and applies the associated action.

Following are some use cases where ICAP content Inspection callout is needed:

  • On receiving the SSH handshake request, ICAP client (Citrix ADC appliance) might classify the accessed domain and decide whether to continue the handshake or drop it.
  • On receiving an HTTP request for a service, the appliance might check the access permission for an external server based on the tenant ID of the user and take the appropriate action.

In both the scenarios, the ICAP server does not have any idea about the configured policy based on the available information, instead it just sends back the requested information to the appliance. The appliance then applies the policy on the received response information and applies the associated action. The ICAP content inspection callout is added to the ICAP framework to return the request information from an external ICAP server. The functionality of this callout is very much similar to how an HTTP callout works. Any policy expression, for example, Responder or AppFirewall can trigger the ICAP request to the configured ICAP server. The requested information, configured through returnExpr, is then extracted from the ICAP response and passed to the requested module

The ICAP content inspection callout is added to the ICAP framework to return the request information from an external ICAP server. The functionality of this callout is very much similar to how an HTTP callout works. The ICAP module can use an existing Advanced policy expressions can be used to trigger an ICAP callout to the configured ICAP server

Content inspection callout policy expression

The following content inspection policy expression is used as the return expression in the ICAP callout. The syntax of this content inspection callout expression is similar to an HTTP callout expression.

SYS.CI_CALLOUT(<ContentInspection callout name>).Operator

Where, <ContentInspection callout name> is the ContentInspection callout of type ICAP that defines the properties of the ICAP server and the ICAP Profile to be used to send and receive the request to/from the ICAP server. The return type of the response from the ICAP callout agent determines the set of operators that you can use on the response. If the part of the response that you want to analyze is text, you can use a text operator to analyze the response. For example, you can use the CONTAINS(<string>) operator to check whether the specified portion of the response contains a particular string.

Example:

SYS.CI_CALLOUT(CI-callout).contains(“value to be checked”)

Configuring ICAP content inspection callout

Complete the following steps to configure ICAP content inspection callout on your appliance.

  1. Add ICAP profile
  2. Add content inspection callout
  3. set content inspection callout expression
  4. Invoke content inspection callout

Add ICAP profile

Add content inspection callout

The ContentInspectioncCallout command specifies the ICAP server information and the return expression and its type.

At the command prompt, type:

add contentInspection callout <name> -type ICAP [-profileName <string>] (-serverName <string> | (-serverip <ip_addr|ipv6_addr> [-serverport <positive_integer>])) [-returnType <returnType>] [-resultExpr <string>] [-comment <string>]

Where:

<profileName> - Name of the ICAP Profile <returnType> - ( BOOL | NUM | TEXT ) <resultExpr> - Expression to be evaluated on receiving the ICAP response, must start with ICAP.RES.

Example:

To extract the value of the X-URL-Category ICAP response header, the resultExpr can be specified as shown below.

add contentInspection callout cic –type ICAP –profileName profile1 –resultExpr “ICAP.RES.HEADER("X-URL-Category")”

The above expression returns the value of the X-URL- checks the return value and apply the associated action.

Feature policy using content inspection callout and feature action

When a Citrix ADC feature need to interact with an external service using ICAP, the feature can use the content inspection callout, CI_CALLOUT. In this mode, the feature uses the CI_CALLOUT in the feature policy expression to trigger the ICAP request to the external ICAP server. On receiving the response, the feature can specify the resultExpression in the ContentInspection action to extract the required information from the ICAP response. The result can be Boolean, numeric or text. The feature then can take the associated action based on the extracted result. Let’s see an use case of how the feature policies using CI Callout to take the feature action.

Use case 1: To extract SNI using Video Optimization detection policy and drop the handshake if the domain is “Social Media”

Complete the following steps to configure the use case:

  1. Add ICAP profile

    add icapProfile ICAPProfileName –mode REQMOD -insertHTTPRequest q{ "GET / HTTP/1.1\r\nHost: " + CLIENT.SSL.DETECTED_DOMAIN + "\r\n\r\n"}

  2. Add content inspection callout representing the ICAP server and the result expression to extract category information from the ICAP response.

    add contentInspection callout cic -type ICAP -serverName icap-server-name -icapProfile ICAPProfileName -resultExpr "ICAP.res.header("X-URL-Category")" –resultType [same as callout resultType]

  3. Add video detection policy and expression to fetch the URL category information for received domain and drop the request if the category is “Social Media”.

    add videooptimization detectionpolicy policy_urlcat -rule " SYS.CI_CALLOUT(cic).EQ(\"Social Media\")" -action DROP

Use case 2: To retrieve the URL category from the ICAP server and block it using a pattern set

Complete the following steps to configure the use case:

  1. Add ICAP Profile that defines the mode and the HTTP Request.

    add icapProfile ICAPProfileName –mode REQMOD -insertHTTPRequest q{ "GET / HTTP/1.1\r\nHost: " + CLIENT.SSL.DETECTED_DOMAIN + "\r\n\r\n"}

  2. Add a Content Inspection callout to fetch the Category information.

    add contentInspection callout cic -type ICAP -serverName icap-server-name -icapProfile ICAPProfileName -resultExpr "ICAP.res.header("X-URL-Category")"

  3. Add a pattern set and bind the blocked category pattern to it.

    add policy patset blocked-category bind policy patset blocked-category “gambling” –index 1 bind policy patset blocked-category “social media” –index 2 bind policy patset blocked-category “games” –index 3

  4. Add a video optimization detection policy to invoke the ICAP callout and take action.

    add videooptimization detectionpolicy policy_urlcat –rule SYS.CI_CALLOUT(cic).CONTAINS_ANY("blocked-category")" -action DROP