A lightweight antivirus scanner for Debian-based Linux systems (Ubuntu, Pop!_OS, Debian, etc.) that integrates with VirusTotal API to scan files and folders for malware.
- 🔍 File Scanning: Scan individual files or entire directories
- 📁 Directory Scanning: Recursive directory scanning with configurable depth
- 🎯 Extension Filtering: Filter scans by file extensions (.deb, .appimage, etc.)
- 👁️ File Monitoring: Real-time monitoring of directories for new files
- ⚙️ Configuration File: Easy configuration management
- 📊 Detailed Reports: Clear scan results with threat detection statistics
- 🔒 VirusTotal Integration: Leverage 70+ antivirus engines via VirusTotal API
- 💾 API Quota Management: Warnings when approaching API limits
- Python 3.6 or higher
- Debian-based Linux distribution (Ubuntu, Pop!_OS, Debian, Linux Mint, etc.)
- VirusTotal API key (free tier available)
- Clone the repository:
git clone https://github.com/rykemc/Linux-av.git
cd Linux-av- Run the installation script:
chmod +x install.sh
sudo ./install.sh- Edit the configuration file and add your VirusTotal API key:
nano ~/.linux-av.conf- Install dependencies:
sudo apt update
sudo apt install python3 python3-pip
pip3 install -r requirements.txt- Make scripts executable:
chmod +x linux_av.py file_monitor.py- Create a configuration file:
./linux_av.py --create-configThe configuration file is located at ~/.linux-av.conf by default.
[VirusTotal]
api_key = YOUR_API_KEY_HERE
[Scanning]
extensions = .deb, .appimage, .exe, .sh, .run
download_dir = /home/username/Downloads
schedule = manual- api_key: Your VirusTotal API key (get one at https://www.virustotal.com/)
- extensions: Comma-separated list of file extensions to scan
- download_dir: Default directory to monitor for new files
- schedule: Scan schedule (currently: manual)
- Visit https://www.virustotal.com/
- Create a free account
- Go to your profile settings
- Copy your API key
- Add it to your configuration file
Note: The free tier allows up to 500 requests per day and 4 requests per minute.
linux-av --file /path/to/suspicious_file.deb# Scan Downloads folder (non-recursive)
linux-av --directory ~/Downloads
# Scan recursively
linux-av --directory ~/Downloads --recursive# Only scan .deb and .appimage files
linux-av --directory ~/Downloads --extensions .deb .appimage# Monitor Downloads folder
linux-av-monitor --directory ~/Downloads
# Monitor with extension filter
linux-av-monitor --directory ~/Downloads --extensions .deb .appimage
# Monitor multiple directories
linux-av-monitor --directory ~/Downloads /tmp/downloadslinux-av --config /path/to/config.conf --file myfile.deboptional arguments:
-h, --help Show help message
--config, -c PATH Configuration file path (default: ~/.linux-av.conf)
--file, -f PATH Scan a single file
--directory, -d PATH Scan a directory
--recursive, -r Scan directory recursively
--extensions, -e EXT File extensions to scan (e.g., .deb .appimage)
--api-key KEY VirusTotal API key (overrides config)
--create-config Create default configuration file
optional arguments:
-h, --help Show help message
--config, -c PATH Configuration file path
--directory, -d PATH Directories to monitor (can specify multiple)
--extensions, -e EXT File extensions to scan
linux-av --directory ~/Downloads --extensions .deblinux-av-monitor --directory ~/Downloads --extensions .appimage# Scan common download locations
linux-av --directory ~/Downloads --recursive
linux-av --directory ~/Desktop
linux-av --directory /tmp# Enable and start the monitoring service
sudo systemctl enable linux-av-monitor
sudo systemctl start linux-av-monitor
# Check status
sudo systemctl status linux-av-monitor
# View logs
journalctl -u linux-av-monitor -fWhen a file is scanned, you'll see output like:
Scanning: /home/user/Downloads/file.deb
✅ Clean
Clean: 65, Malicious: 0, Suspicious: 0
or if a threat is detected:
Scanning: /home/user/Downloads/suspicious.exe
🚨 THREAT DETECTED!
Malicious: 45, Suspicious: 12
The numbers represent how many antivirus engines detected the file as:
- Malicious: Confirmed malware
- Suspicious: Potentially unwanted or suspicious behavior
- Clean: Safe/harmless
The free VirusTotal API has limits:
- 500 requests per day
- 4 requests per minute
The scanner will:
- Warn you when scanning many files
- Stop scanning if rate limit is reached
- Show API request count in scan summary
Tips to conserve API quota:
- Use extension filters to scan only specific file types
- Avoid recursive scans of large directories
- The scanner checks file hashes first (cached results) before uploading
- Keep your API key secure: Don't share your configuration file
- Review threats carefully: Investigate any detected threats
- Use extension filters: Focus on potentially dangerous file types
- Regular scans: Periodically scan download directories
- File size limits: Free API has 32MB file size limit
Edit your config file and add your API key:
nano ~/.linux-av.confYou've hit the daily or per-minute limit. Wait before scanning more files, or:
- For daily limit: Wait until the next day
- For per-minute limit: Wait 60 seconds
The free VirusTotal API doesn't support files over 32MB. Consider:
- Using VirusTotal Premium API
- Skipping large files
- Manually checking large files on virustotal.com
Make sure pyinotify is installed:
pip3 install pyinotifyContributions are welcome! Please feel free to submit a Pull Request.
This project is open source and available under the MIT License.
This tool is provided as-is for educational and security purposes. While VirusTotal aggregates results from 70+ antivirus engines, no antivirus solution is 100% effective. Always exercise caution when handling suspicious files.
For issues, questions, or suggestions, please open an issue on GitHub.
- VirusTotal for providing the scanning API
- The Python community for excellent libraries
- Contributors and users of this tool