THA-CERT VT Tool

Welcome to VT_Tool by THA-CERT!

VirusTotal analysis tool with local caching and optional MISP integration.

vt_tool retrieves analysis information for IP addresses, hashes, URLs, and domains using the VirusTotal v3 API. It supports interactive and non-interactive modes, local result caching via SQLite, structured CSV/TXT export, and MISP integration.

Features

• Query VirusTotal for:

  • IPv4 addresses
  • File hashes (MD5, SHA-1, SHA-256)
  • URLs
  • Domains

• Automatic quota checking (hourly VT API quota)

• Local SQLite caching (avoids re-querying existing values)

• CSV and TXT report generation

• Template-based input processing

• Optional MISP event creation/update

• Proxy support

• Interactive CLI (Rich UI)

• Fully non-interactive automation mode

Architecture Overview

CLI (argparse)
   │
   ├── Input Handling (file / template / CLI args)
   ├── Validator (IP / hash / URL / domain)
   ├── Local SQLite cache
   ├── VirusTotal API v3 client
   ├── Report processing
   │     ├── CSV export
   │     └── TXT formatted report
   └── Optional MISP integration

Requirements

• Python 3.8+
• VirusTotal API key
• Internet access
• Optional: MISP instance (for integration)

Dependencies are listed in requirements.txt.

Installation

git clone https://github.com/thalesgroup-cert/vt_tool.git
cd vt_tool
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

1️⃣ VirusTotal API Key

You can provide the API key in one of three ways:

Option A — Environment variable (recommended)

export VTAPIKEY="your_api_key"

Option B — CLI argument

--api_key YOUR_KEY

Option C — API key file

--api_key_file path/to/keyfile.txt

You cannot use both --api_key and --api_key_file at the same time.

2️⃣ Proxy (optional)

--proxy http://127.0.0.1:8080

Usage

python vt_tools.py [OPTIONS] VALUES...

If no values or input file are provided, execution stops with error.

CLI Arguments (Complete Reference)

Option	Short	Description
--template_file	-tf	Template file to use for structured IOC input.
--input_file	-f	File containing IOCs to analyze.
--output_dir	-o	Directory where output reports are saved.
--type	-t	Type of values to analyze: ips, hashes, urls, domains, all (default: all).
--non_interactive	-n	Disable interactive prompts. Required for automation.
--case_id	-c	Case ID or MISP event UUID (zero-padded to 6 digits).
--api_key	-a	VirusTotal API key.
--api_key_file	-af	Path to file containing API key.
--proxy	-p	Proxy URL for outbound requests.
values	—	One or more IPs, hashes, URLs, or domains.

Supported Types

Type	CLI Value
IP addresses	ips
File hashes	hashes
URLs	urls
Domains	domains
All types	all

Input Methods

1️⃣ Direct CLI values

python vt_tools.py -t ips 8.8.8.8 1.1.1.1

2️⃣ Input file

python vt_tools.py -f iocs.txt

File format:

8.8.8.8
example.com
44d88612fea8a8f36de82e1278abb02f

3️⃣ Template mode

python vt_tools.py -tf template.csv

Template options available:

Option	Template Structure
1	value,comment
2	value,comment,source
3	value,category,type,comment,to_ids,tag1,tag2

Interactive selection will prompt template choice.

Interactive vs Non-Interactive Mode

Interactive (default)

• Prompts for analysis type
• Prompts for MISP integration
• Displays Rich UI panels

Non-Interactive

python vt_tools.py -n -t ips -f iocs.txt

• No prompts
• No MISP interactive selection
• Logging output instead of Rich prompts

Quota Handling

Before analysis begins:

• The tool queries VirusTotal hourly quota.
• If quota is exhausted, execution stops.
• If requested IOCs exceed remaining quota, a warning is shown.
• Already cached IOCs do not consume quota.

Local Database

• SQLite database: vttools.sqlite

• Automatically created if not present

• Prevents re-querying existing values

• Skips:

  • Private IPs
  • Loopback IPs
  • Reserved IP ranges
  • Unsupported hash types (SHA-224, SHA-384, SHA-512, SSDEEP)

Output

For each analysis type:

1️⃣ CSV Report

Generated automatically. Contains structured VT results.

2️⃣ TXT Report

Formatted table version of results.

Files are saved in:

• Current directory (default)
• Or --output_dir if provided

MISP Integration

If:

• Running in interactive mode
• Or using template mode

The tool can:

• Create new MISP event
• Update existing MISP event (via --case_id)

Non-interactive mode skips MISP integration.

Example Commands

Analyze single IP

python vt_tools.py -t ips 8.8.8.8

Analyze hashes from file

python vt_tools.py -t hashes -f hashes.txt

Full automation mode

python vt_tools.py -n -t all -f iocs.txt --api_key YOUR_KEY

Using template mode

python vt_tools.py -tf template.csv -c 123456

Error Handling

The tool handles:

• Invalid IOCs
• Unsupported value types
• Quota exhaustion
• API failures
• Network errors
• Duplicate DB entries

Errors are counted and reported at the end of execution.

Exit Behavior

Execution ends with:

• Total time taken
• Remaining quota
• Number of skipped values
• Number of errors

Logging

• INFO level logging enabled by default
• Errors logged to console
• In non-interactive mode, logs replace UI prompts

Security Considerations

• API keys are never logged
• Proxy support for controlled outbound traffic
• Local DB prevents unnecessary API calls
• Invalid or sensitive IP ranges are filtered

Development

Run directly

python vt_tools.py --help

Code structure highlights

• Initializator → handles DB, validator, reporter
• ValueReader → parses input/template files
• db_handler → manages SQLite
• reporter → calls VT API
• validator → validates IOC format

License

See LICENSE file.