release(v3.1.3): ClamAV exclude paths (Admin + env) for upload scanning (answers #94)

- add VIRUS_SCAN_EXCLUDE_DIRS (env) + Admin setting to exclude upload paths from ClamAV scanning
- support comma/newline-separated exclude paths relative to the source root
- allow per-source excludes via `sourceId:/path` prefixes (Pro Sources)
- apply excludes in UploadModel scan flow (local + shared-folder uploads) and lock Admin field when env is set

Author: error311

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## Changes 01/20/2026 (v3.1.3)
+
+`release(v3.1.3): ClamAV exclude paths (Admin + env) for upload scanning (answers #94)`
+
+**Commit message**  
+
+```text
+release(v3.1.3): ClamAV exclude paths (Admin + env) for upload scanning (answers #94)
+
+- add VIRUS_SCAN_EXCLUDE_DIRS (env) + Admin setting to exclude upload paths from ClamAV scanning
+- support comma/newline-separated exclude paths relative to the source root
+- allow per-source excludes via `sourceId:/path` prefixes (Pro Sources)
+- apply excludes in UploadModel scan flow (local + shared-folder uploads) and lock Admin field when env is set
+```
+
+**Added**  
+
+- **ClamAV exclude paths setting**
+  - Admin setting: **Exclude upload paths** (`clamav.excludeDirs`)
+  - Env override: `VIRUS_SCAN_EXCLUDE_DIRS` (locks the Admin field when set)
+  - Input format: comma or newline-separated paths **relative to the source root**
+    - Examples: `snapshot`, `tmp`
+    - Pro Sources: prefix with a source id: `s3:/snapshot`, `gdrive:/tmp`
+
+**Changed**  
+
+- **Upload virus scan now checks excludes before running ClamAV**
+  - Exclude rules are normalized (trim, normalize slashes, strip leading/trailing `/`)
+  - Rules can optionally target a specific source id; otherwise they apply to the active source
+- **Shared-folder uploads pass folder context into the scan**
+  - Shared uploads now reuse the same exclude logic by providing the destination folder key.
+
+**Notes**  
+
+- Excludes match against the *destination folder path* (relative to the source root). Keep patterns simple (short paths) for predictable behavior.
+- If `VIRUS_SCAN_EXCLUDE_DIRS` is set, it is treated as the source of truth and the Admin field is read-only.
+
+---
+
 ## Changes 01/20/2026 (v3.1.2)
 
 `release(v3.1.2): configurable ignore rules for indexing/tree + admin UX polish (fixes #91, refs #92)`

public/js/adminPanel.js

@@ -2378,6 +2378,7 @@ function captureInitialAdminConfig() {
     ignoreRegex: (document.getElementById("ignoreRegex")?.value || "").trim(),
 
     clamavScanUploads: !!document.getElementById("clamavScanUploads")?.checked,
+    clamavExcludeDirs: (document.getElementById("clamavExcludeDirs")?.value || "").trim(),
     proSearchEnabled: !!document.getElementById("proSearchEnabled")?.checked,
     proSearchLimit: (document.getElementById("proSearchLimit")?.value || "").trim(),
     proAuditEnabled: !!document.getElementById("proAuditEnabled")?.checked,
@@ -2423,6 +2424,7 @@ function hasUnsavedChanges() {
     getVal("fileListSummaryDepth") !== (o.fileListSummaryDepth || "") ||
     getVal("ignoreRegex") !== (o.ignoreRegex || "") ||
     getChk("clamavScanUploads") !== o.clamavScanUploads ||
+    getVal("clamavExcludeDirs") !== (o.clamavExcludeDirs || "") ||
     getChk("proSearchEnabled") !== o.proSearchEnabled ||
     getVal("proSearchLimit") !== o.proSearchLimit ||
     getChk("proAuditEnabled") !== o.proAuditEnabled ||
@@ -4691,6 +4693,28 @@ export function openAdminPanel() {
     </small>
   </div>
 
+  <div class="form-group" style="margin-top:10px;">
+    <label for="clamavExcludeDirs">
+      ${tf("clamav_exclude_dirs_label", "Exclude upload paths")}
+    </label>
+    <textarea
+      id="clamavExcludeDirs"
+      class="form-control"
+      rows="2"
+      placeholder="${escapeHTML(tf("clamav_exclude_dirs_placeholder", "snapshot, tmp"))}"
+    ></textarea>
+    <small
+      id="clamavExcludeDirsHelp"
+      class="d-block text-muted"
+      style="margin-top:2px;"
+    >
+      ${tf(
+          "clamav_exclude_dirs_help",
+          "Comma or newline separated paths relative to the source root (example: snapshot, tmp). For Pro sources you can prefix with source id (example: s3:/snapshot)."
+        )}
+    </small>
+  </div>
+
   <div class="mt-2">
     <button
       type="button"
@@ -6018,6 +6042,18 @@ ${t("shared_max_upload_size_bytes")}
             }
           }
         }
+        const clamExclude = document.getElementById("clamavExcludeDirs");
+        if (clamExclude) {
+          clamExclude.value = (cfgClam.excludeDirs || "").toString();
+          if (cfgClam.excludeLockedByEnv) {
+            clamExclude.disabled = true;
+            const help = document.getElementById("clamavExcludeDirsHelp");
+            if (help) {
+              help.textContent =
+                'Controlled by container env VIRUS_SCAN_EXCLUDE_DIRS. Change it in your Docker/host env.';
+            }
+          }
+        }
         // Rebuild ONLYOFFICE section from fresh config
         initOnlyOfficeUI({ config });
 
@@ -6121,6 +6157,23 @@ ${t("shared_max_upload_size_bytes")}
             }
           }
         }
