Item10700: initial checkin

git-svn-id: http://svn.foswiki.org/trunk/ClamAVScanPlugin@11613 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

data/System/ClamAVScanPlugin.txt

@@ -0,0 +1,120 @@
+%META:TOPICPARENT{name="Plugins"}%
+<!--
+One line description, required for extensions repository catalog.
+   * Set SHORTDESCRIPTION = Scans attachments for viruses during upload using <nop>ClamAV
+-->
+<div style="float:right">
+<img src="%ATTACHURLPATH%/ClamAVScanLogo.png" alt="ClamAV Scan Plugin Logo" title="ClamAVScanPlugin Logo" /> 
+</div>
+
+---+!! <nop>ClamAV Scan Plugin
+
+%SHORTDESCRIPTION%
+
+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
+
+<noautolink>
+<blockquote class="foswikiHelp">
+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.
+</blockquote>
+</noautolink>
+
+---++ 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.
+
+---+++ =%<nop>CLAMAVSTATUS%=
+
+This macro returns status information from the =clamd= daemon.  Or reports any
+failure messages if unable to connect to the clamd socket.
+
+%CLAMAVSTATUS{}%
+
+---+++ Scanning existing attachments.
+
+The current attachments and attachment rcs files 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.
+
+All attachments are scanned.  There is no facility to request scan of an
+individual attachment.
+
+This operation is restricted to users in the Admin group
+.
+%SCRIPTURL{rest}%/ClamAVScanPlugin/scan/Web/Topic
+
+---+++ 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.
+
+[[%SCRIPTURL{rest}%/ClamAVScanPlugin/reload][Reload Signatures]]
+
+---++ Preferences
+
+This plugin does not use any preferences.  All configuration is done using
+[[%SCRIPTURL{"configure"}%][%ICON{"wrench"}% configure]]
+
+---++ Installation
+%$INSTALL_INSTRUCTIONS%
+
+%X% *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:
+<!--
+   * Set CC = &#58;&#58;
+-->
+
+   $ ==$Foswiki%CC%cfg{Plugins}{ClamAVScanPlugin}{clamdPort}==: The unix socket used to communicate with the =clamd= daemon.  Defaults to =/tmp/clamd=
+
+   $ ==$Foswiki%CC%cfg{Plugins}{ClamAVScanPlugin}{mandatoryScan}==: Should attachments 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%CC%cfg{Plugins}{ClamAVScanPlugin}{scanTopics}==: !ClamAV can perform HTML scanning for certain embedded script threats.  It can also perform "Data Loss Prevention".  When DLP 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.
+
+<div class="foswikiAlert">
+*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 %ATTACHFILESIZELIMIT% in this web, this value can be set per web.
+</div>
+
+---++ Info
+
+*Note:* The module =Foswiki::Plugins::ClamAVScanPlugin::ClamAV= module is based upon the CPAN module =File::Scan::ClamAV=.  Copyright information from that module:
+<verbatim>
+AUTHOR
+  Colin Faber <cfaber@fpsn.net> All Rights Reserved.
+  Originally based on the Clamd module authored by Matt Sergeant.
+
+LICENSE
+  This is free software and may be used and distribute under terms of perl itself.
+</verbatim>
+
+|  Author: | GeorgeClark |
+|  Copyright: | &copy; 2011, Foswiki Contributors |
+|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
+|  Release: | %$RELEASE% |
+|  Version: | %$VERSION% |
+|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
+|  1.0.0 (XX Mmm 20XX): | Initial version |
+|  Home: | http://foswiki.org/Extensions/%TOPIC% |
+|  Support: | http://foswiki.org/Support/%TOPIC% |
+

data/System/VarCLAMAVSTATUS.txt

@@ -0,0 +1,7 @@
+%META:TOPICINFO{author="ProjectContributor" date="1297235055" format="1.1" version="$Rev$"}%
+%META:TOPICPARENT{name="ClamAVScanPlugin"}%
+#VarCLAMAVSTATUS
+---+++ CLAMAVSTATUS -- report !ClamAV availability and version
+   * The =%<nop>CLAMAVSTATUS{}%= variable is handled by the ClamAVScanPlugin
+   * Syntax: =%<nop>CLAMAVSTATUS{}%=
+   * Related: ClamAVStatusPlugin

lib/Foswiki/Plugins/ClamAVScanPlugin.pm

@@ -0,0 +1,239 @@
+# See bottom of file for default license and copyright information
+
+=begin TML
+
+---+ package Foswiki::Plugins::ClamAVScanPlugin
+
+This plugin will pass topic data and attachments to clamd for scanning by ClamAV
+
+
+=cut
+
+package Foswiki::Plugins::ClamAVScanPlugin;
+
+# Always use strict to enforce variable scoping
+use strict;
+use warnings;
+
+use Foswiki::Func    ();    # The plugins API
+use Foswiki::Plugins ();    # For the API version
+use Foswiki::Plugins::ClamAVScanPlugin::ClamAV;
+
+our $VERSION           = '$Rev$';
+our $RELEASE           = '1.0.0';
+our $SHORTDESCRIPTION  = 'Scans attachments for viruses during upload';
+our $NO_PREFS_IN_TOPIC = 1;
+
+my $clamdPort;              # Unix socket used to communicate with clamd daemon
+
+=begin TML
+
+---++ ClassMethod initPlugin($topic, $web, $user) -> $boolean
+
+=cut
+
+sub initPlugin {
+    my ( $topic, $web, $user, $installWeb ) = @_;
+
+    # check for Plugins.pm versions
+    if ( $Foswiki::Plugins::VERSION < 2.0 ) {
+        Foswiki::Func::writeWarning( 'Version mismatch between ',
+            __PACKAGE__, ' and Plugins.pm' );
+        return 0;
+    }
+
+    # Socket used to communicate with clamd daemon
+    $clamdPort = $Foswiki::cfg{Plugins}{ClamAVScanPlugin}{clamdPort}
+      || '/tmp/clamd';
+
+    # Register status tag - reports information on the clamdscan connection
+    Foswiki::Func::registerTagHandler( 'CLAMAVSTATUS', \&_CLAMAVSTATUS );
+
+    # Request clamd to reload the virus signatures
+    Foswiki::Func::registerRESTHandler( 'reload', \&reloadSignatures );
+
+    # Request clamd to scan the attachments of a topic
+    Foswiki::Func::registerRESTHandler( 'scan', \&scanAttachments );
+
+    # Plugin correctly initialized
+    return 1;
+}
+
+=begin TML
+
+---++ ClassMethod _CLAMAVSTATUS() -> $string
+
+Registered Handler: Implements the CLAMAVSTATUS macro. Returns the status string.
+
+=cut
+
+sub _CLAMAVSTATUS {
+
+    my $report = "*<nop>ClamAV Status* \n";
+
+    $report .= "   * Connecting to socket ==$clamdPort== \n";
+
+#return $report .= "      * <span class=\"foswikiAlert\"> %X% *FAIL* socket does not exist </span>" unless (-e $clamdPort);
+
+    my $av =
+      new Foswiki::Plugins::ClamAVScanPlugin::ClamAV( port => "$clamdPort" );
+    return $report .= "      * Error string " . $av->errstr() . "\n"
+      if ( $av->errstr() );
+
+    if ( $av->ping ) {
+        $report .= "      * *PING Success* - clamd alive\n";
+    }
+    else {
+        return $report .=
+            "      * <span class=\"foswikiAlert\"> *PING failed* "
+          . $av->errstr()
+          . "</span> \n";
+    }
+
+    my $version = $av->version();
+    chomp $version;
+    $report .=
+      "      * *Version:* <noautolink><code>$version</code></noautolink>\n";
+    $report .=
+      "      * *Mandatory Scan* - Upload denied unless !ClamAV is available.\n"
+      if $Foswiki::cfg{Plugins}{ClamAVScanPlugin}{mandatoryScan};
+    $report .= "      * *Topic Scans* - Topic text scanned for threats.\n"
+      if $Foswiki::cfg{Plugins}{ClamAVScanPlugin}{scanTopics};
+
+    return $report;
+}
+
+=begin TML
+
+---++ ClassMethod beforeUploadHandler() -> $boolean
+
+Intercepts the newly uploaded attachment before it has been stored in Foswiki.
+
+Passes the stream to clamd for scanning.  Throws an exception under two conditions:
+   * clamd daemon is not available, and mandatoryScan requested
+   * clamd reported a threat in the file.
+
+=cut
+
+sub beforeUploadHandler {
+    my ( $attrs, $meta ) = @_;
+
+    my $av =
+      new Foswiki::Plugins::ClamAVScanPlugin::ClamAV( port => "$clamdPort" );
+    unless ( $av->ping ) {
+        return unless $Foswiki::cfg{Plugins}{ClamAVScanPlugin}{mandatoryScan};
+        throw Foswiki::OopsException(
+            'clamavattach',
+            def    => 'clamav_offline',
+            params => [ $attrs->{name} ]
+        );
+    }
+
+    my ( $ok, $virus ) = $av->scan_stream( $attrs->{stream} );
+
+    if ( $ok eq 'FOUND' ) {
+        Foswiki::Func::writeEvent("ClamAV","$virus detected in attachment $attrs->{name} - Upload blocked.");
+        throw Foswiki::OopsException(
+            'clamavattach',
+            def    => 'clamav_upload',
+            params => [ $attrs->{name}, $virus ]
+        );
+    }
+
+    return 1;
+}
+
+=begin TML
+
+---++ ClassMethod beforeSaveHandler() -> $boolean
+
+Intercepts an upated topic prior to save.
+
+Passes the topic text to clamd for scanning.  Throws an exception:
+   * scanTopics requested and clamd reported a threat in the file.
+
+=cut
+
+sub beforeSaveHandler {
+    my ( $text, $topic, $web, $meta ) = @_;
+
+    return unless $Foswiki::cfg{Plugins}{ClamAVScanPlugin}{scanTopics};
+
+    my $av =
+      new Foswiki::Plugins::ClamAVScanPlugin::ClamAV( port => "$clamdPort" );
+
+    my ( $ok, $virus ) = $av->scan_string($text);
+
+    if ( $ok eq 'FOUND' ) {
+        Foswiki::Func::writeEvent("ClamAV","$virus detected in topic text during save - Save blocked.");
+        throw Foswiki::OopsException( 'clamavsave', params => [$virus] );
+    }
+
+    return 1;
+}
+
+=begin TML
+
+---++ ClassMethod reloadSignatures($session) -> $text
+
+Implements the rest handler "reload"
+
+Force a reload of the antivirus signatures.
+This function is only available to administrators.
+
+=cut
+
+sub reloadSignatures {
+    my ( $session, $subject, $verb, $response ) = @_;
+
+    return "Not authorized" unless Foswiki::Func::isAnAdmin();
+    Foswiki::Func::writeEvent("ClamAV","Signature reload requested.");
+    my $av =
+      new Foswiki::Plugins::ClamAVScanPlugin::ClamAV( port => "$clamdPort" );
+    unless ( $av->ping ) {
+        return "clamd not available: " . $av->errstr();
+        }
+    $av->reload();
+
+    return "Reload of ClamAV virus signatures requested\n";
+}
+
+=begin TML
+
+---++ ClassMethod scanAttachments($session) -> $text
+
+Implements the rest handler "scan"
+
+Performs a virus scan of all attachment for a topic.
+This function is only available to administrators.
+
+=cut
+
+sub scanAttachments {
+    my ( $session, $subject, $verb, $response ) = @_;
+
+    return "Not authorized" unless Foswiki::Func::isAnAdmin();
+    return "SCAN initiated for $subject \n\n";
+}
+1;
+
+__END__
+Foswiki - The Free and Open Source Wiki, http://foswiki.org/
+
+Author: GeorgeClark
+
+Copyright (C) 2008-2011 Foswiki Contributors. Foswiki Contributors
+are listed in the AUTHORS file in the root of this distribution.
+NOTE: Please extend that file, not this notice.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version. For
+more details read LICENSE in the root of this distribution.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+As per the GPL, removal of this notice is prohibited.