Skip to content

setup.md

Latest commit

 

History

History
184 lines (138 loc) · 5.03 KB

setup.md

File metadata and controls

184 lines (138 loc) · 5.03 KB
Raw

Malware Detection System - Setup Guide

This guide explains how to set up and run the Malware Detection System locally.

Prerequisites

  • Python 3.11+ (required)
  • uv - Python package manager (install guide)
  • Git (optional, for cloning)

Quick Start

1. Install Dependencies

# Navigate to the project directory (IMPORTANT: must be inside malware-detector)
cd "C:\Users\haris\Desktop\New folder\malware-detector"

# Install all dependencies using uv
uv sync

This creates a virtual environment in .venv/ and installs all required packages.

2. Configure Environment

# Copy the example environment file
cp backend/.env.example backend/.env

Edit backend/.env if needed (defaults work for local development).

3. Run the Backend

# Make sure you're in the malware-detector directory
cd "C:\Users\haris\Desktop\New folder\malware-detector"

# Start the FastAPI server
uv run uvicorn backend.app.main:app --reload --port 8000

The API will be available at:

4. Run the Frontend

The frontend is a static HTML/CSS/JS application. You can serve it with any static file server:

Option A: Python's built-in server

cd frontend
python -m http.server 3000

Option B: Using Node.js (if installed)

npx serve frontend -l 3000

Then open http://localhost:3000 in your browser.

Project Structure

malware-detector/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── main.py         # Application entry point
│   │   ├── config.py       # Configuration settings
│   │   ├── database.py     # SQLite database setup
│   │   ├── models/         # Pydantic schemas & DB models
│   │   ├── routers/        # API endpoints
│   │   ├── services/       # Business logic (classifier, GradCAM)
│   │   └── utils/          # Helper functions
│   ├── ml_model/           # Trained model files
│   │   ├── model.pth       # PyTorch model weights
│   │   └── class_labels.json
│   └── .env.example        # Environment template
├── frontend/               # Static web frontend
│   ├── index.html
│   ├── css/styles.css
│   └── js/app.js
├── training/               # Model training code
│   ├── train_malware_detector.ipynb
│   └── requirements.txt
├── pyproject.toml          # Project configuration & dependencies
└── uv.lock                 # Locked dependency versions

Training Dependencies (Optional)

If you want to train or fine-tune the model, install the training extras:

uv sync --extra training

This adds:

  • matplotlib, seaborn (visualization)
  • scikit-learn (metrics)
  • jupyter, ipywidgets (notebooks)
  • tqdm (progress bars)

Running Training Notebook

uv run jupyter notebook training/train_malware_detector.ipynb

Note for GPU Training: The default PyTorch installation is CPU-only. For CUDA support, you need to install PyTorch with CUDA manually:

# CUDA 12.1
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# CUDA 11.8
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

Development

Running Tests

uv run pytest

Code Formatting & Linting

# Check code style
uv run ruff check .

# Auto-fix issues
uv run ruff check . --fix

API Endpoints

Method Endpoint Description
GET / API information
GET /health Health check
POST /api/scan Upload and analyze a file
GET /api/history Get scan history
GET /api/reports/{scan_id}/pdf Download PDF report
GET /api/reports/{scan_id}/json Download JSON report

Environment Variables

Variable Default Description
APP_NAME Malware Detection System Application name
APP_VERSION 1.0.0 Version string
DEBUG True Enable debug mode
MAX_FILE_SIZE 52428800 Max upload size (50MB)
DATABASE_URL sqlite:///./malware_detector.db Database connection
MODEL_PATH ./ml_model/model.pth Path to trained model
IMAGE_SIZE 256 Image size for CNN

Troubleshooting

"Model not found" error

Ensure the trained model exists at backend/ml_model/model.pth. If not, you'll need to train the model first using the training notebook.

Import errors

Make sure you're running commands with uv run to use the virtual environment:

uv run python -c "import torch; print(torch.__version__)"

Port already in use

Change the port number:

uv run uvicorn backend.app.main:app --reload --port 8001

CORS issues

The backend allows all origins by default (allow_origins=["*"]). For production, restrict this in backend/app/main.py.