VirusTotal

Enrichment Threat Intelligence

Synopsis

Enriches events by querying the VirusTotal API for threat intelligence about files, URLs, domains, and IP addresses.

Schema

virustotal:
  - field: <ident>
  - api_key: <string>
  - query_type: <enum>
  - interval: <numeric>
  - timeout: <numeric>
  - description: <text>
  - if: <script>
  - ignore_failure: <boolean>
  - ignore_missing: <boolean>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - tag: <string>
  - target_field: <ident>

Configuration

Field	Required	Default	Description
field	Y	-	Field containing hash, URL, domain, or IP to query
api_key	Y	${VIRUSTOTAL_API_KEY}	VirusTotal API key for authentication
query_type	N	hash	Type of query: hash, url, domain, or ip
interval	N	1	Polling interval in seconds for URL analysis
timeout	N	10	Maximum number of polling attempts
target_field	N	field	Field to store the API response
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue if API call fails
ignore_missing	N	false	Continue if source field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier

Details

The processor supports queries for file hashes (e.g. MD5, SHA-1, SHA-256), URLs (including scanning and analysis retrieval), domain names, and IP addresses. It also fetches reputation data.

caution

Consider VirusTotal API rate limits.

Responses are returned as structured objects. Analysis stats provide counts from multiple engines.

Automated URL scanning, and rich threat intelligence are also available, so responses may include rich metadata.

note

File scan results may not be immediately available, and URL scanning may have additional delays.

Error handling and success/failure options are supported, as well.

warning

API keys should be securely stored.

Examples

File Hashes

Checking a file hash...

{ "hash": "44d88612fea8a8f36de82e1278abb02f" } virustotal: - field: hash - query_type: hash - api_key: "${VIRUSTOTAL_API_KEY}"

retrieves the relevant results:

{ "hash": { "antiy_info": "Trojan/Generic.ASBOL.2A", "crowdsourced_ai_results": [ { "analysis": "EICAR is a test string used to detect and test antivi...", "category": "code_insight", "id": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c45...", "source": "palm" } ], "crowdsourced_yara_results": [ { "author": "Marc Rivero | McAfee ATR Team", "description": "Rule to detect the EICAR pattern", "match_date": 1739087937, "rule_name": "malw_eicar", "ruleset_id": "0019ab4291", "ruleset_name": "MALW_Eicar", "source": "https://github.com/advanced-threat-research/Yara-Rules" } ], "filecondis": { "dhash": "9300009100008090", "raw_md5": "bcf2bafa8b4e580d7c0f48b4c698f596" }, "first_seen_itw_date": 1582585760, "first_submission_date": 1148301722, "known_distributors": { "data_sources": ["National Software Reference Library (NSRL)"], "distributors": ["Offensive Security"], "filenames": ["eicar.com"], "products": ["BlackArch Linux", "Kali Linux Nethunter"] }, "last_analysis_date": 1739087924, "last_analysis_stats": { "confirmed-timeout": 0, "failure": 0, "harmless": 0, "malicious": 63, "suspicious": 0, "timeout": 0, "type-unsupported": 8, "undetected": 4 }, "last_modification_date": 1739088845, "last_submission_date": 1739087924, "magic": "EICAR virus test files", "magika": "VBA", "md5": "44d88612fea8a8f36de82e1278abb02f", "meaningful_name": "eicar.com-46473", "names": [ "eicar.com-46473", "eicar.txt", "eicar.com-33076", "eicar.com-28456", "eicar.com.txt" ], "popular_threat_classification": { "popular_threat_category": [ {"count": 15, "value": "virus"}, {"count": 2, "value": "trojan"} ], "popular_threat_name": [ {"count": 57, "value": "eicar"}, {"count": 47, "value": "test"}, {"count": 33, "value": "file"} ], "suggested_threat_label": "virus.eicar/test" }, "reputation": 3652, "sandbox_verdicts": { "Lastline": { "category": "malicious", "malware_classification": ["MALWARE", "TROJAN"] }, "OS X Sandbox": { "category": "malicious", "confidence": 52, "malware_classification": ["MALWARE", "TROJAN", "EVADER"], "malware_names": ["EICAR"] }, "Zenbox": { "category": "harmless", "confidence": 100, "malware_classification": ["CLEAN"] } }, "size": 68, "total_votes": { "harmless": 2161, "malicious": 385 }, "type_description": "VBA", "type_tag": "vba", "type_tags": ["source", "vba", "vbs"] } }

URLs

Analyze a URL with custom polling settings...

{ "url": "http://example.com/file.exe" } virustotal: - field: url - query_type: url - interval: 2 - timeout: 15 - target_field: url_analysis - api_key: "${VIRUSTOTAL_API_KEY}"

submits the scan and retrieves the results:

{ "url": { "date": 1739089412, "results": { "0xSI_f33d": { "category": "undetected", "engine_name": "0xSI_f33d", "method": "blacklist", "result": "unrated" }, "ADMINUSLabs": { "category": "harmless", "engine_name": "ADMINUSLabs", "method": "blacklist", "result": "clean" }, "AlienVault": { "category": "harmless", "engine_name": "AlienVault", "method": "blacklist", "result": "clean" }, "Antiy-AVL": { "category": "harmless", "engine_name": "Antiy-AVL", "method": "blacklist", "result": "clean" }, "BitDefender": { "category": "harmless", "engine_name": "BitDefender", "method": "blacklist", "result": "clean" } }, "stats": { "harmless": 73, "malicious": 0, "suspicious": 0, "timeout": 0, "undetected": 23 }, "status": "completed" } }

Domains

Querying domain reputation...

{ "domain": "google.com" } virustotal: - field: domain - query_type: domain - target_field: domain_info - api_key: "${VIRUSTOTAL_API_KEY}"

adds domain intelligence:

{ "domain": "google.com", "domain_info": { "categories": { "BitDefender": "trackers", "Forcepoint ThreatSeeker": "search engines and portals", "Sophos": "information technology" }, "creation_date": 874306800, "last_analysis_stats": { "harmless": 67, "malicious": 0, "suspicious": 0, "timeout": 0, "undetected": 27 }, "registrar": "MarkMonitor Inc.", "reputation": 602, "total_votes": { "harmless": 399, "malicious": 66 }, "popularity_ranks": { "Alexa": {"rank": 1, "timestamp": 1684083480}, "Cisco Umbrella": {"rank": 1, "timestamp": 1739025487} }, "last_https_certificate": { "subject": {"CN": "*.google.com"}, "validity": { "not_before": "2025-01-20 08:36:04", "not_after": "2025-04-14 08:36:03" } } } }

Error Handling

Anticipating API failures...	{ "ip": "8.8.8.8" } virustotal: - field: ip - query_type: ip - api_key: "invalid-key" - ignore_failure: true - on_failure: - set: field: lookup_status value: "failed"
continues execution:	{ "ip": "8.8.8.8", "lookup_status": "failed" }

note

• URL analysis includes both scanning and result retrieval with configurable polling
• API key can be specified directly or via environment variable
• Responses are returned as structured objects
• Analysis stats provide counts from multiple engines
• API responses may include rich metadata

warning

• API keys should be securely stored
• Consider VirusTotal API rate limits
• URL scanning may have additional delays based on polling settings
• File scan results may not be immediately available
• Long polling intervals may impact processing time