How to Enable Antivirus Protection in OPNsense?
OPNsense provides HTTP(S) protection by utilizing its highly flexible proxy and the industry-standard ICAP. To provide maximum protection against malware such as ransomware, trojans, and viruses, an external engine from a well-known vendor is used. You can also enhance your network security further by the built-in Intrusion Prevention System and Category Based Web filtering or third-party Zenarmor next-generation firewall plugin.
Antivirus proxies function similarly to traditional web proxies, with the exception that they scan all content passing through the proxy for malware or virus signatures. If the proxy deems the content to be harmful, the download will be halted and the user will be redirected to an error page.
The main benefit of scanning for viruses directly on the router is that malicious network packets can be stopped before they enter the network. This network security method is especially useful for guest networks and other cases where you can't be certain that all clients have an up-to-date antivirus program installed. Furthermore, even if each of your clients has an antivirus application, the defense-in-depth principle suggests adding another layer of protection by utilizing a central antivirus system.
OPNsense includes a ClamAV plugin that can be used in conjunction with the C-ICAP plugin, or it can rely on third-party engines from well-known vendors.
In this tutorial, we'll show you how to configure an OPNsense routing platform to act as an anti-virus proxy using C-ICAP and ClamAV Plugins.
You can enable antivirus protection in your OPNsense router with C-ICAP and ClamAV Plugins by following the 5 main steps explained in the next sections:
- Set up Basic Caching Proxy Server in OPNsense
- Enable Transparent HTTP and SSL Mode in OPNsense Proxy
- Install and Set up the ClamAV and C-ICAP plugins
- Configure ICAP in OPNsense
- EICAR Testing
1. Set up a Basic Caching Proxy Server in OPNsense​
To prevent your clients from accessing malicious files, such as viruses or malware, during web surfing, first, you can set up a basic caching proxy server in your OPNsense.
2. Enable Transparent HTTP and SSL Mode in OPNsense Proxy​
As a second step, you can enable transparent mode in OPNsense caching proxy server for both HTTP and SSL traffic to eliminate the client-side or browser side configuration. This mode is most commonly used in large corporate organizations where client-side configuration is difficult due to a large number of clients.
3. Install and Set up the ClamAV and C-ICAP plugins​
This section will explain briefly what the ClamAV and C-ICAP plugins are and how to install and configure them in the OPNsense firewall.
ClamAV® is an anti-virus engine that can be used for email scanning, web scanning, and endpoint security. It includes a scalable and flexible multi-threaded daemon, a command-line scanner, and an advanced tool for automatic database updates. It is licensed under the GNU General Public License, Version 2. ClamAV recognizes millions of viruses, trojans, worms, and other types of malware.
ClamAV® will only execute trusted signature definitions if the signature database is signed. It not only scans within archives and compressed files, but also guards against archive bombs.
note
Recommended System Requirements for ClamAV® are as follows:
- Minimum RAM For FreeBSD and Linux server editions:
2 GiB+
- Minimum recommended CPU:
1 CPU at 2.0 Ghz+
- Minimum available hard disk space required:
5 GB
C-ICAP is an ICAP server implementation. It can be used to implement content adaptation and filtering services with HTTP proxies that support the ICAP protocol. It has the following major features:
- basic C API for developing custom content adaptation and filtering services
- LDAP integration
- simple ICAP client API
- plugins interface
3.1. ClamAV® Installation & Signature Download in OPNsense​
To install the ClamAV
plugin in your OPNsense firewall, follow the steps below:
- Login to your OPNsense Web GUI using an account with administrative access such as
root
.
- Navigate to
System
>Firmware
>Plugins
.
- Type
os-clamav
in the search field to find the ClamAV® plugin.
Figure 1: Installing the ClamAV® plugin in OPNsense
- Click on the
+
icon next toos-clamav
to install the ClamAV® Antivirus engine for detecting malicious threats. Then you will be redirected to the Update menu tab.
- Click on the
Plugins
tab. You should see that theos-clamav
plugin is installed. If you cannot see the newly installed plugin, please refresh your web UI with the F5 button.
Figure 2: os-clamav
plugin is installed
After the plugin installation, you will get a new menu entry under Services
for ClamAV
.
Figure 3: Accessing ClamAV® menu in OPNsense Web UI
Now, before enabling the ClamAV® antivirus engine, you must download the virus signatures.
To download the ClamAV
signatures in your OPNsense firewall, you may follow the steps below:
- Navigate to
System
->Services
->ClamAV
in your OPNsense web UI. - Click the Download Signatures button at the that top right corner of the page.
Figure 4: Downloading ClamAV® virus signatures in OPNsense Web UI
3.2. ClamAV® Configuration OPNsense​
To configure the ClamAV
plugin in your OPNsense firewall, you may follow the steps below:
- Navigate to
System
>Services
>ClamAV
in your OPNsense web UI. - Check the Enable clamd service option for enabling ClamAV® to scan files.
- Check the Enable fresh clam service option to update your malware signatures on a regular basis.
- Check the Enable TCP Port option to enable TCP port
3310
in addition to the local socket. - Set the Maximum number of threads running option to the number of cores your OPNsense has for avoiding denial of service of the daemon and your router.
- Set the Maximum number of queued items option. This option is used for the maximum number of files that can be queued for scanning. It is recommended to have this value at least twice MaxThreads if possible.
- You may leave the Idle Timeout option as default. If the connection is inactive for this amount of time, it will be disconnected. If the other socket endpoint is a machine, this value can be low, but if you intend to use it for development purposes, you can increase it.
- You may leave the Max directory recursion option that is used to limit the depth of the directory tree as default. In the worst-case scenario, there is a loop that causes the scanner to run indefinitely, which this setting should prevent.
- You may check the Follow directory symlinks option to force ClamAV® to follow directory symlinks. Since it may lead to a loop, make sure the recursion limit is set to a useful value when enabling this option.
- You may check the Follow regular file symlinks option to force ClamAV® to follow symlinks to regular files. This may expose file system information that the user should not have access to.
- You may check the Disable cache option not to cache the results. Since it slows the response time, it is only useful for development environments.
- Check the Scan portable executable option to scan PE files, such as .exe, .dll, *.bat, etc.
- Check Scan executable and linking format options to scan ELF-files are used on Linux-based and BSD-based operating systems.
- You may check the Detect broken executables option to mark an executable as broken if it does not match the spec. An executable may be corrupted as a result of a download error or manipulation. In any case, there should be no justification for passing a broken executable.
- Check the Scan OLE2 option to analyze the OLE2 files which may contain macros to download and install malware.
- You may check the OLE2 block macros option if you don't use macros and don't expect them from your partners.
- Check the Scan PDF files option to scan PDF files.
Figure 5: Configuring ClamAV® antivirus engine in OPNsense Web UI-1
- Check the Scan SWF option to scan Flash files.
- Check the Scan XMLDOCS option to scan XML Documents.
- You may check the Scan HWP3 option to scan Korean documents. If you don't use them, blocking them in the proxy is advised.
- Check the Decode mail files option to scan email attachments that may contain malware.
- Check the Scan HTML option to scan HTML files that may have dangerous embedded JavaScript.
- Check the Scan archives option to scan files inside archives which can contain malware.
- Check the Block encrypted archive option. Beware that the ClamAV® cannot scan encrypted archives and detect harmful files they contain. To avoid detection, some malware authors use encrypted archives and instruct the victim on how to unpack them in the email text.
- You may leave the Max scan size option as default.
- You may leave the Max file size option as default. Files larger than this value won't be scanned.
- You may leave the Max recursion option as default. Nested archives are scanned recursively. If a RAR archive contains a Zip file, all files within it will also be scanned.
- You may leave the Max files option which specifies the number of files to be scanned within an archive, a document, or any other container file as default.
- Check the Freshclam log verbose option to enable verbose logging.
- You may leave the Freshclam database mirror option as default.
- You may leave the Freshclam connect timeout option as default.
- You may activate third-party signatures by adding Malware Expert, BLURL, JURLBLA and BOFHLand signatures.
Figure 6: Configuring ClamAV® antivirus engine in OPNsense Web UI-2
- Click
Save
at the bottom of the page to activate the settings.
You can view the ClamAV® engine version and total number of signatures by clicking on the Versions
tab.
Figure 7: Viewing the ClamAV® engine version in OPNsense
3.3. C-ICAP Installation in OPNsense​
Now, you can install C-ICAP
plugin in your OPNsense firewall to connect the web proxy with the ClamAV® virus scanner.
To install the C-ICAP
plugin in your OPNsense firewall, follow the steps below:
- Login to your OPNsense Web GUI using an account with administrative access such as
root
.
- Navigate to
System
->Firmware
->Plugins
.
- Type
os-c-icap
in the search field to find the C-ICAP plugin.
Figure 8: Installing the C-ICAP plugin in OPNsense
- Click on the
+
icon next toos-cicap
to install the C-ICAP plugin. Then you will be redirected to the Update menu tab.
- Click on the
Plugins
tab. You should see thatos-cicap
plugin is installed. If you cannot see the newly installed plugin, please refresh your web UI with the F5 button.
Figure 9: os-c-icap
plugin is installed
After the plugin installation, you will get a new menu entry under Services
for C-ICAP
.
Figure 10: Accessing ClamAV® menu in OPNsense Web UI
3.4. C-ICAP Configuration OPNsense​
To configure the C-ICAP
plugin in your OPNsense firewall, you may follow the steps below:
- Navigate to
System
>Services
>C-ICAP
in your OPNsense web UI. - Check the Enable c-icap service option to handle ICAP requests.
- You may leave the Timeout option as default. The socket will be closed when the timer expires.
- You may leave the Max keepalive requests option as default. This option limits the maximum number of requests that can be served by one connection.
- You may leave the Max keepalive timeout option as default. If the timer expires and the socket remains inactive, it will be closed.
- You may leave the Start servers option as default. It specifies the number of server processes that will be spawned. Each server process generates a number of threads, which serve the requests.
- You may leave the Max servers option that limits the count of processes as default.
- You may leave the Min spare threads option as default. If the number of the available threads is less than this value, the c-icap server starts a new child.
- You may leave the Max spare threads option as default. If the number of the available threads is more than the number then the c-icap server kills a child.
- You may leave the Threads per child option that specifies the number of threads per child process. as default.
- You may leave the Max requests per child option as default.
- You may leave the Listen address option in which the server should be bound as default. (::1 for IPv6 or 127.0.0.1 for IPv4)
- Set the Server admin option to an email address that acts as a contact for users, who are having issues with the server.
- You may set the Servername option to override the server name displayed on error pages.
- Check the Enable access logging option.
- Check the Use c-icap with local squid option to take user name settings from local squid.
Figure 11: Configuring C-ICAP General Settings in OPNsense
- Click on the
Antivirus
tab. - Check the Enable ClamAV option to enable the virus-scan using ClamAV.
- Select the type of files which should be analyzed into the Scan for file types option field. It is recommended to scan as many file types as possible, but keep in mind that scanning necessitates the availability of resources.
- You may set the amount of data of the original file which should be included in the preview into the Send percentage data option. More data leads to better scanning results and improves security, whereas a lower value improves performance.
- You may set the Start send percentage data option.
- You may check the Allow 204 response option.
info
A 204 response
has the advantage of not requiring the data to be sent over the wire again. In the event of a preview, no further data is sent to the ICAP server, and the data is forwarded to the client. If the ICAP server has received all of the data, the data does not need to be sent back. Please keep in mind that the ICAP client must support 204 responses.
- Check the Pass on error option to pass through the file that can not be scanned. Be aware that this could jeopardize your network.
- You may set the Max object size option that specifies the maximum size of files that will be scanned by the antivirus engine. You can use K and M indicators to define size in Kilobytes or Megabytes respectively.
- Click
Save
to activate the settings.
Figure 12: Configuring C-ICAP Antivirus Settings in OPNsense
4. Configure ICAP in OPNsense​
You may easily configure ICAP by following the next steps given below:
- Navigate to
Services
>Proxy
>Administration
in your OPNsense web UI. - Click on the down arrow icon on the Forward Proxy tab.
- Select
ICAP Settings
. - Click on the
advanced mode
toggle button to view all options. - Check the Enable ICAP option to use an ICAP server to filter or replace content.
- You may leave the Request Modify URL option as default,
icap://[::1]:1344/avscan
. - You may leave the Response Modify URL option as default,
icap://[::1]:1344/avscan
. - You may leave the Default Options TTL option as default,
60
. - You may check the Send Client IP option to send the client IP address to the ICAP server. It may be useful if you want to filter traffic based on IP addresses.
- You may check the Send Username option to send the client username to the ICAP server. It may be useful if you want to filter traffic based on IP username. Authentication is required to use usernames.
- You may check the Encode Username option.
- You may leave the Username Header option which should be used to send the username to the ICAP server as default.
- Check the Enable Preview option to improve the performance.If you use previews, only a part of the data is sent to the ICAP server.
- You may leave the Preview Size option as default.
- You may add destination domains into the Exclusion List option, such as
unharmful.com
,sunnyvalley.io
, etc. - Click on
Apply
.
Figure 13: Enabling ICAP for Web Proxy in OPNsense
5. EICAR Testing​
Now, you should verify that the ClamAV® antivirus engine is operational and functional in your OPNsense proxy server. To test the antivirus protection in the OPNsense router, you may follow the steps given below:
- Open a browser on your client's PC.
- Go to
https://www.eicar.org/?page_id=3950
page where you will find several files you can test. You may try to download the following files:
https://secure.eicar.org/eicar.com
https://secure.eicar.org/eicar.com.txt
https://secure.eicar.org/eicar_com.zip
https://secure.eicar.org/eicarcom2.zip
warning
DOWNLOADING THESE FILES IS AT YOUR OWN RISK.
First test the HTTP protocol version. If that works, test the HTTPS version if you have also configured the transparent SSL proxy mode.
If you configured the ClamAV® and C-ICAP plugins successfully in your OPNsense proxy server, your antivirus engine should block downloading these files. You should see the Virus Detected
messages in logs similar to figure 14. You may view C-ICAP logs by navigating to the Services
> C-ICAP
> Log File
.
Figure 14: Viewing C-ICAP Logs in OPNsense