icapclient3 1.2.1
Python3 module for creating ICAP clients
Keywords: icap,antivirus

icapclient3
===========

A Python3 module for creating ICAP clients. This is a fork of
https://github.com/vrasneur/icapclient with Python3.X support. The
module API is somewhat inspired by the `httplib`_ python module.

This module is written in pure C, and uses the C-ICAP library to handle
the ICAP protocol.

This branch works with the latest versions of C-ICAP (0.4.x - 0.5.x). If you
are using an older version, check the legacy branch.

What is an ICAP client?
-----------------------

ICAP is a protocol defined in `RFC3507`_. `Errata`_ are available for
the ICAP specification and there is a draft RFC about `ICAP
extensions`_.

It is a client-server protocol that is primarily used to do virus
scanning and content rewriting. E.g. an ICAP client sends a potentially
infected file to the ICAP server. This server does some analysis and
sends back information about the file to the client, such as the
detected virus name. Or a proxy can send content to an ICAP server that
will modify the content and send it back to the proxy.

ICAP is implemented by many antivirus gateways or web proxies. You have
a list of implementations in the `Wikipedia article about ICAP`_ or at
the `ICAP-forum Products page`_.

Requirements
------------

-  Python 3.X
-  the `C-ICAP`_ library, (>= 0.4.x)
-  GCC or clang

Installation
------------

1. Install all the required development packages.

   E.g. on a Debian system, as root :

   .. code:: bash

       # install the Python development stuff
       apt-get install python-dev
       # install the C-ICAP API
       apt-get install libicapapi-dev

2. Build the library, as a normal user

   .. code:: bash

       cd /path/to/icapclient
       python setup.py build

3. Install the library, as root

   .. code:: bash

       python setup.py install

Example
-------

To send files and get the ICAP server response

    .. code:: python

        # import the icap client library
        >>> import icapclient
        # for pretty printing
        >>> from pprint import pprint
        # create an ICAP connection, default port is 1344
        >>> conn = icapclient.ICAPConnection('192.168.1.5')
        # check that the ICAP server recognizes the EICAR virus test file
        # send a REQMOD request, default url is '/' and default service is 'avscan'
        # specify another service explicitly if you are using "eset" for example
        >>> conn.request('REQMOD', '/home/vincent/malwares/eicar.txt', service="avscan")
        # get the server response
        >>> resp = conn.getresponse()
        # get the ICAP response status code
        >>> resp.icap_status
        200
        # get the ICAP response reason string
        >>> resp.icap_reason
        'OK'
        # print the ICAP response headers
        # they are a list of (name, value) tuples
        >>> pprint(resp.icap_headers)
        [('Server', 'C-ICAP/0.3.4'),
         ('Connection', 'keep-alive'),
         ('ISTag', 'CI0001-xhZPmAmHArrMLzamxkH5CwAA'),
         ('X-Infection-Found', 'Type=0; Resolution=2; Threat=Eicar-Test-Signature;'),
         ('Encapsulated', 'res-hdr=0, res-body=108')]
        # get a specific header value
        # here, check if a virus has been found
        # Note that "x-infection-found" is a draft and not all antiviruses implement it.
        # For example, Eset NOT 32 does not.
        # Sometimes you should look inside the incapsulated HTTP response.
        >>> resp.get_icap_header('x-infection-found')
        'Type=0; Resolution=2; Threat=Eicar-Test-Signature;'
        # get the first line of the encapsulated HTTP request
        >>> resp.http_req_line
        'POST / HTTP/1.1'
        # get the first line of the encapsulated HTTP response
        >>> resp.http_resp_line
        'HTTP/1.0 403 Forbidden'
        # okay, test files are great, but try with a real PDF exploit
        # send the REQMOD request and reuse the socket
        >>> conn.request('REQMOD', '/home/vincent/malwares/exploit.pdf')
        # get the ICAP response
        >>> resp = conn.getresponse()
        # the response is OK
        >>> resp.icap_status
        200
        >>> resp.icap_reason
        'OK'
        # pretty-print the ICAP response headers
        >>> pprint(resp.icap_headers)
        [('Server', 'C-ICAP/0.3.4'),
         ('Connection', 'keep-alive'),
         ('ISTag', 'CI0001-xhZPmAmHArrMLzamxkH5CwAA'),
         ('X-Infection-Found', 'Type=0; Resolution=2; Threat=Exploit.PDF-28560;'),
         ('Encapsulated', 'res-hdr=0, res-body=108')]
        # does the request contain a PDF exploit? yes
        >>> resp.get_icap_header('x-infection-found')
        'Type=0; Resolution=2; Threat=Exploit.PDF-28560;'
        >>> resp.http_resp_line
        'HTTP/1.0 403 Forbidden'
        # try a REQMOD request with a file with no malware in it
        >>> conn.request('REQMOD', '/home/vincent/files/normal.txt')
        >>> resp = conn.getresponse()
        >>> resp.icap_status
        200
        >>> resp.icap_reason
        'OK'
        >>> pprint(resp.icap_headers)
        [('Server', 'C-ICAP/0.3.4'),
         ('Connection', 'keep-alive'),
         ('ISTag', 'CI0001-xhZPmAmHArrMLzamxkH5CwAA'),
         ('Encapsulated', 'req-hdr=0, req-body=124')]
        # no virus or malware found
        >>> resp.get_icap_header('x-infection-found') is None
        True
        # close the ICAP connection
        >>> conn.close()

To enable the verbose mode:

    .. code:: python

        >>> import icapclient
        >>> icapclient.set_debug_stdout(True)
        >>> icapclient.set_debug_level(10)

.. _httplib: https://docs.python.org/2/library/httplib.html
.. _RFC3507: http://tools.ietf.org/html/rfc3507
.. _Errata: http://www.measurement-factory.com/std/icap/
.. _ICAP extensions: https://tools.ietf.org/html/draft-stecher-icap-subid-00
.. _Wikipedia article about ICAP: http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol
.. _ICAP-forum Products page: http://www.icap-forum.org/icap?do=products
.. _C-ICAP: http://c-icap.sourceforge.net