cchokaaa/malware-hash-scanner

# 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.