TIP ClamAVScanPlugin is not installed on Foswiki.org.

ClamAV Scan Plugin Logo

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

Note that the extensions does not scan subdirectories of the attachment directory. If Foswiki is configured for the PlainFileStore, then attachment history will not be scanned.

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 wrench 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.

ALERT! 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.
Caution: In addition to these settings, the clamd.conf setting StreamMaxLength needs to be large enough to accommodate the largest Foswiki setting for ATTACHFILESIZELIMIT. Currently 100000 in this web, this value can be set per web.

Dependencies

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

Note: ALERT! 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

PackageForm edit

Author GeorgeClark
Version 1.2
Release 31 Aug 2016
Description Scans attachments for viruses, malware and other threats during upload
Copyright © 2011-2016, George Clark, Foswiki Contributors

Module Foswiki::Plugins::ClamAVScanPlugin::ClamAV is based upon the CPAN module File::Scan::ClamAV
Copyright Colin Faber All Rights Reserved.
Originally based on the Clamd module authored by Matt Sergeant.
License GPL (GNU General Public License). Foswiki::Plugins::ClamAVScanPlugin::ClamAV is licensed under the terms of Perl itself.
Home http://foswiki.org/Extensions/ClamAVScanPlugin
Support http://foswiki.org/Support/ClamAVScanPlugin
Repository https://github.com/foswiki/ClamAVScanPlugin
ExtensionClassification Admin, Data and Files, Security
ExtensionType PluginPackage
Compatibility Foswiki 1.0, 1.1 and 2.x Not tested on Windows.
IncompatibleWith
ImageUrl ClamAVScanLogo.png
DemoUrl http://
SupportUrl ClamAVScanPlugin
ModificationPolicy CoordinateWithAuthor
NewsFlash
Topic attachments
I Attachment Action Size Date Who Comment
ClamAVScanPlugin.md5md5 ClamAVScanPlugin.md5 manage 171 bytes 07 Sep 2016 - 00:21 GeorgeClark  
ClamAVScanPlugin.sha1sha1 ClamAVScanPlugin.sha1 manage 195 bytes 07 Sep 2016 - 00:21 GeorgeClark  
ClamAVScanPlugin.tgztgz ClamAVScanPlugin.tgz manage 66 K 07 Sep 2016 - 00:20 GeorgeClark  
ClamAVScanPlugin.zipzip ClamAVScanPlugin.zip manage 74 K 07 Sep 2016 - 00:20 GeorgeClark  
ClamAVScanPlugin_installerEXT ClamAVScanPlugin_installer manage 5 K 07 Sep 2016 - 00:20 GeorgeClark  
Topic revision: r2 - 07 Sep 2016, GeorgeClark - This page was cached on 09 Dec 2016 - 03:33.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License