https://github.com/masteribro/dynamic-malware-detection
A behavioral-based malware analysis tool that monitors and classifies program activities in real-time using sandboxing techniques.
https://github.com/masteribro/dynamic-malware-detection
Last synced: 26 days ago
JSON representation
A behavioral-based malware analysis tool that monitors and classifies program activities in real-time using sandboxing techniques.
- Host: GitHub
- URL: https://github.com/masteribro/dynamic-malware-detection
- Owner: masteribro
- Created: 2026-02-15T10:26:28.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-06-01T12:58:53.000Z (about 1 month ago)
- Last Synced: 2026-06-01T14:25:58.702Z (about 1 month ago)
- Language: Python
- Homepage: https://v0-dynamic-malware-detection.vercel.app
- Size: 254 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MalwareGuard — Dynamic Malware Detection System
A web-based malware detection platform that combines static file analysis, YARA signature scanning, VirusTotal API integration, MalwareBazaar lookups, entropy analysis, and behavioural simulation to classify files as benign, suspicious, or malicious.
---
## Features
- **User Authentication** — Login/registration with role-based access (Admin / Analyst)
- **Real File Scanning** — Upload a file and get verdicts from VirusTotal (70+ AV engines), MalwareBazaar, and YARA rules
- **Behavioural Simulation** — Simulate program behaviour and classify using a weighted heuristic scoring model
- **YARA Signatures** — Detect process injection, ransomware, trojans, and more via custom YARA rules
- **Entropy Analysis** — Flags packed or encrypted binaries using Shannon entropy
- **Suspicious String Extraction** — Identifies dangerous API calls and keywords in binary files
- **History & Statistics** — Searchable analysis history with detection rate charts
- **SQLite Database** — Persistent storage for all analyses
---
## Prerequisites
- Python 3.8 or higher
- pip
- A VirusTotal API key (free tier works — sign up at https://www.virustotal.com)
---
## Setup & Installation
### 1. Clone the repository
```bash
git clone https://github.com/masteribro/dynamic-malware-detection.git
cd dynamic-malware-detection
```
### 2. Create and activate a virtual environment
```bash
python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
# OR
.venv\Scripts\activate # Windows
```
### 3. Install dependencies
```bash
pip install -r requirements.txt
```
### 4. Configure your VirusTotal API key
The app reads the API key from a `config.py` file in the project root (this file is gitignored and must be created manually).
Create `config.py` in the project root:
```python
VIRUSTOTAL_API_KEY = 'your_virustotal_api_key_here'
```
**Alternative — use an environment variable instead:**
```bash
export VIRUSTOTAL_API_KEY='your_virustotal_api_key_here'
```
> The app will fall back to the environment variable if `config.py` is not present. Without a valid API key, VirusTotal lookups will be skipped but all other detection methods (YARA, entropy, MalwareBazaar) will still work.
### 5. (Optional) Set a custom secret key
By default the app uses a development secret key. For any serious deployment set:
```bash
export SECRET_KEY='your-random-secret-key'
```
---
## Running the Application
```bash
source .venv/bin/activate # make sure the virtual environment is active
python3 web_interface/app.py
```
The app starts on **http://localhost:8000**
> **Note for macOS users:** Port 5000 is blocked by AirPlay Receiver. The app uses port 8000 by default. You can override this with `export PORT=5001` before running.
---
## First-Time Login
1. Open **http://localhost:8000** in your browser.
2. Click **Register** to create an account.
3. The **first registered user** is automatically assigned the **Admin** role. All subsequent users become Analysts.
4. Log in and you will be taken to the dashboard.
---
## Usage
### Real File Scan (Analyze Tab)
1. Click the **Analyze** tab.
2. Toggle to **Real File Scan**.
3. Drag and drop or browse for a file (supported: `.exe`, `.dll`, `.pdf`, `.zip`, `.js`, `.ps1`, `.bat`, `.doc`, `.xls`, and more).
4. Click **Scan File**.
5. Results include:
- Verdict: **Malicious / Suspicious / Benign**
- VirusTotal engine breakdown
- MalwareBazaar hash match
- YARA rule hits
- Shannon entropy value
- Suspicious strings found
- MD5 / SHA-1 / SHA-256 hashes
### Behavioural Simulation (Analyze Tab)
1. Toggle to **Behavioural Simulation**.
2. Enter a program name and select a behaviour type.
3. The system simulates runtime behaviour, extracts 6 behavioural features, and classifies via weighted heuristic scoring.
---
## Environment Variables Reference
| Variable | Required | Description |
|---|---|---|
| `VIRUSTOTAL_API_KEY` | Recommended | VirusTotal API v3 key for file/hash scanning |
| `SECRET_KEY` | Optional | Flask session secret key (use a strong random value in production) |
| `PORT` | Optional | Port to run the app on (default: `8000`) |
---
## Project Structure
```
dynamic-malware-detection/
├── web_interface/
│ ├── app.py # Flask application (auth, routes, API endpoints)
│ ├── scanner.py # Real file scan pipeline (VT, YARA, entropy)
│ ├── templates/
│ │ ├── login.html
│ │ ├── register.html
│ │ └── index.html # Main dashboard
│ └── static/
│ ├── css/style.css
│ └── js/main.js
├── src/
│ ├── main.py # DynamicMalwareDetector orchestrator
│ ├── monitor/
│ │ └── behavior_monitor.py # Behaviour simulation
│ ├── analysis/
│ │ ├── feature_extractor.py # 6-feature extraction
│ │ ├── classifier.py # Heuristic + ML classifier
│ │ └── yara_integration.py # YARA engine wrapper
│ ├── data/
│ │ └── dataset_generator.py
│ ├── models/
│ │ └── model_trainer.py
│ ├── evaluation/
│ │ └── evaluator.py
│ └── reporting/
│ └── report_generator.py
├── yara_rules/
│ ├── trojan_behaviors.yar # Process injection, C2 patterns
│ ├── ransomware_signatures.yar # Shadow copy deletion, encryption markers
│ ├── trojan_droppers.yar
│ └── worm_patterns.yar
├── models/
│ ├── ensemble_model.pkl # Trained RandomForest + GradientBoosting
│ └── scaler.pkl
├── scripts/
│ └── train_simple.py # Train ML model on synthetic data
├── tests/
│ └── test_comprehensive.py
├── reports/ # Generated scan reports (JSON)
├── uploads/ # Temporary file upload directory
├── requirements.txt
├── config.py # YOUR API KEY — create this manually, not committed
└── malware_detection.db # SQLite database (auto-created on first run)
```
---
## Troubleshooting
**`ModuleNotFoundError: No module named 'flask'`**
- You are not in the virtual environment. Run `source .venv/bin/activate` first.
**`python: command not found`**
- macOS uses `python3`. Always use `python3 web_interface/app.py`.
**Port already in use**
- Set a different port: `export PORT=8080` then rerun.
**VirusTotal returns no results**
- Check your API key in `config.py` or the `VIRUSTOTAL_API_KEY` environment variable.
- Free-tier keys have a rate limit of 4 requests/minute and 500/day.
**YARA rules not loading**
- Ensure `yara-python` installed correctly: `pip install yara-python>=4.3.0`
- On Apple Silicon Macs you may need: `brew install yara` first.
**Database errors**
- Delete `malware_detection.db` to reset all data: `rm malware_detection.db`
---
## License
MIT License