+        const clamExclude = document.getElementById("clamavExcludeDirs");
+        if (clamExclude) {
+          clamExclude.value = (cfgClam.excludeDirs || "").toString();
+          clamExclude.disabled = false;
+          const help = document.getElementById("clamavExcludeDirsHelp");
+          if (help) {
+            help.textContent =
+              'Comma or newline separated paths relative to the source root (example: snapshot, tmp). For Pro sources you can prefix with source id (example: s3:/snapshot).';
+          }
+          if (cfgClam.excludeLockedByEnv) {
+            clamExclude.disabled = true;
+            if (help) {
+              help.textContent =
+                'Controlled by container env VIRUS_SCAN_EXCLUDE_DIRS. Change it in your Docker/host env.';
+            }
+          }
+        }
         const uploadScope = document.getElementById("uploadContent");
         const headerSettingsScope = document.getElementById("headerSettingsContent");
         wireIgnoreRegexPresetButton(headerSettingsScope);
@@ -6318,6 +6371,7 @@ function handleSave() {
     },
     clamav: {
       scanUploads: document.getElementById("clamavScanUploads").checked,
+      excludeDirs: (document.getElementById("clamavExcludeDirs")?.value || "").trim(),
     },
     proSearch: {
       enabled: !!document.getElementById("proSearchEnabled")?.checked,

src/controllers/AdminController.php

@@ -1768,6 +1768,7 @@ public function updateConfig(): void
             ],
             'clamav'              => [
                 'scanUploads' => false,
+                'excludeDirs' => '',
             ],
             'proAudit'            => [
                 'enabled' => false,
@@ -2033,6 +2034,8 @@ public function updateConfig(): void
         // --- ClamAV: store admin toggle only when not locked by env/constant ---
         $envScanRaw    = getenv('VIRUS_SCAN_ENABLED');
         $clamLockedEnv = ($envScanRaw !== false && $envScanRaw !== '') || defined('VIRUS_SCAN_ENABLED');
+        $envExcludeRaw = getenv('VIRUS_SCAN_EXCLUDE_DIRS');
+        $clamExcludeLockedEnv = ($envExcludeRaw !== false && trim((string)$envExcludeRaw) !== '');
 
         if (!$clamLockedEnv && isset($data['clamav']) && is_array($data['clamav'])) {
             if (array_key_exists('scanUploads', $data['clamav'])) {
@@ -2042,6 +2045,13 @@ public function updateConfig(): void
                 );
             }
         }
