Skip to content

AbdullahMaqbool22/NeuroWare

BranchesTags

Repository files navigation

NeuroWare — AI-Powered Malware Detection Platform

A real-time security analysis and threat detection system built with Next.js (frontend) and Django (backend). Combines local heuristic classifiers, a PE-aware ML ensemble, Docker-based sandbox execution, optional VirusTotal multi-engine scanning, and an optional Gemini LLM report layer.

Features

  • JWT Authentication — secure login, signup, and token refresh
  • 5-stage Analysis Pipeline — heuristic → ML ensemble → sandbox → multi-engine → Gemini LLM
  • Docker Sandbox — live container execution with --network none, --memory 128m, --cpus 0.5; falls back to deep forensic static analysis when Docker is unavailable
  • Forensic Static Analysis — PE/ELF/PDF/OLE/ZIP/script dissection without any external tool
  • ML Ensemble Scoring — PE-aware Random Forest + generic Random Forest, weighted 55/45 with heuristic
  • Real-time Threat Dashboard — Recharts area + donut charts, per-day scan activity
  • Multi-file Upload Queue — drag-and-drop with per-file progress and risk ranking
  • Threat Prioritization — files ranked by fused threat score
  • Detailed Report Pages — sandbox behaviors, ML probabilities, network IOCs, print-to-PDF
  • Dark Cyber Theme — electric cyan + neon green glassmorphism UI
  • Support Chat — AI assistant powered by Gemini (optional)

Branding

The NeuroWare mark is a hex security boundary (Ware) wrapping a connected-node neural network (Neuro), with a glowing live-accent core matching the dashboard's active-scan indicators.

Tech Stack

Frontend

Technology Purpose
Next.js 16 React framework (App Router)
TypeScript Type-safe development
Tailwind CSS v4 Utility-first styling
shadcn/ui + Radix UI Accessible component primitives
Recharts 2 Threat charts and visualisations
Space Grotesk + Space Mono Fonts (via next/font/google)

Backend

Technology Purpose
Django 6.0 Python web framework
Django REST Framework REST API
Daphne + ASGI ASGI server with HTTP/2 support
scikit-learn ML malware detection ensemble
pefile / struct PE feature extraction (stdlib fallback)
Docker SDK Live sandbox container execution
VirusTotal API Optional 70+ engine multi-scan
Gemini API Optional LLM threat report generation
SQLite / PostgreSQL Database
Simple JWT Token-based authentication
drf-spectacular Auto-generated Swagger/Redoc API docs

Quick Start

One command — creates the venv, installs all dependencies, runs migrations, creates an admin user, and starts both servers:

python project_setup.py

All prompts have sensible defaults (press Enter to accept):

Question Default
Run mode development
SECRET_KEY auto-generated
ALLOWED_HOSTS localhost,127.0.0.1
Database SQLite (zero config)
Backend port 8000
Frontend port 3000
JWT access token lifetime 24 hours
Max upload size 100 MB
Create admin superuser? yes 
# Skip wizard, just start servers (uses existing .env)
python project_setup.py --start

# Wipe .env files and re-run the full wizard
python project_setup.py --reset

Manual Setup

Prerequisites

  • Python 3.9+
  • Node.js 18+ and pnpm
  • Git
  • Docker Desktop (optional — enables live sandbox execution)

Backend

cd django_backend

python -m venv ../.venv
..\.venv\Scripts\activate      # Windows
source ../.venv/bin/activate   # macOS / Linux

pip install -r requirements.txt

cp .env.example .env           # edit .env as needed

python manage.py migrate
python manage.py runserver 0.0.0.0:8000

Frontend

# From the project root
pnpm install
echo "NEXT_PUBLIC_DJANGO_API_URL=http://127.0.0.1:8000" > .env.local
pnpm dev
Service URL
Frontend http://localhost:3000
Backend API http://localhost:8000/api/
Swagger UI http://localhost:8000/api/schema/swagger/
Django Admin http://localhost:8000/admin/

Analysis Pipeline

File upload
    │
    ├─ 1. Local heuristic classifier   (always — no API key required)
    │       Feature extraction: entropy, PE sections, strings, imports
    │
    ├─ 2. ML Ensemble scorer           (always — no API key required)
    │       PE-aware Random Forest + generic RF
    │       Weighted fusion: heuristic 55% + ML 45%
    │
    ├─ 3. Sandbox execution            (always — Docker or forensic fallback)
    │       Docker mode:    live container, --network none, --memory 128m
    │       Forensic mode:  PE/ELF/PDF/OLE/ZIP/script static dissection
    │       Sandbox mode reported in result: "docker+forensic" | "forensic_analysis" | "docker"
    │
    ├─ 4. Multi-engine scan            (optional — requires VIRUSTOTAL_API_KEY in .env)
    │       70+ AV engines via VirusTotal API
    │
    └─ 5. AI threat report             (optional — requires GEMINI_API_KEY in .env)
            Gemini LLM generates executive summary, findings, recommendations

