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.
You can get the Anti-Virus extension from the marketplace. 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 Web interface .
General Info
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.
Starting with Anti-Virus version 1.1.0, additional scanners like the FortiSandbox and McAfee Web Gateway have been added as selectable ICAP scanners.
ClamAV In Native Mode
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.
ClamAV Integration Into ownCloud
ownCloud integrates with antivirus tools by connecting to them via:
-
A URL
-
A host name and port
-
A socket
-
Streaming the data from the command line via a pipe with a configured executable
In case of ClamAV, ownCloud’s antivirus extension sends files either through a unix-domain socket (which requires clamd running on the same host) or through a pipe to stdin/stdout of the clamscan executable (installed on the same host) or through the network using a host name and port pair (which allows running the clamd daemon on another server).
Individual chunks are not scanned. The whole file is scanned when it is moved or saved 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. In case of an infected upload, the appropriate action is always to delete the file(s). The choice "delete" or "log" for the infected condition only applies to the special case of background scans.
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 only. |
Scanning Notes for ClamAV
-
Files are checked when they are uploaded or updated but not when they are downloaded.
-
ownCloud does not maintain a cache of previously scanned files.
-
If the app is either not configured or is misconfigured, then it rejects file uploads.
-
If ClamAV is unavailable, then the app rejects file uploads.
-
A file size limit applies both to background scans and to file uploads.
-
After installing ClamAV and the related tools, you will have two configuration files:
/etc/freshclam.conf
and/etc/clamd.d/scan.conf
. -
We recommend that you enable verbose logging in both
clamd.conf
andfreshclam.conf
initially, to verify correct operation of both.
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 and start the clamd
service with following commands.
sudo systemctl daemon-reload
sudo systemctl enable clamav-daemon.service
sudo systemctl start clamav-daemon.service
When successful, an output similar to the following should appear on the terminal:
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
-
You can manually start the updating process with this command:
sudo freshclam
You should update manually at least once before using ClamAV within ownCloud. The initial update can take several minutes. In case of persisting issues running
freshclam
, you can gently end the process with the following command:sudo pkill -15 -x freshclam
and retry manually updating again.
-
To automate the update process, run this cron entry for example.
# m h dom mon dow command 47 * * * * /usr/bin/freshclam --quiet
Avoid any multiples of 10 to better distribute the load on the ClamAV virus pattern servers. This can reduce the load on the servers and therefore update times.
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).
To install the App directly via the occ command, execute:
sudo -u www-data occ market:install files_antivirus
Configuring ClamAV within ownCloud
If the app is enabled but either not or incorrectly configured, it will strictly reject all uploads for the whole instance! |
ClamAV can be configured in the following two ways:
Change Log Level Temporarily
Once ClamAV is installed, select
and, in the "Log" section, temporarily set Log level to "Everything (fatal issues, errors, warnings, info, debug)".Configure ClamAV Using the AV Configuration Panel
Navigate to
, where you’ll find the "Antivirus Configuration" panel as you can see in the example screenshot below.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 occ config:app:set files_antivirus \
av_socket --value="/var/run/clamav/clamd.ctl"
To get a current option run for example:
sudo -u www-data occ config:app:get files_antivirus \
av_socket
Setting | Description | Default |
---|---|---|
|
Extra command line options (comma-separated) to pass to ClamAV. |
|
|
The host name or IP address of the antivirus server. |
|
|
The action to take when infected files were found during a background scan. |
|
|
The maximum file size limit; |
|
|
The Anti Virus binary operating mode. |
|
|
The path to the |
|
|
The port number of the antivirus server. |
|
|
Should scans run in the background? |
|
|
The name of ClamAV’s UNIX socket file. |
|
|
The maximum stream length that ClamAV will accept in bytes (*). |
|
(*) The Stream Length
value sets the number of bytes to read in one pass and defaults to 26214400 bytes (twenty-six megabytes). This value should be no larger than the PHP memory_limit
settings or physical memory if memory_limit
is set to -1 (no limit).
Configuration Modes
ClamAV runs in one of three modes:
In both daemon modes, background scans are enabled by default. If you want to disable them, run the command:
|
Daemon (Socket, Same Server)
In Daemon (Socket) 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. Consider that high CPU usage can occur when users upload large volumes of files.
You must run freshclam at least once for ClamAV to generate the socket.
|
-
Set Mode to "Daemon (Socket)". ownCloud should detect your
clamd
socket and fill in the "Socket" field. This is theLocalSocket
option inclamd.conf
.You can run
ss
(a utility to investigate sockets) 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 havenetstat
installed. If so, you can run the following to check if ClamAV is running:netstat -a | grep -q clam && echo "ClamAV is running"
-
When infected files were found during a background scan, you have the choice of either:
-
Logging any alerts without deleting the files
-
Immediately deleting infected files
-
Daemon (Different Server)
In Daemon mode, ClamAV runs on a different server. This is a good option to reduce load on the ownCloud servers when high network bandwidth is available and many concurrent uploads happen.
-
Set Mode to "Daemon".
-
Set Host to the host name 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 Executable mode, ClamAV runs on the same server as the ownCloud installation, with the clamscan
command running only when a file is uploaded.
clamscan can respond slower and may not always be reliable for on-demand usage; it is better to use one of the daemon modes.
|
The image shows a command line option --allmatch=yes
(continue scanning within the file after finding a match) which is not necessary to be set and just used here for demonstration purposes of the field.
Starting with ownCloud Anti-Virus version 1.0.0, the path to clamscan and the command line options are set via a config.php entry and are read-only in the user interface. Refer to the config.php parameters for apps for more details.
|
If you had configured the path and command line options before via the user interface, the values are being migrated from the database to config.php automatically. Check the settings in config.php for their presence after upgrading. |
-
Set Mode to "Executable".
-
Set Path to clamscan to the path of
clamscan
, which is the interactive ClamAV scanning command, on your server. To find the exact path, runwhich clamscan
Set Back Log Level
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 Anti-Virus App shows one of three warnings if it is misconfigured or ClamAV is not available. You can see an example of all three below.
Manage Infected Files Found
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.
Response Rule Configuration
ownCloud provides the ability to customize how it reacts to the response given by an antivirus scan. To do so, under
click Advanced, which you can see in the screenshot below, you can view and change the existing rules. You can also add new ones.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 Rule Set
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:
-
Infected
-
Error
-
Clean
In case there are no matching rules, the status would be Unknown
and a warning would be logged.
Update an Existing Rule
-
You can change the rules to either match an exit status or the scanner’s output.
-
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 [✓] 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.
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, McAfee Web Gateway and FortiSandbox although far more products might simply work. The use of ICAP requires an enterprise license. The functionality can be tested without a license with a grace period of 24 hours.
Installation
-
If you haven’t done so already, install the Anti-Virus app from the ownCloud marketplace. Alternatively, use this occ command:
sudo -u www-data occ market:install files_antivirus
-
Enable the app as admin in ownCloud under
in the categorySecurity
or with the following occ command:sudo -u www-data occ app:enable files_antivirus
General Configuration
ICAP can be configured via the Web interface as admin user or via occ config:app commands.
Antivirus Configuration Panel
Log in to ownCloud as admin via the Web interface and go to
and you’ll see the Antivirus Configuration dialog.Enter the desired values:
Mode
-
Set to
Daemon (ICAP)
. Host
-
Enter the IP address 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) andX-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
orOnly 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. |
ICAP Configuration
You can configure the ownCloud Anti-Virus app either via the Web interface or the command line. The Web interface fields can be easily matched to the command line field names. On the command line, change into your ownCloud directory, usually /var/www/owncloud
, and enter the following occ commands with an IP address and port based on your environment:
-
Set the IP address of your anti-virus server:
sudo -u www-data 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 occ config:app:set files_antivirus \ av_port --value="1344"
-
Set the mode to ICAP:
sudo -u www-data 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 to do with the offending file:
sudo -u www-data occ config:app:set files_antivirus \ av_infected_action --value="delete"
Possible values are
delete
andonly_log
.Depending on your ICAP server, select one of the following example configurations.
Run ClamAV in ICAP Mode
c-icap
can be configured to use ClamAV. For more information see: c-icap on sourceforge (for selecting ClamAV see their section: Selecting virus scan engine to use).
-
Install ClamAV based on the instructions at the beginning of this document and
c-icap
as referenced above. -
Select c-icap with ClamAV from the dropdown in the Anti Virus app or use the command line:
sudo -u www-data occ config:app:set files_antivirus \ av_request_service --value="avscan"
-
Set the respective response header:
sudo -u www-data occ config:app:set files_antivirus \ av_response_header --value="X-Infection-Found"
Run with Kaspersky Anti-Virus in ICAP Mode
-
Install the Kaspersky ScanEngine (KAV) based on their instructions and prepare KAV for running in ICAP mode.
-
Select req from the dropdown in the Anti Virus app or use the command line:
sudo -u www-data occ config:app:set files_antivirus \ av_request_service --value="req"
-
Set the respective response header:
sudo -u www-data occ config:app:set files_antivirus \ av_response_header --value="X-Virus-ID"
The older versions of Kaspersky’s KAV did not send back the virus/infection name in an ICAP header. Starting with KAV v2.0.0, the header to transport the virus can be configured. Default: No header is sent. For more configuration details see Using Kaspersky Scan Engine in ICAP mode.
Run with McAfee Web Gateway in ICAP Mode
Follow this procedure to configure ownCloud for the McAfee Web Gateway 10.x and higher in ICAP Mode.
-
Install McAfee Web Gateway based on their instructions.
-
Select McAfee Web Gateway 10.x and higher from the dropdown in the Anti Virus app.
-
To use McAfee Web Gateway, set the mode to
respmod
either from the Web interface or via command line:sudo -u www-data occ config:app:set files_antivirus \ av_request_service --value="respmod"
-
Set the response header to
X-Virus-Name
sudo -u www-data occ config:app:set files_antivirus \ av_response_header --value="X-Virus-Name"
McAfee provides demo versions with limited runtime for evaluation purposes. Have a look at the McAfee Web page for the Web Gateway. |
Run with FortiSandbox in ICAP Mode
-
Install FortiSandbox based on their instructions.
-
Select Fortinet from the dropdown in the Anti-Virus app.
-
To use FortiSandbox, set the mode to
respmod
either from the Web interface or via command line:sudo -u www-data occ config:app:set files_antivirus \ av_request_service --value="respmod"
-
Set the response header to
X-Virus-Name
sudo -u www-data occ config:app:set files_antivirus \ av_response_header --value="X-Virus-Name"
Fortinet provides some demo versions of the FortiSandbox. Have a look at their product page for more information. |