ICAP Plugin

Note: As of ATS v10.0.0, this plugin is deprecated and unsupported.

The ICAP plugin enables passing along the response header and body to an external server for additional processing (generally scanning) using the ICAP protocol. The scanner, depending on whether the file contains malicious content, will return a transformed version of the file. If the file is clean, then the exact same file will be returned. Otherwise, the scanner will block the file and return a message containing information regarding the infection.

Installation

To make this plugin available, you must enable experimental plugins when building Traffic Server by passing the -DBUILD_EXPERIMENTAL_PLUGINS=ON to the cmake command when building.

To use this plugin, you need to compile the plugin and add the following line in plugin.config (assuming the compiled plugin library is called icap_plugin.so):

icap_plugin.so scanner_server_ip scanner_server_port avoid_port debug_enable

There are 4 parameters to this plugin: the scanner_server_ip and scanner_server_port (standard ICAP port is 1344) is required to initiate connection to the ICAP server, and the avoid_port is specified to avoid processing traffic that appears on particular ports (e.g, requests passed via the parent select and already checked). Parameter debug_enable will enable debug mode, which, in cases of ICAP server connection error or ICAP server too busy to handle the request, will return the origin response body to the client instead of an error message.

ICAP

ICAP is a light-weight protocol for executing a remote procedure call on HTTP messages. It is very handy to request transformations on HTTP requests and responses since ICAP servers are set up on the edge of the Internet. Therefore, ICAP has become an industry standard for Anti Virus service.

Virus Scanning via ICAP

Performing virus scanning via ICAP has several advantages over the traditional local host virus scanner deployment model. By performing virus scanner on a remote server, local resources are not used, allowing the main thread on the server be more performant. ICAP servers are frequently deployed on the edge near Traffic Server proxies, adding minimal latency on file transmission.

Plugin Design

The plugin is a transform plugin that is called on READ_RESPONSE_HDR_HOOK. Upon initiating the transform, the plugin will initiate a socket connection to the scanner server. Once the connection is made successfully, the plugin will formulate an ICAP request header, and send it out along with the response body from origin server. Since ICAP requires chunked transfer-encoding for transmitting body, the request sending to the scanner server should take the following form:

RESPMOD icap://127.0.0.1/avscan ICAP/1.0
Host: 127.0.0.1
Encapsulated: req-hdr=0, res-hdr=137, res-body=296

GET /origin-resource HTTP/1.1
Host: www.origin-server.com
Accept: text/html, text/plain, image/gif
Accept-Encoding: gzip, compress

HTTP/1.1 200 OK
Date: Mon, 10 Jan 2000 09:52:22 GMT
Server: Apache/1.3.6 (Unix)
ETag: "63840-1ab7-378d415b"
Content-Type: text/html
Content-Length: 51

33
This is data that was returned by an origin server.
0

After finishing sending the message, the plugin will receive the returned message from the scanner and try to determine the action to take. ICAP's response message takes the following form:

ICAP/1.0 200 OK
Date: Mon, 10 Jan 2000  09:55:21 GMT
Server: ICAP-Server-Software/1.0
Connection: close
ISTag: "W3E4R7U9-L2E4-2"
Encapsulated: res-hdr=0, res-body=222

HTTP/1.1 200 OK
Date: Mon, 10 Jan 2000  09:55:21 GMT
Via: 1.0 icap.example.org (ICAP Example RespMod Service 1.1)
Server: Apache/1.3.6 (Unix)
ETag: "63840-1ab7-378d415b"
Content-Type: text/html
Content-Length: 95

5f
This is data that was returned by an origin server, but with
value modified by an ICAP server.
0

In case of virus detected, the scanner will include fields like "X-Infection-Found" and "X-Violations-Found" in the ICAP response header. Therefore, by evaluating the ICAP header, if infection headers are found, then plugin will discard the HTTP response header from the origin server and use the HTTP header returned by ICAP server to generate the response header. Otherwise, the file is clean, in which case headers will not be modified. Once finished reading headers, the plugin proceeds to read the message body, which is, if file is clean, an exact copy of the response from origin server or, if file is bad, an error message generated by scanner server.

Scanner Server

We have tested with the Symantec Protection Engine. We have also tested with the open-source ICAP server C-ICAP with the ClamAV scanning module.

Limitations

In the current version, the plugin only supports IPv4 addressing from the plugin to the ICAP server.

The plugin only processes responses. It could be extended to also support passing the request headers and bodies to ICAP servers for processing.