+        if (!$clamExcludeLockedEnv && isset($data['clamav']) && is_array($data['clamav'])) {
+            if (array_key_exists('excludeDirs', $data['clamav'])) {
+                $rawExclude = (string)$data['clamav']['excludeDirs'];
+                $rawExclude = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', '', $rawExclude);
+                $merged['clamav']['excludeDirs'] = trim((string)$rawExclude);
+            }
+        }
 
         // --- Pro Search Everywhere: respect env lock, otherwise persist toggle/limit ---
         $envProSearch    = getenv('FR_PRO_SEARCH_ENABLED');

src/controllers/FolderController.php

@@ -1652,7 +1652,17 @@ public function uploadToSharedFolder(): void
         }
 
         // ---- ClamAV: reuse UploadModel scan logic on the tmp file ----
-        $scan = UploadModel::scanSingleUploadIfEnabled($fileUpload);
+        $shareRecord = FolderModel::getShareFolderRecord($token);
+        $shareFolderKey = 'root';
+        if (is_array($shareRecord)) {
+            $rawFolder = trim((string)($shareRecord['folder'] ?? ''), "/\\ ");
+            $shareFolderKey = ($rawFolder === '' ? 'root' : $rawFolder);
+        }
+        $scan = UploadModel::scanSingleUploadIfEnabled($fileUpload, [
+            'folder' => $shareFolderKey,
+            'file'   => $basename,
+            'source' => 'shared',
+        ]);
         if (is_array($scan) && isset($scan['error'])) {
             // scanSingleUploadIfEnabled() already deletes the tmp file on infection
             http_response_code(400);

src/models/AdminModel.php

@@ -226,6 +226,15 @@ public static function buildPublicSubset(array $config): array
             $clamLockedByEnv = false;
         }
 
+        $envExcludeRaw = getenv('VIRUS_SCAN_EXCLUDE_DIRS');
+        if ($envExcludeRaw !== false && trim((string)$envExcludeRaw) !== '') {
+            $clamExcludeDirs = trim((string)$envExcludeRaw);
+            $clamExcludeLockedByEnv = true;
+        } else {
+            $clamExcludeDirs = (string)($config['clamav']['excludeDirs'] ?? '');
+            $clamExcludeLockedByEnv = false;
+        }
+
         // Pro search (public awareness + env lock)
         $proSearchCfg = isset($config['proSearch']) && is_array($config['proSearch'])
             ? $config['proSearch']
@@ -255,6 +264,8 @@ public static function buildPublicSubset(array $config): array
         $public['clamav'] = [
             'scanUploads' => $clamScanUploads,
             'lockedByEnv' => $clamLockedByEnv,
+            'excludeDirs' => $clamExcludeDirs,
+            'excludeLockedByEnv' => $clamExcludeLockedByEnv,
         ];
 
         $public['proSearch'] = [
@@ -403,13 +414,20 @@ public static function updateConfig(array $configUpdate): array
             $configUpdate['uploads']['resumableChunkMb'] = max(0.5, min(100, $num));
         }
 
-        // ---- ClamAV (simple boolean flag) ----
+        // ---- ClamAV (upload scan toggle + exclude list) ----
         if (!isset($configUpdate['clamav']) || !is_array($configUpdate['clamav'])) {
             $configUpdate['clamav'] = [
                 'scanUploads' => false,
+                'excludeDirs' => '',
             ];
         } else {
             $configUpdate['clamav']['scanUploads'] = !empty($configUpdate['clamav']['scanUploads']);
+            $rawExclude = $configUpdate['clamav']['excludeDirs'] ?? '';
+            if (!is_string($rawExclude)) {
+                $rawExclude = '';
+            }
+            $rawExclude = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', '', $rawExclude);
+            $configUpdate['clamav']['excludeDirs'] = trim((string)$rawExclude);
         }
 
         // Normalize authBypass & authHeaderName
