VirusTotal Shell Helper

A lightweight shell script to check file cleanliness via VirusTotal. No Python, no complex setup — just vt CLI, jq, and bash.

Important

This tool is not a replacement for real-time antivirus software. It provides on-demand scanning and file quarantine capabilities but does not offer real-time protection, behavioral analysis, or active threat prevention. Use this alongside proper security software, not as a substitute.

Features

• Hash-based lookup — checks if file already exists in VirusTotal before uploading
• Auto-upload — uploads new files for analysis if not found
• Desktop notifications — supports notify-send, dunstify, kdialog, zenity
• File manager integration — right-click context menu for supported file managers
• Auto-tagging — tags files as clean/malicious (visible in KDE Dolphin)
• Auto-lockdown — removes execute/write permissions from malicious files
• One-click quarantine — isolate malicious files with noexec protection
• Comprehensive audit logging — JSON logs track all scans, detections, and file actions

Quick Start

Installation

./install.sh

The installer will:

1. Check system dependencies
2. Download vt CLI if needed
3. Install vt-check, vt-actions.sh, and vt-manage to ~/.local/bin/
4. Set up file manager context menu integration
5. Optionally configure tmpfs quarantine mount

After installation, configure your VirusTotal API key:

vt init

Get a free API key at: https://www.virustotal.com/gui/my-apikey

Uninstallation

./uninstall.sh

The uninstaller will:

1. Remove all installed scripts
2. Remove file manager integrations
3. Optionally remove quarantine files and audit logs
4. Optionally remove tmpfs mount (if configured)

Usage

vt-check [OPTIONS] <file>

Options:
  --no-wait    Don't wait for analysis if upload needed
  --notify     Show desktop notifications
  -h, --help   Show help

Or right-click any file → Scan with VirusTotal

Supported Platforms

Tested on:

• CachyOS, KDE Plasma, Dolphin

Should work on:

• Most Linux distributions with supported file managers
• Notification backends: notify-send (libnotify), dunstify, kdialog, zenity
• File managers: Dolphin, Nautilus, Nemo, Thunar, Caja

Contributions and testing on other platforms welcome!

Requirements

• vt — VirusTotal CLI
• jq — JSON processor
• sha256sum — usually pre-installed

Documentation

See docs/ or the 📖 Wiki for detailed documentation:

• Installation — setup guide
• Usage — CLI options and examples
• How It Works — technical overview
• File Managers — context menu setup
• Quarantine & Tagging — file tagging and quarantine features
• Audit Logging — complete scan and action history in JSON format
• Isolation — noexec mount setup for enhanced security
• Features — quick reference guide
• Troubleshooting — common issues

Privacy & Security

Warning

Files uploaded to VirusTotal are shared with security researchers and antivirus companies. Do not upload sensitive or confidential files.

Contributing

Contributions and testing on other platforms welcome! See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Links

• 📖 Documentation Wiki
• VirusTotal CLI
• Get a Free API Key

---

Note: This is an unofficial tool and is not affiliated with or endorsed by VirusTotal.