Malware Interception Framework

A proactive Windows download interception and malware analysis framework.

Instead of waiting until after execution, the framework watches the Downloads folder, intercepts newly arrived files, performs static analysis, and either releases or quarantines the file before the user can open it.

Key Features

• Real-time monitoring of the Windows Downloads folder.
• PDF malware detection using a trained XGBoost model over 31 structural features.
• Word document detection for .docx and .doc using macro, IOC, DDE, and obfuscation checks.
• PE .exe detection using static PE features, with support for a dedicated ML model.
• PE .exe detection using the published EMBER2024 LightGBM PE model when available.
• Safe PE fallback scoring when the PE model files have not been trained or added yet.
• System tray dashboard with scan history, risk levels, and quarantine actions.
• Automatic quarantine for files at or above the configured risk threshold.

How It Works

1. file_monitor.py watches the Downloads folder with watchdog.
2. New files are allowed to finish downloading, then renamed with .scanning to lock them during analysis.
3. The file is routed by type:
   • PDF -> pdf_feature_extractor.py
   • Word -> docx_feature_extractor.py
   • PE .exe -> pe_feature_extractor.py
4. The monitor decides whether to unlock the file or move it into quarantine.
5. tray_app.py surfaces the result in the tray UI and dashboard.

Supported File Types

• .pdf
• .docx
• .doc
• .exe

Setup and Run

Prerequisites:

• Windows 10 or 11
• Python 3.10+

Quick Run / Smoke Test

Use this path first after cloning the repository. It runs the app from source so you can confirm that the environment, dependencies, and model files are working before building a packaged executable.

cd "C:\path\to\Malware-Int-Framework"
python -m venv venv
.\venv\Scripts\activate
python -m pip install -r requirements.txt
python tray_app.py

If the virtual environment already exists, you can skip the python -m venv venv line.

Build Packaged EXE

Use this path only after the quick run works.

cd "C:\path\to\Malware-Int-Framework"
.\venv\Scripts\activate
python -m pip install pyinstaller
pyinstaller tray_app.spec

The compiled executable will be written to dist/MalwareMonitor.exe.

Models

Required for PDF ML scanning

Place these files in models/:

• malware_classifier.pkl
• feature_names.pkl

Optional for PE ML scanning

Place these files in models/:

• pe_malware_classifier.pkl
• pe_feature_names.pkl
• EMBER2024_PE.model

PE model priority:

• EMBER2024_PE.model if present
• custom pe_malware_classifier.pkl if present
• built-in fallback static PE scorer otherwise

The repository is already wired to the published EMBER2024 PE benchmark model format. If models/EMBER2024_PE.model is present, .exe files are scored with that model automatically.

Important: models/EMBER2024_PE.model is a LightGBM text model and must keep LF line endings. The repository includes .gitattributes to prevent Windows line-ending conversion from corrupting the file during clone or checkout.

PE Training

The repository now includes train_pe_model.py, which trains a PE malware classifier from labeled .exe samples using the same runtime feature space as the PE extractor.

Expected dataset layout:

dataset/
  pe/
    benign/
      *.exe
    malicious/
      *.exe

Example:

python train_pe_model.py --dataset-root dataset/pe

This saves:

• models/pe_malware_classifier.pkl
• models/pe_feature_names.pkl

Testing

1. Run the application.
2. Download or copy a PDF, Word document, or .exe into your Downloads folder.
3. The monitor will lock the file, scan it, and either restore or quarantine it.
4. Review the result in the dashboard or in monitor.log.

Quick Validation Notes

• Start with the Quick Run / Smoke Test path above before trying to build dist/MalwareMonitor.exe.
• For PE .exe validation, a safe benign local executable such as the environment's python.exe can be copied into the watched folder to confirm:
  • the file is intercepted
  • the .scanning suffix is removed after analysis
  • a dashboard history entry is written
  • the justification popup matches the displayed confidence and prediction
• If a fresh Windows clone shows LightGBM Model format error, expect a tree here, refresh models/EMBER2024_PE.model after pulling the latest repo metadata, because that usually means the model file was checked out with CRLF instead of LF line endings.

Project Structure

tray_app.py               # System tray entry point and dashboard
file_monitor.py           # Download interception and routing
pdf_feature_extractor.py  # PDF static feature extraction + ML scoring
docx_feature_extractor.py # Word malware scoring
pe_feature_extractor.py   # PE feature extraction + optional ML scoring
train_model.py            # PDF model training pipeline
train_pe_model.py         # PE model training pipeline
tray_app.spec             # PyInstaller build spec
models/                   # Trained model artifacts
dataset/                  # Training data assets

Notes

• The original academic project focused on PDF malware detection first.
• The current codebase now extends the same interception architecture to Word and PE files.
• For a broader architectural narrative, see PROJECT_README.md, but treat this README as the most current high-level source of truth.

Extra Documentation

• PDF inspection rundown
• DOCX inspection rundown
• EXE inspection rundown
• Copy-ready citations