ClamAV Real-Time Protection Configuration (Linux)

This will attempt to notify the user that downloaded the file. You can customize the script as needed for your environment. The script tries to see who owns the file to determine who might have downloaded it. Ownership will be overwritten by the user folder the file was downloaded to (this allows the script to handle files downloaded using sudo). If ownership can't be determined, it will notify all users on the device.

For notifications, it will provide an alert in all shell sessions (local and ssh) and an alert via the GUI. It also attempts to play an alert sound via the shell and via the GUI.

1. Install libnotify if not already installed

   sudo dnf install -y libnotify

2. Create notification script

   sudo nano /usr/local/bin/clamav-notify.sh

3. Paste the following into the script file

   #!/bin/bash
   
   # Pull the values securely from ClamAV's environment variables
   VIRUS_NAME="$CLAM_VIRUSEVENT_VIRUSNAME"
   FILE_PATH="$CLAM_VIRUSEVENT_FILENAME"
   
   # --- 1. SECURE DEBOUNCE & CACHE ---
   ALERTS_DIR="/run/clamav-alerts"
   mkdir -p "$ALERTS_DIR"
   chmod 700 "$ALERTS_DIR"
   
   # Clean up cache files older than 10 minutes to prevent accumulation
   find "$ALERTS_DIR" -type f -mmin +10 -delete
   
   SAFE_PATH=$(echo "$FILE_PATH" | tr '/' '_')
   CACHE_FILE="${ALERTS_DIR}/clamav_alert_${SAFE_PATH}"
   
   if [ -f "$CACHE_FILE" ]; then
       LAST_ALERT=$(stat -c %Y "$CACHE_FILE" 2>/dev/null)
       now=$(date +%s)
       if [ $((NOW - LAST_ALERT)) -lt 10 ]; then
           exit 0 
       fi
   fi
   touch "$CACHE_FILE"
   
   # --- 2. Log to the system journal ---
   logger -p authpriv.warning -t CLAMAV-ALERT "Malware $VIRUS_NAME found at $FILE_PATH"
   
   # --- 3. Determine who to notify ---
   if [ -f "$FILE_PATH" ]; then
       TARGET_USER=$(stat -c '%U' "$FILE_PATH")
   else
       TARGET_USER="root"
   fi
   
   # OVERRIDE: If the file is in a user's home directory, alert that user directly 
   if [[ "$FILE_PATH" == /home/* ]]; then
       TARGET_USER=$(echo "$FILE_PATH" | awk -F'/' '{print $3}')
   fi
   
   # --- 4. Notification Function ---
   send_alerts() {
       local USER_TO_ALERT="$1"
       
       # Send SSH/Terminal Alert
       if id "$USER_TO_ALERT" &>/dev/null; then
           
           # FILTER: Use 'ps' to find TTYs actively running a shell. 
           # This finds hidden GUI terminals and ignores overlapping SSH/tmux wrappers.
           local USER_TTYS=$(ps -u "$USER_TO_ALERT" -o tty=,comm= | awk '$2 ~ /^(bash|zsh|fish|tcsh|ksh|sh)$/ {print $1}' | grep -E '^(pts/|tty)' | sort -u)
           
           for TERM_DEV in $USER_TTYS; do
               if [ -w "/dev/$TERM_DEV" ]; then
                   echo -e "\a\r\n================================================================\r
   🚨 CLAMAV ALERT: Malware detected! 🚨\r
   Threat: $VIRUS_NAME\r
   Location: $FILE_PATH\r
   Action: Quarantined\r
   ================================================================\r\n" > "/dev/$TERM_DEV"
               fi
           done
       fi
   
       # Send GUI Alert
       local GUI_DISPLAY=$(who | grep "^$USER_TO_ALERT " | grep -E '(:[0-9])' | awk '{print $2}' | head -n 1)
       if [ -n "$GUI_DISPLAY" ]; then
           local UID_TO_ALERT=$(id -u "$USER_TO_ALERT")
           local message=$(printf "<b>Threat:</b> '%s'\n<b>Location:</b> '%s'\n<b>Action:</b> Quarantined" "$VIRUS_NAME" "$FILE_PATH")
   
           # PLAY AUDIO: Automatically detect and use the available audio player
           if command -v pw-play &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" pw-play /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null &
           elif command -v paplay &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null &
           elif command -v canberra-gtk-play &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env display="$GUI_DISPLAY" XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" canberra-gtk-play -i dialog-warning 2>/dev/null &
           elif command -v aplay &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null &
           fi
   
           # FIRE NOTIFICATION: Send the visual pop-up
           sudo -u "$USER_TO_ALERT" env DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$UID_TO_ALERT/bus" notify-send -u critical -t 10000 -i security-high "ClamAV Threat Detected" "$MESSAGE"
       fi
   }
   
   # --- 5. Execute Alerts ---
   if [ "$TARGET_USER" == "root" ]; then
       for ACTIVE_USER in $(who | awk '{print $1}' | sort -u); do
           send_alerts "$ACTIVE_USER"
       done
   else
       send_alerts "$TARGET_USER"
   fi

4. Make the script executable

   sudo chmod +x /usr/local/bin/clamav-notify.sh

5. Grant clamscan sudo permission to execute the script

   sudo visudo -f /etc/sudoers.d/clamav-notify

   1. Add the following two lines to the new file

      Defaults!/usr/local/bin/clamav-notify.sh env_keep += "CLAM_VIRUSEVENT_FILENAME CLAM_VIRUSEVENT_VIRUSNAME"
      clamscan all=(root) NOPASSWD: /usr/local/bin/clamav-notify.sh

6. Edit the scan config to trigger the notification

   sudo nano /etc/clamd.d/scan.conf

   1. Update or add the following line in the VirusEvent section

      VirusEvent sudo /usr/local/bin/clamav-notify.sh

7. Restart the Daemons

   sudo systemctl restart clamd@scan clamonacc

This will attempt to notify the user that downloaded the file. You can customize the script as needed for your environment. The script tries to see who owns the file to determine who might have downloaded it. Ownership will be overwritten by the user folder the file was downloaded to (this allows the script to handle files downloaded using sudo). If ownership can't be determined, it will notify all users on the device.

For notifications, it will provide an alert in all shell sessions (local and ssh) and an alert via the GUI. It also attempts to play an alert sound via the shell and via the GUI.

1. Install libnotify if not already installed

   sudo apt install -y libnotify-bin

2. Create notification script

   sudo nano /usr/local/bin/clamav-notify.sh

3. Paste the following into the script file

   #!/bin/bash
   
   # Pull the values securely from ClamAV's environment variables
   VIRUS_NAME="$CLAM_VIRUSEVENT_VIRUSNAME"
   FILE_PATH="$CLAM_VIRUSEVENT_FILENAME"
   
   # If FILE_PATH starts with /var/quarantine, exit immediately
   if [[ "$FILE_PATH" =~ ^/var/quarantine/ ]]; then
        exit 0
   fi
   
   # --- 1. SECURE DEBOUNCE & CACHE ---
   ALERTS_DIR="/run/clamav-alerts"
   mkdir -p "$ALERTS_DIR"
   chmod 700 "$ALERTS_DIR"
   
   # Clean up cache files older than 10 minutes to prevent accumulation
   find "$ALERTS_DIR" -type f -mmin +10 -delete
   
   SAFE_PATH=$(echo "$FILE_PATH" | tr '/' '_')
   CACHE_FILE="${ALERTS_DIR}/clamav_alert_${SAFE_PATH}"
   
   if [ -f "$CACHE_FILE" ]; then
       LAST_ALERT=$(stat -c %Y "$CACHE_FILE" 2>/dev/null)
       now=$(date +%s)
       if [ $((NOW - LAST_ALERT)) -lt 10 ]; then
           exit 0 
       fi
   fi
   touch "$CACHE_FILE"
   
   # --- 2. Log to the system journal ---
   logger -p authpriv.warning -t CLAMAV-ALERT "Malware $VIRUS_NAME found at $FILE_PATH"
   
   # --- 3. Determine who to notify ---
   if [ -f "$FILE_PATH" ]; then
       TARGET_USER=$(stat -c '%U' "$FILE_PATH")
   else
       TARGET_USER="root"
   fi
   
   # OVERRIDE: If the file is in a user's home directory, alert that user directly 
   if [[ "$FILE_PATH" == /home/* ]]; then
       TARGET_USER=$(echo "$FILE_PATH" | awk -F'/' '{print $3}')
   fi
   
   # --- 4. Notification Function ---
   send_alerts() {
       local USER_TO_ALERT="$1"
       
       # Send SSH/Terminal Alert
       if id "$USER_TO_ALERT" &>/dev/null; then
           
           # FILTER: Use 'ps' to find TTYs actively running a shell. 
           # This finds hidden GUI terminals and ignores overlapping SSH/tmux wrappers.
           local USER_TTYS=$(ps -u "$USER_TO_ALERT" -o tty=,comm= | awk '$2 ~ /^(bash|zsh|fish|tcsh|ksh|sh)$/ {print $1}' | grep -E '^(pts/|tty)' | sort -u)
           
           for TERM_DEV in $USER_TTYS; do
               if [ -w "/dev/$TERM_DEV" ]; then
                   echo -e "\a\r\n================================================================\r
   🚨 CLAMAV ALERT: Malware detected! 🚨\r
   Threat: $VIRUS_NAME\r
   Location: $FILE_PATH\r
   Action: Quarantined\r
   ================================================================\r\n" > "/dev/$TERM_DEV"
               fi
           done
       fi
   
       # Send GUI Alert (Wayland & X11 compatible)
       local UID_TO_ALERT=$(id -u "$USER_TO_ALERT")
       local DBUS_PATH="/run/user/$UID_TO_ALERT/bus"
       
       if [ -S "$DBUS_PATH" ]; then
           local message=$(printf "Threat: '%s'\nLocation: '%s'\nAction: Quarantined" "$VIRUS_NAME" "$FILE_PATH")
   
           # PLAY AUDIO: Automatically detect and use the available audio player
           if command -v pw-play &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" pw-play /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null &
           elif command -v paplay &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null &
           elif command -v aplay &> /dev/null; then
               sudo -u "$USER_TO_ALERT" env XDG_RUNTIME_DIR="/run/user/$UID_TO_ALERT" aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null &
           fi
   
           # FIRE NOTIFICATION: Send the visual pop-up
           sudo -u "$USER_TO_ALERT" env DBUS_SESSION_BUS_ADDRESS="unix:path=$DBUS_PATH" notify-send -u critical -t 10000 -i security-high "ClamAV Threat Detected" "$MESSAGE"
       fi
   }
   
   # --- 5. Execute Alerts ---
   if [ "$TARGET_USER" == "root" ]; then
       for ACTIVE_USER in $(who | awk '{print $1}' | sort -u); do
           send_alerts "$ACTIVE_USER"
       done
   else
       send_alerts "$TARGET_USER"
   fi

4. Make the script executable

   sudo chmod +x /usr/local/bin/clamav-notify.sh

5. Grant clamav sudo permission to execute the script

   sudo visudo -f /etc/sudoers.d/clamav-notify

   1. Add the following two lines to the new file

      Defaults!/usr/local/bin/clamav-notify.sh env_keep += "CLAM_VIRUSEVENT_FILENAME CLAM_VIRUSEVENT_VIRUSNAME"
      clamav all=(root) NOPASSWD: /usr/local/bin/clamav-notify.sh

6. If the aa-complain AppArmor option wasn't used, configure AppArmor to allow clamav to access the notification script.
   1. Edit the local AppArmor override file

      sudo nano /etc/apparmor.d/local/usr.sbin.clamd

   2. Add the following lines to trigger the notification script

      # Allow clamd to spawn the shell required to run the VirusEvent command
      /usr/bin/dash ix,
      /usr/bin/sh ix,
      
      # Allow the daemon to execute the notification script via sudo
      /usr/bin/sudo PUx,
      /usr/local/bin/clamav-notify.sh PUx,

   3. Reload the AppArmor profile

      sudo apparmor_parser -r /etc/apparmor.d/usr.sbin.clamd

7. Edit the scan config to trigger the notification

   sudo nano /etc/clamav/clamd.conf

   1. Update or add the following line in the VirusEvent section

      # Trigger notification script on event
      VirusEvent sudo /usr/local/bin/clamav-notify.sh

8. Restart the Daemons

   sudo systemctl restart clamav-daemon clamav-clamonacc