// project

VT Bulk Enricher

Automated bulk IOC enrichment tool that queries hundreds of file hashes, IPs, and domains against the VirusTotal API and returns a triage-ready CSV report in minutes.

Python Threat Hunting IOC Enrichment VirusTotal API SOC
View on GitHub
The Problem It Solves

During a triage session you might have 200 suspicious IPs from firewall logs, 50 file hashes from an endpoint alert, and a list of domains from a phishing email. Checking each one manually on the VirusTotal website is not viable at scale. This tool takes your full list, queries the VirusTotal v3 API for each indicator, and hands you back a clean, sortable CSV with verdicts and detection counts ready for triage.

It handles rate limiting automatically, prints live progress to the terminal, and flags anything malicious immediately so you know where to focus without waiting for the full run to complete.

Capabilities
Example Terminal Output
[*] Loaded 5 IOCs of type 'ip'
[*] Estimated time: ~1 min 15 sec

[1/5] Looking up: 185.220.101.45 ... MALICIOUS (72/94)
[2/5] Looking up: 8.8.8.8 ... CLEAN (0/94)
[3/5] Looking up: 1.1.1.1 ... CLEAN (0/94)
[4/5] Looking up: 45.33.32.156 ... SUSPICIOUS (3/94)
[5/5] Looking up: 192.168.1.1 ... not_found

========================================
TRIAGE SUMMARY
========================================
MALICIOUS : 1
SUSPICIOUS : 1
CLEAN : 2
ERRORS : 1
TOTAL : 5
========================================

[!] MALICIOUS IOCs:
185.220.101.45 (72/94 engines)
Usage
# Check a list of file hashes
python3 vt_enricher.py --input hashes.txt --type hash --apikey $VT_API_KEY

# Check a list of IPs
python3 vt_enricher.py --input ips.txt --type ip --apikey $VT_API_KEY

# Check domains with custom output file
python3 vt_enricher.py --input domains.txt --type domain --apikey $VT_API_KEY --output report.csv
INPUT FILE FORMAT
# suspicious IPs from firewall logs - 2026-03-01
185.220.101.45
45.33.32.156
198.51.100.0
Verdict Thresholds
CLEAN
0 detections across all engines.
SUSPICIOUS
1-5 detections for hashes. 1-3 for IPs and domains. Warrants review.
MALICIOUS
6+ detections for hashes. 4+ for IPs and domains. Thresholds are configurable.
Why I Built It

Manual IOC lookups do not scale. In a real SOC environment, an alert can produce dozens of indicators that all need to be checked before you can make a triage decision. This tool compresses what would be an hour of clicking into a few minutes of automated querying.

Building it required understanding the VirusTotal v3 API properly: how different endpoint structures work for hashes versus IPs versus domains, how to interpret detection ratios, and how to handle pagination and rate limiting gracefully without dropping results. Those are the kinds of practical details that matter in a production tool.

It pairs intentionally with the IOC Database project: the enricher produces the output, and the database stores the confirmed indicators for ongoing tracking and investigation correlation.