A cross-platform Python command-line tool for the VirusTotal API that intelligently manages file scanning with automatic upload capabilities.
✨ Smart File Analysis
- Checks if file exists on VirusTotal before uploading
- Automatically uploads files not found in VirusTotal database
- Respects API rate limits and upload quotas
🔐 Secure Configuration
- Stores API keys securely in platform-specific config directories
- Cross-platform support (Windows, macOS, Linux)
- File permissions set to 600 for security
📊 Quota Management
- Tracks daily API request and upload limits
- Displays remaining quota
- Prevents exceeding rate limits
- Automatic daily quota reset
⚡ Fast & Efficient
- SHA256 hash calculation for quick lookups
- Progress indicators for long operations
- Formatted output with color coding
- Support for files up to 650 MB
🍎 macOS-Friendly
- Automatic detection and extraction of .app bundles
- Scans the main executable within macOS applications
- Seamless support for
/Applications/scanning
- Python 3.8 or higher
- VirusTotal API key (free from virustotal.com)
Clone the repository and install from source:
git clone https://github.com/noobaly-original/vt-cli-wrapper.git
cd vt-cli-wrapper🪟 Windows 10/11: See INSTALL_WINDOWS.md for detailed instructions. Quick start:
# PowerShell (Recommended)
powershell -ExecutionPolicy Bypass -File install.ps1
# Or Command Prompt
install.cmd🍎 macOS / 🐧 Linux:
# Using uv (recommended)
bash install.sh
# Or manual installation
python3 -m venv venv
source venv/bin/activate
pip install -e .- See INSTALL.md for macOS/Linux detailed instructions
- See INSTALL_WINDOWS.md for Windows detailed instructions
Once published to PyPI, installation will be as simple as:
pip install vt-cli-wrapperCheck back for updates!
vt-cli setupYou'll be prompted to enter your VirusTotal API key. It will be validated and stored securely.
vt-cli scan /path/to/your/fileThe tool will:
- Calculate the file's SHA256 hash
- Check if it exists on VirusTotal
- Display results if found, or upload for analysis
- Show detection statistics and verdict
vt-cli quotaDisplays your remaining API requests and upload quota for the day.
Configure your VirusTotal API key.
vt-cli setupAnalyze a file using VirusTotal.
vt-cli scan <file_path> [OPTIONS]Supported file types:
- Regular files:
.exe,.dll,.pdf,.zip, etc. - macOS applications:
.appbundles (automatically extracts and scans the main executable)
Options:
--force-upload: Force upload even if file exists on VirusTotal
Examples:
# Regular file
vt-cli scan suspicious.exe
vt-cli scan document.pdf --force-upload
# macOS .app bundle
vt-cli scan /Applications/MyApp.app
vt-cli scan ~/Downloads/SomeApp.appmacOS .app Support:
When scanning a .app bundle, the tool automatically:
- Detects the .app package
- Extracts the main executable from
Contents/MacOS/ - Scans the executable binary
- Displays the app name alongside the executable
Display API usage and remaining quota.
vt-cli quotaReset all configuration and API key.
vt-cli resetDisplay version information.
vt-cli --versionConfiguration is stored in platform-specific directories:
- Windows:
%APPDATA%\vt-cli-wrapper\vt_config.json - macOS:
~/.config/vt-cli-wrapper/vt_config.json - Linux:
~/.config/vt-cli-wrapper/vt_config.json
The configuration file includes:
- API key
- Daily request count
- Daily upload count
- Last reset date
- API limits
The tool respects VirusTotal's API rate limits:
Free Tier:
- 4 requests per minute (approximately 5,760 per day)
- 4 file uploads per minute
Premium Tier:
- Higher limits available (configure in config file)
The tool tracks daily usage and prevents exceeding limits.
- Maximum file size: 650 MB
- Larger files will be rejected with an error message
The tool provides clear error messages for:
- Invalid or missing API keys
- File not found errors
- Network connectivity issues
- Quota exceeded scenarios
- Upload failures
Example error handling:
✗ Daily request quota exceeded. Requests remaining: 0
Tested and verified on:
- ✅ Windows 10/11 - PowerShell or Command Prompt
- See INSTALL_WINDOWS.md for detailed setup
- ✅ macOS 10.15+ - zsh, bash
- Use
bash install.shfor automated setup
- Use
- ✅ Ubuntu 20.04+ - bash
- ✅ CentOS 7+ - bash
- ✅ Debian - bash
All systems require Python 3.8+ and are fully cross-platform compatible.
- API Key Storage: Keys are stored with restricted file permissions (0600)
- HTTPS Only: All API communication uses HTTPS
- No Logging: Sensitive information is never logged
- User-Agent: Identifies as vt-cli-wrapper for API transparency
Run vt-cli setup to configure your API key.
Ensure the file path exists and is readable.
Your daily limit has been reached. Check back after the quota resets (typically at midnight UTC).
Check your internet connection and firewall settings.
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"pytest tests/Uses PEP 8 with Black formatting:
black src/For more information about VirusTotal API:
MIT License - See LICENSE file for details
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This tool is provided as-is for security research and file scanning purposes. The authors are not responsible for misuse or any damages caused by this tool. Always respect VirusTotal's Terms of Service.
- ✨ Initial release
- 🔍 File lookup by SHA256
- 📤 Automatic file upload
- 📊 Quota tracking
- 🔐 Secure API key storage
- 🌐 Cross-platform support