Virus Scanner Support

Introduction

When sharing files, security is a key aspect. The ownCloud Anti-Virus extension helps by protecting against malicious software like trojans or viruses. It forwards files that are being uploaded to the ownCloud server to a malware scanning engine before they are written to the storage. When a file is recognized as malicious, it can be logged and prevented from being uploaded to the server to ensure that files in ownCloud are free of malware. More sophisticated rules may be specified as admin in the ownCloud Webinterface Admin  Settings  Security.

Out of the box, the ownCloud Anti-Virus extension works with Clam AntiVirus (ClamAV) as the directly supported virus scanner. It detects all forms of malware including trojans, viruses and worms and scans compressed files, executables, image files, PDF, as well as many other file types. The ownCloud Anti-Virus application relies on the underlying ClamAV virus scanning engine, to which the admin points ownCloud when configuring the application. The ClamAV virus definitions need to be kept up to date in order to provide effective protection.

Starting with Anti-Virus version 1.0.0, the app also offers an ICAP integration for Enterprise installations. Admins can integrate their favorite enterprise-grade Antivirus Scanners through the open standard Internet Content Adaptation Protocol (ICAP). With this set up, ownCloud can delegate the scanning of uploaded files to another machine, the ICAP server. The ICAP server then checks them and either greenlights them or, if malicious code is found, treats the offending file(s) as specified in the settings and notifies the ownCloud server. ownCloud can then act accordingly and based on the settings made reject the upload. Offloading the anti-virus scans to another dedicated server can greatly improve performance compared to running the ClamAV virus scanner on the same machine as ownCloud.

ClamAV

Feature List:

  • Operates on all major operating systems, including Windows, Linux, and macOS.

  • Detects all forms of malware including Trojan horses, viruses, and worms.

  • Scans compressed files, executables, image files, Flash, PDF, as well as many others.

What’s more, ClamAV’s Freshclam daemon automatically updates its malware signature database at scheduled intervals.

Installing ClamAV

Install ClamAV on Ubuntu with the following command:

sudo apt install clamav clamav-daemon

This automatically creates the default configuration files and launches the clamd and freshclam daemons.

Enabling and Running ClamAV

Enable the clamd service file and start clamd.

sudo systemctl enable clamav-daemon.service
sudo systemctl start clamav-daemon.service

When successful, output similar to the following renders to the console:

Synchronizing state of clamav-daemon.service with SysV service script \
with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable clamav-daemon

ClamAV Virus Database Updates

First we have to ensure the process is currently not running. Gently end the freshclam process with this command:

sudo pkill -15 -x freshclam

Then we manually start the updating process. Start the refresh process again with this command:

sudo freshclam

Automate the update process with this cron entry for example.

# m   h  dom mon dow  command
47  *  *  *  *  /usr/bin/freshclam --quiet
Please avoid any multiples of 10, because those are when the ClamAV servers are hit the hardest for updates.

Install the ownCloud Anti-Virus App

The Anti-Virus app needs to be installed from the ownCloud Market (it’s available in the "Security" category).

image

To install the App via occ command, execute:

sudo -u www-data php occ market:install files_antivirus

Configuring ClamAV within ownCloud

If the app is enabled but either not configured or incorrectly configured it will strictly reject all uploads for the whole instance

ClamAV can be configured in two ways:

Configure ClamAV Using the Antivirus Configuration Panel

Once ClamAV is installed, select Settings  General (Admin) and, in the "Log" section, set Log level to "Everything (fatal issues, errors, warnings, info, debug)".

the ownCloud Antivirus configuration panel

Now, navigate to Settings  Security (Admin), where you’ll find the "Antivirus Configuration" panel. There, as below, you’ll see the configuration options which ownCloud passes to ClamAV.

The antivirus configuration panel in ownCloud

Configure ClamAV Using occ

All of the configuration settings for ClamAV are configurable by passing the relevant key and value to the occ config:app:set files_antivirus command. For example:

sudo -u www-data php occ config:app:set \
    files_antivirus av_socket --value="/var/run/clamav/clamd.ctl"
