🛡️ MalwareGuard AI

Static & Behavioral Malware Detection Platform

Upload executables → static analysis + YARA rules + 3-model AI ensemble + VirusTotal cross-check → family prediction + PDF/JSON export

---

📸 Screenshots

Upload Console

Analysis Result — YARA, VT, CNN Ensemble

Batch Mode — Multiple Files at Once

Scan History + PDF/JSON Export

---

✨ Features

Feature	Details
📤 Single & batch upload	Single file or up to 20 files at once (drag-drop or file picker), never executed
🔬 Static analysis	PE header, section entropy, imports, byte histogram (38 features, EMBER-schema-compatible)
🎯 YARA rule matching	9 original heuristic rules — injection, anti-debug, keylogging, ransomware, backdoor, persistence, packers, credential theft
🧠 Dynamic analysis	Heuristic behavior prediction from static indicators (anti-debug, injection, network, crypto)
🤖 3-model AI ensemble	Random Forest + Gradient Boosting + 1D-CNN (byte histogram) — transparent per-engine scores
🧬 Family classification	8 families: ransomware, trojan, worm, rootkit, spyware, adware, backdoor, downloader
🔍 VirusTotal lookup	Hash-only lookup (file never sent) — cross-checks local verdict against VT's 60+ engines
📋 Scan history	Persistent JSON-based history, stats dashboard, per-entry PDF/JSON export
💡 Explainable verdicts	Every result shows the top features that drove the classification

AI Models

Model	Input	Role
🌳 Random Forest	38 tabular EMBER-schema features	Primary binary classifier
📈 Gradient Boosting	Same 38 features	Alternate; best of two auto-selected by AUC
🧮 1D-CNN (numpy/sklearn)	256-bin byte histogram	Secondary ensemble signal; genuine Conv1D→ReLU→MaxPool

The CNN is implemented by hand in numpy + sklearn (no PyTorch/TensorFlow) to keep the install lean (~310MB). For larger-scale training, the byte-histogram input and predict_proba() interface are drop-in compatible with a real PyTorch Conv1D model.

---

🚀 Quick Start

First-time setup

Linux / macOS:

git clone <your-repo-url> MalwareGuardAI
cd MalwareGuardAI
chmod +x setup_and_run.sh run.sh
./setup_and_run.sh

Windows:

git clone <your-repo-url> MalwareGuardAI
cd MalwareGuardAI
setup_and_run.bat

This installs all dependencies (~310MB), trains models, and launches:

• Web UI: http://localhost:5173
• API + Docs: http://localhost:8000/docs

Daily use

./run.sh        # Linux/macOS
run.bat         # Windows

VirusTotal (optional)

Get a free API key at https://www.virustotal.com/gui/my-apikey (500 lookups/day).

Create a .env file in the project root (already gitignored):

echo "VT_API_KEY=your_key_here" > .env

Then run ./run.sh — the backend loads .env automatically at startup. The health endpoint at http://localhost:8000/ confirms virustotal_configured: true.

Without a key the VT card shows "No VT_API_KEY set" — everything else works normally.

---

🐛 Troubleshooting

Problem	Fix
ModuleNotFoundError: No module named 'requests'	Run: pip install requests==2.31.0 urllib3==2.0.7 charset-normalizer==3.3.2
RequestsDependencyWarning: urllib3 ... doesn't match	Run: pip install requests==2.31.0 urllib3==2.0.7 charset-normalizer==3.3.2
"ENGINES OFFLINE" in UI	Backend not running — open a second terminal and run run.bat or check http://localhost:8000/
Models not found error	Run python backend/models/train.py from the project root
pefile.PEFormatError	Uploaded file is not a valid PE executable (.exe/.dll/.sys)
VT shows "No API key"	Create .env with VT_API_KEY=your_key and restart the backend
PDF/JSON download 404	History entry not found — may have been cleared
Frontend CORS error	Ensure backend is running on port 8000
yara-python install fails on Windows	Run: pip install yara-python --no-binary yara-python
yara-python install fails on macOS	Run: brew install yara first, then pip install yara-python
yara-python install fails on Linux	Run: sudo apt install libyara-dev first, then pip install yara-python