@@ -901,6 +919,7 @@ public static function getConfig(): array
             ],
             'clamav'                => [
                 'scanUploads' => false,
+                'excludeDirs' => '',
             ],
             'publishedUrl'          => '',
             'ffmpegPath'            => '',

src/models/UploadModel.php

@@ -211,6 +211,102 @@ private static function isVirusScanEnabled(): bool
         return !empty($cfg['clamav']['scanUploads']);
     }
 
+    private static function getVirusScanExcludeRules(): array
+    {
+        static $rules = null;
+        if ($rules !== null) {
+            return $rules;
+        }
+
+        $raw = '';
+        $env = getenv('VIRUS_SCAN_EXCLUDE_DIRS');
+        if ($env !== false && trim((string)$env) !== '') {
+            $raw = (string)$env;
+        } elseif (class_exists('AdminModel')) {
+            $cfg = AdminModel::getConfig();
+            if (is_array($cfg) && !isset($cfg['error'])) {
+                $raw = (string)($cfg['clamav']['excludeDirs'] ?? '');
+            }
+        }
+
+        $rules = [];
+        if (trim($raw) !== '') {
+            $parts = preg_split('/[,\r\n]+/', $raw);
+            if (is_array($parts)) {
+                foreach ($parts as $entry) {
+                    $entry = trim((string)$entry);
+                    if ($entry === '') {
+                        continue;
+                    }
+
+                    $source = '';
+                    $path = $entry;
+                    if (strpos($entry, ':') !== false) {
+                        [$maybeSource, $rest] = explode(':', $entry, 2);
+                        $maybeSource = trim($maybeSource);
+                        if ($maybeSource !== '' && preg_match('/^[A-Za-z0-9_-]{1,64}$/', $maybeSource)) {
+                            $source = $maybeSource;
+                            $path = $rest;
+                        }
+                    }
+
+                    $path = self::normalizeVirusScanExcludePath($path);
+                    if ($path === '') {
+                        continue;
+                    }
+
+                    $rules[] = [
+                        'source' => $source,
+                        'path'   => $path,
+                    ];
+                }
+            }
+        }
+
+        return $rules;
+    }
+
+    private static function normalizeVirusScanExcludePath(string $path): string
+    {
+        $norm = str_replace('\\', '/', trim($path));
+        return trim($norm, "/ \t\n\r\0\x0B");
+    }
+
+    private static function isVirusScanExcluded(array $context): bool
+    {
+        $rules = self::getVirusScanExcludeRules();
+        if (empty($rules)) {
+            return false;
+        }
+
+        $folder = trim((string)($context['folder'] ?? ''));
+        if ($folder === '') {
+            return false;
+        }
+        $folder = self::normalizeVirusScanExcludePath($folder);
+        if ($folder === '') {
+            return false;
+        }
+
+        $activeSource = class_exists('SourceContext') ? SourceContext::getActiveId() : 'local';
+
+        foreach ($rules as $rule) {
+            $ruleSource = (string)($rule['source'] ?? '');
+            if ($ruleSource !== '' && $ruleSource !== $activeSource) {
+                continue;
+            }
+            $path = (string)($rule['path'] ?? '');
+            if ($path === '') {
+                continue;
+            }
+            if ($folder === $path || str_starts_with($folder, $path . '/')) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Public helper: scan a single $_FILES-style upload array, if ClamAV is enabled.
      *
@@ -774,6 +870,10 @@ private static function scanFileIfEnabled(string $path, array $context = []): ?a
             return ['error' => 'Virus scan failed: uploaded file not found.'];
         }
 
+        if (self::isVirusScanExcluded($context)) {
+            return null; // excluded path
+        }
+
         $cmd = defined('VIRUS_SCAN_CMD') ? VIRUS_SCAN_CMD : 'clamscan';
 
         $cmdline = escapeshellcmd($cmd)