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:

1. Set up Basic Caching Proxy Server in OPNsense
2. Enable Transparent HTTP and SSL Mode in OPNsense Proxy
3. Install and Set up the ClamAV and C-ICAP plugins
4. Configure ICAP in OPNsense
5. 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:

1. Login to your OPNsense Web GUI using an account with administrative access such as root.

2. Navigate to System > Firmware > Plugins.

3. Type os-clamav in the search field to find the ClamAV® plugin.

Figure 1: Installing the ClamAV® plugin in OPNsense

4. Click on the + icon next to os-clamav to install the ClamAV® Antivirus engine for detecting malicious threats. Then you will be redirected to the Update menu tab.

5. Click on the Plugins tab. You should see that the os-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:

1. Navigate to System -> Services -> ClamAV in your OPNsense web UI.
2. 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:

1. Navigate to System > Services > ClamAV in your OPNsense web UI.
2. Check the Enable clamd service option for enabling ClamAV® to scan files.

3. Check the Enable fresh clam service option to update your malware signatures on a regular basis.
4. Check the Enable TCP Port option to enable TCP port 3310 in addition to the local socket.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. 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.
11. 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.
12. Check the Scan portable executable option to scan PE files, such as .exe, .dll, *.bat, etc.
13. Check Scan executable and linking format options to scan ELF-files are used on Linux-based and BSD-based operating systems.
14. 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.
15. Check the Scan OLE2 option to analyze the OLE2 files which may contain macros to download and install malware.
16. You may check the OLE2 block macros option if you don't use macros and don't expect them from your partners.
17. Check the Scan PDF files option to scan PDF files.

Figure 5: Configuring ClamAV® antivirus engine in OPNsense Web UI-1

18. Check the Scan SWF option to scan Flash files.
19. Check the Scan XMLDOCS option to scan XML Documents.
20. You may check the Scan HWP3 option to scan Korean documents. If you don't use them, blocking them in the proxy is advised.
21. Check the Decode mail files option to scan email attachments that may contain malware.
22. Check the Scan HTML option to scan HTML files that may have dangerous embedded JavaScript.
23. Check the Scan archives option to scan files inside archives which can contain malware.
24. 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.
25. You may leave the Max scan size option as default.
26. You may leave the Max file size option as default. Files larger than this value won't be scanned.
27. 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.
28. 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.
29. Check the Freshclam log verbose option to enable verbose logging.
30. You may leave the Freshclam database mirror option as default.
31. You may leave the Freshclam connect timeout option as default.
32. 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

33. 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:

1. Login to your OPNsense Web GUI using an account with administrative access such as root.

2. Navigate to System -> Firmware -> Plugins.

3. Type os-c-icap in the search field to find the C-ICAP plugin.

Figure 8: Installing the C-ICAP plugin in OPNsense

4. Click on the + icon next to os-cicap to install the C-ICAP plugin. Then you will be redirected to the Update menu tab.

5. Click on the Plugins tab. You should see that os-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:

1. Navigate to System > Services > C-ICAP in your OPNsense web UI.
2. Check the Enable c-icap service option to handle ICAP requests.
3. You may leave the Timeout option as default. The socket will be closed when the timer expires.
4. 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.
5. You may leave the Max keepalive timeout option as default. If the timer expires and the socket remains inactive, it will be closed.
6. 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.
7. You may leave the Max servers option that limits the count of processes as default.
8. 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.
9. 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.
10. You may leave the Threads per child option that specifies the number of threads per child process. as default.
11. You may leave the Max requests per child option as default.
12. 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)
13. Set the Server admin option to an email address that acts as a contact for users, who are having issues with the server.
14. You may set the Servername option to override the server name displayed on error pages.
15. Check the Enable access logging option.
16. 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

17. Click on the Antivirus tab.
18. Check the Enable ClamAV option to enable the virus-scan using ClamAV.
19. 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.
20. 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.
21. You may set the Start send percentage data option.
22. 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.

23. Check the Pass on error option to pass through the file that can not be scanned. Be aware that this could jeopardize your network.
24. 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.

25. 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:

1. Navigate to Services > Proxy > Administration in your OPNsense web UI.
2. Click on the down arrow icon on the Forward Proxy tab.
3. Select ICAP Settings.
4. Click on the advanced mode toggle button to view all options.
5. Check the Enable ICAP option to use an ICAP server to filter or replace content.
6. You may leave the Request Modify URL option as default, icap://[::1]:1344/avscan.
7. You may leave the Response Modify URL option as default, icap://[::1]:1344/avscan.
8. You may leave the Default Options TTL option as default, 60.
9. 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.
10. 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.
11. You may check the Encode Username option.
12. You may leave the Username Header option which should be used to send the username to the ICAP server as default.
13. 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.
14. You may leave the Preview Size option as default.
15. You may add destination domains into the Exclusion List option, such as unharmful.com, sunnyvalley.io, etc.
16. 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:

1. Open a browser on your client's PC.
2. Go to https://www.eicar.org/?page_id=3950page 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