Available Configuration Settings
Setting Description Default

av_cmd_options

Extra command line options (comma-separated) to pass to ClamAV.

av_host

The hostname or IP address of the Antivirus server.

av_infected_action

The action to take when infected files were found during a background scan. It can be set to one of only_log and delete.

only_log

av_max_file_size

The maximum file size limit; -1 means no limit.

-1

av_mode

The operating mode. It can be set to one of executable, daemon, and socket.

executable

av_path

The path to the clamscan executable.

/usr/bin/clamscan

av_port

The port number of the Antivirus server. Allowed values are 1 - 65535.

av_socket

The name of ClamAV’s UNIX socket file.

/var/run/clamav/clamd.ctl

av_stream_max_length

The maximum stream length that ClamAV will accept.

26214400

Mode Configuration

ClamAV runs in one of three modes:

Daemon (Socket)

In this mode, ClamAV runs in the background on the same server as the ownCloud installation, or the socket can be made available via a share mount. When there is no activity, clamd places a minimal load on your system. However, if your users upload large volumes of files, you will see high CPU usage. Please keep this in mind.

You must run freshclam at least once for ClamAV to generate the socket.

image

First, set Mode to "Daemon (Socket)". ownCloud should detect your clamd socket and fill in the "Socket" field. This is the LocalSocket option in clamd.conf.

You can run ss to verify it, as in the example below:

sudo ss -a | grep -iq clamav && echo "ClamAV is running"

If you don’t have ss installed, you may have netstat installed. If so, you can run the following to check if ClamAV is running:

netstat -a | grep -q clam && echo "ClamAV is running"

The Stream Length value sets the number of bytes to read in one pass; 10485760 bytes (ten megabytes) is the default. This value should be no larger than the PHP memory_limit settings or physical memory if memory_limit is set to -1 (no limit).

When infected files were found during a background scan gives you the choice of either:

  • Logging any alerts without deleting the files

  • Immediately deleting infected files

Daemon

In this mode, ClamAV runs on a different server. This is a good option for ownCloud servers with high volumes of file uploads.

image

First, set Mode to "Daemon". Then, you need to set Host to the hostname or IP address of the remote server running ClamAV, and set Port to the server’s port number.

The port number is the value of TCPSocket in /etc/clamav/clamd.conf.
Executable

In this mode, ClamAV runs on the same server as the ownCloud installation, with the clamscan command running only when a file is uploaded.

clamscan is slow and not always reliable for on-demand usage; it is better to use one of the daemon modes.

image

First, set Mode to "Executable". Then, set Path to clamscan to the path to clamscan, which is the interactive ClamAV scanning command, on your server. ownCloud should automatically find it. However, if it doesn’t, run which clamscan to find the command’s path.

When you are satisfied with how ClamAV is operating, you might want to go back and change all of your logging to less verbose levels.

Configuration Warnings

The Antivirus App shows one of three warnings if it is misconfigured or ClamAV is not available. You can see an example of all three below.

Configuration error message: 'Antivirus app is misconfigured or antivirus inaccessible. Could not connect to host 'localhost' on port 999'.

Configuration error message: 'Antivirus app is misconfigured or antivirus inaccessible. The antivirus executable could not be found at path '/usr/bin/clamsfcan''.

Configuration error message: 'Antivirus app is misconfigured or antivirus inaccessible. Could not connect to socket ┬┤/var/run/clamav/cslamd-socket┬┤: No such file or directory (code 2)'.

What To Do With Infected Files Found During Scans

During an upload these actions are taken:

  • The upload is blocked.

  • The event is logged in the owncloud server log.

  • The event is reported and/or logged by the client / Web UI.

During a background scan the app can take one of two actions:

  • Log Only Log the event.

  • Delete file: Delete the detected file.

Set When infected files were found during a background scan to the value that suits your needs.

Rule Configuration

ownCloud provides the ability to customize how it reacts to the response given by an antivirus scan. To do so, under Admin  Security (Admin) click Advanced, which you can see in the screenshot below, you can view and change the existing rules. You can also add new ones.

