CoolFace
Apppublic

alirezaaminzadeh/ThreatScanDashboard-MalwareScanHub

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
App README

MalwareScanHub (ThreatScanDashboard)

A security dashboard for scanning files and URLs for malware and phishing threats. It combines a modern web UI with a REST API and is designed for Docker-based deployment. The scan engine uses configurable heuristics and is structured so you can plug in ML models (e.g. from Hugging Face) later.

Author

FieldValue
NameAlireza Aminzadeh
Hugging Facesyeedalireza
LinkedInalirezaaminzadeh
Contactalireza.aminzadeh@hotmail.com

Features

  • —File scan — Upload files (e.g. executables, scripts, documents) for threat analysis.
  • —URL scan — Submit URLs for phishing and malware-style checks.
  • —Dashboard — View the latest result and a list of recent scans with risk scores.
  • —REST API — Endpoints for file and URL scanning, plus health and scan history; ready to add API key or JWT auth if needed.
  • —Docker — Single-command run; only the reverse proxy is exposed on port 80; backend is not exposed to the host.

Technologies, Tools & Libraries

CategoryTechnologies / tools / libraries
FrontendReact 18, Vite, Tailwind CSS
BackendFastAPI, Uvicorn, Pydantic, Pydantic-Settings
ProxyNginx
RuntimeDocker, Docker Compose
SecurityEnv-based config, CORS, configurable upload limits; API key / rate limiting can be added
Extensible to MLScan service is built to swap heuristics for a Hugging Face (e.g. Transformers) or other ML model; see backend/app/services/scan_service.py

Quick start

  1. 1.Clone and enter the project
bash
   git clone <your-repo-url> malwarescanhub
   cd malwarescanhub
  1. 1.Configure environment
bash
   cp .env.example .env
   # Edit .env and set API_SECRET_KEY (and optionally other values).
  1. 1.Run with Docker Compose (Docker Desktop must be running on Windows)
bash
   docker compose up -d
  1. 1.Open the dashboard
  2. 2.App: http://localhost
  3. 3.API docs: http://localhost/api/docs

Project structure

.
├── backend/                 # FastAPI app (scan API, business logic)
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── api/routes.py
│   │   └── services/scan_service.py
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                # React SPA (dashboard, upload, results)
│   ├── src/
│   ├── nginx.conf           # Nginx config for production (serves SPA + proxies /api)
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
├── .env.example
└── README.md

API overview

MethodEndpointDescription
GET/api/healthHealth check
POST/api/scan/fileUpload a file for scanning
POST/api/scan/urlSubmit a URL for scanning
GET/api/scansList recent scans (query param: limit)

Configuration (CORS, upload limits, etc.) is driven by environment variables; see .env.example.

Security notes

  • —Only the frontend container (Nginx) exposes port 80 on the host; the backend is reachable only on the Docker network.
  • —Secrets and keys belong in .env; never commit .env.
  • —Upload size and other limits are configurable via .env.

Note on the scan engine

The current implementation uses heuristic rules (e.g. file extension, URL patterns) to produce a risk score and status. This is intentional for a portable demo and makes it easy to replace or extend with an ML model (e.g. a Hugging Face Transformers model for malware or phishing) in ScanService without changing the API or UI.

Publishing on Hugging Face

This repo is set up to be pushed to a Hugging Face repository. Use the link and token you receive to add the remote and push. See [PUSH_TO_HF.md](PUSH_TO_HF.md) for step-by-step instructions.

License

MIT.