Malware Hash Scanner Pro

A professional malware analysis tool that computes cryptographic hashes, queries VirusTotal for threat intelligence, verifies file types, tracks historical scans, and generates structured JSON and PDF reports.

---

Features

Core Capabilities

• Multi-hash computation (MD5, SHA1, SHA256)
• VirusTotal API integration
• Threat level classification
• Batch directory scanning
• JSON report export

Advanced Features

• File type verification using file signature analysis
• Historical scan tracking
• PDF report generation
• Structured audit-style reporting

---

Project Structure

malware-hash-scanner/
│
├── main.py
├── file_hasher.py
├── threat_checker.py
├── file_type_checker.py
├── history_tracker.py
├── report_generator.py
│
├── README.md
├── requirements.txt
├── .gitignore
├── LICENSE
│
├── reports/
│   └── (generated reports)
│
├── history/
│   └── scan_history.json
│
└── sample/
    └── suspicious_files/
        └── test.txt

---

Installation

1. Clone the Repository

git clone https://github.com/cchokaaa/malware-hash-scanner.git
cd malware-hash-scanner

2. Create a Virtual Environment

python -m venv venv

3. Activate the Virtual Environment

Windows PowerShell

venv\Scripts\Activate.ps1

Git Bash

source venv/Scripts/activate

4. Install Dependencies

pip install -r requirements.txt

---

VirusTotal API Setup

This project uses the VirusTotal API to retrieve malware detection statistics based on file SHA256 hashes.

Create a free account at:

https://www.virustotal.com/

Generate an API key and configure it as an environment variable.

PowerShell

$env:VT_API_KEY="your_api_key_here"

Git Bash

export VT_API_KEY="your_api_key_here"

---

Usage

Scan a Single File

python main.py sample/suspicious_files/test.txt

Export JSON Report

python main.py sample/suspicious_files/test.txt --json reports/report.json

Export PDF Report

python main.py sample/suspicious_files/test.txt --pdf reports/report.pdf

Export Both JSON and PDF Reports

python main.py sample/suspicious_files/test.txt --json reports/report.json --pdf reports/report.pdf

Batch Scan a Directory

python main.py sample/suspicious_files

---

Sample Output

============================================================
file_name: test.txt
file_path: D:\malware-hash-scanner\sample\suspicious_files\test.txt
file_size: 43
md5: a123f7b957092282734d4a91fd193c05
sha1: 77b56de4e98c1a0889224fba1a506a2a870b72f7
sha256: adfa5212baafb6f3b92ad0ed5e093601bcad32d1f29694f66214447b2c8a23eb
detected_type: unknown
extension_matches: True
suspicious: False
malicious_count: 0
threat_level: Low
============================================================

---

Threat Level Classification

Malicious Detections	Threat Level
0	Low
1–3	Medium
4–10	High
>10	Critical

---

How It Works

1. Cryptographic Hash Calculation
   Computes MD5, SHA1, and SHA256 hashes for each file.

2. File Type Verification
   Uses magic-byte analysis to detect extension spoofing.

3. VirusTotal Lookup
   Sends the SHA256 hash to VirusTotal and retrieves malware detection statistics.

4. Threat Scoring
   Maps malicious detections to Low, Medium, High, or Critical.

5. Historical Tracking
   Stores each scan result in history/scan_history.json.

6. Report Generation
   Exports scan results to JSON and PDF formats.

---

Example JSON Report Structure

{
    "file_name": "test.txt",
    "file_path": "D:/malware-hash-scanner/sample/suspicious_files/test.txt",
    "file_size": 43,
    "md5": "...",
    "sha1": "...",
    "sha256": "...",
    "detected_type": "unknown",
    "extension_matches": true,
    "suspicious": false,
    "malicious_count": 0,
    "threat_level": "Low"
}

---

Security Concepts Demonstrated

• Cryptographic hashing
• Threat intelligence integration
• File signature analysis
• Malware triage
• Risk scoring
• Historical audit tracking
• Automated reporting

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

Author

cchokaaa

---

Disclaimer

This project is intended for educational, research, and defensive security purposes only.

Users are responsible for complying with all applicable laws, regulations, and third-party service terms.