🔍 File Type Identifier

A powerful, dependency-free CLI tool for identifying file types using magic number (file signature) analysis. Built for forensics, malware triage, and CTF challenges on Linux.

---

✨ Features

Feature	Description
🪄 Magic Number Detection	Identifies 50+ file types from raw bytes, not file extensions
⚠️ Extension Mismatch	Flags files masquerading under a fake extension
📊 Entropy Analysis	Shannon entropy to detect packed/encrypted/obfuscated files
#️⃣ Hash Generation	Computes MD5, SHA1, and SHA256 per file
🦠 VirusTotal Lookup	Queries VT API v3 by SHA256 to check malware detections
🐙 Polyglot Detection	Identifies files valid in multiple formats simultaneously
📁 Recursive Scan	Scan entire directory trees with -r
📄 JSON / CSV Export	Export findings into your SIEM or SOAR pipeline

---

🚀 Quick Start

git clone https://github.com/Athar2410/magic-id.git
cd magic-id

# Add your VirusTotal API key
cp .env.example .env
nano .env   # paste your VT_API_KEY

# Run — no pip installs needed
python3 magic_id.py file.exe

---

⚙️ Usage

# Basic scan
python3 magic_id.py suspicious.exe

# Scan multiple files
python3 magic_id.py file1 file2 file3

# Recursive directory scan
python3 magic_id.py -r /evidence/

# Recursive scan with VirusTotal lookup
python3 magic_id.py -r /samples/ --vt-key YOUR_KEY

# Verbose mode — full 64-byte hex dump
python3 magic_id.py -v malware.bin

# Export results to JSON and CSV
python3 magic_id.py -r /samples/ --json report.json --csv report.csv

# Suppress banner (for piping/scripting)
python3 magic_id.py --no-banner * 2>/dev/null

All Flags

Flag	Description
targets	One or more files / directories to scan
-r	Recursively scan directories
-v	Show full 64-byte hex dump of file header
--vt-key KEY	VirusTotal API key (overrides .env)
--json FILE	Save results as JSON
--csv FILE	Save results as CSV
--no-banner	Suppress the banner (useful for scripting)

---

🔑 Environment Variables

Copy .env.example to .env and fill in your key:

cp .env.example .env

# .env
VT_API_KEY=your_virustotal_api_key_here

🔗 Get a free VirusTotal API key at virustotal.com
Free tier allows 4 lookups/min and 500 lookups/day

---

📊 Entropy Thresholds

The tool uses Shannon entropy to flag suspicious files:

Entropy Range	Label	Meaning
< 1.0	Very Low	Likely empty or null file
1.0 – 3.5	Low	Plaintext or structured data
3.5 – 6.0	Normal	Typical binary or text file
6.0 – 7.0	Elevated	Likely compressed data
7.0 – 7.5	High ⚠️	Possibly compressed/encrypted
> 7.5	Very High 🚨	Possible packed/encrypted malware

---

🗂️ Supported File Types

Click to expand — 50+ signatures

Category	Formats
Images	JPEG, PNG, GIF, BMP, PSD, TIFF, ICO, WebP, PostScript
Documents	PDF, MS Office (legacy + OOXML), RTF, CHM
Executables	ELF, PE (exe/dll), Java Class, Mach-O (32/64-bit), Scripts
Archives	ZIP, GZIP, BZIP2, XZ, RAR (v1.5+/v5+), 7-Zip, TAR, CAB, CRX
Audio	MP3 (ID3/raw), FLAC, OGG, MIDI
Video	MKV/WebM, FLV, SWF, ASF/WMV/WMA
Databases	SQLite
Disk Images	VMware VMDK, VHD
Crypto/Certs	PGP (public/private), PEM certificates & keys
Fonts	OTF, TTF, WOFF, WOFF2

---

🎯 Use Cases

• CTF Forensics — Identify hidden or renamed files in challenges
• Malware Triage — Quick first-pass analysis of suspicious samples
• Incident Response — Scan captured filesystems for masquerading files
• Penetration Testing — Detect file upload filter bypass artifacts
• SIEM/SOAR Enrichment — Feed JSON/CSV output into your pipeline

---

📁 Project Structure

magic-id/
├── magic_id.py        ← Main tool (single file, no dependencies)
├── .env               ← Your API keys (git ignored)
├── .env.example       ← Safe template (committed)
├── .gitignore         ← Blocks .env from git
└── README.md

---

📦 Dependencies

None. Pure Python 3 standard library only.

python 3.x   ← only requirement

No pip install needed. Ever.

---

🧪 Test It Quickly

# Create a spoofed file (PDF renamed as .jpg)
echo '%PDF-1.4 test' > fake.jpg

# Scan it — will trigger extension mismatch warning
python3 magic_id.py fake.jpg

# Scan a real system binary
python3 magic_id.py /bin/bash /bin/ls

---

📜 License

This project is licensed under the MIT License — free to use, modify, and distribute.

---

👤 Author

Made by Atharva Amle
🔗 github.com/Athar2410

Built on Kali Linux for the security community.