vt-cli: Essential Commands and Workflow Tipsvt-cli is the official command-line client for VirusTotal’s API, designed to help security researchers, incident responders, and developers interact with VirusTotal services directly from the terminal. This article covers installation, configuration, the most useful commands, practical workflows, scripting tips, and best practices to help you integrate vt-cli into your malware analysis and threat-hunting toolset.
What vt-cli is and when to use it
vt-cli provides a fast, scriptable way to query VirusTotal for file and URL reports, upload samples, retrieve scanning results and behavior reports, and search VirusTotal’s datasets. Use vt-cli when you need automation, reproducibility, or to integrate VirusTotal lookups into shell scripts, CI pipelines, or incident response playbooks.
Installation and setup
Requirements
- Python 3.8+ (vt-cli is a Python package).
- A valid VirusTotal API key (public or private, depending on desired functionality).
Installing vt-cli
Install with pip:
pip install vt-cli If you prefer a user-local install:
pip install --user vt-cli Configuration
Initialize vt-cli with your API key:
vt init This will prompt you for your API key and create a config file (typically at ~/.vt/ or in your user config directory). Alternatively, set the key via environment variable:
export VT_API_KEY="your_api_key_here" Core concepts
- Entity: an object in VirusTotal (file, URL, domain, IP, comment, etc.).
- Analysis: a dynamic or static analysis report associated with an entity.
- Object ID (e.g., file SHA256, URL id): used to reference entities when calling the API.
- Comments, tags, and votes: collaborative features to add context to VirusTotal entities.
Essential commands
Below are the most frequently used vt-cli commands grouped by common task.
File-related commands
- Upload a file for scanning:
vt file scan <path-to-file> - Get a file report (by SHA256 or filename if already uploaded):
vt file info <file-id-or-path> - Download a file from VirusTotal (if available):
vt file download <file-id> --output downloaded.bin - Delete a file from your private uploads (if supported by your plan):
vt file delete <file-id>
URL-related commands
- Scan a URL:
vt url scan <url> - Get URL analysis/report:
vt url info <url-or-id>
IP and domain commands
- Get domain/report:
vt domain info <example.com> - Get IP report:
vt ip info <1.2.3.4>
Search
- Search VirusTotal datasets with a query:
vt search query "behavior_static:dropper AND last_modification_date:>2024-01-01" - Paginate results using –limit and –cursor options.
Analyses and relations
- List analyses for an object:
vt analysis list <object-id> - Get a specific analysis:
vt analysis info <analysis-id> - Retrieve related objects:
vt relationships <object-id>
Metadata and enrichment
- Add a tag:
vt tag add <object-id> my-tag - Add a comment:
vt comment add <object-id> "Observed in phishing campaign X" - Vote (malicious/benign):
vt vote malware <object-id>
Practical workflows
1) Quick triage of a suspicious file
- Compute SHA256 locally:
sha256sum suspicious.exe - Check VirusTotal for existing report:
vt file info <sha256> - If no report exists or you need fresh analysis, upload:
vt file scan suspicious.exe - Retrieve the analysis once complete:
vt analysis info <analysis-id> vt file info <sha256> - Add contextual tags/comments for team awareness:
vt tag add <sha256> "phishing-2025" vt comment add <sha256> "Seen in SMTP logs from 203.0.113.5"
2) Bulk scanning and enrichment from a CSV
Assume a CSV with file paths or URLs. Use a bash loop or Python script:
Bash example:
while IFS=, read -r id path; do vt file scan "$path" || vt url scan "$path" done < samples.csv Python example (using subprocess or vt-python SDK) is recommended for better error handling and rate-limiting.
3) Integrate vt-cli into an incident response playbook
- Automatically hash newly acquired artifacts, query vt-cli for reputation, and based on results, trigger containment scripts (block IPs/domains, quarantine files).
- Example (pseudo):
sha=$(sha256sum "$file" | cut -d' ' -f1) report=$(vt file info "$sha" --json) malicious=$(echo "$report" | jq '.data.attributes.last_analysis_stats.malicious') if [ "$malicious" -gt 0 ]; then quarantine "$file" notify-team "$file $sha" fi
Scripting tips and best practices
- Rate limits: honor VirusTotal API rate limits; implement exponential backoff and respect HTTP 429 responses.
- Use –json output when scripting to parse with jq or Python’s json module:
vt file info <sha256> --json - Store API keys securely (environment variables, vaults). Avoid embedding keys in checked-in scripts.
- Use vt-cli’s pagination flags (–limit, –cursor) for large searches to avoid overwhelming the API.
- Cache results locally (short TTL) to reduce repeated queries for the same artifact.
- For bulk jobs, consider the commercial API or an elevated plan for higher throughput.
Advanced usage
- Use vt-python (the SDK) alongside vt-cli for complex automation and richer control.
- Combine vt-cli with syslog/SiEM: push vt-cli outputs into SIEM for correlation.
- Use vt-cli in CI pipelines to block deploying artifacts flagged by VirusTotal scans.
Troubleshooting
- Authentication errors: verify VT_API_KEY, run vt init again.
- ⁄401: API key lacks required permissions; check account plan.
- 429 Too Many Requests: slow down requests, implement retry/backoff.
- Unexpected JSON: use –raw or –json flags and validate with jq.
Security and privacy considerations
- Don’t upload sensitive, proprietary, or personally identifiable files without authorization; uploads may expose content to VirusTotal and its partners per their policies.
- Use private or sandboxed environments for handling live malware samples.
- Keep API keys confidential.
Conclusion
vt-cli is a compact, powerful tool to bring VirusTotal’s capabilities into your terminal, scripts, and automation workflows. Focus on mastering core commands (file/url info, scan, search), automate safely with rate‑limit handling and JSON parsing, and integrate vt-cli into incident response and threat-hunting processes to speed triage and improve context.
Leave a Reply