HomeScanArchitecture
hero

Integrating Antivirus Scanning To File Uploads

Mohammad Yusuf

In enterprise applications, uploaded files pose a major security risk. Traditional file scanning workflows were slow and disruptive. This solution intercepts files on the fly during uploads, scans them for viruses, and flags malicious content—all in real time.

Cover Image for Architecture
Photo by Growtika on Unsplash
Built with security and pipeline integration in mind, this architecture demonstrates how to leverage ICAP and ClamAV to process files efficiently while maintaining high levels of protection against threats.
The system integrates multiple components seamlessly to provide a robust file-scanning solution. It begins with file uploads via a user-friendly Next.js web app. These files are securely transmitted to a wrapper REST API. The API, in turn, communicates with an ICAP server running ClamAV for real-time virus scanning.
  1. Web Application
    2. The web app is built using Next.js and TailwindCSS. Its purpose is to provide an intuitive and engaging interface for users. The scan feature has been integrated with Google reCaptcha v3 to prevent abuse.
    Credit where it's due, for the assets on upload page, the PDF icon is created by Smashicons on Flaticon. The Bug report icon created by Freepik on Flaticon. The JPG icon is created by Smashicons on Flaticon. The stock image is a photo by Michael Geiger on Unsplash.
  2. Wrapper REST API
    3. The wrapper REST API, written in Node.js, ensures secure communication with the ICAP server. By using Nginx as a reverse proxy for this API, a layer of security is added between the web app and ICAP server. Security features like API keys, SSL , firewall and rate limiting rules have been implemented.
  3. ICAP Server with ClamAV
    4. The ICAP server processes file scans in real time. It uses ClamAV, a powerful antivirus engine, to detect threats. It allows files to be scanned on the fly without saving them locally. The virus definition is updated every 2 hours to ensure the latest virus definitions are used for scanning. This frequent update mechanism helps in maintaining a high level of protection against new and emerging threats.
React Flow
Real-Time File Processing Pipelines
One of the standout features of this architecture is its ability to integrate with existing file processing pipelines. By using the ICAP protocol, files can be scanned as part of their journey through the pipeline. For instance, before a file is processed or stored in an application, it can be scanned for malware. This ensures that no infected file reaches the application, minimising the risk of compromising data integrity or exposing vulnerabilities.
Enterprise-Level Security
This solution is ideal for enterprises handling sensitive files, such as financial or legal documents. The architecture's emphasis on security (API keys, SSL, and ICAP protocols) ensures compliance with industry standards.
Scalability and Flexibility
The modular design allows individual components to be scaled or replaced as needed. For example, the ICAP server can be migrated to a different environment, or additional VMs can be deployed for increased traffic.
ClamAV is a free, open-source antivirus engine designed for detecting malware and viruses. It is lightweight and highly customisable, making it ideal for integrations in projects requiring antivirus scanning.
c-icap is an ICAP server implementation that acts as a bridge between your application and ClamAV. It processes ICAP requests and leverages ClamAV to scan files in real-time. This combination ensures efficient malware detection in file pipelines.
Below are detailed steps for setting up ClamAV v1.4.1 with c-icap v0.5.13 on Ubuntu.
  • ClamAV
    1. Install Required Dependencies
      2. Run the following commands to update the system and install required libraries:
      sudo apt update && sudo apt upgrade -y
sudo apt install build-essential libtool libtool-bin libssl-dev zlib1g-dev libpcre3-dev libicapapi-dev -y
    2. Install ClamAV
      3. Run the following commands to install ClamAV and ClamAV daemon
      sudo apt install clamav clamav-daemon -y
    3. Update Virus definition
      4. Stop the ClamAV services to update the virus definitions manually. It auto updates periodically (12 times a day).
      sudo systemctl stop clamav-freshclam
sudo freshclam
sudo systemctl start clamav-freshclam
    4. Start ClamAV daemon
      5. Start ClamAV daemon and verify that ClamAV is up and running correctly
      sudo systemctl start clamav-daemon
clamdscan --version
  • c-icap
    1. Install c-icap
      2. c-icap is not available in Ubuntu repository. Download and extract c-icap
      wget http://sourceforge.net/projects/c-icap/files/c-icap/0.5.x/c_icap-0.5.13.tar.gz
tar -xzf c_icap-0.5.13.tar.gz
cd c_icap-0.5.13
    2. Configure and build c-icap project
      3. Configure the project with path for the directory and build the project
      sudo ./configure --prefix=/usr/local/c-icap
