Skip to main content

Python3 module for creating ICAP clients

Project description

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 :

    # 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

    cd /path/to/icapclient
    python setup.py build
    
  3. Install the library, as root

    python setup.py install
    

Example

To send files and get the ICAP server response

# 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:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
icapclient3-1.1.2.tar.gz (10.0 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page