🛡️ File Malware Analyzer

Scan any downloaded file for hidden, harmful code — before you open it.

A local-first security tool that inspects documents, pictures, executables, and archives using static analysis (it never runs the file), then gives you a clear, plain-language verdict: Clean · Low · Medium · High risk.

Built for security & defense coursework. Combines a fast Python analysis engine with a clean, modern web dashboard.

---

✨ What it does

You just downloaded a file — a PDF, an image, an installer, a .zip. Is it safe? Drop it in, and the analyzer runs a full battery of checks in seconds:

Category	Checks performed
🔎 Any file	SHA-256 / SHA-1 / MD5 hashes · file-type vs. extension mismatch · Shannon entropy (packing/encryption) · suspicious strings, URLs & IPs
📄 PDFs	Embedded JavaScript · auto-open actions · /Launch actions · embedded files · encryption
📝 Office docs	VBA macros · Auto_Open triggers · Shell() calls · external links (.docx/.xlsx/.pptx & legacy .doc/.xls)
🖼️ Images	EXIF/GPS metadata · PNG/JPEG chunk & segment structure · data hidden after the image's end marker · embedded file signatures (steganography / polyglot tricks)
⚙️ Executables	Windows PE (imports, sections, packing, overlays) · macOS Mach-O (signing, encryption, dylibs) · Linux ELF
📦 Archives	Lists contents · flags dangerous payloads inside · zip-bomb detection · path-traversal entries
📜 Scripts	Obfuscation heuristics · PowerShell -EncodedCommand / download cradles · eval/exec abuse
🦠 Signatures	ClamAV local antivirus engine · custom YARA rules (reverse shells, droppers, ransomware, credential theft, shellcode)
☁️ Optional cloud	VirusTotal lookup by hash (bring your own free API key)

Every finding rolls up into a transparent risk score (0–100) with the exact reasons listed, so you understand why a file was flagged.

🖥️ Two ways to use it

Web dashboard — drag & drop, live results, and a searchable report history:

python3 app.py
# open http://localhost:8080

Command line — great for scripting and batch scans:

python3 analyzer.py suspicious.pdf
python3 analyzer.py ~/Downloads/ --recursive --save
python3 analyzer.py installer.exe --vt-key YOUR_VIRUSTOTAL_KEY

🚀 Quick start (macOS / Apple Silicon)

git clone https://github.com/<your-username>/file-malware-analyzer.git
cd file-malware-analyzer
./setup.sh          # installs libmagic, ClamAV, YARA + Python deps
python3 app.py      # then open http://localhost:8080

The setup.sh script installs the system dependencies via Homebrew and all Python packages, then updates ClamAV's virus definitions.

Manual install

# System libraries (Homebrew)
brew install libmagic clamav yara
freshclam                       # download ClamAV virus definitions

# Python packages
pip3 install -r requirements.txt

Linux: replace the Homebrew line with your package manager, e.g. sudo apt install libmagic1 clamav yara && sudo freshclam.

🔒 How to test it safely

Use the EICAR test file — an industry-standard, completely harmless string that every antivirus is designed to detect:

printf 'X5O!P%%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > eicar.txt
python3 analyzer.py eicar.txt      # → flagged: Eicar-Test-Signature

It contains no malicious code but triggers the detection pipeline so you can see a real "threat found" result.

🧱 How it works

        ┌──────────────┐      ┌─────────────────────┐      ┌──────────────┐
 File → │  Web UI /    │  →   │  Analysis engine    │  →   │  Risk score  │
        │  CLI         │      │  (analyzer.py +      │      │  + reasons   │
        └──────────────┘      │   deep_analysis.py) │      └──────────────┘
                              └─────────────────────┘
                          hashes · type · entropy · strings
                          PE/Mach-O/ELF · PDF · Office · images
                          archives · scripts · ClamAV · YARA · VT

File	Role
app.py	Flask web server & upload/scan API
analyzer.py	Core engine + CLI + risk scoring
deep_analysis.py	Low-level inspection (images, Mach-O/ELF, carving, IOCs, polyglot)
templates/index.html	The web dashboard (single-file UI)
yara_rules/	Custom YARA detection rules
setup.sh	One-command environment setup

⚠️ Disclaimer

This project is for educational and defensive purposes only. It performs static analysis — it inspects files without executing them and never runs any payload. No scanner is perfect: a Clean result is not a guarantee of safety, and a High risk result can occasionally be a false positive. Always pair it with good judgment and up-to-date antivirus. Analyzed files stay on your machine unless you choose to use the optional VirusTotal integration.

📄 License

Released under the MIT License.