sudo make
sudo make install
    3. Install c-icap-modules
      4. c-icap-modules package is not available in Ubuntu repository either. Download and extract c-icap-modules. cd out of the c_icap directory if haven't done already.
      wget http://sourceforge.net/projects/c-icap/files/c-icap-modules/0.5.x/c_icap_modules-0.5.7.tar.gz
tar -xzf c_icap_modules-0.5.7.tar.gz
cd c_icap_modules-0.5.7
    4. Configure and build c-icap-modules project
      5. Configure the project with path for c-icap module and path for its own directory and build the project
      sudo ./configure --with-c-icap=/usr/local/c-icap --prefix=/usr/local/c-icap
sudo make
sudo make install
  • Configuration
    1. Configure c-icap.conf
      2. Configure c-icap configuration to include virus scan configurations
      sudo nano /usr/local/c-icap/etc/c-icap.conf
      Add the following line at the end of the file:
      Include virus_scan.conf
    2. Configure virus_scan.conf
      3. Configure virus_scan configuration to use clamd virus engine
      sudo nano /usr/local/c-icap/etc/virus_scan.conf
      Add the following lines at the end of the file:
      virus_scan.DefaultEngine clamd
Include clamd_mod.conf
    3. Configure clamd_mod.conf
      4. Configure clamd configuration with path for clamd
      sudo nano /usr/local/c-icap/etc/clamd_mod.conf
      Add the following lines at the end of the file:
      clamd_mod.ClamdSocket /var/run/clamav/clamd.ctl
    4. Start the c-icap service
      5. Start c-icap service and verify that it is running correctly
      sudo /usr/local/c-icap/bin/c-icap -D
sudo /usr/local/c-icap/bin/c-icap -V
Building a Node.js ICAP client requires working directly with the net module to construct raw ICAP requests. Since there are limited libraries for ICAP clients in Node.js, you will need to manually define request headers, send them to the server, and parse the response. Explore the Github repository.
Once connected to the ICAP server, an OPTIONS ICAP request is constructed and sent. This verifies that the service is up and running. It also gives us allowed methods and the preview size expected by the service. Using this information, an RESPMOD ICAP request is made with either the preview of the file first or the entirety of the file. The response is parsed to check if the file is clean or infected.
Sample ICAP OPTIONS request
OPTIONS icap://example.com/scan ICAP/1.0
Host: <ICAP_SERVER>
User-Agent: <USER_AGENT>
Sample ICAP OPTIONS response
ICAP/1.0 200 OK
Methods: RESPMOD, REQMOD
Service: C-ICAP/0.5.13 server - Antivirus service
ISTag: "CI0001-mb0AP9ICKOwfVAjLJBB"
Transfer-Preview: *
Options-TTL: 3600
Date: Thu, 16 Jan 2025 16:51:08 GMT
Preview: 1024
Allow: 204
Encapsulated: null-body=0
Sample ICAP RESPMOD request
RESPMOD icap://example.com/scan ICAP/1.0
Host: <ICAP_SERVER>
Connection: close
User-Agent: <USER_AGENT>
Allow: 204
Encapsulated: req-hdr=0, res-hdr=67, res-body=168

GET /testFile.txt HTTP/1.1
Host: <ICAP_SERVER>

HTTP/1.1 200 OK
Date: Fri, 16 Jan 2025 20:05:04 GMT
Content-Type: text/plain
Content-Length: 20

14
This is a test file.
0
Sample ICAP RESPMOD response when file is clean
ICAP/1.0 204 Unmodified
Server: C-ICAP/0.5.13
Connection: close
ISTag: "CI0001-zIgGlDsuophyh"
Sample ICAP OPTIONS response when file is infected
ICAP/1.0 200 OK
Server: C-ICAP/0.5.13
Connection: close
ISTag: "CI0001-zIgGlDsuophyh"
X-Infection-Found: Type=0; Resolution=2; Threat=Eicar-Signature;
X-Violations-Found: 1
        -
        Eicar-Signature
        0
        0
Encapsulated: res-hdr=0, res-body=173

HTTP/1.0 403 Forbidden
Server: C-ICAP
Connection: close
Content-Type: text/html
Content-Language: en
Via: ICAP/1.0 <ICAP_SERVER> (C-ICAP/0.5.13 Antivirus service )
With this section, a comprehensive breakdown of the solution's components, deployment steps, and integration details have been outlined. By following the guide, developers can leverage the ICAP protocol to leverage on-the-fly virus scanning.