image

Rules can match on either an exit status (e.g., 0, 1, or 40) or a pattern in the string returned from ClamAV (e.g., /.: (.) FOUND$/).

Here are some points to bear in mind about rules:

  • Scanner exit status rules are used to handle errors when ClamAV is run in CLI mode, while

  • Scanner output rules are used in daemon/socket mode.

  • Daemon output is parsed by regexp.

  • In case there are no matching rules, the status is: Unknown, and a warning will be logged.

Default Ruleset

The default rule set for ClamAV is populated automatically with the following rules:

Exit Status or Signature Description Marks File As

0

Clean

1

Infected

40

Unknown option passed

Unchecked

50

Database initialization error

Unchecked

52

Not supported file type

Unchecked

53

Can’t open directory

Unchecked

54

Can’t open file

Unchecked

55

Error reading file

Unchecked

56

Can’t stat input file

Unchecked

57

Can’t get absolute path name of current working directory

Unchecked

58

I/O error

Unchecked

62

Can’t initialize logger

Unchecked

63

Can’t create temporary files/directories

Unchecked

64

Can’t write to temporary directory

Unchecked

70

Can’t allocate memory (calloc)

Unchecked

71

Can’t allocate memory (malloc)

Unchecked

/.*: OK$/

Clean

/.: (.) FOUND$/

Infected

/.: (.) ERROR$/

Unchecked

The rules are always checked in the following order:

  1. Infected

  2. Error

  3. Clean

In case there are no matching rules, the status would be Unknown and a warning would be logged.

Update An Existing Rule

To match on an exit status, change the "Match by" dropdown list to "Scanner exit status" and in the "Scanner exit status or signature to search" field, add the status code to match on.

To match on the scanner’s output, change the "Match by" dropdown list to "Scanner output" and in the "Scanner exit status or signature to search" field, add the regular expression to match against the scanner’s output.

Then, while not mandatory, add a description of what the status or scan output means. After that, set what ownCloud should do when the exit status or regular expression you set matches the value returned by ClamAV. To do so change the value of the dropdown in the "Mark as" column.

The dropdown supports the following three options:

Option Description

Clean

The file is clean and contains no viruses

Infected

The file contains a virus

Unchecked

No action should be taken

With all these changes made, click the check mark on the left-hand side of the "Match by" column, to confirm the change to the rule.

Add A New Rule

To add a new rule, click the button marked Add a rule at the bottom left of the rules table. Then follow the process outlined in Update An Existing Rule.

Delete An Existing Rule

To delete an existing rule, click the rubbish bin icon on the far right-hand side of the rule that you want to delete.

How ClamAV Works With ownCloud

ownCloud integrates with antivirus tools by connecting to them via:

  • A URL and port

  • A socket

  • Streaming the data from the command-line via a pipe with a configured executable

In the case of ClamAV, ownCloud’s Antivirus extension sends files as streams to a ClamAV service (which can be on the same ownCloud server or another server within the same network) which in turn scans them and returns a result to stdout.

Individual chunks are not scanned. The whole file is scanned when it is moved to the final location.

The information is then parsed, or an exit code is evaluated if no result is available to determine the response from the scan. Based on ownCloud’s evaluation of the response (or exit code) an appropriate action is then taken, such as recording a log message or deleting the file.

Scanner exit status rules are used to handle errors when ClamAV is run in CLI mode. Scanner output rules are used in daemon/socket mode.

Things To Note

  1. Files are checked when they are uploaded or updated (whether because they were edited or saved) but not when they are downloaded.

  2. ownCloud doesn’t support a cache of previously scanned files.

  3. If the app is either not configured or is misconfigured, then it rejects file uploads.

  4. If ClamAV is unavailable, then the app rejects file uploads.

  5. A file size limit applies both to background jobs and to file uploads.

  6. After installing ClamAV and the related tools, you will have two configuration files: /etc/freshclam.conf and /etc/clamd.d/scan.conf.

  7. We recommend that you enable verbose logging in both clamd.conf and freshclam.conf until you get any kinks with your ClamAV installation worked out