---

📂 Project Structure

MalwareGuardAI/
├── setup_and_run.sh / .bat     # First-time setup + launch
├── run.sh / run.bat            # Daily launch (fast)
├── requirements.txt            # All backend deps — pinned versions
├── .env                        # Your secrets (gitignored, create manually)
├── .gitignore
│
├── backend/
│   ├── api.py                  # FastAPI — single, batch, history, export endpoints
│   ├── analysis/
│   │   ├── static_analysis.py  # PE feature extraction + byte histogram (pefile)
│   │   ├── dynamic_analysis.py # Heuristic behavior prediction rules
│   │   ├── yara_scan.py        # YARA rule matching engine
│   │   ├── virustotal.py       # VirusTotal hash lookup (hash-only, graceful fallback)
│   │   └── generate_dataset.py # EMBER-schema-compatible synthetic training dataset
│   ├── models/
│   │   ├── cnn.py              # Lightweight numpy/sklearn 1D-CNN
│   │   ├── train.py            # RF + GB + CNN training pipeline
│   │   └── predict.py          # Ensemble inference + explanations
│   ├── storage/
│   │   ├── history.py          # JSON-file scan history (rolling 500 entries)
│   │   └── report_export.py    # PDF (reportlab) + JSON report generation
│   ├── yara_rules/
│   │   └── generic_malware.yar # 9 original heuristic YARA rules
│   └── artifacts/              # Trained model files (auto-generated by train.py)
│
├── frontend/                   # React + TypeScript + Vite
│   └── src/
│       ├── App.tsx             # Main UI — scan, batch, history views
│       ├── api.ts              # Typed API client (axios)
│       └── components/
│           └── ByteStrip.tsx   # Hex-dump decorative header element
│
├── data/                       # Training datasets (auto-generated)
│   ├── pe_features_dataset.csv
│   └── byte_histograms.npy
│
└── screenshots/                # README screenshots

---

🛠️ API Reference

Method	Endpoint	Description
GET	/	Health check, model metadata, VT configured status
POST	/analyze	Upload single PE file → full analysis result
POST	/analyze/batch	Upload up to 20 PE files → per-file results
GET	/history	List scan history, newest first
GET	/history/stats	Total scans, malicious count, family breakdown
GET	/history/{id}	Full single history entry
DELETE	/history/{id}	Delete one entry
DELETE	/history	Clear all history
GET	/report/{id}/json	Download JSON report for a past scan
GET	/report/{id}/pdf	Download PDF report for a past scan

Interactive Swagger docs: http://localhost:8000/docs

---

📦 Dataset

Bundled training data is synthetic and EMBER-schema-compatible — same column structure as the EMBER dataset, family-specific feature skews hand-authored from published malware-family research. Not real malware samples.

To swap in real data:

• EMBER — 1.1M pre-extracted PE feature vectors, benign + malicious
• Microsoft Malware Classification Challenge — 9 families, raw bytes (BIG 2015)

Map their features to the schema in backend/analysis/static_analysis.py, replace data/pe_features_dataset.csv + data/byte_histograms.npy, then rerun backend/models/train.py. No other code changes needed.

---

⚠️ Safety Notes

• Files are never executed — only parsed as binary data via pefile
• VirusTotal lookups send only the SHA-256 hash — the file itself never leaves your machine
• YARA and VT results are transparent corroborating signals, not automatic verdict overrides
• 50 MB per-file upload limit enforced server-side
• History stored locally in backend/storage/history.json — never transmitted anywhere
• .env (containing your VT API key) is gitignored — never committed to version control

---

📋 Verified Versions

Package	Version
Python	3.10–3.12
scikit-learn	1.5.2
numpy	1.26.4
pandas	2.2.3
pefile	2024.8.26
yara-python	4.5.1
reportlab	4.2.5
requests	2.31.0
urllib3	2.0.7
charset-normalizer	3.3.2
joblib	1.4.2
fastapi	0.115.5
uvicorn	0.32.0
python-dotenv	1.0.1
React	19
Vite	8

---

⚠️ For research and educational use only. Always verify findings through multiple channels before taking action.