Environment Variables

Backend .env

# Required
SECRET_KEY=your-django-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Database (default: SQLite)
DATABASE_URL=sqlite:///db.sqlite3

# Optional integrations
VIRUSTOTAL_API_KEY=    # enables multi-engine scanning (70+ AV engines)
GEMINI_API_KEY=        # enables AI threat report generation
GEMINI_MODEL=gemini-1.5-flash

Frontend .env.local

NEXT_PUBLIC_DJANGO_API_URL=http://127.0.0.1:8000

Docker Sandbox

The sandbox uses --network none (no internet access), --memory 128m, and --cpus 0.5 per container. Supported file execution:

Extension Container Execution
.py python:3.11-alpine timeout 25 python3 <file>
.js node:20-alpine timeout 10 node <file>
.sh alpine:latest timeout 10 sh <file>
.exe, .dll, .pdf, etc. alpine:latest grep-based IOC extraction (no Wine)

No Docker? The engine automatically falls back to forensic_analysis mode — a pure-Python deep dissection of PE headers, ELF sections, PDF streams, OLE VBA, ZIP members, and script patterns. Every finding is evidence-based from actual file bytes.

To enable Docker: install Docker Desktop and start the daemon. The engine detects it automatically on the next upload.

API Endpoints

Authentication

Method Path Description
POST /auth/signup Register new user
POST /auth/login Login — returns JWT access + refresh tokens
POST /auth/token/refresh Refresh access token
POST /auth/logout Blacklist refresh token
GET /auth/profile/me Current user profile
PUT /auth/profile/update_profile Update profile

File Analysis

Method Path Description
POST /api/analyses/upload/ Upload file for analysis
GET /api/analyses/ List user's analyses
GET /api/analyses/{id}/ Analysis detail
GET /api/analyses/{id}/report/ Detailed sandbox + ML report

Dashboard

Method Path Description
GET /api/dashboard/overview/ Full stats + recent analyses
GET /api/dashboard/stats/ Aggregated counts + health
GET /api/dashboard/scan_activity/?days=30 Per-day scan/threat counts for charts
GET /api/dashboard/timeline/?hours=24 Threat timeline
GET /api/dashboard/distribution/ Threat type breakdown

Utilities

Method Path Description
GET /api/health/ Health check (no auth required)
POST /api/support/chat/ AI support assistant

Project Structure

neuroware/
├── project_setup.py              # one-command setup + launcher
│
├── app/                          # Next.js App Router pages
│   ├── auth/                     # login / signup
│   ├── dashboard/                # main dashboard with Recharts
│   ├── upload/                   # file upload + live results
│   ├── analysis/                 # analysis list
│   ├── report/[id]/              # per-file detailed report + print
│   ├── settings/
│   └── profile/
│
├── components/
│   ├── ui/                       # shadcn/ui primitives
│   ├── file-upload-zone.tsx      # upload queue + real-time results
│   ├── overview-cards.tsx        # dashboard metric cards
│   ├── recent-analyses.tsx       # activity feed
│   ├── support-chat.tsx          # AI help widget
│   ├── logo.tsx                   # NeuroWare logo mark (hex + neural net)
│   └── header.tsx                # NeuroWare nav header
│
├── lib/
│   ├── api.ts                    # djangoFetch + JWT refresh
│   └── auth-context.tsx          # auth provider
│
└── django_backend/
    ├── api/                      # analysis models, views, serializers
    ├── authentication/           # JWT auth endpoints
    ├── utils/
    │   ├── analysis.py           # 5-stage pipeline orchestrator
    │   ├── sandbox.py            # Docker + forensic sandbox engine
    │   ├── ml_model.py           # ML ensemble scorer
    │   ├── local_classifier.py   # heuristic classifier
    │   ├── pe_extractor.py       # PE feature extraction
    │   ├── ai_analyzer.py        # Gemini LLM integration
    │   └── multi_engine_client.py# VirusTotal integration
    └── models/
        └── malware_models/       # pretrained .pkl artifacts

Available Scripts

Frontend

pnpm dev        # development server (http://localhost:3000)
pnpm build      # production build
pnpm start      # serve production build
pnpm lint       # ESLint

Backend

python manage.py runserver       # development server
python manage.py migrate         # apply migrations
python manage.py createsuperuser # create admin user
python manage.py test            # run tests

Deployment

Frontend — Vercel

pnpm build
# push to GitHub and connect to Vercel
# set NEXT_PUBLIC_DJANGO_API_URL to your backend URL

Backend — Railway / Render / Heroku

See django_backend/DEPLOYMENT.md for step-by-step instructions.

License

MIT — see LICENSE for details.

About

AI-powered Malware classification

Topics

ai analysis malware reports malware-analysis intelligent malware-detection llm reports-dashboard

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages