General developer forum

Sorry to keep posting about this whole Clam Anti Virus integration thing, I thought maybe someone might be interested in reading the specification for the patches provided in this thread: http://moodle.org/mod/forum/discuss.php?d=11695

(Pretty OpenOffice document at http://nzvle.eduforge.org/clam/clam_moodle_integration.sxw or keep reading)
--------------------------------------
MOODLE INTEGRATION WITH CLAM ANTIVIRUS

1.New Configuration parameters

There are four new configuration parameters, defined in admin/config.html:

a. runclamonupload
This just defines whether to run clam on uploads or not.
b. pathtoclam
The path to clamscan or clamdscan. If runclamonupload is set to yes and this is wrong, clamfailureonupload will determine how the system will act.
c. quarantinedir
The directory to act as the quarantine area for infected files. This needs to be writable by www-data. If it is left empty, or is invalid, the files will be deleted.
d. clamfailureonupload
This determinds how the system should behave if clam is set to run on upload and fails, either because pathtoclam is wrong, or clam is misconfigured somehow. The options are to treat all files as though they are viruses (this is dangerous if quarantinedir is empty or invalid), or treat files as ok, which will let users upload files. In either case, administrators are emailed a notification that moodle-clam integration is misconfigured:

i. If clamfailureonupload is set to treat files as viruses:

Moodle is configured to run clam on file upload, but the path supplied to Clam AV, /usr/bin/clamdscana, is invalid.
In addition, moodle is configured so that if clam fails to run, files are treated like viruses. This essentially means that no student can upload a file successfully until you fix this.

The file has been moved to your specified quarantine directory, the new location is [quarantinedir]/20040906103924-user-1-infected
The user recieves the following message:

Your administrator has enabled virus checking for file uploads but has misconfigured something.
Your submission was NOT successful. Your administrator has been emailed to notify them so they can fix it.

ii. If clamfailureonupload is set to treat files as ok:

Moodle is configured to run clam on file upload, but the path supplied to Clam AV, /usr/bin/clamdscana, is invalid.

2.Clam scanning on upload

There is a new function in moodlelib.php called handle_file_upload which primarily acts as a central location for all the 'policy' behaviour for file uploads (for example calling clean_filename), as well as (optionally) handling filename collisions and (new) registering the upload in the log table (this is important for cron-based clam scanning to be able to resolve an infected file back to the user who uploaded it).

The function checks $CFG->runclamonupload and if it's on, calls a new function called clam_scan_file which executes clamscan (or clamdscan) and, depending on the outcome, behaves in a number of ways:

a. return code 0 (no virus found):
Does nothing, just returns.
b. return code 1 (virus found):
Calls clam_handle_infected_file ( which will either move the file to the quarantine directory, or delete it, depending on $CFG-> quarantinedir) and then clam_mail_admins, which will notify all moodle administrators that a virus has been found and give them a summary of what has happened to the file:

Attention administrator! Clam AV has found a virus in a file uploaded by Full Name for the course Test Course. Here is the output of clamscan:

/tmp/phpUp0p35: ClamAV-Test-Signature FOUND

----------- SCAN SUMMARY -----------
Known viruses: 23766
Scanned directories: 0
Scanned files: 1
Infected files: 1
Data scanned: 0.00 MB
I/O buffer size: 131072 bytes
Time: 3.336 sec (0 m 3 s)


The file has been moved to your specified quarantine directory, the new location is [quarantinedir]/20040906114132-user-1-infected

The user recieves the following message:

The file you have uploaded has been scanned by a virus checker and found to be infected! Your submission was NOT successful.

c. any other return code (error), or if pathtoclam is invalid:
Checks $CFG->clamfailureonupload and calls clam_handle_infected_file if it's set to treat files as viruses. then calls clam_mail_admins to notify them that clam is misconfigured, and (optionally) if something has happened to the file. If pathtoclam was valid, but there was an error return code, the email will include the description of the error code (from the clam man page). Note that clamdscan will only ever give 2: An error occurred while clamscan will give much more useful errors:
40: Unknown option passed.
50: Database initialization error.
52: Not supported file type.
53: Can't open directory.
54: Can't open file. (ofm)
55: Error reading file. (ofm)
56: Can't stat input file / directory.
57: Can't get absolute path name of current working directory.
58: I/O error, please check your filesystem.
59: Can't get information about current user from /etc/passwd.
60: Can't get information about user 'clamav' (default name) from /etc/passwd.
61: Can't fork.
63: Can't create temporary files/directories (check permissions).
64: Can't write to temporary directory (please specify another one).
70: Can't allocate and clear memory (calloc).
71: Can't allocate memory (malloc).

If clam_scan_file returns 0, handle_file_upload will continue to save the file.

3. Clam scanning on cron

Clam scanning on cron is not directly handled by moodle, as it may be prudent to time it just after freshclam runs to ensure the virus database is always up to date before scanning files.

Additionally, it may be useful to run in such a manner that it only scans files that have a last modified date within two weeks (using something like find [datadir] -ctime -14 | xargs clamscan [options] )

However, the new php script, handlevirus.php can be called for infected files, and it will lookup the log for uploads in the moodle database to try and resolve the user that uploaded the file.

handlevirus.php reads php://stdin and expects each line to contain a full path to the infected file, so the usage would be something like
clamscan --infected --no-summary [files] | handlevirus.php

--infected means only display files that are infected, and -no-summary means don't display the standard clam summary at the end.

It calls a function called clam_handle_infected_file, which checks the config parameters and either quarantines the file, or deletes the file. It then calls clam_replace_infected_file, which writes out the following string to the old filename:

This file that has been uploaded was found to contain a virus and has been moved or delted and the user notified.

This is so that files that have links to a forum post or something don't result in 404s. However it will sometimes result in the wrong content-type when a user downloads the file.

If it finds a record in the log table, it will email the user with the following notification:

A file you uploaded on Thursday, 2 September 2004, 03:29 PM with the filename virus.zip for the course Test Course has since been found to contain a virus. Here is a summary of what has happened to your file:
The file has been moved to a quarantine directory.
If this was submitted work, you may want to resubmit it so that your
tutor can see it.

It also emails all Moodle administrators the following notification:

Attention administrator! A file that was uploaded on Thursday, 2 September 2004, 03:29 PM with the filename virus.zip for the course Test Course by the user Full Name has since been found to contain a virus. Here is a summary of what has happened to the file:
The file has been moved to a quarantine directory.
The user has also been notified.
If no entry is found in the log table (this could occur for files newer than the patch that logs uploads, or for files uploaded for modules that don't use handle_file_upload), it emails Moodle administrators the following notification:

Attention administrator! A file that was uploaded with the filename
virus-7.zip has since been found to contain a virus. Moodle was unable to resolve this file back to the user that originally uploaded it.
Here is a summary of what has happened to the file:

The file has been moved to your specified quarantine directory, the new
location is [quarantinedir]/20040903150947-user-0-infected

We get more info in this one since it doesn't have to be userfriendly we don't want the users knowing the new location of the file on the server.

--------------------------------------------

Cheers,
Penny