VirusTotal Shell Helper

Fast hash lookups and on-demand VirusTotal malware analysis for Linux — right from your desktop.

VirusTotal Shell Helper adds VirusTotal checks to your everyday Linux workflow:

right-click (or run from shell/script) > hash lookup > auto-upload if unknown > notify > tag > quarantine (optional)

It’s written in bash, intentionally lightweight, and built around the official VirusTotal CLI (vt); leveraging the VirusTotal API — no Python environments or heavy frameworks.

Not a real-time antivirus — it’s an on-demand verification helper.

Why I built this

On Linux I found myself constantly switching between terminal and browser whenever I needed to verify a suspicious download. A lot of tooling either pulled in heavy dependencies, lacked proper desktop integration, or pushed you toward manual web uploads.

I wanted something that feels like part of the system: fast, lightweight, and integrated with the file manager — the Unix philosophy applied to a real workflow.

Confession: I probably over-engineered quarantine/auditing — tmpfs isolation, optional noexec, and structured JSON logs. Overkill? Maybe. Useful? Definitely.

What’s next (how I plan to use it)

For my own setup I am working on adding a Downloads watcher that calls vt-check for new files. No core feature changes required — this project already supports CLI use — it’s just workflow glue for my environment.

What it does

Hash-first lookup: checks VirusTotal for an existing report before uploading (saves time and quota).
Automatic upload when missing: if there’s no existing report, it uploads the file for analysis.
Desktop integration: right-click context menus + native notifications (notify-send, dunstify, kdialog, zenity).
Auto-tagging: marks files as clean/malicious in supported file managers (e.g., KDE Dolphin).
Instant quarantine: one-click isolation into a dedicated tmpfs quarantine, with optional noexec protection and locked-down permissions.
Complete audit trail: JSON logs tracking scans, detections, and actions for traceability.

Quick start

./install.sh
vt init
vt-check --notify suspicious.exe

Or simply right-click any file and select Scan with VirusTotal.

What you need

vt — VirusTotal CLI (auto-installed)
jq — JSON processor
sha256sum — typically pre-installed

That’s it.

Tested & supported

Tested on CachyOS + KDE Plasma + Dolphin. Should work across most Linux distributions.

File managers: Dolphin, Nautilus, Nemo, Thunar, Caja
Notifications: notify-send, dunstify, kdialog, zenity

Security & privacy

Important: files uploaded to VirusTotal may be shared with security researchers and antivirus vendors. Never upload sensitive, confidential, or proprietary files.

This tool is not a real-time antivirus replacement — it’s an on-demand verification helper.

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

Full documentation and issues are on GitHub.