Malware Hash Database & Lookup Tool

A comprehensive Python tool for calculating file hashes (MD5, SHA1, SHA256, SHA512) and checking them against online databases (VirusTotal API) and local hash databases for malware detection.

Features

• Hash Calculation: MD5, SHA1, SHA256, SHA512 with progress bars for large files
• VirusTotal Integration: Query VirusTotal API v3 for malware detection
• Local Hash Databases:
  • SQLite database with metadata (malware name, family, source, tags)
  • Simple text file database for quick lookups
• Multiple Interfaces: CLI tool, Python API, batch scanning
• Flexible Output: Table, JSON, and simple text formats
• Configuration: INI-based config with API key management
• Sample Database: Pre-populated with known malware hashes (EICAR, WannaCry, NotPetya, etc.)

Installation

# Clone the repository
git clone https://github.com/ng-sudo/malware-hash-lookup.git

# Change to the directory
cd malware_hash_lookup

# Install dependencies
pip install -r requirements.txt

Requirements

• Python 3.7+
• requests
• click
• colorama
• tqdm
• python-dotenv

Quick Start

1. Configure VirusTotal API (Optional)

# Get your API key from https://www.virustotal.com/gui/my-apikey
malware_hash_lookup.py config --key YOUR_API_KEY

2. Create Sample Database (for testing)

malware_hash_lookup.py create-db --sample

3. Scan a File

malware_hash_lookup.py scan suspicious_file.exe

4. Look up a Hash

malware_hash_lookup.py lookup d41d8cd98f00b204e9800998ecf8427e

5. Batch Scan Directory

malware_hash_lookup.py batch ./samples --recursive -e exe -e dll

Usage Examples

Scan a Single File

malware_hash_lookup.py scan malware_sample.exe

Output:

======================================================================
FILE: malware_sample.exe
======================================================================

FILE HASHES:
  MD5    : d41d8cd98f00b204e9800998ecf8427e
  SHA1   : da39a3ee5e6b4b0d3255bfef95601890afd80709
  SHA256 : e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

LOCAL DATABASE MATCHES:
  [MATCH] SHA256: EICAR-Test-File (Test) [eicar]

VIRUSTOTAL: MALICIOUS DETECTED
  Name: EICAR-Test-File
  Detection: 45/72 engines

  Top detections:
    Kaspersky: EICAR-Test-File (not a virus)
    Microsoft: EICAR-Test-File
    ...

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
THREAT DETECTED: This file matches known malware!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  Source: LOCAL_DB
  Malware: EICAR-Test-File
  Family: Test
  Hash: SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Look up a Hash Directly

malware_hash_lookup.py lookup 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f

Batch Scan with Only Matches

malware_hash_lookup.py batch ./samples --recursive --only-matches -e exe -e dll -e sys

Export/Import Hash Databases

# Export to text file
malware_hash_lookup.py export hashes.txt --type sha256

# Import from text file
malware_hash_lookup.py import hashes.txt --type sha256 --source mysource

Add File Hash to Local Database

malware_hash_lookup.py add-hash suspicious_file.exe

View Statistics

malware_hash_lookup.py stats

Configuration

The tool uses config.ini for configuration:

[config]
virustotal_api_key = YOUR_API_KEY_HERE
local_hash_db_path = ./hash_database/malware_hashes.db
hash_algorithms = md5,sha1,sha256
output_format = table
verbose = false
vt_rate_limit = 4

VirusTotal API Key

1. Create account at VirusTotal
2. Go to My API Key
3. Copy your API key
4. Run: malware_hash_lookup.py config --key YOUR_API_KEY

Rate Limits:

• Free tier: 4 requests/minute
• Premium: Higher limits

Python API Usage

from malware_hash_lookup import MalwareHashLookup, HashCalculator, VirusTotalAPI

# Initialize tool
tool = MalwareHashLookup()

# Scan a file
results = tool.scan_file("suspicious.exe")
print(tool.format_results(results))

# Calculate hashes only
calculator = HashCalculator(['md5', 'sha1', 'sha256'])
hashes = calculator.calculate_hashes("file.exe")
print(hashes)

# Direct VirusTotal lookup
vt = VirusTotalAPI("YOUR_API_KEY")
result = vt.get_file_report("sha256_hash_here")
print(f"Malicious: {result.malicious}/{result.total_engines}")

# Use local database
from malware_hash_lookup import LocalHashDatabase
db = LocalHashDatabase("./hash_database/malware_hashes.db")
matches = db.lookup_hash("sha256_hash")

Database Schema

SQLite Database (malware_hashes.db)

CREATE TABLE malware_hashes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    hash_value TEXT NOT NULL,
    hash_type TEXT NOT NULL,  -- md5, sha1, sha256, sha512
    malware_name TEXT,
    malware_family TEXT,
    source TEXT,              -- eicar, virustotal, manual, imported
    tags TEXT,                -- JSON array
    first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(hash_value, hash_type)
);

Text File Database (malware_hashes.txt)

Simple format - one hash per line:

d41d8cd98f00b204e9800998ecf8427e
da39a3ee5e6b4b0d3255bfef95601890afd80709
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Sample Hashes Included

The sample database includes hashes for:

• EICAR Test File (standard AV test file)
• WannaCry ransomware
• NotPetya/ExPetr wiper
• Emotet banking trojan
• TrickBot banking trojan
• Mirai IoT botnet

Output Formats

Table (Default)

Color-coded table with file info, hashes, and detection results.

JSON

Machine-readable format for scripting:

{
  "file": "suspicious.exe",
  "hashes": {
    "md5": "...",
    "sha1": "...",
    "sha256": "..."
  },
  "matches": [...],
  "virustotal": {...}
}

Simple

Minimal text output for quick scanning.

Exit Codes

• 0: Clean (no matches found)
• 1: Malware detected (matches found)
• 2: Error occurred

Building Standalone Executable

pip install pyinstaller
pyinstaller --onefile malware_hash_lookup.py

The executable will be in dist/malware_hash_lookup.exe

Project Structure

malware_hash_lookup/
├── malware_hash_lookup.py    # Main CLI entry point
├── hash_calculator.py        # Hash calculation module
├── virustotal_api.py         # VirusTotal API integration
├── local_hash_db.py          # Local database modules
├── config.ini                # Configuration file
├── requirements.txt          # Python dependencies
├── hash_database/            # Local hash databases
│   ├── malware_hashes.db     # SQLite database
│   └── malware_hashes.txt    # Text file database
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details.

Disclaimer

This tool is for educational and authorized security testing purposes only. Always ensure you have proper authorization before scanning files or systems. The sample malware hashes are from publicly known samples and test files.

Resources

• VirusTotal API Documentation
• EICAR Test File
• Malware Hash Databases
• MITRE ATT&CK