.. _icap-plugin: .. include:: ../../common.defs ICAP Plugin *********** .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 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 ------------ This plugin is only built if the configure option :: --enable-experimental-plugins is given at build time. 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): .. code-block:: text 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 |TS| 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: .. code-block:: text 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: .. code-block:: text 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.