ClamAV Scan Plugin

Scans attachments for viruses, malware and other threats during upload

This plugin intercepts each attachment during upload and passes the content of the attachment to the clamd daemon for virus scanning. The attachment is only saved if the virus scan does not detect any threats.

From the description of ClamAV at http://www.clamav.net

ClamAV is an open source (GPL) antivirus engine designed for detecting Trojans, viruses, malware and other malicious threats. It is the de facto standard for mail gateway scanning. It provides a high performance mutli-threaded scanning daemon, command line utilities for on demand file scanning, and an intelligent tool for automatic signature updates. The core ClamAV library provides numerous file format detection mechanisms, file unpacking support, archive support, and multiple signature languages for detecting threats.

Usage

No changes to existing topics are required by this plugin. Once the plugin is enabled, attachments will be scanned during upload. If a virus or other threat is detected, the upload will thow an exception, and the attachment will not be saved. The scan is performed before the attachment is saved to disk.

This plugin is also able to scan the topic text prior to save. This enables scanning for embedded MS Script encoded threats and for certain sensitive data formats such as credit card numbers and social security numbers. See the ClamAV documentation on HTML scanning and the Data Loss Prevention (DLP) module for further information.

%CLAMAVSTATUS%

This macro returns status information from the clamd daemon. Or reports any failure messages if unable to connect to the clamd socket. This information is only displayed for administrators.

%CLAMAVSTATUS{}%

Scanning existing attachments.

The current attachments and attachment rcs ,v files of an existing topic can be scanned using a rest handler. Each attachment and corresponding rcs file if it exists is passed to clamd for scanning. Results of the scan are reported back in the rest results. There is no facility to request scan of an individual attachment. The scan is done by reading the contents of the directory. The attachment API is not used.

The rest handler takes two parameters:

Parameter	Usage	Default
topic	The Web.Topic used as the BASEWEB.BASETOPIC.	System default topic
scan	The Web.Topic name that will be subject of the attachment scan.	topic

This operation is restricted to users in the Admin group.

Web interface:

Shell interface

   cd [Foswiki/bin] directory
   ./rest /ClamAVScanPlugin/scan -scan System.PatternSkin

Reloading the Virus Signatures.

This plugin includes a rest handler to force reload of the virus signatures. This operation is restricted to users in the Admin group. The plugin sends a command to the clamd daemon to request the reload.

Note that reloading the signatures does not download newer signatures from ClamAV. It only reloads the existing signature files into the clamd daemon.

Preferences

This plugin does not use any preferences. All configuration is done using configure

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Note: This plugin depends upon a properly configured and operational version of the clamd daemon. Actual scans are executed by the clamd daemon. ClamAV must be local to the Foswiki system.

Configuration

This plugin uses the following settings:

$Foswiki::cfg{Plugins}{ClamAVScanPlugin}{clamdPort}

The unix socket used to communicate with the clamd daemon. Defaults to /tmp/clamd

$Foswiki::cfg{Plugins}{ClamAVScanPlugin}{mandatoryScan}

Should attach be blocked if clamd is unavailable to scan attachments. If this option is enabled, any attempt to attach a file will result in an error when clamd is not available. Default is disabled - Attachments will be added without scanning if clamd is unavailable.

$Foswiki::cfg{Plugins}{ClamAVScanPlugin}{scanTopics}

ClamAV can perform HTML scanning for certain embedded script threats. It can also perform "Data Loss Prevention". When StructuredDataDetection is enabled in clamd.conf, it will detect certain data such as social security numbers and credit card numbers in content. Default is disabled. Enable this option to perform scanning of topic data for structured data and embedded HTML threats. If a threat is detected, ClamAV will block the topic save.

$Foswiki::cfg{Plugins}{ClamAVScanPlugin}{forceFilename}

Force scan by Filename instead of passing an open file handle to the backend.

Dependencies

Name	Version	Description
File::Find	>=0	required for lib/Foswiki/Plugins/ClamAVScanPlugin/ClamAV.pm
IO::Socket	>=0	required for lib/Foswiki/Plugins/ClamAVScanPlugin/ClamAV.pm
Socket::PassAccessRights	>=0	optional passes file descriptors to clamd for access rights

Note: Socket::PassAccessRights is "optional" however on most systems this module will be required for correct operation. The clamd daemon must have full access to each scanned file. This module allows a file descriptor to be passed to clamd ensuring full access. If this module is not installed, the file name will be passed to the clamd daemon. If insufficient rights are available, the scan will fail. (On Foswiki 1.1, scans during attachment upload will still work, as the stream is passed to clamd. On Foswiki 1.0, the temporary file name will be passed resulting in possible access rights issues.)

Debugging

A TRACE constant can be enabled in lib/Foswiki/Plugins/ClamAVScanPlugin.pm and lib/Foswiki/Plugins/ClamAVScanPlugin/ClamAV.pm for detailed debug logging.

If ClamAV is reporting that it is unable to read the files, check several things:

• Ensure that Socket::PassAccessRights is installed. If not availabe,
• Ensure that file permissions allow all attachments to be read by the clamd backend task.
• If your system uses AppArmor, be sure that the permissions allow AppArmor to read the web attachments. /etc/apparmor.d/local/usr.sbin.clamd should have a line to pemit read of attachments, such as:

   /var/www/foswiki/pub/** r

Info

Change History:
1.2 (31 Aug 2016)	Foswikitask:Item14149 Update for Foswiki 2.0+: - Add configuration to set forceFilename scanning. - Change REST calls to require POST and validation - Support utf-8 / Unicode web, topic and attachment names.
1.1.0 (13 June 2011)	Foswikitask:Item10835 Add backwards compatibility with Foswiki 1.0
1.0.1 (11 May 2011)	Foswikitask:Item10700 Initial version