clamAV-Utils

Python 3 Bash ClamAV multiprocessing tqdm Security

GitHub: stevenvo780/clamAV-Utils

---

What it is

clamAV-Utils provides a parallel, scriptable wrapper around ClamAV (clamdscan / clamscan) that makes large filesystem scans practical: it batches files, distributes batches across CPU cores, shows a live progress bar, quarantines infected files, and writes structured logs — all from a single CLI command.

The repo contains two implementations:

File	Approach
antivirus.py	Python 3 — multiprocessing.Pool, tqdm, argparse, full quarantine support
cleanVirus.sh	Bash — GNU parallel + pv, auto-installs deps via apt, simpler but less configurable

antivirus.py is the primary tool. cleanVirus.sh is an older approach kept for reference.

---

How it works

antivirus.py scans one or more directories in parallel:

1. Walk: recursively lists all files under the target directories; skips unreadable files with a warning.
2. Exclude system dirs: /proc, /sys, /dev, /run, /tmp, /var/lib, /var/run are excluded by default to avoid spurious errors and infinite loops.
3. Batch: divides the file list into batches (default 500 files per batch).
4. Parallel scan: submits batches to a multiprocessing.Pool; each worker calls clamdscan (preferred) or clamscan as a subprocess.
5. Quarantine: if --quarantine-dir is specified, infected files are moved there via clamdscan --move=<dir>.
6. Progress: tqdm shows a live progress bar with batch count and ETA.
7. Logging: every scan event (clean, infected, error, permission denied) is appended to the log file.

---

Installation

Python (recommended)

git clone https://github.com/stevenvo780/clamAV-Utils.git
cd clamAV-Utils

# Install ClamAV (Debian/Ubuntu)
sudo apt install clamav clamav-daemon

# Install Python dependency
pip install tqdm

# Update virus definitions
sudo freshclam

Arch / CachyOS

sudo pacman -S clamav
pip install tqdm

# Enable and start the ClamAV daemon
sudo systemctl enable --now clamav-daemon
sudo freshclam

Bash variant

# cleanVirus.sh auto-installs its own deps via apt:
#   clamav, parallel, pv
# Just run it directly:
bash cleanVirus.sh /home /var/www

clamdscan vs clamscan

antivirus.py prefers clamdscan (daemon mode) for speed — the daemon keeps virus signatures in memory and responds instantly to scan requests. If clamdscan is not available, it falls back to clamscan automatically. For large scans, starting clamav-daemon first makes a significant difference in throughput.

---

Usage

# Basic scan of home directory
python3 antivirus.py /home

# Scan multiple directories with 8 parallel workers
python3 antivirus.py /home /var/www -j 8

# Quarantine infected files
python3 antivirus.py /home --quarantine-dir /var/quarantine

# Update virus definitions first, then scan
python3 antivirus.py /home --update-db

# Custom batch size and log file
python3 antivirus.py /home --batch-size 200 --log-file /var/log/myscan.log

# Exclude additional directories
python3 antivirus.py /home --exclude-dirs /home/user/.cache /home/user/.local/share/Steam

# Use all cores except 2 (leave headroom for other processes)
python3 antivirus.py /home --nucleos-libres 2

---

CLI reference

Argument	Default	Description
directories	(required)	One or more paths to scan
-j, --jobs	CPU count	Number of parallel worker processes
--nucleos-libres	0	Reserve N cores — effective jobs = CPUs − N
--exclude-dirs	system dirs	Additional directories to skip
--quarantine-dir	(none)	Move infected files here instead of leaving them in place
--log-file	clamav_scan.log	Path to the output log file
--batch-size	500	Files per batch sent to each worker
--update-db	off	Run freshclam before scanning

---

Stack

Layer	Technology
Scanner	ClamAV (clamdscan / clamscan)
Parallelism	Python multiprocessing.Pool
Progress bar	tqdm
CLI	argparse
Quarantine	clamdscan --move + shutil
Logging	Python logging (file + stderr)
Bash variant	GNU parallel + pv