lookup-virustotal
Skill35 starsChanged 48 days agoMITView on GitHub
Use when you need to check an IP, domain, file hash, or URL against VirusTotal's reputation database. Returns detection ratio, verdict, community score, and key findings. Commonly invoked by investigation skills (/ip-investigation, /domain-investigation, /hash-investigation, /url-investigation) and by analysts enriching IOCs. Other agents/skills can chain this for VirusTotal enrichment.
- Reads credentials
In this repository79 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- abuseipdb-apiSkill
- achSkill
- campaign-trackingSkill
- carding-financial-fraudSkill
- censys-apiSkill
- china-cyber-espionageSkill
- claim-extractionSkill
- confidence-levelsSkill
- control-coverage-mappingSkill
- crowdstrike-apiSkill
- cti-hyperloopSkill
- cti-orchestratorSkill
- cti-setupSkill
- darkweb-collectionSkill
- devils-advocacySkill
- domain-investigationSkill
- dprk-cyber-espionageSkill
- feedback-loopsSkill
- greynoise-apiSkill
- hacktivismSkill
- hash-investigationSkill
- horizon-scanningSkill
- indicator-pivotingSkill
- infostealersSkill
- initial-access-brokersSkill
- intelligence-sharingSkill
- intelligence-writingSkill
- ioc-enrichment-workflowSkill
- ioc-exportSkill
- ip-investigationSkill
- iran-cyber-espionageSkill
- key-assumptions-checkSkill
- kql-writingSkill
- likelihood-languageSkill
- lookup-abuseipdbSkill
- lookup-censysSkill
- lookup-crowdstrikeSkill
- lookup-greynoiseSkill
- lookup-liberty91Skill
- lookup-mispSkill
- lookup-openctiSkill
- lookup-otxSkill
- lookup-ransomwareliveSkill
- lookup-reversinglabsSkill
- lookup-sentinelSkill
- lookup-shodanSkill
- lookup-urlscanSkill
- malware-analysisSkill
- maturity-assessmentSkill
- mitre-attackSkill
- osint-methodologySkill
- otx-apiSkill
- phishing-social-engineeringSkill
- pir-managementSkill
- quality-controlSkill
- quality-of-information-checkSkill
- ransomware-ecosystemSkill
- reversinglabs-apiSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 99
Default rating for downstream /score-source: B2 (usually reliable, probably true).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
lookup-virustotal
Queries VirusTotal API v3 for reputation data on IPs, domains, file hashes, and URLs. Retrieval only — do not interpret, assess, or conclude. The invoking skill or agent reasons about the result.
When to invoke
- User asks to check an IP, domain, hash, or URL against VirusTotal
- Investigation skill needs reputation context for a collected indicator
- IOC enrichment pipeline is deduplicating + scoring a batch
How to invoke
Two CLIs are provided. Pick by capability needed:
Basic lookup — Node CLI (zero deps)
node tools/clis/virustotal.js <type> <value>
# where <type> is one of: ip, domain, hash, urlHits the basic object endpoint only and distils to a verdict. Best for fast retrieval inside an investigation chain.
Full surface — Python CLI (stdlib only)
python3 tools/clis/virustotal.py file <hash> [--relationships R1,R2] [--limit N]
python3 tools/clis/virustotal.py ip <ip> [--relationships R1,R2] [--limit N]
python3 tools/clis/virustotal.py domain <domain> [--relationships R1,R2] [--limit N]
python3 tools/clis/virustotal.py url <url> [--relationships R1,R2] [--limit N]
python3 tools/clis/virustotal.py submit-url <url>
python3 tools/clis/virustotal.py comments <type> <id>
python3 tools/clis/virustotal.py search <query> # Intel — premiumStdlib only — no install, no venv.
Capabilities the Node CLI doesn't have:
- Relationship traversal — the killer feature for pivoting. For an IP, fetch
communicating_files,downloaded_files,resolutions,urls,related_threat_actors,historical_whois. For a file:contacted_ips,contacted_domains,dropped_files,similar_files,behaviours. For a domain:subdomains,siblings,resolutions. For a URL:contacted_ips,contacted_domains,last_serving_ip_address. Each--relationshipsentry is a separate API request — be deliberate about which to pull. - URL submission (
submit-url) — push a URL into the analysis queue; returns an analysis ID. - Comments — community comments on any object.
- Intel search — VT Intelligence query language (
type:peexe size:1mb+ p:5+). Premium endpoint; will 403 on free.
Examples:
# Pivot from a malicious IP to communicating samples and resolutions
python3 tools/clis/virustotal.py ip 185.220.101.45 --relationships communicating_files,resolutions
# Get a hash plus its sandbox behaviours and contacted infrastructure
python3 tools/clis/virustotal.py file 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8 \
--relationships behaviours,contacted_ips,contacted_domains,dropped_files
# Submit a suspicious URL for fresh analysis
python3 tools/clis/virustotal.py submit-url "http://suspicious-site.example/login"Both CLIs accept --dry-run to preview the request(s) without spending quota. Both exit code 2 if $VIRUSTOTAL_API_KEY is unset (when not in dry-run). Report missing key; do not fabricate.
Quota awareness
Free tier is 4 req/min, 500/day. Each --relationships entry is a separate API call on top of the base lookup. A single ip 1.2.3.4 --relationships a,b,c,d burns 5 requests. Use --dry-run first to count calls before live runs.
Response format
The CLI returns JSON. Skills consuming it should treat it as:
source: virustotal
indicator: <queried value>
type: ip | domain | hash | url
query_time: <ISO8601>
detection_ratio: <malicious>/<total>
community_score: <number>
verdict: malicious | suspicious | clean | unknown
key_findings:
- <finding 1>
- <finding 2>
additional_context:
<relevant fields from API response>Rate limits
Free tier: 4 req/min, 500/day, 15.5k/month. Premium: 1000 req/min. Back off on 429.
Source reliability (Admiralty default)
Default rating for downstream /score-source: B2 (usually reliable, probably true). Community-driven detection aggregator; high-volume but vendor signals vary in quality. Downgrade to C3 if only 1-2 engines detect.
Related skills
/lookup-otx— community pulse context for the same indicator/lookup-urlscan— live scan of URLs/domains/lookup-abuseipdb— IP abuse reports/score-source— apply Admiralty rating to the result/ip-investigation,/domain-investigation,/hash-investigation,/url-investigation— skills that chain this lookup
See also
- Integration setup:
tools/integrations/virustotal.md - Node CLI source:
tools/clis/virustotal.js - Python CLI source:
tools/clis/virustotal.py - Official API reference: https://gtidocs.virustotal.com/reference/api-responses
- Endpoint docs: https://docs.virustotal.com/reference/overview
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