ICAP

ICAP is an open standard supported by many antivirus products. With the release of the Anti-Virus app 1.0.0, other virus scanners beside ClamAV can be used via ICAP if you are running it on an ownCloud Enterprise Edition. Currently the only tested and supported virus scanners, besides ClamAV, are Kaspersky ScanEngine and McAfee Antivirus although far more products might simply work.

Installation

  • Install the Anti-Virus app from the ownCloud marketplace. Alternatively, use this occ command:

sudo -u www-data php occ market:install files_antivirus
  • Enable the app as admin in ownCloud under menu:[Settings > Apps] in the category Security or with the following occ command:

sudo -u www-data php occ app:enable files_antivirus

General Configuration

ICAP can be configured via the Web interface as admin user or via occ commands.

Antivirus Configuration Panel

Log in to ownCloud as admin via the Web interface and go to Admin  Settings  Security and you’ll see the Antivirus Configuration dialog.

Security Settings

Enter the desired values:

Mode

Set to Daemon (ICAP).

Host

Enter the IP addess of your ICAP server.

Port

Specify the port number (default 1344).

Stream Length

Set the length of streams sent to the ICAP server in bytes.

File size limit

If you want to limit the file size, enter the maximum value in bytes. Default is no limit (-1).

ICAP request service

Select the antivirus software you want to use: avscan for ClamAV, req for Kaspersky ScanEngine or wwreqmod for McAfee.

ICAP response header holding the virus information

Use X-Infection-Found for ClamAV (avscan) and X-Virus-ID for KAV (req). McAfee doesn’t offer response headers.

When infected files were found during a background scan

Specify what to do with the flagged files. Possible values: Delete file or Only log.

Do not change the rules hidden under Advanced unless you know exactly what you’re doing. The defaults should work best. If you have special requirements, contact us at consulting@owncloud.com.

Command-line Configuration

On the command line, change into your ownCloud directory, usually /var/www/owncloud, and enter the following occ commands:

  • To set the IP address of your anti-virus server:

sudo -u www-data php occ config:app:set files_antivirus \
    av_host --value="172.17.0.3"
  • Specify the port of the anti-virus server:

sudo -u www-data php occ config:app:set files_antivirus \
    av_port --value="1344"
  • Set the mode to ICAP:

sudo -u www-data php occ config:app:set files_antivirus \
    av_mode --value="icap"
The setting icap triggers a grace period of 24 hours if you don’t have an Enterprise license but want to test ICAP.
  • Specify what do do with the offending file:

sudo -u www-data php occ config:app:set files_antivirus \
    av_infected_action --value="delete"

Possible values are 'delete' and 'only_log'.

Run with c-icap/ClamAV

c-icap has a built in ClamAV module. For more information see: c-icap on sourceforge.

  • The IP address needs to be set in the general configuration above.

  • Now set the mode to 'c-icap with ClamAV':

sudo -u www-data php occ occ config:app:set files_antivirus \
    av_request_service --value="avscan"
  • Next, set the response header:

sudo -u www-data php occ config:app:set files_antivirus \
    av_response_header --value="X-Infection-Found"

Run with Kaspersky Anti-Virus (KAV)

  • Install Kaspersky ScanEngine for Kubernetes.7z and follow the instructions.

  • Set KAV as virus scanner with the value req:

sudo -u www-data php occ config:app:set files_antivirus \
    av_request_service --value="req"
  • Set the respective response header:

sudo -u www-data php occ config:app:set files_antivirus \
    av_response_header --value="X-Virus-ID"
Older versions of KAV did not send back the virus/infection name in an ICAP header. Version 2.0.0 of KAV allows you to configure the header to transport the virus. By default no header is sent.

Run with McAfee

Install the McAfee virus scanner.

  • The IP address needs to be set in the general configuration above.

  • Now set the mode to wwreqmod to use McAfee:

sudo -u www-data php occ occ config:app:set files_antivirus \
    av_request_service --value="wwreqmod"
McAfee does not offer response headers.