Deploy MalwareGuard FastAPI backend clean

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.vercel
+venv
+frontend/node_modules
+frontend/dist
+data
+*.log
+*-dev.out.log
+*-dev.err.log
+MalwareGuard_Report.*
+test_folder

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+urlmodel_info/case_study_scores.png filter=lfs diff=lfs merge=lfs -text
+urlmodel_info/eda_feature_distributions.png filter=lfs diff=lfs merge=lfs -text
+urlmodel_info/feature_importance_xgb.png filter=lfs diff=lfs merge=lfs -text
+urlmodel_info/results_accuracy_bar.png filter=lfs diff=lfs merge=lfs -text
+urlmodel_info/results_roc_curves.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY backend/requirements.txt /app/backend/requirements.txt
+RUN pip install --no-cache-dir -r /app/backend/requirements.txt
+
+COPY backend /app/backend
+COPY xgb_malware_model.joblib /app/xgb_malware_model.joblib
+COPY urlmodel_info /app/urlmodel_info
+
+WORKDIR /app/backend
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,13 @@
 ---
 title: MalwareGuard
-emoji: 🐢
-colorFrom: indigo
-colorTo: purple
+emoji: 🛡️
+colorFrom: red
+colorTo: gray
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MalwareGuard Backend
+
+FastAPI backend for MalwareGuard, deployed as a Hugging Face Docker Space.

backend/app/__init__.py

@@ -0,0 +1 @@
+# Backend package

backend/app/config.py

@@ -0,0 +1,78 @@
+"""
+Configuration module for the Malware Detection Platform.
+Loads environment variables and provides app-wide settings.
+"""
+
+
+
+import os
+from pathlib import Path
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    
+    # API Keys
+    gemini_api_key: str = ""
+    virustotal_api_key: str = ""
+
+    
+    # Model Configuration
+    model_path: str = "xgb_malware_model.joblib"
+    prediction_threshold: float = 0.5
+
+    
+    # Server Configuration
+    host: str = "0.0.0.0"
+    port: int = 8000
+    debug: bool = True
+
+    
+    # EMBER Dataset Configuration
+    ember_feature_count: int = 2381  # EMBER 2018 v2 feature count
+
+    
+    # Rate Limiting
+    rate_limit_prediction: str = "60/minute"
+    rate_limit_virustotal: str = "10/minute"
+
+    
+    # CORS Origins
+    cors_origins: list[str] = [
+        "http://localhost:5173",
+        "http://localhost:3000",
+        "http://127.0.0.1:5173",
+        "http://127.0.0.1:3000",
+    ]
+    
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        extra = "ignore"
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """
+    Get cached settings instance.
+    Uses LRU cache to avoid re-reading .env file on every call.
+    """
+    # Look for .env in parent directory (project root)
+    env_path = Path(__file__).parent.parent.parent / ".env"
+    if env_path.exists():
+        os.environ.setdefault("ENV_FILE", str(env_path))
+
+    
+    return Settings(_env_file=env_path if env_path.exists() else ".env")
+
+
+
+# Export settings instance for easy import
+settings = get_settings()
+
+
+

backend/app/main.py

@@ -0,0 +1,232 @@
+"""
+Malware Detection Platform - FastAPI Main Application
+
+Production-ready malware detection API combining:
+- XGBoost ML model for EMBER 2018 v2 feature classification
+- Gemini AI for human-readable explanations
+- VirusTotal API for secondary verification
+
+Author: AI Security Engineer
+"""
+# Used libraries
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+from .config import settings
+from .routers import predict, virustotal, chat, upload, url, feedback
+from .services.ml_service import get_ml_service
+from .services.shap_service import get_shap_service
+from .services.gemini_service import get_gemini_service
+from .services.virustotal_service import get_virustotal_service
+from .services.url_service import get_url_service
+from .services.feedback_service import get_feedback_service
+
+# Configure logging.
+logging.basicConfig(
+    level=logging.INFO if settings.debug else logging.WARNING,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# Rate limiter
+limiter = Limiter(key_func=get_remote_address)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan manager.
+    Handles startup and shutdown events.
+    """
+    # Startup.
+    logger.info("=" * 60)
+    logger.info("Malware Detection Platform Starting...")
+    logger.info("=" * 60)
+    
+    # Load ML model (single load for all requests).
+    try:
+        ml_service = get_ml_service()
+        logger.info(f"ML Model loaded: {ml_service.get_model_info()}")
+    except Exception as e:
+        logger.error(f"Failed to load ML model: {e}")
+        raise
+    
+    # Initialize SHAP service.
+    try:
+        shap_service = get_shap_service()
+        shap_service.initialize(ml_service.model)
+        logger.info("SHAP service initialized")
+    except Exception as e:
+        logger.warning(f"SHAP initialization failed (non-critical): {e}")
+    
+    # Initialize Gemini service
+    try:
+        gemini_service = get_gemini_service()
+        if gemini_service.initialized:
+            logger.info("Gemini AI service initialized")
+        else:
+            logger.warning("Gemini AI service not initialized (check API key)")
+    except Exception as e:
+        logger.warning(f"Gemini initialization failed (non-critical): {e}")
+    
+    # Check VirusTotal configuration
+    vt_service = get_virustotal_service()
+    if vt_service.initialized:
+        logger.info("VirusTotal service configured")
+    else:
+        logger.warning("VirusTotal API key not configured")
+    
+    # Load URL HyperModel
+    try:
+        url_service = get_url_service()
+        if url_service.model_loaded:
+            logger.info(f"URL HyperModel loaded: {url_service.get_model_info()['model_type']}")
+        else:
+            logger.warning("URL HyperModel not loaded")
+    except Exception as e:
+        logger.warning(f"URL HyperModel initialization failed (non-critical): {e}")
+    
+    # Initialize RL Feedback service
+    try:
+        fb_service = get_feedback_service()
+        stats = fb_service.get_stats()
+        logger.info(
+            f"RL Feedback service ready "
+            f"(malware={stats['malware_total']}, url={stats['url_total']} samples)"
+        )
+    except Exception as e:
+        logger.warning(f"RL Feedback initialization failed (non-critical): {e}")
+    
+    logger.info("=" * 60)
+    logger.info("Malware Detection Platform Ready!")
+    logger.info(f"API available at: http://{settings.host}:{settings.port}")
+    logger.info("=" * 60)
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down Malware Detection Platform...")
+    
+    # Close VirusTotal client
+    await vt_service.close()
+    
+    logger.info("Shutdown complete")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Malware Detection Platform",
+    description="""
+    ## AI-Powered Malware Detection API
+
+    This platform combines machine learning with AI explanations for comprehensive malware analysis.
+
+    ### Features
+    - **XGBoost Prediction**: Fast malware classification using EMBER 2018 v2 features
+    - **Gemini AI Explanation**: Human-readable analysis and recommendations
+    - **VirusTotal Verification**: Cross-reference with 70+ antivirus engines
+    - **URL Scanner**: Malicious URL detection via stacking HyperModel
+
+    ### Endpoints
+    - `/api/predict` - Run XGBoost malware prediction
+    - `/api/predict/explain` - Prediction with Gemini AI explanation
+    - `/api/virustotal/{hash}` - Look up file hash on VirusTotal
+    - `/api/virustotal/compare` - Compare XGBoost vs VirusTotal verdicts
+    - `/api/url/analyze` - Analyze URL for malicious indicators
+    """,
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Add rate limiter to app state
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Global exception handler
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    """Handle uncaught exceptions with meaningful error messages."""
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    
+    # Don't expose internal errors in production
+    if settings.debug:
+        detail = str(exc)
+    else:
+        detail = "An internal error occurred. Please try again later."
+    
+    return JSONResponse(
+        status_code=500,
+        content={"detail": detail}
+    )
+
+
+# Include routers
+app.include_router(predict.router)
+app.include_router(virustotal.router)
+app.include_router(chat.router)
+app.include_router(upload.router)
+app.include_router(url.router)
+app.include_router(feedback.router)
+
+
+@app.get("/", tags=["root"])
+async def root():
+    """Root endpoint with API information."""
+    return {
+        "name": "Malware Detection Platform",
+        "version": "1.0.0",
+        "status": "running",
+        "docs": "/docs",
+        "endpoints": {
+            "prediction": "/api/predict",
+            "prediction_with_explanation": "/api/predict/explain",
+            "virustotal_lookup": "/api/virustotal/{hash}",
+            "comparison": "/api/virustotal/compare"
+        }
+    }
+
+
+@app.get("/health", tags=["health"])
+async def health_check():
+    """Global health check endpoint."""
+    ml_service = get_ml_service()
+    vt_service = get_virustotal_service()
+    gemini_service = get_gemini_service()
+    
+    return {
+        "status": "healthy",
+        "services": {
+            "ml_model": ml_service.model_loaded,
+            "gemini": gemini_service.initialized,
+            "virustotal": vt_service.initialized
+        }
+    }
+
+
+# For running with: python -m app.main
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug
+    )

backend/app/models/__init__.py

@@ -0,0 +1 @@
+# Models package

backend/app/models/feedback.py

@@ -0,0 +1,126 @@
+"""
+Pydantic models for Reinforcement Learning feedback.
+
+Two feedback channels:
+  1. Malware analysis: auto-reward based on VirusTotal agreement (+1 agree, -1 disagree)
+  2. URL analysis: user-submitted reward via popup ("Was this correct?" Yes → +1, No → -1)
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict
+from enum import Enum
+
+
+class FeedbackType(str, Enum):
+    MALWARE = "malware"
+    URL = "url"
+
+
+# ── Malware RL Feedback ──────────────────────────────────────────────────────
+
+class MalwareFeedbackRequest(BaseModel):
+    """
+    Auto-generated feedback when VirusTotal results are compared with
+    XGBoost prediction.  Reward is computed server-side.
+    """
+    features: List[float] = Field(
+        ...,
+        min_length=2381,
+        max_length=2381,
+        description="EMBER 2018 v2 feature vector",
+    )
+    sha256: str = Field(
+        ...,
+        pattern=r"^[a-fA-F0-9]{64}$",
+        description="SHA256 hash of the analysed file",
+    )
+    predicted_label: str = Field(
+        ...,
+        description="XGBoost prediction: 'Malicious' or 'Benign'",
+    )
+    predicted_probability: float = Field(..., ge=0.0, le=1.0)
+    vt_malicious_count: int = Field(..., ge=0)
+    vt_total_engines: int = Field(..., ge=0)
+    vt_detection_ratio: float = Field(..., ge=0.0, le=1.0)
+
+
+# ── URL RL Feedback ──────────────────────────────────────────────────────────
+
+class URLFeedbackRequest(BaseModel):
+    """
+    User-submitted feedback for URL predictions.
+    The user confirms or denies the model's verdict.
+    """
+    url: str = Field(..., min_length=3, description="Analysed URL")
+    predicted_label: str = Field(
+        ...,
+        description="Model prediction: 'Malicious' or 'Benign'",
+    )
+    malicious_score: float = Field(..., ge=0.0, le=1.0)
+    is_correct: bool = Field(
+        ...,
+        description="True if user confirms prediction is correct, False otherwise",
+    )
+    base_model_scores: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Base model malicious probabilities for meta-feature reconstruction",
+    )
+
+
+# ── Responses ────────────────────────────────────────────────────────────────
+
+class FeedbackResponse(BaseModel):
+    """Response after submitting feedback."""
+    success: bool
+    reward: int
+    message: str
+    total_feedback_count: int
+
+
+class FeedbackStats(BaseModel):
+    """Aggregated RL statistics."""
+    malware_total: int
+    malware_agree: int
+    malware_disagree: int
+    malware_agreement_rate: float
+    url_total: int
+    url_correct: int
+    url_incorrect: int
+    url_accuracy_rate: float
+    recent_malware: List[dict] = []
+    recent_url: List[dict] = []
+    model_updates: List[dict] = []
+
+
+class ModelUpdateRequest(BaseModel):
+    """Request to trigger incremental model update."""
+    model_type: str = Field(
+        ...,
+        description="Which model to update: 'malware' or 'url'",
+        pattern=r"^(malware|url)$",
+    )
+    min_samples: int = Field(
+        10,
+        ge=1,
+        description="Minimum feedback samples required to proceed",
+    )
+    learning_rate: float = Field(
+        0.01,
+        ge=0.001,
+        le=0.1,
+        description="Learning rate for incremental training",
+    )
+    num_boost_rounds: int = Field(
+        5,
+        ge=1,
+        le=50,
+        description="Number of additional boosting rounds",
+    )
+
+
+class ModelUpdateResponse(BaseModel):
+    """Response from model update trigger."""
+    success: bool
+    model_type: str
+    samples_used: int
+    message: str

backend/app/models/prediction.py

@@ -0,0 +1,149 @@
+"""
+Pydantic models for prediction requests and responses.
+Defines the data structures for the XGBoost malware detection API.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+from typing import Optional, List
+
+from enum import Enum
+
+
+class PredictionLabel(str, Enum):
+    """Prediction classification labels."""
+    MALICIOUS = "Malicious"
+    BENIGN = "Benign"
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence level categories based on probability."""
+    HIGH = "High"
+    MEDIUM = "Medium"
+    LOW = "Low"
+
+
+class SeverityLevel(str, Enum):
+    """Severity levels for Gemini analysis."""
+    CRITICAL = "Critical"
+    HIGH = "High"
+    MEDIUM = "Medium"
+    LOW = "Low"
+    NONE = "None"
+
+
+class PredictionRequest(BaseModel):
+    """
+    Request model for malware prediction.
+    Accepts EMBER 2018 v2 feature vector (2381 features).
+    """
+    features: List[float] = Field(
+        ...,
+        description="EMBER 2018 v2 feature vector (2381 float values)",
+        min_length=2381,
+        max_length=2381
+    )
+    sha256: Optional[str] = Field(
+        None,
+        description="Optional SHA256 hash for reference",
+        pattern=r"^[a-fA-F0-9]{64}$"
+    )
+    threshold: Optional[float] = Field(
+        None,
+        description="Custom prediction threshold (0.0-1.0)",
+        ge=0.0,
+        le=1.0
+    )
+    include_shap: Optional[bool] = Field(
+        False,
+        description="Include SHAP feature importance analysis"
+    )
+
+    
+    @field_validator('features')
+    @classmethod
+    def validate_features(cls, v):
+        """Validate feature values are within reasonable bounds."""
+        if not all(isinstance(x, (int, float)) for x in v):
+            raise ValueError("All features must be numeric values")
+        return v
+
+
+
+class FeatureImportance(BaseModel):
+    """Single feature importance entry from SHAP analysis."""
+    feature_index: int
+    feature_name: str
+    importance_value: float
+    contribution: str  # "increases" or "decreases" malware probability
+
+
+
+class PredictionResponse(BaseModel):
+    """
+    Response model for malware prediction.
+    Contains prediction, probability, and optional SHAP analysis.
+    """
+    prediction: PredictionLabel
+    probability: float = Field(..., ge=0.0, le=1.0)
+    confidence: ConfidenceLevel
+    threshold_used: float
+    sha256: Optional[str] = None
+    top_features: Optional[List[FeatureImportance]] = None
+    inference_time_ms: float
+
+
+
+class GeminiExplanation(BaseModel):
+    """Gemini AI analysis response."""
+    risk_explanation: str
+    severity_level: SeverityLevel
+    key_indicators: List[str]
+    analyst_summary: str
+    mitigation_steps: Optional[List[str]] = None
+
+
+
+class MalwareTypeInfo(BaseModel):
+    """Malware type classification result."""
+    primary_type: str
+    confidence: str
+    secondary_types: List[str] = []
+    indicators: List[str] = []
+    source: str
+
+
+
+class PredictionWithExplanationResponse(BaseModel):
+    """
+    Combined response with XGBoost prediction and Gemini explanation.
+    """
+    prediction: PredictionResponse
+    explanation: GeminiExplanation
+    malware_type: Optional[MalwareTypeInfo] = None
+
+
+
+class CompareRequest(BaseModel):
+    """Request to compare XGBoost prediction with VirusTotal."""
+    features: List[float] = Field(
+        ...,
+        min_length=2381,
+        max_length=2381
+    )
+    sha256: str = Field(
+        ...,
+        pattern=r"^[a-fA-F0-9]{64}$",
+        description="SHA256 hash to check on VirusTotal"
+    )
+
+
+class ComparisonResult(BaseModel):
+    """Result of comparing XGBoost and VirusTotal verdicts."""
+    xgboost_prediction: PredictionLabel
+    xgboost_probability: float
+    virustotal_malicious_count: int
+    virustotal_total_engines: int
+    virustotal_detection_ratio: float
+    agreement: bool
+    agreement_description: str

backend/app/models/url.py

@@ -0,0 +1,68 @@
+"""
+Pydantic models for URL malware detection requests and responses.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional, Dict, List
+from enum import Enum
+
+
+class URLPredictionLabel(str, Enum):
+    """URL prediction labels."""
+    MALICIOUS = "Malicious"
+    BENIGN = "Benign"
+
+
+class URLConfidenceLevel(str, Enum):
+    """Confidence levels."""
+    HIGH = "High"
+    MEDIUM = "Medium"
+    LOW = "Low"
+
+
+class URLAnalyzeRequest(BaseModel):
+    """Request to analyze a URL for malicious indicators."""
+    url: str = Field(
+        ...,
+        description="URL to analyze",
+        min_length=3,
+        max_length=4096,
+    )
+    threshold: Optional[float] = Field(
+        None,
+        description="Custom prediction threshold (0.0-1.0)",
+        ge=0.0,
+        le=1.0,
+    )
+
+    @field_validator("url")
+    @classmethod
+    def validate_url(cls, v):
+        v = v.strip()
+        if not v:
+            raise ValueError("URL cannot be empty")
+        return v
+
+
+class URLAnalyzeResponse(BaseModel):
+    """Response from URL malware analysis."""
+    url: str
+    prediction: URLPredictionLabel
+    malicious_score: float = Field(..., ge=0.0, le=1.0)
+    confidence: str
+    confidence_level: URLConfidenceLevel
+    threshold_used: float
+    base_model_scores: Dict[str, float]
+    top_signals: Dict[str, float]
+    inference_time_ms: float
+
+
+class URLModelInfoResponse(BaseModel):
+    """Information about the URL model."""
+    model_type: str
+    base_models: List[str]
+    meta_learner: str
+    scaler_features: int
+    meta_features: int
+    dl_available: bool
+    feature_categories: List[str]

backend/app/models/virustotal.py

@@ -0,0 +1,72 @@
+"""
+Pydantic models for VirusTotal API responses.
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, List
+from datetime import datetime
+
+
+class EngineResult(BaseModel):
+    """Single antivirus engine scan result."""
+    engine_name: str
+    category: str  # "malicious", "undetected", "suspicious", etc.
+    result: Optional[str] = None  # Detection name if malicious
+    engine_version: Optional[str] = None
+    engine_update: Optional[str] = None
+
+
+class VirusTotalStats(BaseModel):
+    """Aggregated statistics from VirusTotal scan."""
+    malicious: int = 0
+    suspicious: int = 0
+    undetected: int = 0
+    harmless: int = 0
+    timeout: int = 0
+    confirmed_timeout: int = 0
+    failure: int = 0
+    type_unsupported: int = 0
+
+
+class MalwareTypeInfo(BaseModel):
+    """Malware type classification information."""
+    primary_type: str
+    confidence: str  # "High", "Medium", "Low"
+    secondary_types: List[str] = []
+    indicators: List[str] = []
+    source: str  # "heuristic", "virustotal", "combined"
+
+
+class VirusTotalRequest(BaseModel):
+    """Request model for VirusTotal hash lookup."""
+    sha256: str = Field(
+        ...,
+        pattern=r"^[a-fA-F0-9]{64}$",
+        description="SHA256 hash to look up"
+    )
+
+
+class VirusTotalResponse(BaseModel):
+    """
+    Response model for VirusTotal hash lookup.
+    Contains detection stats and engine results.
+    """
+    sha256: str
+    found: bool
+    stats: Optional[VirusTotalStats] = None
+    detection_ratio: Optional[float] = None
+    total_engines: Optional[int] = None
+    malicious_count: Optional[int] = None
+    reputation_score: Optional[int] = None
+    engine_results: Optional[List[EngineResult]] = None
+    first_submission_date: Optional[str] = None
+    last_analysis_date: Optional[str] = None
+    meaningful_name: Optional[str] = None
+    malware_type: Optional[MalwareTypeInfo] = None
+    error_message: Optional[str] = None
+
+
+class VirusTotalError(BaseModel):
+    """Error response from VirusTotal."""
+    error: str
+    code: Optional[str] = None

backend/app/routers/__init__.py

@@ -0,0 +1 @@
+# Routers package

backend/app/routers/chat.py

@@ -0,0 +1,179 @@
+"""
+Chat Router - Gemini-powered chatbot endpoint for the malware detection platform.
+"""
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+from typing import Optional, List
+import logging
+
+from ..services.gemini_service import get_gemini_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/chat", tags=["chat"])
+
+
+class ChatRequest(BaseModel):
+    """Chat request model."""
+
+    message: str = Field(..., description="User message", min_length=1, max_length=2000)
+    history: Optional[List[str]] = Field(default=[], description="Conversation history")
+
+
+class ChatResponse(BaseModel):
+    """Chat response model."""
+
+    response: str = Field(..., description="AI response")
+    success: bool = Field(default=True)
+
+
+def _fallback_chat_response(message: str) -> str:
+    """Return a local fallback answer when Gemini is unavailable."""
+    text = message.lower()
+
+    if any(
+        keyword in text
+        for keyword in [
+            "malware detection",
+            "how does malware",
+            "how it works",
+            "detect malware",
+        ]
+    ):
+        return (
+            "MalwareGuard analyzes Windows PE files by extracting EMBER features, "
+            "running an XGBoost malware classifier, and then showing confidence, "
+            "SHAP feature importance, and an optional malware-type interpretation."
+        )
+
+    if any(keyword in text for keyword in ["ember", "dataset", "features"]):
+        return (
+            "The platform uses the EMBER 2018 v2 feature format. Each sample is "
+            "represented by 2,381 static features derived from PE structure, imports, "
+            "exports, strings, headers, and byte-level statistics."
+        )
+
+    if any(
+        keyword in text for keyword in ["virustotal", "hash", "sha256", "md5", "sha1"]
+    ):
+        return (
+            "Use the VirusTotal lookup tab to submit a file hash such as SHA256, MD5, "
+            "or SHA1. MalwareGuard queries VirusTotal and returns detection ratio, engine "
+            "results, and malware-type hints when available."
+        )
+
+    if any(keyword in text for keyword in ["url", "link", "phishing"]):
+        return (
+            "The URL scanner extracts lexical and structural signals from a URL, runs the "
+            "URL model stack, and returns a malicious or benign verdict with top signals. "
+            "Users can also submit feedback to improve the model over time."
+        )
+
+    if any(
+        keyword in text for keyword in ["dashboard", "feedback", "reinforcement", "rl"]
+    ):
+        return (
+            "The dashboard summarizes malware and URL feedback, agreement rates, and model "
+            "update activity. Feedback is stored locally and can be used to trigger model updates."
+        )
+
+    return (
+        "Gemini is currently unavailable, so I am answering in fallback mode. "
+        "I can still help explain MalwareGuard features such as PE file analysis, URL scanning, "
+        "VirusTotal lookup, SHAP explanations, and the feedback dashboard."
+    )
+
+
+# System context for the chatbot
+CHATBOT_SYSTEM_PROMPT = """You are MalwareGuard AI, a helpful and knowledgeable assistant for a malware detection platform. Your role is to help users understand:
+
+1. **About the Platform**: MalwareGuard is an AI-powered malware detection platform that uses:
+   - XGBoost machine learning model trained on the EMBER 2018 v2 dataset
+   - SHAP (SHapley Additive exPlanations) for feature importance analysis
+   - Gemini AI for human-readable explanations
+   - VirusTotal API integration for cross-referencing with 70+ antivirus engines
+
+2. **How Malware Detection Works**:
+   - The platform analyzes PE (Portable Executable) file features
+   - Features include: byte histograms, PE header info, import/export tables, section characteristics, string analysis
+   - The ML model outputs a probability (0-1) indicating malware likelihood
+   - SHAP explains which features contributed most to the prediction
+
+3. **How to Use the Platform**:
+   - AI Prediction Tab: Input EMBER features (2381 float values) for malware analysis
+   - VirusTotal Tab: Look up file hashes (SHA256, MD5, SHA1) for antivirus scan results
+   - Results include confidence levels, explanations, and mitigation recommendations
+
+4. **The EMBER Dataset**:
+   - EMBER = Endgame Malware BEnchmark for Research
+   - Contains 2018 v2 features extracted from Windows PE files
+   - 2381 features per sample including: byte histograms (256), section info, imports, exports, etc.
+   - Training set: ~1 million samples (malware + benign)
+
+5. **Team Information**:
+   - This is a graduation project 2026 developed by a team of 5 members
+   - Hesham Ahmed Wageeh Elsayed — AI Engineer
+   - Ahmed Mohamed Ramadan — UI/UX Designer
+   - Kamal Khaled — AI Engineer
+   - Zeyad Waleed — Full Stack Developer
+   - Ali Hassan Ali — Full Stack Developer
+
+Guidelines:
+- Be helpful, professional, and accurate
+- Focus on cybersecurity and malware detection topics
+- If asked about something outside your expertise, politely redirect
+- Keep responses concise but informative
+- Use markdown formatting for readability when appropriate
+- Never reveal sensitive technical details about bypassing detection
+
+User message: {message}"""
+
+
+@router.post("/", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """
+    Send a message to the AI chatbot.
+
+    The chatbot can answer questions about:
+    - How the malware detection platform works
+    - EMBER dataset and features
+    - Using the prediction and VirusTotal features
+    - General cybersecurity questions
+    """
+    gemini_service = get_gemini_service()
+
+    if not gemini_service.initialized:
+        gemini_service.initialize()
+
+    if not gemini_service.initialized or gemini_service.model is None:
+        logger.warning("Gemini chatbot unavailable, using fallback response")
+        return ChatResponse(response=_fallback_chat_response(request.message))
+
+    try:
+        # Format the prompt with user message
+        prompt = CHATBOT_SYSTEM_PROMPT.format(message=request.message)
+
+        # Call Gemini API
+        response = gemini_service.model.generate_content(prompt)
+
+        if response.text:
+            return ChatResponse(response=response.text)
+        else:
+            logger.warning("Gemini returned an empty chatbot response, using fallback")
+            return ChatResponse(response=_fallback_chat_response(request.message))
+
+    except Exception as e:
+        logger.error(f"Chat error: {e}")
+        return ChatResponse(response=_fallback_chat_response(request.message))
+
+
+@router.get("/health")
+async def chat_health():
+    """Check if the chat service is healthy."""
+    gemini_service = get_gemini_service()
+
+    return {
+        "status": "healthy" if gemini_service.initialized else "unavailable",
+        "gemini_initialized": gemini_service.initialized,
+    }

backend/app/routers/feedback.py

@@ -0,0 +1,156 @@
+"""
+Reinforcement Learning Feedback Router
+
+Endpoints:
+  POST /api/feedback/malware       — Log malware RL reward (VT agreement)
+  POST /api/feedback/url           — Log URL RL reward (user confirmation)
+  GET  /api/feedback/stats         — Aggregated RL statistics
+  POST /api/feedback/update-model  — Trigger incremental model update
+  GET  /api/feedback/health        — Health check
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException
+
+from ..models.feedback import (
+    MalwareFeedbackRequest,
+    URLFeedbackRequest,
+    FeedbackResponse,
+    FeedbackStats,
+    ModelUpdateRequest,
+    ModelUpdateResponse,
+)
+from ..services.feedback_service import get_feedback_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/api/feedback",
+    tags=["Reinforcement Learning"],
+    responses={500: {"description": "Internal Server Error"}},
+)
+
+
+# ── Malware RL ────────────────────────────────────────────────────────────────
+
+@router.post("/malware", response_model=FeedbackResponse)
+async def submit_malware_feedback(body: MalwareFeedbackRequest):
+    """
+    Submit malware RL feedback based on VirusTotal comparison.
+
+    Reward:
+      +1 if XGBoost and VirusTotal agree (both malicious or both benign)
+      -1 if they disagree
+    """
+    try:
+        svc = get_feedback_service()
+        result = svc.log_malware_feedback(
+            features=body.features,
+            sha256=body.sha256,
+            predicted=body.predicted_label,
+            probability=body.predicted_probability,
+            vt_mal=body.vt_malicious_count,
+            vt_total=body.vt_total_engines,
+            vt_ratio=body.vt_detection_ratio,
+        )
+        # Auto-trigger incremental update when enough samples accumulate
+        svc.maybe_auto_update("malware")
+        return FeedbackResponse(**result)
+    except Exception as e:
+        logger.error(f"Malware feedback error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Feedback failed: {e}")
+
+
+# ── URL RL ────────────────────────────────────────────────────────────────────
+
+@router.post("/url", response_model=FeedbackResponse)
+async def submit_url_feedback(body: URLFeedbackRequest):
+    """
+    Submit URL RL feedback from user confirmation popup.
+
+    Reward:
+      +1 if user confirms prediction is correct
+      -1 if user says prediction is wrong
+    """
+    try:
+        svc = get_feedback_service()
+        result = svc.log_url_feedback(
+            url=body.url,
+            predicted=body.predicted_label,
+            malicious_score=body.malicious_score,
+            is_correct=body.is_correct,
+            base_model_scores=body.base_model_scores,
+        )
+        # Auto-trigger incremental update when enough samples accumulate
+        svc.maybe_auto_update("url")
+        return FeedbackResponse(**result)
+    except Exception as e:
+        logger.error(f"URL feedback error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Feedback failed: {e}")
+
+
+# ── Statistics ────────────────────────────────────────────────────────────────
+
+@router.get("/stats", response_model=FeedbackStats)
+async def get_feedback_stats():
+    """Get aggregated RL feedback statistics for both channels."""
+    try:
+        svc = get_feedback_service()
+        return FeedbackStats(**svc.get_stats())
+    except Exception as e:
+        logger.error(f"Stats error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ── Model Update ─────────────────────────────────────────────────────────────
+
+@router.post("/update-model", response_model=ModelUpdateResponse)
+async def update_model(body: ModelUpdateRequest):
+    """
+    Trigger incremental model update using accumulated feedback.
+
+    Uses XGBoost continuation training (xgb_model parameter) to add
+    additional boosting rounds from feedback samples without full re-training.
+    """
+    try:
+        svc = get_feedback_service()
+        if body.model_type == "malware":
+            result = svc.update_malware_model(
+                min_samples=body.min_samples,
+                lr=body.learning_rate,
+                rounds=body.num_boost_rounds,
+            )
+        elif body.model_type == "url":
+            result = svc.update_url_model(
+                min_samples=body.min_samples,
+                lr=body.learning_rate,
+                rounds=body.num_boost_rounds,
+            )
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail="model_type must be 'malware' or 'url'",
+            )
+        return ModelUpdateResponse(**result)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Model update error: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Model update failed: {e}")
+
+
+# ── Health ────────────────────────────────────────────────────────────────────
+
+@router.get("/health")
+async def feedback_health():
+    """Health check for the RL feedback service."""
+    try:
+        svc = get_feedback_service()
+        stats = svc.get_stats()
+        return {
+            "status": "healthy",
+            "malware_samples": stats["malware_total"],
+            "url_samples": stats["url_total"],
+        }
+    except Exception as e:
+        return {"status": "unhealthy", "error": str(e)}

backend/app/routers/predict.py

@@ -0,0 +1,205 @@
+"""
+Prediction API Router.
+Handles XGBoost malware prediction and Gemini explanation endpoints.
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from ..models.prediction import (
+    PredictionRequest,
+    PredictionResponse,
+    PredictionWithExplanationResponse,
+)
+from ..services.ml_service import get_ml_service, MLService
+from ..services.gemini_service import get_gemini_service, GeminiService
+from ..services.shap_service import get_shap_service, SHAPService
+from ..services.malware_type_service import get_malware_type_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/predict", tags=["prediction"])
+
+
+class MalwareTypeInfo(BaseModel):
+    """Malware type classification result."""
+    primary_type: str
+    confidence: str
+    secondary_types: list = []
+    indicators: list = []
+    source: str
+
+
+class PredictionWithTypeResponse(BaseModel):
+    """Prediction response with malware type."""
+    prediction: PredictionResponse
+    malware_type: Optional[MalwareTypeInfo] = None
+
+
+@router.post("", response_model=PredictionWithTypeResponse)
+async def predict(
+    request: PredictionRequest,
+    ml_service: MLService = Depends(get_ml_service)
+) -> PredictionWithTypeResponse:
+    """
+    Run XGBoost malware prediction on EMBER features.
+    
+    Accepts a feature vector of 2381 float values (EMBER 2018 v2 format)
+    and returns the prediction, probability, and confidence level.
+    
+    - **features**: List of 2381 float values (EMBER 2018 v2 features)
+    - **sha256**: Optional SHA256 hash for reference
+    - **threshold**: Optional custom prediction threshold (default: 0.5)
+    - **include_shap**: Include SHAP feature importance (slower)
+    """
+    try:
+        # Run prediction
+        prediction = ml_service.predict(
+            features=request.features,
+            threshold=request.threshold,
+            sha256=request.sha256
+        )
+        
+        # Add SHAP analysis if requested
+        if request.include_shap:
+            shap_service = get_shap_service()
+            if not shap_service.initialized:
+                shap_service.initialize(ml_service.model)
+            
+            top_features = shap_service.get_feature_importance(
+                features=request.features,
+                model=ml_service.model,
+                top_k=10
+            )
+            prediction.top_features = top_features
+        
+        # Classify malware type if suspicious/malicious
+        malware_type_info = None
+        if prediction.prediction == "Malicious" or prediction.probability > 0.3:
+            try:
+                malware_type_service = get_malware_type_service()
+                # Use heuristic classification based on features
+                type_result = malware_type_service.classify()
+                malware_type_info = MalwareTypeInfo(
+                    primary_type=type_result.primary_type,
+                    confidence=type_result.confidence,
+                    secondary_types=type_result.secondary_types,
+                    indicators=type_result.indicators,
+                    source=type_result.source
+                )
+            except Exception as e:
+                logger.warning(f"Malware type classification failed: {e}")
+        
+        return PredictionWithTypeResponse(
+            prediction=prediction,
+            malware_type=malware_type_info
+        )
+        
+    except ValueError as e:
+        logger.error(f"Validation error: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except RuntimeError as e:
+        logger.error(f"Runtime error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as e:
+        logger.error(f"Prediction error: {e}")
+        raise HTTPException(status_code=500, detail="Prediction failed")
+
+
+@router.post("/explain", response_model=PredictionWithExplanationResponse)
+async def predict_with_explanation(
+    request: PredictionRequest,
+    ml_service: MLService = Depends(get_ml_service),
+    gemini_service: GeminiService = Depends(get_gemini_service)
+) -> PredictionWithExplanationResponse:
+    """
+    Run XGBoost prediction with Gemini AI explanation.
+    
+    Combines the XGBoost prediction with a detailed analysis from
+    Gemini AI explaining why the sample was classified as malicious
+    or benign.
+    
+    **Note**: Gemini does NOT override the model prediction. It only
+    provides explanation and context.
+    """
+    try:
+        # Run prediction
+        prediction = ml_service.predict(
+            features=request.features,
+            threshold=request.threshold,
+            sha256=request.sha256
+        )
+        
+        # Get SHAP features for better explanation
+        shap_service = get_shap_service()
+        if not shap_service.initialized:
+            shap_service.initialize(ml_service.model)
+        
+        top_features = shap_service.get_feature_importance(
+            features=request.features,
+            model=ml_service.model,
+            top_k=10
+        )
+        prediction.top_features = top_features
+        
+        # Get Gemini explanation
+        explanation = await gemini_service.explain_prediction(
+            prediction=prediction,
+            features=top_features
+        )
+        
+        # Classify malware type if suspicious/malicious
+        malware_type_info = None
+        if prediction.prediction == "Malicious" or prediction.probability > 0.3:
+            try:
+                from ..services.malware_type_service import get_malware_type_service
+                from ..models.prediction import MalwareTypeInfo
+                malware_type_service = get_malware_type_service()
+                type_result = malware_type_service.classify()
+                malware_type_info = MalwareTypeInfo(
+                    primary_type=type_result.primary_type,
+                    confidence=type_result.confidence,
+                    secondary_types=type_result.secondary_types,
+                    indicators=type_result.indicators,
+                    source=type_result.source
+                )
+            except Exception as e:
+                logger.warning(f"Malware type classification failed: {e}")
+        
+        return PredictionWithExplanationResponse(
+            prediction=prediction,
+            explanation=explanation,
+            malware_type=malware_type_info
+        )
+        
+    except ValueError as e:
+        logger.error(f"Validation error: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except RuntimeError as e:
+        logger.error(f"Runtime error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as e:
+        logger.error(f"Prediction with explanation error: {e}")
+        raise HTTPException(status_code=500, detail="Prediction with explanation failed")
+
+
+@router.get("/model-info")
+async def get_model_info(
+    ml_service: MLService = Depends(get_ml_service)
+) -> dict:
+    """Get information about the loaded XGBoost model."""
+    return ml_service.get_model_info()
+
+
+@router.get("/health")
+async def health_check(
+    ml_service: MLService = Depends(get_ml_service)
+) -> dict:
+    """Health check endpoint for the prediction service."""
+    return {
+        "status": "healthy",
+        "model_loaded": ml_service.model_loaded,
+        "feature_count": ml_service.feature_count
+    }

backend/app/routers/upload.py

@@ -0,0 +1,284 @@
+"""
+File Upload Router - Handle PE file uploads for malware analysis.
+"""
+
+from fastapi import APIRouter, HTTPException, UploadFile, File, Depends
+from pydantic import BaseModel, Field
+from typing import Optional, List
+import logging
+import hashlib
+
+
+from ..services.ember_features import extract_features_from_bytes, extract_features_and_lief, LIEF_AVAILABLE
+from ..services.ml_service import get_ml_service
+from ..services.shap_service import get_shap_service
+from ..services.gemini_service import get_gemini_service
+from ..services.malware_type_service import get_malware_type_service, MalwareTypeResult
+from ..models.prediction import (
+    PredictionResponse,
+    ConfidenceLevel,
+    GeminiExplanation,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/api/upload",
+    tags=["upload"]
+)
+
+
+
+class MalwareTypeInfo(BaseModel):
+    """Malware type classification result."""
+    primary_type: str
+    confidence: str
+    secondary_types: List[str] = []
+    indicators: List[str] = []
+    source: str
+
+
+
+class FileAnalysisResponse(BaseModel):
+    """Response model for file analysis."""
+    filename: str
+    sha256: str
+    file_size: int
+    features_extracted: bool
+    feature_count: int
+    features: Optional[List[float]] = None  # Include features for copy functionality
+    prediction: Optional[PredictionResponse] = None
+    malware_type: Optional[MalwareTypeInfo] = None
+    explanation: Optional[GeminiExplanation] = None
+    error: Optional[str] = None
+
+
+
+class FeatureExtractionResponse(BaseModel):
+    """Response model for feature extraction only."""
+    filename: str
+    sha256: str
+    file_size: int
+    features: List[float]
+    feature_count: int
+
+
+
+@router.post("/analyze", response_model=FileAnalysisResponse)
+async def analyze_file(
+    file: UploadFile = File(..., description="PE file to analyze"),
+    include_explanation: bool = True
+):
+    """
+    Upload a PE file for complete malware analysis.
+    
+    This endpoint:
+    1. Extracts EMBER 2018 v2 features from the PE file
+    2. Runs XGBoost prediction
+    3. Optionally generates Gemini AI explanation
+
+    
+    **Supported files**: Windows PE executables (.exe, .dll, .sys, etc.)
+
+    
+    **Note**: Maximum file size is 50MB.
+    """
+    if not LIEF_AVAILABLE:
+        raise HTTPException(
+            status_code=503,
+            detail="PE parsing library (LIEF) is not available. Feature extraction disabled."
+        )
+    
+    # Read file content
+    try:
+        content = await file.read()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to read file: {str(e)}")
+    
+    if len(content) == 0:
+        raise HTTPException(status_code=400, detail="Empty file uploaded")
+    
+    if len(content) > 50 * 1024 * 1024:  # 50MB limit
+        raise HTTPException(status_code=400, detail="File too large. Maximum size is 50MB.")
+
+    
+    # Check for PE signature (MZ header)
+    if content[:2] != b'MZ':
+        raise HTTPException(
+            status_code=400, 
+            detail="Invalid PE file. File must be a Windows executable (PE format)."
+        )
+
+    
+    
+    filename = file.filename or "unknown"
+    file_size = len(content)
+    sha256 = hashlib.sha256(content).hexdigest()
+    
+    # Extract features and LIEF binary
+    lief_binary = None
+    try:
+        features, _, lief_binary = extract_features_and_lief(content)
+        features_list = features.tolist()
+        feature_count = len(features_list)
+        features_extracted = True
+    except Exception as e:
+        logger.error(f"Feature extraction failed for {filename}: {e}")
+        return FileAnalysisResponse(
+            filename=filename,
+            sha256=sha256,
+            file_size=file_size,
+            features_extracted=False,
+            feature_count=0,
+            error=f"Feature extraction failed: {str(e)}"
+        )
+
+    
+    # Run prediction
+    try:
+        ml_service = get_ml_service()
+        # ml_service.predict returns PredictionResponse directly
+        prediction_response = ml_service.predict(features_list, sha256=sha256)
+    except Exception as e:
+        logger.error(f"Prediction failed for {filename}: {e}")
+        return FileAnalysisResponse(
+            filename=filename,
+            sha256=sha256,
+            file_size=file_size,
+            features_extracted=True,
+            feature_count=feature_count,
+            error=f"Prediction failed: {str(e)}"
+        )
+
+
+    
+    # Classify malware type if prediction is malware
+    malware_type_info = None
+    if prediction_response.prediction == "Malware" or prediction_response.probability > 0.3:
+        try:
+            malware_type_service = get_malware_type_service()
+            if lief_binary:
+                type_result = malware_type_service.classify_from_lief(lief_binary)
+            else:
+                type_result = malware_type_service.classify()
+            
+            malware_type_info = MalwareTypeInfo(
+                primary_type=type_result.primary_type,
+                confidence=type_result.confidence,
+                secondary_types=type_result.secondary_types,
+                indicators=type_result.indicators,
+                source=type_result.source
+            )
+        except Exception as e:
+            logger.warning(f"Malware type classification failed: {e}")
+
+    
+    
+    # Generate explanation if requested
+    explanation = None
+    if include_explanation:
+        try:
+            # Get SHAP feature importance
+            shap_service = get_shap_service()
+            feature_importance = None
+            if shap_service.initialized:
+                feature_importance = shap_service.explain(features_list)
+            
+            # Generate Gemini explanation
+            gemini_service = get_gemini_service()
+            if gemini_service.initialized:
+                explanation = await gemini_service.explain_prediction(
+                    prediction_response,
+                    feature_importance
+                )
+        except Exception as e:
+            logger.warning(f"Explanation generation failed for {filename}: {e}")
+            # Continue without explanation
+
+    
+    
+    return FileAnalysisResponse(
+        filename=filename,
+        sha256=sha256,
+        file_size=file_size,
+        features_extracted=True,
+        feature_count=feature_count,
+        features=features_list,  # Include features for copy functionality
+        prediction=prediction_response,
+        malware_type=malware_type_info,
+        explanation=explanation
+    )
+
+
+
+@router.post("/extract-features", response_model=FeatureExtractionResponse)
+async def extract_features(
+    file: UploadFile = File(..., description="PE file to extract features from")
+):
+    """
+    Extract EMBER 2018 v2 features from a PE file without running prediction.
+    
+    Returns the 2381-dimensional feature vector that can be used
+    for custom analysis or stored for later prediction.
+    
+    **Supported files**: Windows PE executables (.exe, .dll, .sys, etc.)
+    """
+    if not LIEF_AVAILABLE:
+        raise HTTPException(
+            status_code=503,
+            detail="PE parsing library (LIEF) is not available. Feature extraction disabled."
+        )
+
+    
+    # Read file content
+    try:
+        content = await file.read()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to read file: {str(e)}")
+    
+    if len(content) == 0:
+        raise HTTPException(status_code=400, detail="Empty file uploaded")
+    
+    if len(content) > 50 * 1024 * 1024:  # 50MB limit
+        raise HTTPException(status_code=400, detail="File too large. Maximum size is 50MB.")
+    
+    # Check for PE signature
+    if content[:2] != b'MZ':
+        raise HTTPException(
+            status_code=400, 
+            detail="Invalid PE file. File must be a Windows executable (PE format)."
+        )
+    
+    filename = file.filename or "unknown"
+
+    
+    # Extract features
+    try:
+        features, sha256 = extract_features_from_bytes(content)
+        features_list = features.tolist()
+    except Exception as e:
+        logger.error(f"Feature extraction failed for {filename}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Feature extraction failed: {str(e)}"
+        )
+
+    
+    return FeatureExtractionResponse(
+        filename=filename,
+        sha256=sha256,
+        file_size=len(content),
+        features=features_list,
+        feature_count=len(features_list)
+    )
+
+
+
+@router.get("/health")
+async def upload_health():
+    """Check if the upload/feature extraction service is healthy."""
+    return {
+        "status": "healthy" if LIEF_AVAILABLE else "degraded",
+        "lief_available": LIEF_AVAILABLE,
+        "feature_extraction": "enabled" if LIEF_AVAILABLE else "disabled"
+    }

backend/app/routers/url.py

@@ -0,0 +1,89 @@
+"""
+URL Analysis Router — Malicious URL detection via stacking HyperModel.
+
+Endpoints:
+  POST /api/url/analyze    — Analyze a URL for malicious indicators
+  GET  /api/url/model-info — Get URL model information
+  GET  /api/url/health     — Health check
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException, Request
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from ..config import settings
+from ..models.url import URLAnalyzeRequest, URLAnalyzeResponse, URLModelInfoResponse
+from ..services.url_service import get_url_service
+
+logger = logging.getLogger(__name__)
+
+limiter = Limiter(key_func=get_remote_address)
+
+router = APIRouter(
+    prefix="/api/url",
+    tags=["URL Analysis"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@router.post("/analyze", response_model=URLAnalyzeResponse)
+async def analyze_url(request: Request, body: URLAnalyzeRequest):
+    """
+    Analyze a URL for malicious indicators using the stacking HyperModel.
+    
+    The HyperModel combines 5 base models:
+    - XGBoost & LightGBM on 54 lexical features
+    - TF-IDF + Logistic Regression on raw URL text
+    - CharCNN & CharBiLSTM deep learning on character-level URL encoding
+    
+    Their probability outputs are stacked and fed to an XGBoost meta-learner.
+    """
+    try:
+        url_service = get_url_service()
+        
+        if not url_service.model_loaded:
+            raise HTTPException(status_code=503, detail="URL model not loaded")
+        
+        threshold = body.threshold or settings.prediction_threshold
+        result = url_service.predict(body.url, threshold=threshold)
+        
+        logger.info(
+            f"URL analyzed: {body.url[:60]}... → {result['prediction']} "
+            f"(score={result['malicious_score']:.4f}, {result['inference_time_ms']:.1f}ms)"
+        )
+        
+        return URLAnalyzeResponse(**result)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"URL analysis failed: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
+
+
+@router.get("/model-info", response_model=URLModelInfoResponse)
+async def url_model_info():
+    """Get information about the URL detection model."""
+    try:
+        url_service = get_url_service()
+        return URLModelInfoResponse(**url_service.get_model_info())
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/health")
+async def url_health():
+    """Health check for URL analysis service."""
+    try:
+        url_service = get_url_service()
+        return {
+            "status": "healthy" if url_service.model_loaded else "unhealthy",
+            "model_loaded": url_service.model_loaded,
+            "dl_available": url_service._dl_available,
+        }
+    except Exception as e:
+        return {
+            "status": "unhealthy",
+            "error": str(e),
+        }

backend/app/routers/virustotal.py

@@ -0,0 +1,167 @@
+"""
+VirusTotal API Router.
+Handles hash lookup and comparison endpoints.
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException, Depends, Path
+from pydantic import BaseModel, Field
+from typing import List
+
+from ..models.virustotal import VirusTotalResponse
+from ..models.prediction import (
+    PredictionLabel,
+    CompareRequest,
+    ComparisonResult,
+)
+from ..services.virustotal_service import get_virustotal_service, VirusTotalService
+from ..services.ml_service import get_ml_service, MLService
+from ..services.feedback_service import get_feedback_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/virustotal", tags=["virustotal"])
+
+
+@router.get("/health")
+async def health_check(
+    vt_service: VirusTotalService = Depends(get_virustotal_service)
+) -> dict:
+    """Health check endpoint for VirusTotal service."""
+    return {
+        "status": "healthy",
+        "api_configured": vt_service.initialized
+    }
+
+
+@router.get("/{hash}", response_model=VirusTotalResponse)
+async def lookup_hash(
+    hash: str = Path(
+        ...,
+        description="SHA256, SHA1, or MD5 hash to look up",
+        min_length=32,
+        max_length=64
+    ),
+    vt_service: VirusTotalService = Depends(get_virustotal_service)
+) -> VirusTotalResponse:
+    """
+    Look up a file hash on VirusTotal.
+    
+    Returns detection results from multiple antivirus engines,
+    including detection ratio, engine verdicts, and reputation score.
+    
+    - **hash**: SHA256 (64 chars), SHA1 (40 chars), or MD5 (32 chars)
+    """
+    # Basic validation
+    if len(hash) not in [32, 40, 64]:
+        raise HTTPException(
+            status_code=400,
+            detail="Invalid hash length. Expected MD5 (32), SHA1 (40), or SHA256 (64)"
+        )
+    
+    if not all(c in '0123456789abcdefABCDEF' for c in hash):
+        raise HTTPException(
+            status_code=400,
+            detail="Invalid hash format. Only hexadecimal characters allowed."
+        )
+    
+    result = await vt_service.lookup_hash(hash.lower())
+    
+    if not result.found and result.error_message:
+        # Don't raise error for "not found" - just return the response
+        if "not found" not in result.error_message.lower():
+            logger.warning(f"VirusTotal lookup issue: {result.error_message}")
+    
+    return result
+
+
+@router.post("/compare", response_model=ComparisonResult)
+async def compare_predictions(
+    request: CompareRequest,
+    ml_service: MLService = Depends(get_ml_service),
+    vt_service: VirusTotalService = Depends(get_virustotal_service)
+) -> ComparisonResult:
+    """
+    Compare XGBoost prediction with VirusTotal results.
+    
+    Runs the XGBoost model on the provided features and queries
+    VirusTotal for the hash, then compares the verdicts.
+    
+    Returns an agreement indicator showing whether both systems
+    agree on whether the sample is malicious or benign.
+    """
+    try:
+        # Run XGBoost prediction
+        prediction = ml_service.predict(
+            features=request.features,
+            sha256=request.sha256
+        )
+        
+        # Query VirusTotal
+        vt_result = await vt_service.lookup_hash(request.sha256)
+        
+        if not vt_result.found:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Hash not found on VirusTotal: {vt_result.error_message or 'Unknown error'}"
+            )
+        
+        # Determine VirusTotal verdict
+        # Consider malicious if >10% of engines detect it
+        vt_is_malicious = (
+            vt_result.detection_ratio is not None and 
+            vt_result.detection_ratio > 0.1
+        )
+        xgb_is_malicious = prediction.prediction == PredictionLabel.MALICIOUS
+        
+        # Check agreement
+        agreement = vt_is_malicious == xgb_is_malicious
+        
+        if agreement:
+            if xgb_is_malicious:
+                agreement_desc = "Both XGBoost and VirusTotal flag this sample as malicious."
+            else:
+                agreement_desc = "Both XGBoost and VirusTotal consider this sample benign."
+        else:
+            if xgb_is_malicious:
+                agreement_desc = "XGBoost flags as malicious, but VirusTotal has low detection rate."
+            else:
+                agreement_desc = "VirusTotal flags as malicious, but XGBoost predicts benign."
+        
+        # ── Log RL feedback from the comparison ──────────────────────────
+        try:
+            feedback_svc = get_feedback_service()
+            rl_result = feedback_svc.log_malware_feedback(
+                features=request.features,
+                sha256=request.sha256,
+                predicted=prediction.prediction.value,
+                probability=prediction.probability,
+                vt_mal=vt_result.malicious_count or 0,
+                vt_total=vt_result.total_engines or 0,
+                vt_ratio=vt_result.detection_ratio or 0.0,
+            )
+            # Auto-trigger incremental update when enough samples accumulate
+            feedback_svc.maybe_auto_update("malware")
+            logger.info(f"Compare RL feedback: reward={rl_result['reward']}")
+        except Exception as e:
+            logger.warning(f"RL feedback during compare failed (non-critical): {e}")
+        
+        return ComparisonResult(
+            xgboost_prediction=prediction.prediction,
+            xgboost_probability=prediction.probability,
+            virustotal_malicious_count=vt_result.malicious_count or 0,
+            virustotal_total_engines=vt_result.total_engines or 0,
+            virustotal_detection_ratio=vt_result.detection_ratio or 0.0,
+            agreement=agreement,
+            agreement_description=agreement_desc
+        )
+        
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Comparison error: {e}")
+        raise HTTPException(status_code=500, detail="Comparison failed")
+
+

backend/app/services/__init__.py

@@ -0,0 +1,6 @@
+# Services package
+from .ml_service import MLService, get_ml_service
+from .gemini_service import GeminiService, get_gemini_service
+from .virustotal_service import VirusTotalService, get_virustotal_service
+from .shap_service import SHAPService, get_shap_service
+from .feedback_service import FeedbackService, get_feedback_service

backend/app/services/ember_features.py

@@ -0,0 +1,645 @@
+"""
+EMBER Feature Extraction Service
+Ported from elastic/ember for Python 3.12+ compatibility
+
+Extracts 2381 features from PE (Portable Executable) files for malware detection.
+Based on EMBER 2018 v2 feature format.
+
+Original source: https://github.com/elastic/ember
+"""
+
+import re
+import hashlib
+import logging
+import numpy as np
+from typing import Dict, List, Any, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Try to import lief - required for PE parsing
+try:
+    import lief
+    LIEF_AVAILABLE = True
+    LIEF_MAJOR, LIEF_MINOR, *_ = lief.__version__.split('.')
+    LIEF_MAJOR = int(LIEF_MAJOR)
+    LIEF_MINOR = int(LIEF_MINOR)
+    LIEF_EXPORT_OBJECT = LIEF_MAJOR > 0 or (LIEF_MAJOR == 0 and LIEF_MINOR >= 10)
+    LIEF_HAS_SIGNATURE = LIEF_MAJOR > 0 or (LIEF_MAJOR == 0 and LIEF_MINOR >= 11)
+    logger.info(f"LIEF version {lief.__version__} loaded successfully")
+except ImportError:
+    LIEF_AVAILABLE = False
+    LIEF_MAJOR = LIEF_MINOR = 0
+    LIEF_EXPORT_OBJECT = False
+    LIEF_HAS_SIGNATURE = False
+    logger.warning("LIEF library not available. PE feature extraction disabled.")
+
+# Try to import sklearn FeatureHasher
+try:
+    from sklearn.feature_extraction import FeatureHasher
+    SKLEARN_AVAILABLE = True
+except ImportError:
+    SKLEARN_AVAILABLE = False
+    logger.warning("sklearn not available. Feature hashing disabled.")
+
+
+class FeatureType:
+    """Base class for feature extractors."""
+    name = ''
+    dim = 0
+
+    def __repr__(self):
+        return f'{self.name}({self.dim})'
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Any:
+        """Generate JSON-able representation of the file."""
+        raise NotImplementedError
+
+    def process_raw_features(self, raw_obj: Any) -> np.ndarray:
+        """Generate a feature vector from raw features."""
+        raise NotImplementedError
+
+    def feature_vector(self, bytez: bytes, lief_binary) -> np.ndarray:
+        """Calculate feature vector directly from sample."""
+        return self.process_raw_features(self.raw_features(bytez, lief_binary))
+
+
+class ByteHistogram(FeatureType):
+    """Byte histogram (normalized) over the entire binary file."""
+    name = 'histogram'
+    dim = 256
+
+    def raw_features(self, bytez: bytes, lief_binary) -> List[int]:
+        counts = np.bincount(np.frombuffer(bytez, dtype=np.uint8), minlength=256)
+        return counts.tolist()
+
+    def process_raw_features(self, raw_obj: List[int]) -> np.ndarray:
+        counts = np.array(raw_obj, dtype=np.float32)
+        total = counts.sum()
+        if total > 0:
+            normalized = counts / total
+        else:
+            normalized = counts
+        return normalized
+
+
+class ByteEntropyHistogram(FeatureType):
+    """
+    2D byte/entropy histogram based on Saxe and Berlin, 2015.
+    Approximates the joint probability of byte value and local entropy.
+    """
+    name = 'byteentropy'
+    dim = 256
+
+    def __init__(self, step: int = 1024, window: int = 2048):
+        self.window = window
+        self.step = step
+
+    def _entropy_bin_counts(self, block: np.ndarray) -> Tuple[int, np.ndarray]:
+        """Calculate entropy bin and coarse histogram."""
+        # Coarse histogram, 16 bytes per bin
+        c = np.bincount(block >> 4, minlength=16)
+        p = c.astype(np.float32) / self.window
+        wh = np.where(c)[0]
+        
+        if len(wh) > 0:
+            H = np.sum(-p[wh] * np.log2(p[wh])) * 2
+        else:
+            H = 0.0
+        
+        Hbin = int(H * 2)  # Up to 16 bins (max entropy is 8 bits)
+        if Hbin == 16:
+            Hbin = 15
+        
+        return Hbin, c
+
+    def raw_features(self, bytez: bytes, lief_binary) -> List[int]:
+        output = np.zeros((16, 16), dtype=np.int64)
+        a = np.frombuffer(bytez, dtype=np.uint8)
+        
+        if a.shape[0] < self.window:
+            Hbin, c = self._entropy_bin_counts(a)
+            output[Hbin, :] += c
+        else:
+            # Strided trick for efficiency
+            shape = a.shape[:-1] + (a.shape[-1] - self.window + 1, self.window)
+            strides = a.strides + (a.strides[-1],)
+            blocks = np.lib.stride_tricks.as_strided(a, shape=shape, strides=strides)[::self.step, :]
+            
+            for block in blocks:
+                Hbin, c = self._entropy_bin_counts(block)
+                output[Hbin, :] += c
+        
+        return output.flatten().tolist()
+
+    def process_raw_features(self, raw_obj: List[int]) -> np.ndarray:
+        counts = np.array(raw_obj, dtype=np.float32)
+        total = counts.sum()
+        if total > 0:
+            normalized = counts / total
+        else:
+            normalized = counts
+        return normalized
+
+
+class StringExtractor(FeatureType):
+    """Extract string-based features from raw byte stream."""
+    name = 'strings'
+    dim = 104  # 1 + 1 + 1 + 96 + 1 + 1 + 1 + 1 + 1
+
+    def __init__(self):
+        # All consecutive runs of printable ASCII (0x20-0x7f) that are 5+ chars
+        self._allstrings = re.compile(b'[\x20-\x7f]{5,}')
+        # Occurrences of 'C:\'
+        self._paths = re.compile(b'c:\\\\', re.IGNORECASE)
+        # Occurrences of http:// or https://
+        self._urls = re.compile(b'https?://', re.IGNORECASE)
+        # Occurrences of HKEY_
+        self._registry = re.compile(b'HKEY_')
+        # Evidence of MZ header (dropper?)
+        self._mz = re.compile(b'MZ')
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Dict:
+        allstrings = self._allstrings.findall(bytez)
+        
+        if allstrings:
+            string_lengths = [len(s) for s in allstrings]
+            avlength = sum(string_lengths) / len(string_lengths)
+            
+            # Map printable characters 0x20-0x7f to int array 0-95
+            as_shifted_string = [b - ord(b'\x20') for b in b''.join(allstrings)]
+            c = np.bincount(as_shifted_string, minlength=96)
+            csum = c.sum()
+            p = c.astype(np.float32) / csum if csum > 0 else c.astype(np.float32)
+            wh = np.where(c)[0]
+            H = np.sum(-p[wh] * np.log2(p[wh])) if len(wh) > 0 else 0.0
+        else:
+            avlength = 0
+            c = np.zeros((96,), dtype=np.float32)
+            H = 0
+            csum = 0
+
+        return {
+            'numstrings': len(allstrings),
+            'avlength': avlength,
+            'printabledist': c.tolist(),
+            'printables': int(csum),
+            'entropy': float(H),
+            'paths': len(self._paths.findall(bytez)),
+            'urls': len(self._urls.findall(bytez)),
+            'registry': len(self._registry.findall(bytez)),
+            'MZ': len(self._mz.findall(bytez))
+        }
+
+    def process_raw_features(self, raw_obj: Dict) -> np.ndarray:
+        hist_divisor = float(raw_obj['printables']) if raw_obj['printables'] > 0 else 1.0
+        return np.hstack([
+            raw_obj['numstrings'],
+            raw_obj['avlength'],
+            raw_obj['printables'],
+            np.asarray(raw_obj['printabledist']) / hist_divisor,
+            raw_obj['entropy'],
+            raw_obj['paths'],
+            raw_obj['urls'],
+            raw_obj['registry'],
+            raw_obj['MZ']
+        ]).astype(np.float32)
+
+
+class GeneralFileInfo(FeatureType):
+    """General information about the PE file."""
+    name = 'general'
+    dim = 10
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Dict:
+        if lief_binary is None:
+            return {
+                'size': len(bytez),
+                'vsize': 0,
+                'has_debug': 0,
+                'exports': 0,
+                'imports': 0,
+                'has_relocations': 0,
+                'has_resources': 0,
+                'has_signature': 0,
+                'has_tls': 0,
+                'symbols': 0
+            }
+
+        return {
+            'size': len(bytez),
+            'vsize': lief_binary.virtual_size,
+            'has_debug': int(lief_binary.has_debug),
+            'exports': len(lief_binary.exported_functions),
+            'imports': len(lief_binary.imported_functions),
+            'has_relocations': int(lief_binary.has_relocations),
+            'has_resources': int(lief_binary.has_resources),
+            'has_signature': int(lief_binary.has_signatures) if LIEF_HAS_SIGNATURE else int(lief_binary.has_signature),
+            'has_tls': int(lief_binary.has_tls),
+            'symbols': len(lief_binary.symbols),
+        }
+
+    def process_raw_features(self, raw_obj: Dict) -> np.ndarray:
+        return np.asarray([
+            raw_obj['size'],
+            raw_obj['vsize'],
+            raw_obj['has_debug'],
+            raw_obj['exports'],
+            raw_obj['imports'],
+            raw_obj['has_relocations'],
+            raw_obj['has_resources'],
+            raw_obj['has_signature'],
+            raw_obj['has_tls'],
+            raw_obj['symbols']
+        ], dtype=np.float32)
+
+
+class HeaderFileInfo(FeatureType):
+    """Machine, architecture, OS, linker and other header information."""
+    name = 'header'
+    dim = 62
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Dict:
+        raw_obj = {
+            'coff': {'timestamp': 0, 'machine': "", 'characteristics': []},
+            'optional': {
+                'subsystem': "",
+                'dll_characteristics': [],
+                'magic': "",
+                'major_image_version': 0,
+                'minor_image_version': 0,
+                'major_linker_version': 0,
+                'minor_linker_version': 0,
+                'major_operating_system_version': 0,
+                'minor_operating_system_version': 0,
+                'major_subsystem_version': 0,
+                'minor_subsystem_version': 0,
+                'sizeof_code': 0,
+                'sizeof_headers': 0,
+                'sizeof_heap_commit': 0
+            }
+        }
+        
+        if lief_binary is None:
+            return raw_obj
+
+        raw_obj['coff']['timestamp'] = lief_binary.header.time_date_stamps
+        raw_obj['coff']['machine'] = str(lief_binary.header.machine).split('.')[-1]
+        raw_obj['coff']['characteristics'] = [
+            str(c).split('.')[-1] for c in lief_binary.header.characteristics_list
+        ]
+        
+        raw_obj['optional']['subsystem'] = str(lief_binary.optional_header.subsystem).split('.')[-1]
+        raw_obj['optional']['dll_characteristics'] = [
+            str(c).split('.')[-1] for c in lief_binary.optional_header.dll_characteristics_lists
+        ]
+        raw_obj['optional']['magic'] = str(lief_binary.optional_header.magic).split('.')[-1]
+        raw_obj['optional']['major_image_version'] = lief_binary.optional_header.major_image_version
+        raw_obj['optional']['minor_image_version'] = lief_binary.optional_header.minor_image_version
+        raw_obj['optional']['major_linker_version'] = lief_binary.optional_header.major_linker_version
+        raw_obj['optional']['minor_linker_version'] = lief_binary.optional_header.minor_linker_version
+        raw_obj['optional']['major_operating_system_version'] = lief_binary.optional_header.major_operating_system_version
+        raw_obj['optional']['minor_operating_system_version'] = lief_binary.optional_header.minor_operating_system_version
+        raw_obj['optional']['major_subsystem_version'] = lief_binary.optional_header.major_subsystem_version
+        raw_obj['optional']['minor_subsystem_version'] = lief_binary.optional_header.minor_subsystem_version
+        raw_obj['optional']['sizeof_code'] = lief_binary.optional_header.sizeof_code
+        raw_obj['optional']['sizeof_headers'] = lief_binary.optional_header.sizeof_headers
+        raw_obj['optional']['sizeof_heap_commit'] = lief_binary.optional_header.sizeof_heap_commit
+        
+        return raw_obj
+
+    def process_raw_features(self, raw_obj: Dict) -> np.ndarray:
+        return np.hstack([
+            raw_obj['coff']['timestamp'],
+            FeatureHasher(10, input_type="string").transform([[raw_obj['coff']['machine']]]).toarray()[0],
+            FeatureHasher(10, input_type="string").transform([raw_obj['coff']['characteristics']]).toarray()[0],
+            FeatureHasher(10, input_type="string").transform([[raw_obj['optional']['subsystem']]]).toarray()[0],
+            FeatureHasher(10, input_type="string").transform([raw_obj['optional']['dll_characteristics']]).toarray()[0],
+            FeatureHasher(10, input_type="string").transform([[raw_obj['optional']['magic']]]).toarray()[0],
+            raw_obj['optional']['major_image_version'],
+            raw_obj['optional']['minor_image_version'],
+            raw_obj['optional']['major_linker_version'],
+            raw_obj['optional']['minor_linker_version'],
+            raw_obj['optional']['major_operating_system_version'],
+            raw_obj['optional']['minor_operating_system_version'],
+            raw_obj['optional']['major_subsystem_version'],
+            raw_obj['optional']['minor_subsystem_version'],
+            raw_obj['optional']['sizeof_code'],
+            raw_obj['optional']['sizeof_headers'],
+            raw_obj['optional']['sizeof_heap_commit'],
+        ]).astype(np.float32)
+
+
+class SectionInfo(FeatureType):
+    """Information about section names, sizes and entropy."""
+    name = 'section'
+    dim = 255  # 5 + 50 + 50 + 50 + 50 + 50
+
+    @staticmethod
+    def _properties(s) -> List[str]:
+        return [str(c).split('.')[-1] for c in s.characteristics_lists]
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Dict:
+        if lief_binary is None:
+            return {"entry": "", "sections": []}
+
+        # Find entry section
+        try:
+            if LIEF_MAJOR > 0 or (LIEF_MAJOR == 0 and LIEF_MINOR >= 12):
+                section = lief_binary.section_from_rva(
+                    lief_binary.entrypoint - lief_binary.imagebase
+                )
+                if section is None:
+                    raise lief.not_found
+                entry_section = section.name
+            else:
+                entry_section = lief_binary.section_from_offset(lief_binary.entrypoint).name
+        except:
+            # Bad entry point, find first executable section
+            entry_section = ""
+            for s in lief_binary.sections:
+                if lief.PE.SECTION_CHARACTERISTICS.MEM_EXECUTE in s.characteristics_lists:
+                    entry_section = s.name
+                    break
+
+        raw_obj = {"entry": entry_section}
+        raw_obj["sections"] = [{
+            'name': s.name,
+            'size': s.size,
+            'entropy': s.entropy,
+            'vsize': s.virtual_size,
+            'props': self._properties(s)
+        } for s in lief_binary.sections]
+        
+        return raw_obj
+
+    def process_raw_features(self, raw_obj: Dict) -> np.ndarray:
+        sections = raw_obj['sections']
+        general = [
+            len(sections),
+            sum(1 for s in sections if s['size'] == 0),
+            sum(1 for s in sections if s['name'] == ""),
+            sum(1 for s in sections if 'MEM_READ' in s['props'] and 'MEM_EXECUTE' in s['props']),
+            sum(1 for s in sections if 'MEM_WRITE' in s['props'])
+        ]
+        
+        # Section characteristics hashed
+        section_sizes = [(s['name'], s['size']) for s in sections]
+        section_sizes_hashed = FeatureHasher(50, input_type="pair").transform([section_sizes]).toarray()[0]
+        
+        section_entropy = [(s['name'], s['entropy']) for s in sections]
+        section_entropy_hashed = FeatureHasher(50, input_type="pair").transform([section_entropy]).toarray()[0]
+        
+        section_vsize = [(s['name'], s['vsize']) for s in sections]
+        section_vsize_hashed = FeatureHasher(50, input_type="pair").transform([section_vsize]).toarray()[0]
+        
+        entry_name_hashed = FeatureHasher(50, input_type="string").transform([[raw_obj['entry']]]).toarray()[0]
+        
+        characteristics = [p for s in sections for p in s['props'] if s['name'] == raw_obj['entry']]
+        characteristics_hashed = FeatureHasher(50, input_type="string").transform([characteristics]).toarray()[0]
+
+        return np.hstack([
+            general,
+            section_sizes_hashed,
+            section_entropy_hashed,
+            section_vsize_hashed,
+            entry_name_hashed,
+            characteristics_hashed
+        ]).astype(np.float32)
+
+
+class ImportsInfo(FeatureType):
+    """Information about imported libraries and functions."""
+    name = 'imports'
+    dim = 1280
+
+    def raw_features(self, bytez: bytes, lief_binary) -> Dict[str, List[str]]:
+        imports = {}
+        if lief_binary is None:
+            return imports
+
+        for lib in lief_binary.imports:
+            if lib.name not in imports:
+                imports[lib.name] = []
+            
+            for entry in lib.entries:
+                if entry.is_ordinal:
+                    imports[lib.name].append("ordinal" + str(entry.ordinal))
+                else:
+                    imports[lib.name].append(entry.name[:10000])
+
+        return imports
+
+    def process_raw_features(self, raw_obj: Dict[str, List[str]]) -> np.ndarray:
+        # Unique libraries
+        libraries = list(set([l.lower() for l in raw_obj.keys()]))
+        libraries_hashed = FeatureHasher(256, input_type="string").transform([libraries]).toarray()[0]
+
+        # Fully qualified import names
+        imports = [lib.lower() + ':' + e for lib, elist in raw_obj.items() for e in elist]
+        imports_hashed = FeatureHasher(1024, input_type="string").transform([imports]).toarray()[0]
+
+        return np.hstack([libraries_hashed, imports_hashed]).astype(np.float32)
+
+
+class ExportsInfo(FeatureType):
+    """Information about exported functions."""
+    name = 'exports'
+    dim = 128
+
+    def raw_features(self, bytez: bytes, lief_binary) -> List[str]:
+        if lief_binary is None:
+            return []
+
+        if LIEF_EXPORT_OBJECT:
+            clipped_exports = [export.name[:10000] for export in lief_binary.exported_functions]
+        else:
+            clipped_exports = [export[:10000] for export in lief_binary.exported_functions]
+
+        return clipped_exports
+
+    def process_raw_features(self, raw_obj: List[str]) -> np.ndarray:
+        exports_hashed = FeatureHasher(128, input_type="string").transform([raw_obj]).toarray()[0]
+        return exports_hashed.astype(np.float32)
+
+
+class DataDirectories(FeatureType):
+    """Size and virtual address of the first 15 data directories."""
+    name = 'datadirectories'
+    dim = 30  # 15 * 2
+
+    def __init__(self):
+        self._name_order = [
+            "EXPORT_TABLE", "IMPORT_TABLE", "RESOURCE_TABLE", "EXCEPTION_TABLE",
+            "CERTIFICATE_TABLE", "BASE_RELOCATION_TABLE", "DEBUG", "ARCHITECTURE",
+            "GLOBAL_PTR", "TLS_TABLE", "LOAD_CONFIG_TABLE", "BOUND_IMPORT",
+            "IAT", "DELAY_IMPORT_DESCRIPTOR", "CLR_RUNTIME_HEADER"
+        ]
+
+    def raw_features(self, bytez: bytes, lief_binary) -> List[Dict]:
+        output = []
+        if lief_binary is None:
+            return output
+
+        for data_directory in lief_binary.data_directories:
+            output.append({
+                "name": str(data_directory.type).replace("DATA_DIRECTORY.", ""),
+                "size": data_directory.size,
+                "virtual_address": data_directory.rva
+            })
+        return output
+
+    def process_raw_features(self, raw_obj: List[Dict]) -> np.ndarray:
+        features = np.zeros(2 * len(self._name_order), dtype=np.float32)
+        for i in range(len(self._name_order)):
+            if i < len(raw_obj):
+                features[2 * i] = raw_obj[i]["size"]
+                features[2 * i + 1] = raw_obj[i]["virtual_address"]
+        return features
+
+
+class PEFeatureExtractor:
+    """
+    Extract 2381 features from a PE file (EMBER 2018 v2 format).
+    
+    Usage:
+        extractor = PEFeatureExtractor()
+        with open("sample.exe", "rb") as f:
+            features = extractor.feature_vector(f.read())
+        # features is now a numpy array of 2381 float values
+    """
+
+    def __init__(self, feature_version: int = 2):
+        if not LIEF_AVAILABLE:
+            raise ImportError("LIEF library is required for PE feature extraction. Install with: pip install lief")
+        
+        if not SKLEARN_AVAILABLE:
+            raise ImportError("scikit-learn is required for feature hashing. Install with: pip install scikit-learn")
+
+        self.features = [
+            ByteHistogram(),
+            ByteEntropyHistogram(),
+            StringExtractor(),
+            GeneralFileInfo(),
+            HeaderFileInfo(),
+            SectionInfo(),
+            ImportsInfo(),
+            ExportsInfo(),
+        ]
+        
+        if feature_version == 2:
+            self.features.append(DataDirectories())
+        
+        self.dim = sum([fe.dim for fe in self.features])
+        logger.info(f"PEFeatureExtractor initialized with {self.dim} features (version {feature_version})")
+
+    def raw_features(self, bytez: bytes) -> Dict[str, Any]:
+        """Extract raw features from PE bytes."""
+        lief_binary = None
+        
+        try:
+            lief_binary = lief.PE.parse(list(bytez))
+        except Exception as e:
+            logger.warning(f"LIEF parsing error: {e}")
+            lief_binary = None
+
+        features = {"sha256": hashlib.sha256(bytez).hexdigest()}
+        features.update({fe.name: fe.raw_features(bytez, lief_binary) for fe in self.features})
+        return features
+
+    def process_raw_features(self, raw_obj: Dict[str, Any]) -> np.ndarray:
+        """Process raw features into a feature vector."""
+        feature_vectors = [fe.process_raw_features(raw_obj[fe.name]) for fe in self.features]
+        return np.hstack(feature_vectors).astype(np.float32)
+
+    def feature_vector(self, bytez: bytes) -> np.ndarray:
+        """
+        Extract feature vector directly from PE file bytes.
+        
+        Args:
+            bytez: Raw bytes of the PE file
+            
+        Returns:
+            numpy array of 2381 float32 features
+        """
+        return self.process_raw_features(self.raw_features(bytez))
+    
+    def extract_with_hash(self, bytez: bytes) -> Tuple[np.ndarray, str]:
+        """
+        Extract features and return SHA256 hash.
+        
+        Args:
+            bytez: Raw bytes of the PE file
+            
+        Returns:
+            Tuple of (feature_vector, sha256_hash)
+        """
+        raw = self.raw_features(bytez)
+        return self.process_raw_features(raw), raw["sha256"]
+
+
+# Singleton instance
+_extractor_instance: Optional[PEFeatureExtractor] = None
+
+
+def get_feature_extractor() -> PEFeatureExtractor:
+    """Get or create the singleton feature extractor."""
+    global _extractor_instance
+    if _extractor_instance is None:
+        _extractor_instance = PEFeatureExtractor()
+    return _extractor_instance
+
+
+def extract_features_from_file(file_path: str) -> Tuple[np.ndarray, str]:
+    """
+    Extract EMBER features from a PE file.
+    
+    Args:
+        file_path: Path to the PE file
+        
+    Returns:
+        Tuple of (feature_vector, sha256_hash)
+    """
+    with open(file_path, 'rb') as f:
+        bytez = f.read()
+    
+    extractor = get_feature_extractor()
+    return extractor.extract_with_hash(bytez)
+
+
+def extract_features_from_bytes(bytez: bytes) -> Tuple[np.ndarray, str]:
+    """
+    Extract EMBER features from PE file bytes.
+    
+    Args:
+        bytez: Raw bytes of the PE file
+        
+    Returns:
+        Tuple of (feature_vector, sha256_hash)
+    """
+    extractor = get_feature_extractor()
+    return extractor.extract_with_hash(bytez)
+
+
+def extract_features_and_lief(bytez: bytes) -> Tuple[np.ndarray, str, any]:
+    """
+    Extract EMBER features and return LIEF binary for additional analysis.
+    
+    Args:
+        bytez: Raw bytes of the PE file
+        
+    Returns:
+        Tuple of (feature_vector, sha256_hash, lief_binary)
+    """
+    if not LIEF_AVAILABLE:
+        raise ImportError("LIEF is not available")
+    
+    extractor = get_feature_extractor()
+    features, sha256 = extractor.extract_with_hash(bytez)
+    
+    # Parse with LIEF for additional analysis
+    try:
+        lief_binary = lief.PE.parse(list(bytez))
+    except Exception:
+        lief_binary = None
+    
+    return features, sha256, lief_binary

backend/app/services/feedback_service.py

@@ -0,0 +1,474 @@
+"""
+Reinforcement Learning Feedback Service
+
+Persistent SQLite store for reward signals + incremental model updates.
+
+Malware channel:  XGBoost prediction vs VirusTotal consensus → auto-reward
+URL channel:      user confirms/denies model verdict        → manual reward
+
+Model updates use XGBoost's `xgb_model` parameter for incremental boosting
+from the existing model — no full re-training required.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import joblib
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# Database lives alongside backend code — not committed to git
+_DB_DIR = Path(__file__).parent.parent.parent.parent / "data"
+_DB_PATH = _DB_DIR / "feedback.db"
+
+
+class FeedbackService:
+    """SQLite-backed RL feedback store with incremental training."""
+
+    def __init__(self):
+        _DB_DIR.mkdir(parents=True, exist_ok=True)
+        self._conn: Optional[sqlite3.Connection] = None
+        self._init_db()
+
+    # ── Database setup ────────────────────────────────────────────────────
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(_DB_PATH), check_same_thread=False)
+            self._conn.row_factory = sqlite3.Row
+            self._conn.execute("PRAGMA journal_mode=WAL")
+        return self._conn
+    # Create the Feedback In Database
+    def _init_db(self):
+        conn = self._get_conn()
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS malware_feedback (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                sha256      TEXT    NOT NULL,
+                features    TEXT    NOT NULL,
+                predicted   TEXT    NOT NULL,
+                probability REAL    NOT NULL,
+                vt_ratio    REAL    NOT NULL,
+                vt_mal      INTEGER NOT NULL,
+                vt_total    INTEGER NOT NULL,
+                reward      INTEGER NOT NULL,
+                correct_label TEXT  NOT NULL,
+                created_at  TEXT    NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS url_feedback (
+                id               INTEGER PRIMARY KEY AUTOINCREMENT,
+                url              TEXT    NOT NULL,
+                predicted        TEXT    NOT NULL,
+                malicious_score  REAL    NOT NULL,
+                reward           INTEGER NOT NULL,
+                correct_label    TEXT    NOT NULL,
+                base_model_scores TEXT   NOT NULL,
+                created_at       TEXT    NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS model_updates (
+                id            INTEGER PRIMARY KEY AUTOINCREMENT,
+                model_type    TEXT    NOT NULL,
+                samples_used  INTEGER NOT NULL,
+                lr            REAL    NOT NULL,
+                rounds        INTEGER NOT NULL,
+                created_at    TEXT    NOT NULL
+            );
+        """)
+        conn.commit()
+        logger.info(f"Feedback DB ready at {_DB_PATH}")
+
+    # ── Malware feedback ──────────────────────────────────────────────────
+
+    def log_malware_feedback(
+        self,
+        features: list[float],
+        sha256: str,
+        predicted: str,
+        probability: float,
+        vt_mal: int,
+        vt_total: int,
+        vt_ratio: float,
+    ) -> dict:
+        """
+        Log malware prediction feedback based on VirusTotal agreement.
+
+        Reward logic:
+          VT considers malicious if detection_ratio > 0.1
+          +1  if XGBoost and VT agree
+          -1  if they disagree
+        """
+        vt_is_malicious = vt_ratio > 0.1
+        xgb_is_malicious = predicted.lower() == "malicious"
+        agree = vt_is_malicious == xgb_is_malicious
+        reward = 1 if agree else -1
+
+        # Correct label according to VT consensus
+        correct_label = "Malicious" if vt_is_malicious else "Benign"
+
+        now = datetime.now(timezone.utc).isoformat()
+        conn = self._get_conn()
+        conn.execute(
+            """INSERT INTO malware_feedback
+               (sha256, features, predicted, probability, vt_ratio, vt_mal, vt_total,
+                reward, correct_label, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                sha256,
+                json.dumps(features),
+                predicted,
+                probability,
+                vt_ratio,
+                vt_mal,
+                vt_total,
+                reward,
+                correct_label,
+                now,
+            ),
+        )
+        conn.commit()
+
+        total = conn.execute("SELECT COUNT(*) FROM malware_feedback").fetchone()[0]
+        logger.info(
+            f"Malware RL: sha256={sha256[:12]}… pred={predicted} vt_ratio={vt_ratio:.2f} "
+            f"reward={reward:+d} (total={total})"
+        )
+        return {
+            "success": True,
+            "reward": reward,
+            "message": f"{'Agreement' if agree else 'Disagreement'} with VirusTotal logged",
+            "total_feedback_count": total,
+        }
+
+    # ── URL feedback ──────────────────────────────────────────────────────
+
+    def log_url_feedback(
+        self,
+        url: str,
+        predicted: str,
+        malicious_score: float,
+        is_correct: bool,
+        base_model_scores: dict,
+    ) -> dict:
+        """
+        Log URL prediction feedback from user.
+
+        +1 if user says prediction is correct
+        -1 if user says prediction is wrong
+        """
+        reward = 1 if is_correct else -1
+
+        if is_correct:
+            correct_label = predicted
+        else:
+            correct_label = "Benign" if predicted == "Malicious" else "Malicious"
+
+        now = datetime.now(timezone.utc).isoformat()
+        conn = self._get_conn()
+        conn.execute(
+            """INSERT INTO url_feedback
+               (url, predicted, malicious_score, reward, correct_label,
+                base_model_scores, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (
+                url,
+                predicted,
+                malicious_score,
+                reward,
+                correct_label,
+                json.dumps(base_model_scores),
+                now,
+            ),
+        )
+        conn.commit()
+
+        total = conn.execute("SELECT COUNT(*) FROM url_feedback").fetchone()[0]
+        logger.info(
+            f"URL RL: url={url[:40]}… pred={predicted} correct={is_correct} "
+            f"reward={reward:+d} (total={total})"
+        )
+        return {
+            "success": True,
+            "reward": reward,
+            "message": f"Feedback recorded — {'correct' if is_correct else 'incorrect'} prediction",
+            "total_feedback_count": total,
+        }
+
+    # ── Statistics ────────────────────────────────────────────────────────
+
+    # Auto-update threshold: update model after this many NEW samples since last update
+    AUTO_UPDATE_THRESHOLD = 50
+
+    def maybe_auto_update(self, model_type: str) -> Optional[dict]:
+        """
+        Check if enough feedback has accumulated since the last
+        incremental update and trigger one automatically.
+
+        Returns update result dict or None if threshold not yet reached.
+        """
+        conn = self._get_conn()
+        table = "malware_feedback" if model_type == "malware" else "url_feedback"
+
+        total_feedback = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+
+        # How many samples were used in the most recent update?
+        row = conn.execute(
+            "SELECT samples_used FROM model_updates "
+            "WHERE model_type = ? ORDER BY id DESC LIMIT 1",
+            (model_type,),
+        ).fetchone()
+        last_samples = row["samples_used"] if row else 0
+
+        new_samples = total_feedback - last_samples
+        if new_samples >= self.AUTO_UPDATE_THRESHOLD:
+            logger.info(
+                f"Auto-update triggered for {model_type}: "
+                f"{new_samples} new samples ≥ {self.AUTO_UPDATE_THRESHOLD}"
+            )
+            try:
+                if model_type == "malware":
+                    return self.update_malware_model(min_samples=1)
+                else:
+                    return self.update_url_model(min_samples=1)
+            except Exception as e:
+                logger.error(f"Auto-update failed for {model_type}: {e}")
+                return None
+        return None
+
+    def get_stats(self) -> dict:
+        conn = self._get_conn()
+
+        # Malware stats
+        m_total = conn.execute("SELECT COUNT(*) FROM malware_feedback").fetchone()[0]
+        m_agree = conn.execute(
+            "SELECT COUNT(*) FROM malware_feedback WHERE reward = 1"
+        ).fetchone()[0]
+        m_disagree = m_total - m_agree
+        m_rate = (m_agree / m_total * 100) if m_total > 0 else 0.0
+
+        # URL stats
+        u_total = conn.execute("SELECT COUNT(*) FROM url_feedback").fetchone()[0]
+        u_correct = conn.execute(
+            "SELECT COUNT(*) FROM url_feedback WHERE reward = 1"
+        ).fetchone()[0]
+        u_incorrect = u_total - u_correct
+        u_rate = (u_correct / u_total * 100) if u_total > 0 else 0.0
+
+        # Recent malware feedback (last 10)
+        recent_m = [
+            dict(r)
+            for r in conn.execute(
+                "SELECT id, sha256, predicted, probability, vt_ratio, reward, created_at "
+                "FROM malware_feedback ORDER BY id DESC LIMIT 10"
+            ).fetchall()
+        ]
+
+        # Recent URL feedback (last 10)
+        recent_u = [
+            dict(r)
+            for r in conn.execute(
+                "SELECT id, url, predicted, malicious_score, reward, created_at "
+                "FROM url_feedback ORDER BY id DESC LIMIT 10"
+            ).fetchall()
+        ]
+
+        # Model updates
+        updates = [
+            dict(r)
+            for r in conn.execute(
+                "SELECT * FROM model_updates ORDER BY id DESC LIMIT 10"
+            ).fetchall()
+        ]
+
+        return {
+            "malware_total": m_total,
+            "malware_agree": m_agree,
+            "malware_disagree": m_disagree,
+            "malware_agreement_rate": round(m_rate, 1),
+            "url_total": u_total,
+            "url_correct": u_correct,
+            "url_incorrect": u_incorrect,
+            "url_accuracy_rate": round(u_rate, 1),
+            "recent_malware": recent_m,
+            "recent_url": recent_u,
+            "model_updates": updates,
+        }
+
+    # ── Incremental model updates ─────────────────────────────────────────
+
+    def update_malware_model(
+        self, min_samples: int = 10, lr: float = 0.01, rounds: int = 5
+    ) -> dict:
+        """
+        Incrementally update the malware XGBoost model with accumulated
+        feedback.  Uses `xgb_model` for continuation training.
+        """
+        import xgboost as xgb
+        from .ml_service import get_ml_service
+
+        conn = self._get_conn()
+        rows = conn.execute(
+            "SELECT features, correct_label FROM malware_feedback"
+        ).fetchall()
+
+        if len(rows) < min_samples:
+            return {
+                "success": False,
+                "model_type": "malware",
+                "samples_used": len(rows),
+                "message": f"Need ≥ {min_samples} samples, have {len(rows)}",
+            }
+
+        X = np.array([json.loads(r["features"]) for r in rows], dtype=np.float32)
+        y = np.array(
+            [1 if r["correct_label"] == "Malicious" else 0 for r in rows],
+            dtype=np.float32,
+        )
+
+        ml_service = get_ml_service()
+        booster = ml_service.model.get_booster()
+        dtrain = xgb.DMatrix(X, label=y)
+
+        params = {
+            "objective": "binary:logistic",
+            "eval_metric": "logloss",
+            "learning_rate": lr,
+            "max_depth": 3,
+        }
+
+        updated = xgb.train(
+            params, dtrain, num_boost_round=rounds, xgb_model=booster
+        )
+
+        # Patch sklearn model with updated booster
+        ml_service.model._Booster = updated
+
+        # Persist
+        model_path = (
+            Path(__file__).parent.parent.parent.parent / "xgb_malware_model.joblib"
+        )
+        joblib.dump(ml_service.model, model_path)
+
+        # Log update
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "INSERT INTO model_updates (model_type, samples_used, lr, rounds, created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            ("malware", len(rows), lr, rounds, now),
+        )
+        conn.commit()
+
+        logger.info(
+            f"Malware model updated: {len(rows)} samples, lr={lr}, rounds={rounds}"
+        )
+        return {
+            "success": True,
+            "model_type": "malware",
+            "samples_used": len(rows),
+            "message": f"Model updated with {len(rows)} feedback samples ({rounds} rounds, lr={lr})",
+        }
+
+    def update_url_model(
+        self, min_samples: int = 10, lr: float = 0.01, rounds: int = 5
+    ) -> dict:
+        """
+        Incrementally update the URL meta-learner with accumulated
+        user feedback.  Reconstructs 10 meta-features from stored
+        base model scores.
+        """
+        import xgboost as xgb
+        from .url_service import get_url_service
+
+        conn = self._get_conn()
+        rows = conn.execute(
+            "SELECT base_model_scores, correct_label FROM url_feedback"
+        ).fetchall()
+
+        if len(rows) < min_samples:
+            return {
+                "success": False,
+                "model_type": "url",
+                "samples_used": len(rows),
+                "message": f"Need ≥ {min_samples} samples, have {len(rows)}",
+            }
+
+        BASE_MODEL_ORDER = [
+            "XGBoost", "LightGBM", "TF-IDF + LR", "CharCNN", "CharBiLSTM"
+        ]
+
+        meta_features = []
+        labels = []
+        for r in rows:
+            scores = json.loads(r["base_model_scores"])
+            mf = []
+            for name in BASE_MODEL_ORDER:
+                mal = scores.get(name, 0.5)
+                mf.extend([1.0 - mal, mal])
+            meta_features.append(mf)
+            labels.append(1 if r["correct_label"] == "Malicious" else 0)
+
+        X = np.array(meta_features, dtype=np.float32)
+        y = np.array(labels, dtype=np.float32)
+
+        url_service = get_url_service()
+        booster = url_service.meta_learner.get_booster()
+        dtrain = xgb.DMatrix(X, label=y)
+
+        params = {
+            "objective": "binary:logistic",
+            "eval_metric": "logloss",
+            "learning_rate": lr,
+            "max_depth": 3,
+        }
+
+        updated = xgb.train(
+            params, dtrain, num_boost_round=rounds, xgb_model=booster
+        )
+
+        # Patch sklearn model
+        url_service.meta_learner._Booster = updated
+
+        # Persist
+        meta_path = url_service.models_dir / "hypermodel_meta.joblib"
+        joblib.dump(url_service.meta_learner, meta_path)
+
+        # Log update
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "INSERT INTO model_updates (model_type, samples_used, lr, rounds, created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            ("url", len(rows), lr, rounds, now),
+        )
+        conn.commit()
+
+        logger.info(
+            f"URL meta-learner updated: {len(rows)} samples, lr={lr}, rounds={rounds}"
+        )
+        return {
+            "success": True,
+            "model_type": "url",
+            "samples_used": len(rows),
+            "message": f"URL meta-learner updated with {len(rows)} feedback samples ({rounds} rounds, lr={lr})",
+        }
+
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+
+_feedback_service: Optional[FeedbackService] = None
+
+
+def get_feedback_service() -> FeedbackService:
+    """Get or create the singleton feedback service."""
+    global _feedback_service
+    if _feedback_service is None:
+        _feedback_service = FeedbackService()
+    return _feedback_service

backend/app/services/gemini_service.py

@@ -0,0 +1,263 @@
+"""
+Gemini AI Service for malware analysis explanations.
+Provides human-readable explanations of XGBoost predictions.
+"""
+
+import logging
+from typing import Optional, List
+import json
+
+from ..config import settings
+from ..models.prediction import (
+    PredictionResponse,
+    GeminiExplanation,
+    SeverityLevel,
+    FeatureImportance,
+)
+
+logger = logging.getLogger(__name__)
+
+
+PREFERRED_GEMINI_MODELS = [
+    "gemini-flash-lite-latest",
+    "gemini-2.0-flash-lite",
+    "gemini-2.0-flash-lite-001",
+    "gemini-flash-latest",
+    "gemini-2.0-flash",
+]
+
+
+# Gemini prompt template for malware analysis
+ANALYSIS_PROMPT_TEMPLATE = """You are an expert malware analyst assistant. Analyze the following malware detection results and provide a professional cybersecurity assessment.
+
+## Prediction Results
+- **Classification**: {prediction}
+- **Malware Probability**: {probability:.1%}
+- **Confidence Level**: {confidence}
+{sha256_section}
+
+## Top Contributing Features
+{features_section}
+
+## Instructions
+Based on the above prediction results, provide your analysis in the following JSON format:
+
+{{
+    "risk_explanation": "A 2-3 sentence explanation of why this sample was classified as {prediction}. Focus on the technical indicators from the features.",
+    "severity_level": "One of: Critical, High, Medium, Low, None",
+    "key_indicators": ["List of 3-5 key indicators identified from the features"],
+    "analyst_summary": "A professional 2-3 sentence summary suitable for a security analyst report.",
+    "mitigation_steps": ["If malicious, list 3-5 recommended mitigation steps. If benign, set to null."]
+}}
+
+Important:
+- DO NOT override the model's prediction. Your role is to explain, not reclassify.
+- Base your analysis on the provided features and probability.
+- Be specific about which feature categories contribute to the classification.
+- Use professional cybersecurity terminology.
+- If probability is high (>80%), emphasize the confidence. If low confidence, mention uncertainty.
+
+Respond ONLY with the JSON object, no additional text."""
+
+
+def _format_features_section(features: Optional[List[FeatureImportance]]) -> str:
+    """Format feature importance for the prompt."""
+    if not features:
+        return "No detailed feature analysis available."
+
+    lines = []
+    for f in features[:10]:  # Limit to top 10
+        lines.append(
+            f"- **{f.feature_name}**: {f.importance_value:.4f} ({f.contribution} malware probability)"
+        )
+
+    return "\n".join(lines)
+
+
+class GeminiService:
+    """
+    Gemini AI Service for generating malware analysis explanations.
+
+    This service:
+    - Takes XGBoost prediction results
+    - Sends them to Gemini for analysis
+    - Returns structured explanations
+    - Does NOT override the model's prediction
+    """
+
+    def __init__(self):
+        self.model = None
+        self.initialized = False
+        self._genai = None
+
+    def initialize(self) -> bool:
+        """
+        Initialize the Gemini AI client.
+
+        Returns:
+            True if initialization successful
+        """
+        if not settings.gemini_api_key:
+            logger.warning("Gemini API key not configured")
+            return False
+
+        try:
+            import google.generativeai as genai
+
+            self._genai = genai
+
+            genai.configure(api_key=settings.gemini_api_key)
+
+            self.model = None
+            for model_name in PREFERRED_GEMINI_MODELS:
+                try:
+                    self.model = genai.GenerativeModel(model_name)
+                    logger.info(
+                        "Gemini AI service initialized with model %s", model_name
+                    )
+                    break
+                except Exception as model_error:
+                    logger.warning(
+                        "Failed to prepare Gemini model %s: %s", model_name, model_error
+                    )
+
+            if self.model is None:
+                logger.error("No Gemini model could be initialized")
+                return False
+
+            self.initialized = True
+            return True
+
+        except ImportError:
+            logger.error("google-generativeai package not installed")
+            return False
+        except Exception as e:
+            logger.error(f"Failed to initialize Gemini: {e}")
+            return False
+
+    async def explain_prediction(
+        self,
+        prediction: PredictionResponse,
+        features: Optional[List[FeatureImportance]] = None,
+    ) -> GeminiExplanation:
+        """
+        Generate explanation for a malware prediction.
+
+        Args:
+            prediction: XGBoost prediction result
+            features: Optional list of top contributing features
+
+        Returns:
+            GeminiExplanation with analysis
+        """
+        if not self.initialized:
+            self.initialize()
+
+        if not self.initialized or self.model is None:
+            return self._get_fallback_explanation(prediction)
+
+        try:
+            # Build the prompt
+            sha256_section = ""
+            if prediction.sha256:
+                sha256_section = f"- **SHA256 Hash**: {prediction.sha256}"
+
+            features_section = _format_features_section(features)
+
+            prompt = ANALYSIS_PROMPT_TEMPLATE.format(
+                prediction=prediction.prediction.value,
+                probability=prediction.probability,
+                confidence=prediction.confidence.value,
+                sha256_section=sha256_section,
+                features_section=features_section,
+            )
+
+            # Call Gemini API
+            response = self.model.generate_content(prompt)
+
+            # Parse JSON response
+            response_text = response.text.strip()
+
+            # Clean up response if wrapped in code blocks
+            if response_text.startswith("```json"):
+                response_text = response_text[7:]
+            if response_text.startswith("```"):
+                response_text = response_text[3:]
+            if response_text.endswith("```"):
+                response_text = response_text[:-3]
+
+            analysis = json.loads(response_text.strip())
+
+            return GeminiExplanation(
+                risk_explanation=analysis.get(
+                    "risk_explanation", "Analysis unavailable"
+                ),
+                severity_level=SeverityLevel(analysis.get("severity_level", "Medium")),
+                key_indicators=analysis.get("key_indicators", []),
+                analyst_summary=analysis.get("analyst_summary", ""),
+                mitigation_steps=analysis.get("mitigation_steps"),
+            )
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse Gemini response: {e}")
+            return self._get_fallback_explanation(prediction)
+        except Exception as e:
+            logger.error(f"Gemini API error: {e}")
+            return self._get_fallback_explanation(prediction)
+
+    def _get_fallback_explanation(
+        self, prediction: PredictionResponse
+    ) -> GeminiExplanation:
+        """Generate a basic explanation when Gemini is unavailable."""
+        is_malicious = prediction.prediction.value == "Malicious"
+
+        if is_malicious:
+            severity = (
+                SeverityLevel.HIGH
+                if prediction.probability > 0.8
+                else SeverityLevel.MEDIUM
+            )
+            return GeminiExplanation(
+                risk_explanation=f"The XGBoost model classified this sample as malicious with {prediction.probability:.1%} probability. This indicates the presence of suspicious patterns commonly found in malware.",
+                severity_level=severity,
+                key_indicators=[
+                    "Sample matches malware patterns in trained dataset",
+                    f"Prediction confidence: {prediction.confidence.value}",
+                    f"Probability score: {prediction.probability:.1%}",
+                ],
+                analyst_summary=f"Automated analysis flagged this sample as potentially malicious. Manual review recommended.",
+                mitigation_steps=[
+                    "Quarantine the file immediately",
+                    "Do not execute or open the file",
+                    "Scan with multiple antivirus engines",
+                    "Check VirusTotal for additional context",
+                    "Report to security team if in enterprise environment",
+                ],
+            )
+        else:
+            return GeminiExplanation(
+                risk_explanation=f"The XGBoost model classified this sample as benign with {1 - prediction.probability:.1%} confidence. The feature patterns do not match known malware signatures.",
+                severity_level=SeverityLevel.NONE,
+                key_indicators=[
+                    "Sample does not match malware patterns",
+                    f"Benign probability: {1 - prediction.probability:.1%}",
+                    f"Prediction confidence: {prediction.confidence.value}",
+                ],
+                analyst_summary="Automated analysis did not detect malicious patterns. Sample appears to be benign based on static analysis.",
+                mitigation_steps=None,
+            )
+
+
+# Global service instance
+_gemini_service: Optional[GeminiService] = None
+
+
+def get_gemini_service() -> GeminiService:
+    """Get the global Gemini service instance."""
+    global _gemini_service
+
+    if _gemini_service is None:
+        _gemini_service = GeminiService()
+        _gemini_service.initialize()
+
+    return _gemini_service

backend/app/services/malware_type_service.py

@@ -0,0 +1,403 @@
+"""
+Malware Type Classification Service
+
+Combines heuristic analysis of PE features with VirusTotal labels
+to determine the likely type/family of detected malware.
+"""
+
+import logging
+import re
+from typing import Optional, Dict, List, Tuple
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class MalwareType(str, Enum):
+    """Common malware types/categories."""
+    RANSOMWARE = "Ransomware"
+    TROJAN = "Trojan"
+    WORM = "Worm"
+    SPYWARE = "Spyware"
+    ADWARE = "Adware"
+    BACKDOOR = "Backdoor"
+    ROOTKIT = "Rootkit"
+    KEYLOGGER = "Keylogger"
+    BANKER = "Banking Trojan"
+    DROPPER = "Dropper"
+    DOWNLOADER = "Downloader"
+    RAT = "Remote Access Trojan"
+    CRYPTOMINER = "Cryptominer"
+    BOTNET = "Botnet"
+    PUP = "Potentially Unwanted Program"
+    GENERIC = "Generic Malware"
+    UNKNOWN = "Unknown"
+
+
+@dataclass
+class MalwareTypeResult:
+    """Result of malware type classification."""
+    primary_type: str
+    confidence: str  # High, Medium, Low
+    secondary_types: List[str]
+    indicators: List[str]
+    source: str  # "heuristic", "virustotal", "combined"
+
+
+# Suspicious import patterns for different malware types
+MALWARE_IMPORT_SIGNATURES = {
+    MalwareType.RANSOMWARE: [
+        "CryptEncrypt", "CryptDecrypt", "CryptGenKey", "CryptAcquireContext",
+        "CryptImportKey", "CryptDestroyKey", "BCryptEncrypt", "BCryptDecrypt",
+        "FindFirstFile", "FindNextFile", "MoveFileEx", "DeleteFile",
+        "GetLogicalDriveStrings", "GetDriveType"
+    ],
+    MalwareType.KEYLOGGER: [
+        "GetAsyncKeyState", "GetKeyState", "GetKeyboardState", "SetWindowsHookEx",
+        "CallNextHookEx", "GetForegroundWindow", "GetWindowText", "AttachThreadInput"
+    ],
+    MalwareType.SPYWARE: [
+        "GetClipboardData", "OpenClipboard", "CreateToolhelp32Snapshot",
+        "Process32First", "Process32Next", "RegOpenKeyEx", "RegQueryValueEx",
+        "GetUserName", "GetComputerName", "SHGetFolderPath"
+    ],
+    MalwareType.BACKDOOR: [
+        "socket", "connect", "send", "recv", "bind", "listen", "accept",
+        "WSAStartup", "WSASocket", "CreateProcess", "ShellExecute",
+        "WinExec", "CreateRemoteThread"
+    ],
+    MalwareType.RAT: [
+        "CreateDesktop", "SwitchDesktop", "GetDesktopWindow", "keybd_event",
+        "mouse_event", "SendInput", "GetDC", "BitBlt", "CreateCompatibleBitmap",
+        "StartServiceCtrlDispatcher", "RegisterServiceCtrlHandler"
+    ],
+    MalwareType.ROOTKIT: [
+        "NtQuerySystemInformation", "ZwQuerySystemInformation",
+        "NtOpenProcess", "ZwOpenProcess", "NtWriteVirtualMemory",
+        "IoCreateDriver", "ObRegisterCallbacks", "PsSetCreateProcessNotifyRoutine"
+    ],
+    MalwareType.DROPPER: [
+        "URLDownloadToFile", "InternetOpen", "InternetOpenUrl", "InternetReadFile",
+        "CreateFile", "WriteFile", "CreateProcess", "WinExec",
+        "VirtualAlloc", "VirtualProtect"
+    ],
+    MalwareType.DOWNLOADER: [
+        "URLDownloadToFile", "URLDownloadToCacheFile", "InternetOpen",
+        "InternetConnect", "HttpOpenRequest", "HttpSendRequest",
+        "WinHttpOpen", "WinHttpConnect", "WinHttpOpenRequest"
+    ],
+    MalwareType.CRYPTOMINER: [
+        "CreateThread", "GetSystemInfo", "GetCurrentProcess", "SetPriorityClass",
+        "SetThreadPriority", "GetTickCount", "QueryPerformanceCounter"
+    ],
+    MalwareType.WORM: [
+        "NetShareEnum", "NetUserEnum", "WNetOpenEnum", "WNetEnumResource",
+        "FindFirstFile", "FindNextFile", "CopyFile", "GetDriveType",
+        "GetLogicalDriveStrings"
+    ],
+    MalwareType.BANKER: [
+        "InternetQueryOption", "HttpQueryInfo", "InternetSetOption",
+        "CertOpenStore", "CertFindCertificateInStore", "PFXImportCertStore",
+        "SetWindowsHookEx", "GetWindowText", "FindWindow"
+    ],
+}
+
+# String patterns commonly found in malware
+MALWARE_STRING_PATTERNS = {
+    MalwareType.RANSOMWARE: [
+        r"bitcoin", r"btc", r"wallet", r"ransom", r"decrypt", r"encrypt",
+        r"\.locked", r"\.encrypted", r"your files", r"pay.*\$", r"tor.*onion"
+    ],
+    MalwareType.CRYPTOMINER: [
+        r"stratum\+tcp", r"xmrig", r"monero", r"hashrate", r"pool\.",
+        r"mining", r"nicehash", r"coinhive"
+    ],
+    MalwareType.BOTNET: [
+        r"c2", r"command.*control", r"bot.*net", r"ddos", r"flood",
+        r"irc\.", r"mirai", r"tsunami"
+    ],
+    MalwareType.RAT: [
+        r"remote.*access", r"rat", r"njrat", r"darkcomet", r"quasar",
+        r"asyncrat", r"reverse.*shell"
+    ],
+}
+
+# Section characteristics indicating malware types
+SECTION_INDICATORS = {
+    "high_entropy": (7.5, MalwareType.RANSOMWARE),  # Encrypted/packed content
+    "upx": MalwareType.DROPPER,  # UPX packed often used by droppers
+    "executable_data": MalwareType.BACKDOOR,  # Data sections with execute permission
+}
+
+
+class MalwareTypeService:
+    """
+    Service for classifying malware into specific types/families.
+    
+    Uses a combination of:
+    1. Import table analysis
+    2. String pattern matching
+    3. PE section characteristics
+    4. VirusTotal vendor labels (if available)
+    """
+    
+    def __init__(self):
+        self.initialized = True
+        logger.info("Malware Type Service initialized")
+    
+    def classify(
+        self,
+        imports: List[str] = None,
+        strings: List[str] = None,
+        sections: List[Dict] = None,
+        entropy: float = None,
+        vt_labels: List[str] = None
+    ) -> MalwareTypeResult:
+        """
+        Classify malware based on available indicators.
+        
+        Args:
+            imports: List of imported function names
+            strings: List of strings extracted from the file
+            sections: List of PE section info dicts
+            entropy: Overall file entropy
+            vt_labels: Labels from VirusTotal vendors
+            
+        Returns:
+            MalwareTypeResult with classification
+        """
+        type_scores: Dict[MalwareType, float] = {t: 0.0 for t in MalwareType}
+        indicators: List[str] = []
+        
+        # 1. Analyze imports
+        if imports:
+            import_results = self._analyze_imports(imports)
+            for mtype, score, indicator in import_results:
+                type_scores[mtype] += score
+                if indicator:
+                    indicators.append(indicator)
+        
+        # 2. Analyze strings
+        if strings:
+            string_results = self._analyze_strings(strings)
+            for mtype, score, indicator in string_results:
+                type_scores[mtype] += score
+                if indicator:
+                    indicators.append(indicator)
+        
+        # 3. Analyze entropy
+        if entropy and entropy > 7.5:
+            type_scores[MalwareType.RANSOMWARE] += 2.0
+            type_scores[MalwareType.DROPPER] += 1.5
+            indicators.append(f"High entropy ({entropy:.2f}) suggests encryption/packing")
+        
+        # 4. Analyze sections
+        if sections:
+            section_results = self._analyze_sections(sections)
+            for mtype, score, indicator in section_results:
+                type_scores[mtype] += score
+                if indicator:
+                    indicators.append(indicator)
+        
+        # 5. Use VirusTotal labels if available
+        vt_type = None
+        if vt_labels:
+            vt_type = self._parse_vt_labels(vt_labels)
+            if vt_type and vt_type != MalwareType.UNKNOWN:
+                type_scores[vt_type] += 5.0  # VT labels are authoritative
+                indicators.append(f"VirusTotal classification: {vt_type.value}")
+        
+        # Determine primary type
+        sorted_types = sorted(type_scores.items(), key=lambda x: x[1], reverse=True)
+        primary_type = sorted_types[0][0]
+        primary_score = sorted_types[0][1]
+        
+        # If no strong signals, mark as generic
+        if primary_score < 1.0:
+            primary_type = MalwareType.GENERIC
+            confidence = "Low"
+        elif primary_score < 3.0:
+            confidence = "Medium"
+        else:
+            confidence = "High"
+        
+        # Get secondary types (score > 1.0 and not primary)
+        secondary_types = [
+            t.value for t, score in sorted_types[1:4]
+            if score >= 1.0 and t != primary_type
+        ]
+        
+        # Determine source
+        if vt_type and vt_type == primary_type:
+            source = "virustotal"
+        elif vt_labels and indicators:
+            source = "combined"
+        else:
+            source = "heuristic"
+        
+        return MalwareTypeResult(
+            primary_type=primary_type.value,
+            confidence=confidence,
+            secondary_types=secondary_types,
+            indicators=indicators[:5],  # Limit to top 5 indicators
+            source=source
+        )
+    
+    def _analyze_imports(self, imports: List[str]) -> List[Tuple[MalwareType, float, str]]:
+        """Analyze imported functions for malware indicators."""
+        results = []
+        imports_lower = [i.lower() for i in imports]
+        
+        for mtype, signatures in MALWARE_IMPORT_SIGNATURES.items():
+            matches = []
+            for sig in signatures:
+                if sig.lower() in imports_lower or any(sig.lower() in imp for imp in imports_lower):
+                    matches.append(sig)
+            
+            if matches:
+                score = min(len(matches) * 0.5, 3.0)  # Cap at 3.0
+                indicator = f"Suspicious imports for {mtype.value}: {', '.join(matches[:3])}"
+                results.append((mtype, score, indicator))
+        
+        return results
+    
+    def _analyze_strings(self, strings: List[str]) -> List[Tuple[MalwareType, float, str]]:
+        """Analyze strings for malware indicators."""
+        results = []
+        strings_combined = " ".join(strings).lower()
+        
+        for mtype, patterns in MALWARE_STRING_PATTERNS.items():
+            matches = []
+            for pattern in patterns:
+                if re.search(pattern, strings_combined, re.IGNORECASE):
+                    matches.append(pattern)
+            
+            if matches:
+                score = min(len(matches) * 0.7, 3.0)
+                indicator = f"String patterns suggest {mtype.value}"
+                results.append((mtype, score, indicator))
+        
+        return results
+    
+    def _analyze_sections(self, sections: List[Dict]) -> List[Tuple[MalwareType, float, str]]:
+        """Analyze PE sections for malware indicators."""
+        results = []
+        
+        for section in sections:
+            name = section.get("name", "").lower()
+            entropy = section.get("entropy", 0)
+            characteristics = section.get("characteristics", 0)
+            
+            # Check for UPX packing
+            if "upx" in name:
+                results.append((MalwareType.DROPPER, 1.5, "UPX packed section detected"))
+            
+            # Check for high entropy sections
+            if entropy > 7.5:
+                results.append((
+                    MalwareType.RANSOMWARE, 1.0,
+                    f"High entropy section '{name}' ({entropy:.2f})"
+                ))
+            
+            # Check for executable data sections
+            if characteristics:
+                is_executable = characteristics & 0x20000000  # IMAGE_SCN_MEM_EXECUTE
+                is_writable = characteristics & 0x80000000  # IMAGE_SCN_MEM_WRITE
+                if is_executable and is_writable and "text" not in name:
+                    results.append((
+                        MalwareType.BACKDOOR, 1.5,
+                        f"Suspicious RWX section '{name}'"
+                    ))
+        
+        return results
+    
+    def _parse_vt_labels(self, labels: List[str]) -> Optional[MalwareType]:
+        """Parse VirusTotal vendor labels to determine malware type."""
+        labels_combined = " ".join(labels).lower()
+        
+        # Priority order for type detection
+        type_keywords = [
+            (MalwareType.RANSOMWARE, ["ransom", "crypt", "locker", "wannacry", "locky", "cerber"]),
+            (MalwareType.RAT, ["rat", "remoteaccess", "njrat", "darkcomet", "quasar", "asyncrat"]),
+            (MalwareType.BANKER, ["banker", "banking", "zeus", "emotet", "trickbot", "dridex"]),
+            (MalwareType.BACKDOOR, ["backdoor", "back door", "reverseshell"]),
+            (MalwareType.ROOTKIT, ["rootkit", "bootkit"]),
+            (MalwareType.KEYLOGGER, ["keylog", "keylogger"]),
+            (MalwareType.CRYPTOMINER, ["miner", "coinminer", "cryptominer", "xmrig"]),
+            (MalwareType.WORM, ["worm", "conficker", "mydoom"]),
+            (MalwareType.SPYWARE, ["spyware", "spy", "infostealer", "stealer"]),
+            (MalwareType.ADWARE, ["adware", "pup", "unwanted"]),
+            (MalwareType.DROPPER, ["dropper", "downloader"]),
+            (MalwareType.TROJAN, ["trojan", "troj", "agent"]),
+        ]
+        
+        for mtype, keywords in type_keywords:
+            for keyword in keywords:
+                if keyword in labels_combined:
+                    return mtype
+        
+        return MalwareType.UNKNOWN
+    
+    def classify_from_lief(self, lief_binary) -> MalwareTypeResult:
+        """
+        Classify malware type directly from a LIEF parsed binary.
+        
+        Args:
+            lief_binary: LIEF PE binary object
+            
+        Returns:
+            MalwareTypeResult
+        """
+        imports = []
+        sections = []
+        
+        try:
+            # Extract imports
+            if hasattr(lief_binary, 'imports'):
+                for lib in lief_binary.imports:
+                    for entry in lib.entries:
+                        if entry.name:
+                            imports.append(entry.name)
+            
+            # Extract section info
+            if hasattr(lief_binary, 'sections'):
+                for section in lief_binary.sections:
+                    sections.append({
+                        "name": section.name,
+                        "entropy": section.entropy,
+                        "characteristics": section.characteristics
+                    })
+            
+            # Calculate overall entropy
+            entropy = None
+            if sections:
+                entropy = sum(s.get("entropy", 0) for s in sections) / len(sections)
+            
+            return self.classify(
+                imports=imports,
+                sections=sections,
+                entropy=entropy
+            )
+            
+        except Exception as e:
+            logger.error(f"Error classifying from LIEF: {e}")
+            return MalwareTypeResult(
+                primary_type=MalwareType.UNKNOWN.value,
+                confidence="Low",
+                secondary_types=[],
+                indicators=["Error during classification"],
+                source="heuristic"
+            )
+
+
+# Singleton instance
+_malware_type_service: Optional[MalwareTypeService] = None
+
+
+def get_malware_type_service() -> MalwareTypeService:
+    """Get or create the malware type service singleton."""
+    global _malware_type_service
+    if _malware_type_service is None:
+        _malware_type_service = MalwareTypeService()
+    return _malware_type_service

backend/app/services/ml_service.py

@@ -0,0 +1,198 @@
+"""
+Machine Learning Service for XGBoost Malware Detection.
+Handles model loading, inference, and prediction formatting.
+Optimized for fast inference with single model load.
+"""
+
+import time
+import logging
+from pathlib import Path
+from typing import Optional, Tuple
+import numpy as np
+import joblib
+
+from ..config import settings
+from ..models.prediction import (
+    PredictionLabel,
+    ConfidenceLevel,
+    PredictionResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MLService:
+    """
+    XGBoost ML Service for malware detection.
+    
+    Features:
+    - Single model load at startup (no reload per request)
+    - NumPy vectorization for fast inference
+    - Configurable prediction threshold
+    - Confidence level calculation
+    """
+    
+    def __init__(self):
+        self.model = None
+        self.model_loaded = False
+        self.feature_count = settings.ember_feature_count
+        self.default_threshold = settings.prediction_threshold
+        
+    def load_model(self, model_path: Optional[str] = None) -> bool:
+        """
+        Load the XGBoost model from disk.
+        Should be called once at application startup.
+        
+        Args:
+            model_path: Path to the .joblib model file
+            
+        Returns:
+            True if model loaded successfully
+        """
+        if model_path is None:
+            # Look in parent directory (project root)
+            model_path = Path(__file__).parent.parent.parent.parent / settings.model_path
+        else:
+            model_path = Path(model_path)
+            
+        try:
+            logger.info(f"Loading XGBoost model from: {model_path}")
+            start_time = time.time()
+            
+            self.model = joblib.load(model_path)
+            
+            load_time = (time.time() - start_time) * 1000
+            logger.info(f"Model loaded successfully in {load_time:.2f}ms")
+            
+            self.model_loaded = True
+            return True
+            
+        except FileNotFoundError:
+            logger.error(f"Model file not found: {model_path}")
+            raise RuntimeError(f"Model file not found: {model_path}")
+        except Exception as e:
+            logger.error(f"Failed to load model: {e}")
+            raise RuntimeError(f"Failed to load model: {e}")
+    
+    def predict(
+        self,
+        features: list[float],
+        threshold: Optional[float] = None,
+        sha256: Optional[str] = None
+    ) -> PredictionResponse:
+        """
+        Run malware prediction on feature vector.
+        
+        Args:
+            features: EMBER 2018 v2 feature vector (2381 values)
+            threshold: Custom threshold (default from config)
+            sha256: Optional hash for reference
+            
+        Returns:
+            PredictionResponse with prediction, probability, confidence
+        """
+        if not self.model_loaded:
+            raise RuntimeError("Model not loaded. Call load_model() first.")
+        
+        # Validate feature count
+        if len(features) != self.feature_count:
+            raise ValueError(
+                f"Expected {self.feature_count} features, got {len(features)}"
+            )
+        
+        # Use default threshold if not provided
+        if threshold is None:
+            threshold = self.default_threshold
+        
+        # Convert to NumPy array for vectorized inference
+        start_time = time.time()
+        feature_array = np.array(features, dtype=np.float32).reshape(1, -1)
+        
+        # Get probability prediction
+        # XGBoost predict_proba returns [[prob_benign, prob_malicious]]
+        try:
+            probabilities = self.model.predict_proba(feature_array)
+            malware_probability = float(probabilities[0][1])
+        except AttributeError:
+            # Fallback for models without predict_proba
+            prediction = self.model.predict(feature_array)
+            malware_probability = float(prediction[0])
+        
+        inference_time = (time.time() - start_time) * 1000
+        
+        # Determine prediction based on threshold
+        is_malicious = malware_probability >= threshold
+        prediction_label = (
+            PredictionLabel.MALICIOUS if is_malicious 
+            else PredictionLabel.BENIGN
+        )
+        
+        # Calculate confidence level
+        confidence = self._calculate_confidence(malware_probability)
+        
+        return PredictionResponse(
+            prediction=prediction_label,
+            probability=round(malware_probability, 4),
+            confidence=confidence,
+            threshold_used=threshold,
+            sha256=sha256,
+            inference_time_ms=round(inference_time, 2)
+        )
+    
+    def _calculate_confidence(self, probability: float) -> ConfidenceLevel:
+        """
+        Calculate confidence level based on probability distance from threshold.
+        
+        High confidence: probability < 0.2 or > 0.8
+        Medium confidence: probability 0.2-0.35 or 0.65-0.8
+        Low confidence: probability 0.35-0.65
+        """
+        distance_from_uncertain = abs(probability - 0.5)
+        
+        if distance_from_uncertain >= 0.3:
+            return ConfidenceLevel.HIGH
+        elif distance_from_uncertain >= 0.15:
+            return ConfidenceLevel.MEDIUM
+        else:
+            return ConfidenceLevel.LOW
+    
+    def get_model_info(self) -> dict:
+        """Get information about the loaded model."""
+        if not self.model_loaded:
+            return {"loaded": False}
+        
+        info = {
+            "loaded": True,
+            "feature_count": self.feature_count,
+            "default_threshold": self.default_threshold,
+            "model_type": type(self.model).__name__,
+        }
+        
+        # Try to get additional model attributes
+        try:
+            if hasattr(self.model, 'n_estimators'):
+                info["n_estimators"] = self.model.n_estimators
+            if hasattr(self.model, 'max_depth'):
+                info["max_depth"] = self.model.max_depth
+        except Exception:
+            pass
+            
+        return info
+
+
+# Global service instance (singleton pattern)
+_ml_service: Optional[MLService] = None
+
+
+def get_ml_service() -> MLService:
+    """
+    Get the global ML service instance.
+    Creates and loads model on first call.
+    """
+    global _ml_service
+    
+    if _ml_service is None:
+        _ml_service = MLService()
+        _ml_service.load_model()
+    
+    return _ml_service

backend/app/services/shap_service.py

@@ -0,0 +1,203 @@
+"""
+SHAP Service for feature importance extraction.
+Provides explainability for XGBoost malware predictions.
+"""
+
+import logging
+from typing import Optional, List
+import numpy as np
+
+from ..config import settings
+from ..models.prediction import FeatureImportance
+
+logger = logging.getLogger(__name__)
+
+# EMBER 2018 v2 Feature Name Mapping
+# These are the high-level feature categories from EMBER
+EMBER_FEATURE_GROUPS = {
+    # Byte histogram (256 features, indices 0-255)
+    (0, 256): "byte_histogram",
+    # Byte-entropy histogram (256 features, indices 256-511)
+    (256, 512): "byte_entropy_histogram",
+    # String features (104 features, indices 512-615)
+    (512, 616): "string_features",
+    # General file info (10 features, indices 616-625)
+    (616, 626): "general_file_info",
+    # Header features (62 features, indices 626-687)
+    (626, 688): "header_features",
+    # Section features (255 features, indices 688-942)
+    (688, 943): "section_features",
+    # Import features (1280 features, indices 943-2222)
+    (943, 2223): "import_features",
+    # Export features (128 features, indices 2223-2350)
+    (2223, 2351): "export_features",
+    # Data directory features (30 features, indices 2351-2380)
+    (2351, 2381): "data_directory_features",
+}
+
+def get_feature_name(index: int) -> str:
+    """Get human-readable feature name from index."""
+    for (start, end), name in EMBER_FEATURE_GROUPS.items():
+        if start <= index < end:
+            offset = index - start
+            return f"{name}[{offset}]"
+    return f"feature_{index}"
+
+
+def get_feature_category(index: int) -> str:
+    """Get feature category from index."""
+    for (start, end), name in EMBER_FEATURE_GROUPS.items():
+        if start <= index < end:
+            return name
+    return "unknown"
+
+
+class SHAPService:
+    """
+    SHAP (SHapley Additive exPlanations) service for model explainability.
+    
+    Provides feature importance analysis to understand why
+    the model classified a sample as malicious or benign.
+    """
+    
+    def __init__(self):
+        self.explainer = None
+        self.initialized = False
+        self._shap_available = False
+        
+        # Try to import SHAP
+        try:
+            import shap
+            self._shap = shap
+            self._shap_available = True
+        except ImportError:
+            logger.warning("SHAP library not available. Feature importance will be limited.")
+    
+    def initialize(self, model) -> bool:
+        """
+        Initialize SHAP explainer with the model.
+        
+        Args:
+            model: Trained XGBoost model
+            
+        Returns:
+            True if initialization successful
+        """
+        if not self._shap_available:
+            logger.warning("SHAP not available, using fallback importance")
+            self.initialized = True
+            return True
+        
+        try:
+            logger.info("Initializing SHAP TreeExplainer...")
+            self.explainer = self._shap.TreeExplainer(model)
+            self.initialized = True
+            logger.info("SHAP explainer initialized successfully")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to initialize SHAP: {e}")
+            self.initialized = True  # Still mark as initialized to use fallback
+            return False
+    
+    def get_feature_importance(
+        self,
+        features: List[float],
+        model,
+        top_k: int = 10
+    ) -> List[FeatureImportance]:
+        """
+        Get top contributing features for a prediction.
+        
+        Args:
+            features: Input feature vector
+            model: XGBoost model
+            top_k: Number of top features to return
+            
+        Returns:
+            List of FeatureImportance objects
+        """
+        feature_array = np.array(features, dtype=np.float32).reshape(1, -1)
+        
+        if self._shap_available and self.explainer is not None:
+            return self._get_shap_importance(feature_array, top_k)
+        else:
+            return self._get_fallback_importance(feature_array, model, top_k)
+    
+    def _get_shap_importance(
+        self,
+        feature_array: np.ndarray,
+        top_k: int
+    ) -> List[FeatureImportance]:
+        """Get feature importance using SHAP values."""
+        try:
+            shap_values = self.explainer.shap_values(feature_array)
+            
+            # Handle different SHAP output formats
+            if isinstance(shap_values, list):
+                # For binary classification, use positive class
+                values = shap_values[1][0] if len(shap_values) > 1 else shap_values[0][0]
+            else:
+                values = shap_values[0]
+            
+            # Get indices of top features by absolute value
+            top_indices = np.argsort(np.abs(values))[-top_k:][::-1]
+            
+            importance_list = []
+            for idx in top_indices:
+                importance = float(values[idx])
+                importance_list.append(FeatureImportance(
+                    feature_index=int(idx),
+                    feature_name=get_feature_name(idx),
+                    importance_value=round(importance, 4),
+                    contribution="increases" if importance > 0 else "decreases"
+                ))
+            
+            return importance_list
+            
+        except Exception as e:
+            logger.error(f"SHAP calculation failed: {e}")
+            return []
+    
+    def _get_fallback_importance(
+        self,
+        feature_array: np.ndarray,
+        model,
+        top_k: int
+    ) -> List[FeatureImportance]:
+        """
+        Fallback importance using model's feature_importances_.
+        Less accurate than SHAP but faster.
+        """
+        try:
+            if hasattr(model, 'feature_importances_'):
+                importances = model.feature_importances_
+                top_indices = np.argsort(importances)[-top_k:][::-1]
+                
+                importance_list = []
+                for idx in top_indices:
+                    importance_list.append(FeatureImportance(
+                        feature_index=int(idx),
+                        feature_name=get_feature_name(idx),
+                        importance_value=round(float(importances[idx]), 4),
+                        contribution="contributes"  # Can't determine direction without SHAP
+                    ))
+                
+                return importance_list
+        except Exception as e:
+            logger.error(f"Fallback importance failed: {e}")
+        
+        return []
+
+
+# Global service instance
+_shap_service: Optional[SHAPService] = None
+
+
+def get_shap_service() -> SHAPService:
+    """Get the global SHAP service instance."""
+    global _shap_service
+    
+    if _shap_service is None:
+        _shap_service = SHAPService()
+    
+    return _shap_service

backend/app/services/url_feature_engineering.py

@@ -0,0 +1,307 @@
+"""
+URL Feature Engineering — 54 lexical features for malicious URL detection.
+
+Adapted from the URL model notebook for backend integration.
+Features are grouped into 8 categories:
+  1. Length / structural           (7 features)
+  2. Character counts              (14 features)
+  3. Character ratios              (5 features)
+  4. Entropy / randomness          (2 features)
+  5. Boolean indicators            (10 features)
+  6. Domain / TLD signals          (6 features)
+  7. Suspicious-pattern scores     (5 features)
+  8. Path & query analysis         (5 features)
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from urllib.parse import urlparse, parse_qs
+
+import numpy as np
+
+try:
+    import tldextract
+except ImportError:
+    tldextract = None
+
+# ── Regex patterns (compiled once) ────────────────────────────────────────────
+_IP_RE = re.compile(
+    r"(?:^|[/@])(\d{1,3}\.){3}\d{1,3}(?:[:/]|$)"
+)
+_HEX_RE = re.compile(r"%[0-9a-fA-F]{2}")
+_SHORTENERS = frozenset([
+    "bit.ly", "goo.gl", "tinyurl.com", "ow.ly", "t.co", "is.gd",
+    "buff.ly", "adf.ly", "tiny.cc", "lnkd.in", "rb.gy", "cutt.ly",
+    "shorturl.at", "rebrand.ly",
+])
+_SUSPICIOUS_TLDS = frozenset([
+    "tk", "ml", "ga", "cf", "gq", "xyz", "top", "pw", "cc",
+    "club", "work", "date", "racing", "stream", "download",
+    "win", "bid", "icu", "buzz", "monster",
+])
+_SUSPICIOUS_EXT = re.compile(
+    r"\.(exe|zip|rar|scr|bat|cmd|js|vbs|ps1|dll|msi|apk|dmg|iso|php|cgi)(\?|$)",
+    re.IGNORECASE,
+)
+_PHISHING_KW = re.compile(
+    r"(login|signin|verify|account|update|secure|bank|confirm|password|"
+    r"credential|suspend|alert|notification|wallet|paypal|apple|microsoft|"
+    r"amazon|netflix|facebook|instagram|whatsapp|dropbox|google|icloud)",
+    re.IGNORECASE,
+)
+_BRAND_NAMES = [
+    "google", "facebook", "apple", "amazon", "microsoft", "netflix",
+    "paypal", "instagram", "whatsapp", "dropbox", "linkedin", "twitter",
+    "yahoo", "ebay", "chase", "wellsfargo", "bankofamerica", "citibank",
+    "hsbc", "dhl", "fedex", "usps",
+]
+
+
+# Feature names in the exact order the scaler/models expect
+FEATURE_NAMES = [
+    # 1. Length
+    "url_length", "hostname_length", "domain_length", "path_length",
+    "query_length", "fragment_length", "tld_length",
+    # 2. Counts
+    "num_dots", "num_hyphens", "num_underscores", "num_slashes",
+    "num_at_signs", "num_ampersands", "num_equals", "num_question_marks",
+    "num_percent", "num_tilde", "num_digits", "num_letters",
+    "num_special", "num_params",
+    # 3. Ratios
+    "digit_ratio", "letter_ratio", "special_ratio", "uppercase_ratio",
+    "digit_letter_ratio",
+    # 4. Entropy
+    "url_entropy", "domain_entropy",
+    # 5. Booleans
+    "has_ip", "has_https", "has_http", "has_www", "has_port",
+    "has_at_symbol", "is_shortened", "has_double_slash_redirect",
+    "has_punycode", "has_hex_encoding",
+    # 6. Domain
+    "num_subdomains", "subdomain_length", "domain_token_count",
+    "has_suspicious_tld", "domain_has_digits", "domain_hyphen_count",
+    # 7. Suspicious
+    "phishing_keyword_count", "brand_count", "has_suspicious_ext",
+    "brand_in_subdomain", "suspicious_word_ratio",
+    # 8. Path / query
+    "path_depth", "longest_path_token", "avg_path_token_len",
+    "max_consecutive_digits", "path_entropy",
+]
+
+
+def _entropy(s: str) -> float:
+    """Shannon entropy of a string."""
+    if not s:
+        return 0.0
+    cnt = Counter(s)
+    length = len(s)
+    return -sum((c / length) * math.log2(c / length) for c in cnt.values())
+
+
+def extract_url_features(url: str) -> np.ndarray:
+    """
+    Extract 54 lexical features from a single URL string.
+    Returns a 1D numpy array of shape (54,) in float32.
+    """
+    try:
+        features = _extract_features_inner(url)
+    except Exception:
+        features = {name: 0 for name in FEATURE_NAMES}
+
+    return np.array([features[name] for name in FEATURE_NAMES], dtype=np.float32)
+
+
+def extract_url_features_dict(url: str) -> dict:
+    """Extract 54 features and return as a dict with feature names."""
+    try:
+        return _extract_features_inner(url)
+    except Exception:
+        return {name: 0 for name in FEATURE_NAMES}
+
+
+def _extract_features_inner(url: str) -> dict:
+    """Core feature extraction logic."""
+    url = str(url).strip()
+
+    try:
+        parsed = urlparse(url if "://" in url else f"http://{url}")
+    except Exception:
+        try:
+            safe = url.replace("[", "").replace("]", "")
+            parsed = urlparse(safe if "://" in safe else f"http://{safe}")
+        except Exception:
+            parsed = urlparse("http://invalid")
+
+    try:
+        hostname = parsed.hostname or ""
+    except Exception:
+        hostname = ""
+    path = parsed.path or ""
+    query = parsed.query or ""
+    fragment = parsed.fragment or ""
+    scheme = (parsed.scheme or "").lower()
+
+    # TLD extraction
+    if tldextract is not None:
+        ext = tldextract.extract(url)
+        domain = ext.domain
+        tld = ext.suffix
+        subdomain = ext.subdomain
+    else:
+        domain = hostname.split(".")[-2] if hostname.count(".") >= 1 else hostname
+        tld = hostname.split(".")[-1] if "." in hostname else ""
+        subdomain = ".".join(hostname.split(".")[:-2]) if hostname.count(".") >= 2 else ""
+
+    url_lower = url.lower()
+
+    # 1. Length / structural
+    url_length = len(url)
+    hostname_length = len(hostname)
+    domain_length = len(domain)
+    path_length = len(path)
+    query_length = len(query)
+    fragment_length = len(fragment)
+    tld_length = len(tld)
+
+    # 2. Character counts
+    num_dots = url.count(".")
+    num_hyphens = url.count("-")
+    num_underscores = url.count("_")
+    num_slashes = url.count("/")
+    num_at_signs = url.count("@")
+    num_ampersands = url.count("&")
+    num_equals = url.count("=")
+    num_question_marks = url.count("?")
+    num_percent = url.count("%")
+    num_tilde = url.count("~")
+    num_digits = sum(c.isdigit() for c in url)
+    num_letters = sum(c.isalpha() for c in url)
+    num_special = sum(not c.isalnum() and c not in ":/." for c in url)
+    num_params = len(parse_qs(query))
+
+    # 3. Character ratios
+    safe_len = max(url_length, 1)
+    digit_ratio = num_digits / safe_len
+    letter_ratio = num_letters / safe_len
+    special_ratio = num_special / safe_len
+    uppercase_ratio = sum(c.isupper() for c in url) / safe_len
+    digit_letter_ratio = num_digits / max(num_letters, 1)
+
+    # 4. Entropy
+    url_entropy = _entropy(url)
+    domain_entropy = _entropy(hostname)
+
+    # 5. Boolean indicators
+    has_ip = int(bool(_IP_RE.search(url)))
+    has_https = int(scheme == "https")
+    has_http = int(scheme == "http")
+    has_www = int("www." in url_lower)
+    try:
+        _port = parsed.port
+    except (ValueError, TypeError):
+        _port = None
+    has_port = int(_port is not None and _port not in (80, 443))
+    has_at_symbol = int("@" in url)
+    is_shortened = int(any(s in url_lower for s in _SHORTENERS))
+    has_double_slash_redirect = int("//" in path)
+    has_punycode = int("xn--" in url_lower)
+    has_hex_encoding = int(bool(_HEX_RE.search(url)))
+
+    # 6. Domain / TLD signals
+    num_subdomains = subdomain.count(".") + 1 if subdomain else 0
+    subdomain_length = len(subdomain)
+    domain_token_count = len(re.split(r"[.\-_]", hostname))
+    has_suspicious_tld = int(tld.lower() in _SUSPICIOUS_TLDS)
+    domain_has_digits = int(any(c.isdigit() for c in domain))
+    domain_hyphen_count = domain.count("-")
+
+    # 7. Suspicious-pattern scores
+    phishing_keyword_count = len(_PHISHING_KW.findall(url_lower))
+    brand_count = sum(1 for b in _BRAND_NAMES if b in url_lower)
+    has_suspicious_ext = int(bool(_SUSPICIOUS_EXT.search(url_lower)))
+    brand_in_subdomain = int(
+        any(b in subdomain.lower() for b in _BRAND_NAMES) and
+        not any(b in domain.lower() for b in _BRAND_NAMES)
+    ) if subdomain else 0
+    suspicious_word_ratio = phishing_keyword_count / max(
+        len(re.findall(r"[a-zA-Z]+", url)), 1
+    )
+
+    # 8. Path & query analysis
+    path_tokens = [t for t in path.split("/") if t]
+    path_depth = len(path_tokens)
+    longest_path_token = max((len(t) for t in path_tokens), default=0)
+    avg_path_token_len = (
+        sum(len(t) for t in path_tokens) / len(path_tokens) if path_tokens else 0.0
+    )
+    max_consecutive_digits = max(
+        (len(m.group()) for m in re.finditer(r"\d+", url)), default=0
+    )
+    path_entropy = _entropy(path)
+
+    return {
+        # 1. Length
+        "url_length": url_length,
+        "hostname_length": hostname_length,
+        "domain_length": domain_length,
+        "path_length": path_length,
+        "query_length": query_length,
+        "fragment_length": fragment_length,
+        "tld_length": tld_length,
+        # 2. Counts
+        "num_dots": num_dots,
+        "num_hyphens": num_hyphens,
+        "num_underscores": num_underscores,
+        "num_slashes": num_slashes,
+        "num_at_signs": num_at_signs,
+        "num_ampersands": num_ampersands,
+        "num_equals": num_equals,
+        "num_question_marks": num_question_marks,
+        "num_percent": num_percent,
+        "num_tilde": num_tilde,
+        "num_digits": num_digits,
+        "num_letters": num_letters,
+        "num_special": num_special,
+        "num_params": num_params,
+        # 3. Ratios
+        "digit_ratio": digit_ratio,
+        "letter_ratio": letter_ratio,
+        "special_ratio": special_ratio,
+        "uppercase_ratio": uppercase_ratio,
+        "digit_letter_ratio": digit_letter_ratio,
+        # 4. Entropy
+        "url_entropy": url_entropy,
+        "domain_entropy": domain_entropy,
+        # 5. Booleans
+        "has_ip": has_ip,
+        "has_https": has_https,
+        "has_http": has_http,
+        "has_www": has_www,
+        "has_port": has_port,
+        "has_at_symbol": has_at_symbol,
+        "is_shortened": is_shortened,
+        "has_double_slash_redirect": has_double_slash_redirect,
+        "has_punycode": has_punycode,
+        "has_hex_encoding": has_hex_encoding,
+        # 6. Domain
+        "num_subdomains": num_subdomains,
+        "subdomain_length": subdomain_length,
+        "domain_token_count": domain_token_count,
+        "has_suspicious_tld": has_suspicious_tld,
+        "domain_has_digits": domain_has_digits,
+        "domain_hyphen_count": domain_hyphen_count,
+        # 7. Suspicious
+        "phishing_keyword_count": phishing_keyword_count,
+        "brand_count": brand_count,
+        "has_suspicious_ext": has_suspicious_ext,
+        "brand_in_subdomain": brand_in_subdomain,
+        "suspicious_word_ratio": suspicious_word_ratio,
+        # 8. Path / query
+        "path_depth": path_depth,
+        "longest_path_token": longest_path_token,
+        "avg_path_token_len": avg_path_token_len,
+        "max_consecutive_digits": max_consecutive_digits,
+        "path_entropy": path_entropy,
+    }

backend/app/services/url_service.py

@@ -0,0 +1,334 @@
+"""
+URL Malware Detection Service — Stacking HyperModel.
+
+Full inference pipeline:
+  1. Extract 54 lexical features from URL
+  2. Scale features with StandardScaler
+  3. Run 5 base models (XGBoost, LightGBM, TF-IDF+LR, CharCNN, CharBiLSTM)
+  4. Stack their probability outputs → 10 meta-features
+  5. Meta-learner (XGBoost) produces final prediction
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import warnings
+from pathlib import Path
+from functools import lru_cache
+
+import numpy as np
+import joblib
+
+from .url_feature_engineering import extract_url_features, extract_url_features_dict, FEATURE_NAMES
+
+logger = logging.getLogger(__name__)
+
+# ── DL architecture definitions (inline, no external dependency) ──────────────
+# These mirror the exact architectures from the training notebook.
+
+MAX_URL_LEN = 200
+
+# Character lookup table
+_CHAR_LUT = np.zeros(256, dtype=np.int64)
+_PRINTABLE = (
+    "abcdefghijklmnopqrstuvwxyz"
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    "0123456789"
+    "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ "
+)
+for _i, _ch in enumerate(_PRINTABLE, start=1):
+    _CHAR_LUT[ord(_ch)] = _i
+_UNK_ID = len(_PRINTABLE) + 1  # 96
+VOCAB_SIZE = _UNK_ID + 1       # 97
+
+try:
+    import torch
+    import torch.nn as nn
+    TORCH_AVAILABLE = True
+except ImportError:
+    TORCH_AVAILABLE = False
+    logger.warning("PyTorch not available — DL base models will be skipped")
+
+
+def _url_to_tensor(urls: list[str], max_len: int = MAX_URL_LEN):
+    """Vectorised char→int encoding for a batch of URL strings."""
+    arr = np.zeros((len(urls), max_len), dtype=np.int64)
+    for i, url in enumerate(urls):
+        raw = str(url)[:max_len]
+        chars = np.frombuffer(raw.encode("ascii", "ignore"), dtype=np.uint8)
+        if len(chars) == 0:
+            continue
+        ids = _CHAR_LUT[chars]
+        ids = np.where(ids > 0, ids, _UNK_ID)
+        arr[i, : len(ids)] = ids[: max_len]
+    import torch
+    return torch.from_numpy(arr)
+
+
+if TORCH_AVAILABLE:
+    class CharCNNNet(nn.Module):
+        """1-D CNN on character-level URL embeddings."""
+        def __init__(self, num_classes: int = 2, embed_dim: int = 64):
+            super().__init__()
+            self.embed = nn.Embedding(VOCAB_SIZE, embed_dim, padding_idx=0)
+            self.convs = nn.Sequential(
+                nn.Conv1d(embed_dim, 128, kernel_size=3, padding=1),
+                nn.BatchNorm1d(128), nn.ReLU(), nn.MaxPool1d(2),
+                nn.Conv1d(128, 128, kernel_size=3, padding=1),
+                nn.BatchNorm1d(128), nn.ReLU(), nn.MaxPool1d(2),
+                nn.Conv1d(128, 256, kernel_size=3, padding=1),
+                nn.BatchNorm1d(256), nn.ReLU(), nn.AdaptiveMaxPool1d(1),
+            )
+            self.head = nn.Sequential(
+                nn.Dropout(0.3), nn.Linear(256, 128), nn.ReLU(),
+                nn.Dropout(0.2), nn.Linear(128, num_classes),
+            )
+
+        def forward(self, x):
+            x = self.embed(x).permute(0, 2, 1)
+            x = self.convs(x).squeeze(-1)
+            return self.head(x)
+
+    class CharBiLSTMNet(nn.Module):
+        """Bidirectional LSTM on character embeddings."""
+        def __init__(self, num_classes: int = 2, embed_dim: int = 64,
+                     hidden: int = 128, n_layers: int = 2):
+            super().__init__()
+            self.embed = nn.Embedding(VOCAB_SIZE, embed_dim, padding_idx=0)
+            self.lstm = nn.LSTM(
+                embed_dim, hidden, num_layers=n_layers,
+                batch_first=True, bidirectional=True, dropout=0.3,
+            )
+            self.head = nn.Sequential(
+                nn.Dropout(0.3), nn.Linear(hidden * 2, 128), nn.ReLU(),
+                nn.Dropout(0.2), nn.Linear(128, num_classes),
+            )
+
+        def forward(self, x):
+            x = self.embed(x)
+            _, (h, _) = self.lstm(x)
+            h = torch.cat([h[-2], h[-1]], dim=-1)
+            return self.head(h)
+
+
+class URLModelService:
+    """
+    Stacking HyperModel service for URL malware detection.
+    
+    Loads all base models + meta-learner at initialization time.
+    Thread-safe for concurrent FastAPI requests.
+    """
+
+    def __init__(self, models_dir: str | Path | None = None):
+        if models_dir is None:
+            # Default to urlmodel_info/ in project root
+            models_dir = Path(__file__).parent.parent.parent.parent / "urlmodel_info"
+        self.models_dir = Path(models_dir)
+        
+        self.scaler = None
+        self.meta_learner = None
+        self.xgb_model = None
+        self.lgbm_model = None
+        self.tfidf_lr_model = None
+        self.cnn_net = None
+        self.bilstm_net = None
+        self.model_loaded = False
+        self._dl_available = False
+        
+        self._load_models()
+
+    def _load_models(self):
+        """Load all model components."""
+        logger.info("Loading URL HyperModel components...")
+        
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            
+            # 1. Scaler
+            scaler_path = self.models_dir / "scaler.joblib"
+            self.scaler = joblib.load(scaler_path)
+            logger.info(f"  Scaler loaded ({self.scaler.n_features_in_} features)")
+            
+            # 2. Meta-learner
+            meta_path = self.models_dir / "hypermodel_meta.joblib"
+            self.meta_learner = joblib.load(meta_path)
+            logger.info(f"  Meta-learner loaded ({self.meta_learner.n_features_in_} meta-features)")
+            
+            # 3. XGBoost base model
+            xgb_path = self.models_dir / "xgb_binary.joblib"
+            self.xgb_model = joblib.load(xgb_path)
+            logger.info("  XGBoost base model loaded")
+            
+            # 4. LightGBM base model
+            lgbm_path = self.models_dir / "lgbm_binary.joblib"
+            self.lgbm_model = joblib.load(lgbm_path)
+            logger.info("  LightGBM base model loaded")
+            
+            # 5. TF-IDF + LR pipeline
+            tfidf_path = self.models_dir / "tfidf_lr_binary.joblib"
+            self.tfidf_lr_model = joblib.load(tfidf_path)
+            logger.info("  TF-IDF + LR pipeline loaded")
+            
+            # 6. Deep Learning models (optional — requires PyTorch)
+            if TORCH_AVAILABLE:
+                try:
+                    cnn_path = self.models_dir / "char_cnn_net.pt"
+                    bilstm_path = self.models_dir / "char_bilstm_net.pt"
+                    
+                    self.cnn_net = CharCNNNet(num_classes=2)
+                    self.cnn_net.load_state_dict(
+                        torch.load(cnn_path, map_location="cpu", weights_only=True)
+                    )
+                    self.cnn_net.eval()
+                    logger.info("  CharCNN loaded")
+                    
+                    self.bilstm_net = CharBiLSTMNet(num_classes=2)
+                    self.bilstm_net.load_state_dict(
+                        torch.load(bilstm_path, map_location="cpu", weights_only=True)
+                    )
+                    self.bilstm_net.eval()
+                    logger.info("  CharBiLSTM loaded")
+                    
+                    self._dl_available = True
+                except Exception as e:
+                    logger.warning(f"  DL models failed to load: {e}")
+                    self._dl_available = False
+            
+        self.model_loaded = True
+        n_base = 3 + (2 if self._dl_available else 0)
+        logger.info(f"URL HyperModel ready ({n_base} base models + meta-learner)")
+
+    def predict(self, url: str, threshold: float = 0.5) -> dict:
+        """
+        Run the full stacking pipeline on a single URL.
+        
+        Returns dict with:
+          - url: input URL
+          - prediction: 'Malicious' or 'Benign'
+          - malicious_score: float [0, 1]
+          - confidence: str percentage
+          - confidence_level: 'High', 'Medium', or 'Low'
+          - base_model_scores: dict of individual model scores
+          - top_signals: dict of most important feature values
+          - inference_time_ms: float
+        """
+        start = time.perf_counter()
+        
+        # 1. Extract features
+        features = extract_url_features(url)
+        features_dict = extract_url_features_dict(url)
+        X_feat = features.reshape(1, -1)
+        
+        # 2. Scale features
+        X_scaled = self.scaler.transform(X_feat).astype(np.float32)
+        
+        # 3. Get base model predictions
+        p_xgb = self.xgb_model.predict_proba(X_scaled)
+        p_lgbm = self.lgbm_model.predict_proba(X_scaled)
+        p_tfidf = self.tfidf_lr_model.predict_proba(np.array([url]))
+        
+        base_scores = {
+            "XGBoost": float(p_xgb[0, 1]),
+            "LightGBM": float(p_lgbm[0, 1]),
+            "TF-IDF + LR": float(p_tfidf[0, 1]),
+        }
+        
+        # 4. DL models (if available)
+        if self._dl_available:
+            xt = _url_to_tensor([url])
+            with torch.no_grad():
+                p_cnn = torch.softmax(self.cnn_net(xt).float(), dim=-1).numpy()
+                p_bilstm = torch.softmax(self.bilstm_net(xt).float(), dim=-1).numpy()
+            base_scores["CharCNN"] = float(p_cnn[0, 1])
+            base_scores["CharBiLSTM"] = float(p_bilstm[0, 1])
+            meta_features = np.hstack([p_xgb, p_lgbm, p_tfidf, p_cnn, p_bilstm])
+        else:
+            # Fallback: pad with zeros for missing DL models
+            zeros = np.zeros((1, 2), dtype=np.float32)
+            meta_features = np.hstack([p_xgb, p_lgbm, p_tfidf, zeros, zeros])
+        
+        meta_features = meta_features.astype(np.float32)
+        
+        # 5. Meta-learner prediction
+        final_proba = self.meta_learner.predict_proba(meta_features)
+        malicious_score = float(final_proba[0, 1])
+        
+        # Determine verdict
+        prediction = "Malicious" if malicious_score > threshold else "Benign"
+        confidence_pct = abs(malicious_score - 0.5) * 200
+        
+        if confidence_pct >= 80:
+            confidence_level = "High"
+        elif confidence_pct >= 50:
+            confidence_level = "Medium"
+        else:
+            confidence_level = "Low"
+        
+        # Top feature signals
+        important_features = [
+            "has_ip", "has_suspicious_tld", "phishing_keyword_count",
+            "brand_in_subdomain", "has_punycode", "is_shortened",
+            "url_length", "num_subdomains", "has_https", "domain_entropy",
+            "has_suspicious_ext", "has_hex_encoding", "brand_count",
+            "path_depth", "url_entropy",
+        ]
+        top_signals = {}
+        for feat in important_features:
+            if feat in features_dict:
+                val = features_dict[feat]
+                if val != 0:
+                    top_signals[feat] = round(float(val), 4)
+        
+        elapsed = (time.perf_counter() - start) * 1000
+        
+        return {
+            "url": url,
+            "prediction": prediction,
+            "malicious_score": round(malicious_score, 6),
+            "confidence": f"{confidence_pct:.1f}%",
+            "confidence_level": confidence_level,
+            "threshold_used": threshold,
+            "base_model_scores": base_scores,
+            "top_signals": top_signals,
+            "inference_time_ms": round(elapsed, 2),
+        }
+
+    def get_model_info(self) -> dict:
+        """Return info about loaded models."""
+        return {
+            "model_type": "Stacking HyperModel",
+            "base_models": list(self._get_base_model_names()),
+            "meta_learner": "XGBoost (GPU-trained)",
+            "scaler_features": self.scaler.n_features_in_,
+            "meta_features": self.meta_learner.n_features_in_,
+            "dl_available": self._dl_available,
+            "feature_categories": [
+                "Length/structural (7)",
+                "Character counts (14)",
+                "Character ratios (5)",
+                "Entropy/randomness (2)",
+                "Boolean indicators (10)",
+                "Domain/TLD signals (6)",
+                "Suspicious patterns (5)",
+                "Path & query (5)",
+            ],
+        }
+
+    def _get_base_model_names(self):
+        names = ["XGBoost", "LightGBM", "TF-IDF + LR"]
+        if self._dl_available:
+            names.extend(["CharCNN", "CharBiLSTM"])
+        return names
+
+
+# Singleton accessor
+_url_service: URLModelService | None = None
+
+
+def get_url_service() -> URLModelService:
+    """Get or create the singleton URL model service."""
+    global _url_service
+    if _url_service is None:
+        _url_service = URLModelService()
+    return _url_service

backend/app/services/virustotal_service.py

@@ -0,0 +1,226 @@
+"""
+VirusTotal API Service for hash verification.
+Provides secondary verification of malware samples.
+"""
+
+import logging
+from typing import Optional
+import httpx
+
+from ..config import settings
+from ..models.virustotal import (
+    VirusTotalResponse,
+    VirusTotalStats,
+    EngineResult,
+    MalwareTypeInfo,
+)
+from .malware_type_service import get_malware_type_service
+
+logger = logging.getLogger(__name__)
+
+VIRUSTOTAL_API_BASE = "https://www.virustotal.com/api/v3"
+
+
+class VirusTotalService:
+    """
+    VirusTotal API Service for file hash lookups.
+    
+    Provides:
+    - Hash lookup for SHA256/SHA1/MD5
+    - Detection ratio calculation
+    - Engine verdict extraction
+    - Reputation score
+    """
+    
+    def __init__(self):
+        self.api_key = settings.virustotal_api_key
+        self.initialized = bool(self.api_key)
+        self._client: Optional[httpx.AsyncClient] = None
+    
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=30.0,
+                headers={
+                    "x-apikey": self.api_key,
+                    "Accept": "application/json"
+                }
+            )
+        return self._client
+    
+    async def close(self):
+        """Close HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+    
+    async def lookup_hash(self, sha256: str) -> VirusTotalResponse:
+        """
+        Look up a file hash on VirusTotal.
+        
+        Args:
+            sha256: SHA256 hash to look up
+            
+        Returns:
+            VirusTotalResponse with detection results
+        """
+        if not self.initialized:
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=False,
+                error_message="VirusTotal API key not configured"
+            )
+        
+        try:
+            client = await self._get_client()
+            url = f"{VIRUSTOTAL_API_BASE}/files/{sha256}"
+            
+            response = await client.get(url)
+            
+            if response.status_code == 404:
+                return VirusTotalResponse(
+                    sha256=sha256,
+                    found=False,
+                    error_message="Hash not found in VirusTotal database"
+                )
+            
+            if response.status_code == 401:
+                return VirusTotalResponse(
+                    sha256=sha256,
+                    found=False,
+                    error_message="Invalid VirusTotal API key"
+                )
+            
+            if response.status_code == 429:
+                return VirusTotalResponse(
+                    sha256=sha256,
+                    found=False,
+                    error_message="VirusTotal API rate limit exceeded"
+                )
+            
+            response.raise_for_status()
+            data = response.json()
+            
+            return self._parse_response(sha256, data)
+            
+        except httpx.TimeoutException:
+            logger.error(f"VirusTotal API timeout for hash: {sha256}")
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=False,
+                error_message="VirusTotal API request timed out"
+            )
+        except httpx.HTTPError as e:
+            logger.error(f"VirusTotal API error: {e}")
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=False,
+                error_message=f"VirusTotal API error: {str(e)}"
+            )
+        except Exception as e:
+            logger.error(f"Unexpected error in VirusTotal lookup: {e}")
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=False,
+                error_message=f"Unexpected error: {str(e)}"
+            )
+    
+    def _parse_response(self, sha256: str, data: dict) -> VirusTotalResponse:
+        """Parse VirusTotal API response into structured format."""
+        try:
+            attributes = data.get("data", {}).get("attributes", {})
+            
+            # Parse detection stats
+            stats_data = attributes.get("last_analysis_stats", {})
+            stats = VirusTotalStats(
+                malicious=stats_data.get("malicious", 0),
+                suspicious=stats_data.get("suspicious", 0),
+                undetected=stats_data.get("undetected", 0),
+                harmless=stats_data.get("harmless", 0),
+                timeout=stats_data.get("timeout", 0),
+                confirmed_timeout=stats_data.get("confirmed-timeout", 0),
+                failure=stats_data.get("failure", 0),
+                type_unsupported=stats_data.get("type-unsupported", 0),
+            )
+            
+            # Calculate totals
+            malicious_count = stats.malicious + stats.suspicious
+            total_engines = (
+                stats.malicious + stats.suspicious + 
+                stats.undetected + stats.harmless
+            )
+            detection_ratio = malicious_count / total_engines if total_engines > 0 else 0
+            
+            # Parse engine results (top 20 for brevity)
+            engine_results = []
+            vt_labels = []  # Collect labels for malware type classification
+            last_analysis = attributes.get("last_analysis_results", {})
+            for engine_name, result in list(last_analysis.items())[:20]:
+                engine_results.append(EngineResult(
+                    engine_name=engine_name,
+                    category=result.get("category", "unknown"),
+                    result=result.get("result"),
+                    engine_version=result.get("engine_version"),
+                    engine_update=result.get("engine_update"),
+                ))
+                # Collect detection labels for malware type classification
+                if result.get("result"):
+                    vt_labels.append(result.get("result"))
+            
+            # Get dates
+            first_submission = attributes.get("first_submission_date")
+            last_analysis_date = attributes.get("last_analysis_date")
+            
+            # Classify malware type if detected as malicious
+            malware_type = None
+            if malicious_count > 0 and vt_labels:
+                try:
+                    malware_service = get_malware_type_service()
+                    type_result = malware_service.classify(vt_labels=vt_labels)
+                    malware_type = MalwareTypeInfo(
+                        primary_type=type_result.primary_type,
+                        confidence=type_result.confidence,
+                        secondary_types=type_result.secondary_types,
+                        indicators=type_result.indicators,
+                        source=type_result.source
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to classify malware type: {e}")
+            
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=True,
+                stats=stats,
+                detection_ratio=round(detection_ratio, 4),
+                total_engines=total_engines,
+                malicious_count=malicious_count,
+                reputation_score=attributes.get("reputation"),
+                engine_results=engine_results,
+                first_submission_date=str(first_submission) if first_submission else None,
+                last_analysis_date=str(last_analysis_date) if last_analysis_date else None,
+                meaningful_name=attributes.get("meaningful_name"),
+                malware_type=malware_type,
+            )
+            
+        except Exception as e:
+            logger.error(f"Failed to parse VirusTotal response: {e}")
+            return VirusTotalResponse(
+                sha256=sha256,
+                found=True,
+                error_message=f"Failed to parse response: {str(e)}"
+            )
+
+
+# Global service instance
+_vt_service: Optional[VirusTotalService] = None
+
+
+def get_virustotal_service() -> VirusTotalService:
+    """Get the global VirusTotal service instance."""
+    global _vt_service
+    
+    if _vt_service is None:
+        _vt_service = VirusTotalService()
+    
+    return _vt_service

backend/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+pythonpath = .
+asyncio_mode = auto

backend/requirements.txt

@@ -0,0 +1,40 @@
+# Malware Detection Platform - Backend Dependencies
+# Python 3.10+ required
+
+# FastAPI Framework with all extras (includes uvicorn, etc.)
+fastapi[standard]>=0.115.0
+
+# Pydantic for data validation
+pydantic>=2.10.0
+pydantic-settings>=2.7.0
+
+# Async HTTP client for VirusTotal API
+httpx>=0.28.0
+
+# Testing
+pytest>=8.3.0
+pytest-asyncio>=0.25.0
+
+# Rate limiting
+slowapi>=0.1.9
+
+# Machine Learning
+numpy>=2.2.0
+scikit-learn>=1.6.0
+joblib>=1.4.0
+xgboost>=2.1.0
+
+# PE File Parsing for EMBER feature extraction
+lief>=0.15.0
+
+# SHAP for explainability (optional but recommended)
+shap>=0.46.0
+
+# Google Generative AI (Gemini)
+google-generativeai>=0.8.0
+
+# Multipart form data handling
+python-multipart>=0.0.18
+
+# Additional utilities
+python-dotenv>=1.0.1

backend/tests/__init__.py

@@ -0,0 +1 @@
+

backend/tests/conftest.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.models.prediction import ConfidenceLevel, PredictionLabel, PredictionResponse
+from app.models.virustotal import VirusTotalResponse
+
+
+FEATURE_COUNT = 2381
+FEATURES = [0.0] * FEATURE_COUNT
+SHA256 = "a" * 64
+
+
+class FakeMLService:
+    model_loaded = True
+    feature_count = FEATURE_COUNT
+    model = object()
+
+    def predict(self, features, threshold=None, sha256=None):
+        if len(features) != self.feature_count:
+            raise ValueError(f"Expected {self.feature_count} features, got {len(features)}")
+        used_threshold = 0.5 if threshold is None else threshold
+        return PredictionResponse(
+            prediction=PredictionLabel.MALICIOUS,
+            probability=0.91,
+            confidence=ConfidenceLevel.HIGH,
+            threshold_used=used_threshold,
+            sha256=sha256,
+            inference_time_ms=1.2,
+        )
+
+    def get_model_info(self):
+        return {
+            "loaded": True,
+            "feature_count": self.feature_count,
+            "default_threshold": 0.5,
+            "model_type": "FakeModel",
+        }
+
+
+class FakeSHAPService:
+    initialized = True
+
+    def initialize(self, model):
+        self.initialized = True
+
+    def get_feature_importance(self, features, model=None, top_k=10):
+        return []
+
+    def explain(self, features):
+        return []
+
+
+class FakeGeminiService:
+    initialized = False
+    model = None
+
+    def initialize(self):
+        self.initialized = False
+
+    async def explain_prediction(self, prediction, features=None):
+        return {
+            "risk_explanation": "Deterministic test explanation.",
+            "severity_level": "High",
+            "key_indicators": ["test signal"],
+            "analyst_summary": "Smoke test summary.",
+            "mitigation_steps": ["isolate sample"],
+        }
+
+
+class FakeURLService:
+    model_loaded = True
+    _dl_available = False
+
+    def predict(self, url, threshold=0.5):
+        return {
+            "url": url,
+            "prediction": "Malicious",
+            "malicious_score": 0.84,
+            "confidence": "84.0%",
+            "confidence_level": "High",
+            "threshold_used": threshold,
+            "base_model_scores": {"XGBoost": 0.8},
+            "top_signals": {"url_length": 0.4},
+            "inference_time_ms": 3.4,
+        }
+
+    def get_model_info(self):
+        return {
+            "model_type": "Fake URL HyperModel",
+            "base_models": ["XGBoost"],
+            "meta_learner": "XGBoost",
+            "scaler_features": 54,
+            "meta_features": 10,
+            "dl_available": self._dl_available,
+            "feature_categories": ["lexical"],
+        }
+
+
+class FakeVirusTotalService:
+    initialized = True
+    next_result: VirusTotalResponse | None = None
+
+    async def lookup_hash(self, sha256):
+        if self.next_result is not None:
+            return self.next_result
+        return VirusTotalResponse(
+            sha256=sha256,
+            found=True,
+            detection_ratio=0.25,
+            total_engines=20,
+            malicious_count=5,
+        )
+
+
+class FakeFeedbackService:
+    def __init__(self):
+        self.malware_total = 0
+        self.url_total = 0
+
+    def log_malware_feedback(self, **kwargs):
+        self.malware_total += 1
+        return {
+            "success": True,
+            "reward": 1,
+            "message": "Agreement with VirusTotal logged",
+            "total_feedback_count": self.malware_total,
+        }
+
+    def log_url_feedback(self, **kwargs):
+        self.url_total += 1
+        return {
+            "success": True,
+            "reward": 1,
+            "message": "Feedback recorded",
+            "total_feedback_count": self.url_total,
+        }
+
+    def maybe_auto_update(self, model_type):
+        return None
+
+    def get_stats(self):
+        return {
+            "malware_total": self.malware_total,
+            "malware_agree": self.malware_total,
+            "malware_disagree": 0,
+            "malware_agreement_rate": 100.0 if self.malware_total else 0.0,
+            "url_total": self.url_total,
+            "url_correct": self.url_total,
+            "url_incorrect": 0,
+            "url_accuracy_rate": 100.0 if self.url_total else 0.0,
+            "recent_malware": [],
+            "recent_url": [],
+            "model_updates": [],
+        }
+
+
+@dataclass
+class Services:
+    ml: FakeMLService
+    shap: FakeSHAPService
+    gemini: FakeGeminiService
+    url: FakeURLService
+    virustotal: FakeVirusTotalService
+    feedback: FakeFeedbackService
+
+
+@pytest.fixture
+def features():
+    return list(FEATURES)
+
+
+@pytest.fixture
+def sha256():
+    return SHA256
+
+
+@pytest.fixture
+def services(monkeypatch):
+    fakes = Services(
+        ml=FakeMLService(),
+        shap=FakeSHAPService(),
+        gemini=FakeGeminiService(),
+        url=FakeURLService(),
+        virustotal=FakeVirusTotalService(),
+        feedback=FakeFeedbackService(),
+    )
+
+    from app.routers import chat, feedback, predict, upload, url, virustotal
+    from app import main
+
+    app.dependency_overrides[predict.get_ml_service] = lambda: fakes.ml
+    app.dependency_overrides[predict.get_gemini_service] = lambda: fakes.gemini
+    app.dependency_overrides[virustotal.get_ml_service] = lambda: fakes.ml
+    app.dependency_overrides[virustotal.get_virustotal_service] = lambda: fakes.virustotal
+
+    monkeypatch.setattr(main, "get_ml_service", lambda: fakes.ml)
+    monkeypatch.setattr(main, "get_gemini_service", lambda: fakes.gemini)
+    monkeypatch.setattr(main, "get_virustotal_service", lambda: fakes.virustotal)
+    monkeypatch.setattr(predict, "get_shap_service", lambda: fakes.shap)
+    monkeypatch.setattr(chat, "get_gemini_service", lambda: fakes.gemini)
+    monkeypatch.setattr(upload, "get_ml_service", lambda: fakes.ml)
+    monkeypatch.setattr(upload, "get_shap_service", lambda: fakes.shap)
+    monkeypatch.setattr(upload, "get_gemini_service", lambda: fakes.gemini)
+    monkeypatch.setattr(upload, "LIEF_AVAILABLE", True)
+    monkeypatch.setattr(url, "get_url_service", lambda: fakes.url)
+    monkeypatch.setattr(feedback, "get_feedback_service", lambda: fakes.feedback)
+    monkeypatch.setattr(virustotal, "get_feedback_service", lambda: fakes.feedback)
+
+    yield fakes
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture
+def client(services):
+    return TestClient(app)

backend/tests/test_chat.py

@@ -0,0 +1,10 @@
+def test_chat_uses_fallback_when_gemini_unavailable(client):
+    response = client.post(
+        "/api/chat/",
+        json={"message": "How does malware detection work?"},
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["success"] is True
+    assert "MalwareGuard analyzes Windows PE files" in body["response"]

backend/tests/test_feedback.py

@@ -0,0 +1,23 @@
+def test_feedback_log_and_stats_happy_path(client, features, sha256):
+    log_response = client.post(
+        "/api/feedback/malware",
+        json={
+            "features": features,
+            "sha256": sha256,
+            "predicted_label": "Malicious",
+            "predicted_probability": 0.91,
+            "vt_malicious_count": 5,
+            "vt_total_engines": 20,
+            "vt_detection_ratio": 0.25,
+        },
+    )
+
+    assert log_response.status_code == 200
+    assert log_response.json()["total_feedback_count"] == 1
+
+    stats_response = client.get("/api/feedback/stats")
+
+    assert stats_response.status_code == 200
+    stats = stats_response.json()
+    assert stats["malware_total"] == 1
+    assert stats["malware_agree"] == 1

backend/tests/test_health.py

@@ -0,0 +1,24 @@
+def test_root_and_global_health(client):
+    root = client.get("/")
+    health = client.get("/health")
+
+    assert root.status_code == 200
+    assert root.json()["status"] == "running"
+    assert health.status_code == 200
+    assert health.json()["status"] == "healthy"
+
+
+def test_service_health_routes(client):
+    routes = [
+        "/api/predict/health",
+        "/api/virustotal/health",
+        "/api/chat/health",
+        "/api/url/health",
+        "/api/feedback/health",
+        "/api/upload/health",
+    ]
+
+    for route in routes:
+        response = client.get(route)
+        assert response.status_code == 200, route
+        assert "status" in response.json()

backend/tests/test_predict.py

@@ -0,0 +1,23 @@
+def test_predict_happy_path(client, features, sha256):
+    response = client.post("/api/predict", json={"features": features, "sha256": sha256})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["prediction"]["prediction"] == "Malicious"
+    assert body["prediction"]["probability"] == 0.91
+    assert body["prediction"]["sha256"] == sha256
+
+
+def test_predict_rejects_wrong_feature_count(client):
+    response = client.post("/api/predict", json={"features": [0.0] * 10})
+
+    assert response.status_code == 422
+
+
+def test_predict_rejects_bad_threshold(client, features):
+    response = client.post(
+        "/api/predict",
+        json={"features": features, "threshold": 1.5},
+    )
+
+    assert response.status_code == 422

backend/tests/test_upload.py

@@ -0,0 +1,45 @@
+import numpy as np
+
+
+def test_upload_rejects_non_mz_file(client):
+    response = client.post(
+        "/api/upload/analyze",
+        files={"file": ("note.txt", b"hello", "text/plain")},
+    )
+
+    assert response.status_code == 400
+    assert "Invalid PE file" in response.json()["detail"]
+
+
+def test_upload_rejects_size_limit(client):
+    oversized = b"MZ" + (b"0" * (50 * 1024 * 1024 + 1))
+
+    response = client.post(
+        "/api/upload/analyze",
+        files={"file": ("big.exe", oversized, "application/octet-stream")},
+    )
+
+    assert response.status_code == 400
+    assert "File too large" in response.json()["detail"]
+
+
+def test_upload_analyze_happy_path_with_mocked_lief(client, monkeypatch):
+    from app.routers import upload
+
+    monkeypatch.setattr(upload, "LIEF_AVAILABLE", True)
+    monkeypatch.setattr(
+        upload,
+        "extract_features_and_lief",
+        lambda content: (np.zeros(2381, dtype=float), "unused", object()),
+    )
+
+    response = client.post(
+        "/api/upload/analyze?include_explanation=false",
+        files={"file": ("sample.exe", b"MZfake-pe", "application/octet-stream")},
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["features_extracted"] is True
+    assert body["feature_count"] == 2381
+    assert body["prediction"]["prediction"] == "Malicious"

backend/tests/test_url.py

@@ -0,0 +1,19 @@
+def test_url_analyze_happy_path(client):
+    response = client.post(
+        "/api/url/analyze",
+        json={"url": "https://example.com/login", "threshold": 0.4},
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["prediction"] == "Malicious"
+    assert body["threshold_used"] == 0.4
+
+
+def test_url_analyze_returns_503_when_model_not_loaded(client, services):
+    services.url.model_loaded = False
+
+    response = client.post("/api/url/analyze", json={"url": "https://example.com"})
+
+    assert response.status_code == 503
+    assert response.json()["detail"] == "URL model not loaded"

backend/tests/test_virustotal.py

@@ -0,0 +1,23 @@
+from app.models.virustotal import VirusTotalResponse
+
+
+def test_virustotal_rejects_bad_hash(client):
+    response = client.get("/api/virustotal/not-a-hash")
+
+    assert response.status_code == 422
+
+
+def test_virustotal_compare_returns_404_for_not_found(client, features, sha256, services):
+    services.virustotal.next_result = VirusTotalResponse(
+        sha256=sha256,
+        found=False,
+        error_message="Hash not found in VirusTotal database",
+    )
+
+    response = client.post(
+        "/api/virustotal/compare",
+        json={"features": features, "sha256": sha256},
+    )
+
+    assert response.status_code == 404
+    assert "Hash not found" in response.json()["detail"]

urlmodel_info/case_study_results.csv

@@ -0,0 +1,18 @@
+Description,True Label,XGB Score,LGB Score,TF-IDF Score,HyperModel,Prediction,Correct
+Legitimate Google,Benign,0.999,0.999,1.0,1.0,Malicious,❌
+Legitimate Amazon,Benign,1.0,1.0,1.0,1.0,Malicious,❌
+Legitimate GitHub,Benign,0.998,0.998,1.0,1.0,Malicious,❌
+Legitimate Wikipedia,Benign,1.0,1.0,0.998,1.0,Malicious,❌
+Typosquatting Google,Malicious,0.986,0.997,0.999,1.0,Malicious,✅
+Typosquatting Amazon,Malicious,0.993,0.99,0.995,1.0,Malicious,✅
+Typosquatting PayPal,Malicious,0.981,0.988,0.991,1.0,Malicious,✅
+Brand subdomain phishing,Malicious,0.982,0.996,1.0,1.0,Malicious,✅
+Brand path phishing,Malicious,0.997,0.998,0.999,1.0,Malicious,✅
+IP-based phishing,Malicious,1.0,0.999,0.992,1.0,Malicious,✅
+IP-based phishing 2,Malicious,1.0,0.999,0.996,1.0,Malicious,✅
+Punycode phishing,Malicious,0.982,0.974,0.999,1.0,Malicious,✅
+URL shortener (suspicious),Malicious,0.998,0.997,1.0,1.0,Malicious,✅
+Hex-encoded phishing,Malicious,0.903,0.971,0.947,1.0,Malicious,✅
+Long suspicious URL,Malicious,0.877,0.805,0.831,1.0,Malicious,✅
+Legit MS Security,Benign,1.0,1.0,0.999,1.0,Malicious,❌
+Legit Google OAuth,Benign,0.999,0.999,0.993,1.0,Malicious,❌

urlmodel_info/char_bilstm_net.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6abb849aa9d0ecbea8a58b817606fb3be9a8e9a45cc815ef3102c2e28368060d
+size 2537781

urlmodel_info/char_cnn_net.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4dd4f4b78b8d6c34f331ab952846b65e579ecdae1ca4c811984d2e5ba00f3bb3
+size 865013

urlmodel_info/download_data.py

@@ -0,0 +1,111 @@
+"""
+Download the Malicious URLs dataset (~651K rows, 4 classes).
+
+Dataset: Manu Siddhartha — Malicious URLs Dataset
+Source:  https://www.kaggle.com/datasets/sid321axn/malicious-urls-dataset
+Classes: benign (428,103) · defacement (96,457) · phishing (94,111) · malware (32,520)
+"""
+
+import os
+import sys
+import pathlib
+import shutil
+import subprocess
+import glob
+
+KAGGLE_SLUG = "sid321axn/malicious-urls-dataset"
+
+CSV_FILENAME = "malicious_phishing.csv"
+
+
+def download_malicious_urls(data_dir) -> pathlib.Path:
+    """Download and return the path to the Malicious URLs CSV.
+
+    Tries kagglehub first, then the kaggle CLI, then prints manual
+    download instructions.
+
+    Parameters
+    ----------
+    data_dir : str or pathlib.Path
+        Directory to store the downloaded CSV.
+
+    Returns
+    -------
+    pathlib.Path
+        Path to the CSV file.
+    """
+    data_dir = pathlib.Path(data_dir)
+    data_dir.mkdir(parents=True, exist_ok=True)
+    csv_path = data_dir / CSV_FILENAME
+
+    if csv_path.exists():
+        print(f"✅ Dataset already exists: {csv_path}")
+        return csv_path
+
+    # ── Attempt 1: kagglehub ──────────────────────────────────────────────
+    try:
+        import kagglehub
+    except ImportError:
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "kagglehub", "-q"]
+        )
+        import kagglehub
+
+    try:
+        print("Downloading via kagglehub …")
+        dl_path = kagglehub.dataset_download(KAGGLE_SLUG)
+        src = _find_csv(dl_path)
+        if src:
+            shutil.copy2(src, csv_path)
+            print(f"✅ Dataset saved to {csv_path}")
+            return csv_path
+    except Exception as e:
+        print(f"  kagglehub failed: {e}")
+
+    # ── Attempt 2: kaggle CLI ────────────────────────────────────────────
+    if shutil.which("kaggle"):
+        try:
+            print("Downloading via kaggle CLI …")
+            subprocess.check_call(
+                [
+                    "kaggle", "datasets", "download",
+                    "-d", KAGGLE_SLUG,
+                    "-p", str(data_dir),
+                    "--unzip",
+                ],
+                timeout=300,
+            )
+            src = _find_csv(str(data_dir))
+            if src and pathlib.Path(src) != csv_path:
+                shutil.move(src, csv_path)
+            if csv_path.exists():
+                print(f"✅ Dataset saved to {csv_path}")
+                return csv_path
+        except Exception as e:
+            print(f"  kaggle CLI failed: {e}")
+
+    # ── Manual instructions ──────────────────────────────────────────────
+    print("\n" + "=" * 60)
+    print("  MANUAL DOWNLOAD REQUIRED")
+    print("=" * 60)
+    print(f"  1. Visit: https://www.kaggle.com/datasets/{KAGGLE_SLUG}")
+    print(f"  2. Click 'Download' and extract the ZIP")
+    print(f"  3. Place '{CSV_FILENAME}' in: {data_dir.resolve()}")
+    print("=" * 60)
+    raise FileNotFoundError(
+        f"Could not auto-download dataset. Place '{CSV_FILENAME}' in {data_dir}"
+    )
+
+
+def _find_csv(root_dir: str):
+    """Walk a directory tree and return the first CSV file path found."""
+    for dirpath, _, filenames in os.walk(root_dir):
+        for fn in filenames:
+            if fn.endswith(".csv"):
+                return os.path.join(dirpath, fn)
+    return None
+
+
+if __name__ == "__main__":
+    path = download_malicious_urls("data")
+    print(f"Dataset at: {path}")

urlmodel_info/evaluation.py

@@ -0,0 +1,226 @@
+"""
+Evaluation utilities — metrics, comparison tables, and publication-quality plots.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+from sklearn.metrics import (
+    accuracy_score,
+    precision_score,
+    recall_score,
+    f1_score,
+    roc_auc_score,
+    confusion_matrix,
+    classification_report,
+)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Core evaluation
+# ═════════════════════════════════════════════════════════════════════════════
+
+def evaluate_model(
+    name: str,
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    y_proba: np.ndarray | None = None,
+    class_names: list[str] | None = None,
+    task: str = "binary",
+) -> dict:
+    """Compute comprehensive classification metrics.
+
+    Parameters
+    ----------
+    name : str
+        Model name.
+    y_true, y_pred : array-like
+        Ground truth and predicted labels.
+    y_proba : array-like, optional
+        Class probability matrix (n_samples × n_classes).
+    class_names : list[str]
+        Human-readable class names.
+    task : str
+        ``"binary"`` or ``"multiclass"``.
+
+    Returns
+    -------
+    dict with keys: name, accuracy, precision, recall, f1_macro, auc_roc,
+         confusion_matrix, classification_report.
+    """
+    y_true = np.asarray(y_true)
+    y_pred = np.asarray(y_pred)
+
+    acc = accuracy_score(y_true, y_pred)
+    prec = precision_score(y_true, y_pred, average="macro", zero_division=0)
+    rec = recall_score(y_true, y_pred, average="macro", zero_division=0)
+    f1 = f1_score(y_true, y_pred, average="macro", zero_division=0)
+
+    auc = None
+    if y_proba is not None:
+        y_proba = np.asarray(y_proba)
+        try:
+            if task == "binary" and y_proba.ndim == 2:
+                auc = roc_auc_score(y_true, y_proba[:, 1])
+            else:
+                auc = roc_auc_score(y_true, y_proba, multi_class="ovr", average="macro")
+        except Exception:
+            auc = None
+
+    cm = confusion_matrix(y_true, y_pred)
+    target_names = class_names or [str(c) for c in sorted(np.unique(y_true))]
+    cr = classification_report(y_true, y_pred, target_names=target_names, zero_division=0)
+
+    return {
+        "name": name,
+        "accuracy": acc,
+        "precision": prec,
+        "recall": rec,
+        "f1_macro": f1,
+        "auc_roc": auc,
+        "confusion_matrix": cm,
+        "classification_report": cr,
+    }
+
+
+def print_results_banner(result: dict) -> None:
+    """Pretty-print a model's evaluation results."""
+    print(f"\n{'─' * 50}")
+    print(f"  {result['name']}")
+    print(f"{'─' * 50}")
+    print(f"  Accuracy  : {result['accuracy']:.4f}")
+    print(f"  Precision : {result['precision']:.4f}")
+    print(f"  Recall    : {result['recall']:.4f}")
+    print(f"  F1 (macro): {result['f1_macro']:.4f}")
+    if result["auc_roc"] is not None:
+        print(f"  AUC-ROC   : {result['auc_roc']:.4f}")
+    print(f"{'─' * 50}")
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Literature comparison table
+# ═════════════════════════════════════════════════════════════════════════════
+
+_LITERATURE_BASELINES = [
+    {"Method": "RF on URL features (Sahingoz 2019)", "Accuracy": 0.9798,
+     "F1 (macro)": 0.9793, "AUC-ROC": None, "Source": "Literature"},
+    {"Method": "XGBoost (Rao & Pais 2019)", "Accuracy": 0.9685,
+     "F1 (macro)": None, "AUC-ROC": 0.993, "Source": "Literature"},
+    {"Method": "URLNet CharCNN (Le 2018)", "Accuracy": 0.985,
+     "F1 (macro)": None, "AUC-ROC": 0.986, "Source": "Literature"},
+    {"Method": "LSTM (Bahnsen 2018)", "Accuracy": 0.987,
+     "F1 (macro)": None, "AUC-ROC": None, "Source": "Literature"},
+    {"Method": "Stacking CNN+LSTM+GRU (Nguyen 2021)", "Accuracy": 0.975,
+     "F1 (macro)": 0.972, "AUC-ROC": None, "Source": "Literature"},
+    {"Method": "Hybrid DNN+LSTM (Ozcan 2021)", "Accuracy": 0.964,
+     "F1 (macro)": None, "AUC-ROC": 0.973, "Source": "Literature"},
+    {"Method": "CharCNN (Aljofey 2022)", "Accuracy": 0.9675,
+     "F1 (macro)": 0.9671, "AUC-ROC": 0.991, "Source": "Literature"},
+]
+
+
+def build_comparison_table(
+    our_results: list[dict],
+    task: str = "binary",
+) -> pd.DataFrame:
+    """Build a comparison table of our results vs. literature baselines.
+
+    Parameters
+    ----------
+    our_results : list[dict]
+        Each dict is the output of ``evaluate_model()``.
+    task : str
+        ``"binary"`` or ``"multiclass"``.
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    rows = list(_LITERATURE_BASELINES)
+    for r in our_results:
+        rows.append({
+            "Method": r["name"],
+            "Accuracy": r["accuracy"],
+            "F1 (macro)": r["f1_macro"],
+            "AUC-ROC": r["auc_roc"],
+            "Source": "Ours",
+        })
+    df = pd.DataFrame(rows)
+    df = df.sort_values("Accuracy", ascending=False).reset_index(drop=True)
+    return df
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Plotting helpers
+# ═════════════════════════════════════════════════════════════════════════════
+
+def plot_accuracy_bar(
+    comparison_df: pd.DataFrame,
+    save_path: str | None = None,
+) -> plt.Figure:
+    """Horizontal bar chart of accuracies, colour-coded by source."""
+    fig, ax = plt.subplots(figsize=(10, max(5, len(comparison_df) * 0.45)))
+    colors = ["#1976D2" if s == "Ours" else "#BDBDBD"
+              for s in comparison_df["Source"]]
+    y = range(len(comparison_df))
+    ax.barh(y, comparison_df["Accuracy"], color=colors, edgecolor="white", height=0.6)
+    ax.set_yticks(y)
+    ax.set_yticklabels(comparison_df["Method"], fontsize=9)
+    ax.set_xlabel("Accuracy")
+    ax.set_title("Model Accuracy — Ours vs Literature")
+    ax.invert_yaxis()
+    ax.set_xlim(0.85, 1.01)
+    for i, v in enumerate(comparison_df["Accuracy"]):
+        if pd.notna(v):
+            ax.text(v + 0.002, i, f"{v:.4f}", va="center", fontsize=8)
+    plt.tight_layout()
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
+    return fig
+
+
+def plot_confusion_matrix(
+    cm: np.ndarray,
+    class_names: list[str],
+    title: str = "Confusion Matrix",
+    save_path: str | None = None,
+) -> plt.Figure:
+    """Plot an annotated confusion matrix heatmap."""
+    fig, ax = plt.subplots(figsize=(6, 5))
+    sns.heatmap(
+        cm, annot=True, fmt="d", cmap="Blues",
+        xticklabels=class_names, yticklabels=class_names, ax=ax,
+    )
+    ax.set_xlabel("Predicted")
+    ax.set_ylabel("True")
+    ax.set_title(title)
+    plt.tight_layout()
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
+    return fig
+
+
+def plot_feature_importance(
+    feature_names: list[str],
+    importances: np.ndarray,
+    top_n: int = 25,
+    title: str = "Feature Importance",
+    save_path: str | None = None,
+) -> plt.Figure:
+    """Horizontal bar chart of top-N feature importances."""
+    idx = np.argsort(importances)[-top_n:]
+    fig, ax = plt.subplots(figsize=(8, max(4, top_n * 0.3)))
+    ax.barh(
+        [feature_names[i] for i in idx],
+        importances[idx],
+        color="#1976D2", edgecolor="white",
+    )
+    ax.set_xlabel("Importance")
+    ax.set_title(title)
+    plt.tight_layout()
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches="tight")
+    return fig

urlmodel_info/feature_engineering.py

@@ -0,0 +1,347 @@
+"""
+URL Feature Engineering — 50+ lexical features for malicious URL detection.
+
+Features are grouped into 8 categories:
+  1. Length / structural           (7 features)
+  2. Character counts              (14 features)
+  3. Character ratios              (5 features)
+  4. Entropy / randomness          (2 features)
+  5. Boolean indicators            (10 features)
+  6. Domain / TLD signals          (6 features)
+  7. Suspicious-pattern scores     (5 features)
+  8. Path & query analysis         (5 features)
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from urllib.parse import urlparse, parse_qs
+
+import numpy as np
+import pandas as pd
+from joblib import Parallel, delayed
+
+try:
+    import tldextract
+except ImportError:
+    tldextract = None
+
+# ── Regex patterns (compiled once) ────────────────────────────────────────────
+_IP_RE = re.compile(
+    r"(?:^|[/@])(\d{1,3}\.){3}\d{1,3}(?:[:/]|$)"
+)
+_HEX_RE = re.compile(r"%[0-9a-fA-F]{2}")
+_SHORTENERS = frozenset([
+    "bit.ly", "goo.gl", "tinyurl.com", "ow.ly", "t.co", "is.gd",
+    "buff.ly", "adf.ly", "tiny.cc", "lnkd.in", "rb.gy", "cutt.ly",
+    "shorturl.at", "rebrand.ly",
+])
+_SUSPICIOUS_TLDS = frozenset([
+    "tk", "ml", "ga", "cf", "gq", "xyz", "top", "pw", "cc",
+    "club", "work", "date", "racing", "stream", "download",
+    "win", "bid", "icu", "buzz", "monster",
+])
+_SUSPICIOUS_EXT = re.compile(
+    r"\.(exe|zip|rar|scr|bat|cmd|js|vbs|ps1|dll|msi|apk|dmg|iso|php|cgi)(\?|$)",
+    re.IGNORECASE,
+)
+_PHISHING_KW = re.compile(
+    r"(login|signin|verify|account|update|secure|bank|confirm|password|"
+    r"credential|suspend|alert|notification|wallet|paypal|apple|microsoft|"
+    r"amazon|netflix|facebook|instagram|whatsapp|dropbox|google|icloud)",
+    re.IGNORECASE,
+)
+_BRAND_NAMES = [
+    "google", "facebook", "apple", "amazon", "microsoft", "netflix",
+    "paypal", "instagram", "whatsapp", "dropbox", "linkedin", "twitter",
+    "yahoo", "ebay", "chase", "wellsfargo", "bankofamerica", "citibank",
+    "hsbc", "dhl", "fedex", "usps",
+]
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Feature extraction for a single URL
+# ═════════════════════════════════════════════════════════════════════════════
+
+def _entropy(s: str) -> float:
+    """Shannon entropy of a string."""
+    if not s:
+        return 0.0
+    cnt = Counter(s)
+    length = len(s)
+    return -sum((c / length) * math.log2(c / length) for c in cnt.values())
+
+
+def _extract_one(url: str) -> dict:
+    """Extract all features from a single URL string (fully exception-safe)."""
+    try:
+        return _extract_one_inner(url)
+    except Exception:
+        # Return a row of zeros for truly broken URLs
+        return {name: 0 for name in URLFeatureExtractor._NAMES}
+
+
+def _extract_one_inner(url: str) -> dict:
+    """Core logic — may raise on malformed URLs."""
+    url = str(url).strip()
+
+    try:
+        parsed = urlparse(url if "://" in url else f"http://{url}")
+    except Exception:
+        try:
+            safe = url.replace("[", "").replace("]", "")
+            parsed = urlparse(safe if "://" in safe else f"http://{safe}")
+        except Exception:
+            parsed = urlparse("http://invalid")
+
+    try:
+        hostname = parsed.hostname or ""
+    except Exception:
+        hostname = ""
+    path = parsed.path or ""
+    query = parsed.query or ""
+    fragment = parsed.fragment or ""
+    scheme = (parsed.scheme or "").lower()
+
+    # TLD extraction
+    if tldextract is not None:
+        ext = tldextract.extract(url)
+        domain = ext.domain
+        tld = ext.suffix
+        subdomain = ext.subdomain
+    else:
+        domain = hostname.split(".")[-2] if hostname.count(".") >= 1 else hostname
+        tld = hostname.split(".")[-1] if "." in hostname else ""
+        subdomain = ".".join(hostname.split(".")[:-2]) if hostname.count(".") >= 2 else ""
+
+    url_lower = url.lower()
+
+    # ── 1. Length / structural ────────────────────────────────────────────
+    url_length = len(url)
+    hostname_length = len(hostname)
+    domain_length = len(domain)
+    path_length = len(path)
+    query_length = len(query)
+    fragment_length = len(fragment)
+    tld_length = len(tld)
+
+    # ── 2. Character counts ──────────────────────────────────────────────
+    num_dots = url.count(".")
+    num_hyphens = url.count("-")
+    num_underscores = url.count("_")
+    num_slashes = url.count("/")
+    num_at_signs = url.count("@")
+    num_ampersands = url.count("&")
+    num_equals = url.count("=")
+    num_question_marks = url.count("?")
+    num_percent = url.count("%")
+    num_tilde = url.count("~")
+    num_digits = sum(c.isdigit() for c in url)
+    num_letters = sum(c.isalpha() for c in url)
+    num_special = sum(not c.isalnum() and c not in ":/." for c in url)
+    num_params = len(parse_qs(query))
+
+    # ── 3. Character ratios ──────────────────────────────────────────────
+    safe_len = max(url_length, 1)
+    digit_ratio = num_digits / safe_len
+    letter_ratio = num_letters / safe_len
+    special_ratio = num_special / safe_len
+    uppercase_ratio = sum(c.isupper() for c in url) / safe_len
+    digit_letter_ratio = num_digits / max(num_letters, 1)
+
+    # ── 4. Entropy ───────────────────────────────────────────────────────
+    url_entropy = _entropy(url)
+    domain_entropy = _entropy(hostname)
+
+    # ── 5. Boolean indicators ────────────────────────────────────────────
+  
+    has_ip = int(bool(_IP_RE.search(url)))
+    has_https = int(scheme == "https")
+    has_http = int(scheme == "http")
+    has_www = int("www." in url_lower)
+    try:
+        _port = parsed.port
+    except (ValueError, TypeError):
+        _port = None
+    has_port = int(_port is not None and _port not in (80, 443))
+    has_at_symbol = int("@" in url)
+    is_shortened = int(any(s in url_lower for s in _SHORTENERS))
+    has_double_slash_redirect = int("//" in path)
+    has_punycode = int("xn--" in url_lower)
+    has_hex_encoding = int(bool(_HEX_RE.search(url)))
+
+    # ── 6. Domain / TLD signals ──────────────────────────────────────────
+    num_subdomains = subdomain.count(".") + 1 if subdomain else 0
+    subdomain_length = len(subdomain)
+    domain_token_count = len(re.split(r"[.\-_]", hostname))
+    has_suspicious_tld = int(tld.lower() in _SUSPICIOUS_TLDS)
+    domain_has_digits = int(any(c.isdigit() for c in domain))
+    domain_hyphen_count = domain.count("-")
+
+    # ── 7. Suspicious-pattern scores ─────────────────────────────────────
+    phishing_keyword_count = len(_PHISHING_KW.findall(url_lower))
+    brand_count = sum(1 for b in _BRAND_NAMES if b in url_lower)
+    has_suspicious_ext = int(bool(_SUSPICIOUS_EXT.search(url_lower)))
+    # Brand in subdomain but not in registered domain → likely phishing
+    brand_in_subdomain = int(
+        any(b in subdomain.lower() for b in _BRAND_NAMES) and
+        not any(b in domain.lower() for b in _BRAND_NAMES)
+    ) if subdomain else 0
+    suspicious_word_ratio = phishing_keyword_count / max(
+        len(re.findall(r"[a-zA-Z]+", url)), 1
+    )
+
+    # ── 8. Path & query analysis ─────────────────────────────────────────
+    path_tokens = [t for t in path.split("/") if t]
+    path_depth = len(path_tokens)
+    longest_path_token = max((len(t) for t in path_tokens), default=0)
+    avg_path_token_len = (
+        sum(len(t) for t in path_tokens) / len(path_tokens) if path_tokens else 0.0
+    )
+    max_consecutive_digits = max(
+        (len(m.group()) for m in re.finditer(r"\d+", url)), default=0
+    )
+    path_entropy = _entropy(path)
+
+    return {
+        # 1. Length
+        "url_length": url_length,
+        "hostname_length": hostname_length,
+        "domain_length": domain_length,
+        "path_length": path_length,
+        "query_length": query_length,
+        "fragment_length": fragment_length,
+        "tld_length": tld_length,
+        # 2. Counts
+        "num_dots": num_dots,
+        "num_hyphens": num_hyphens,
+        "num_underscores": num_underscores,
+        "num_slashes": num_slashes,
+        "num_at_signs": num_at_signs,
+        "num_ampersands": num_ampersands,
+        "num_equals": num_equals,
+        "num_question_marks": num_question_marks,
+        "num_percent": num_percent,
+        "num_tilde": num_tilde,
+        "num_digits": num_digits,
+        "num_letters": num_letters,
+        "num_special": num_special,
+        "num_params": num_params,
+        # 3. Ratios
+        "digit_ratio": digit_ratio,
+        "letter_ratio": letter_ratio,
+        "special_ratio": special_ratio,
+        "uppercase_ratio": uppercase_ratio,
+        "digit_letter_ratio": digit_letter_ratio,
+        # 4. Entropy
+        "url_entropy": url_entropy,
+        "domain_entropy": domain_entropy,
+        # 5. Booleans
+        "has_ip": has_ip,
+        "has_https": has_https,
+        "has_http": has_http,
+        "has_www": has_www,
+        "has_port": has_port,
+        "has_at_symbol": has_at_symbol,
+        "is_shortened": is_shortened,
+        "has_double_slash_redirect": has_double_slash_redirect,
+        "has_punycode": has_punycode,
+        "has_hex_encoding": has_hex_encoding,
+        # 6. Domain
+        "num_subdomains": num_subdomains,
+        "subdomain_length": subdomain_length,
+        "domain_token_count": domain_token_count,
+        "has_suspicious_tld": has_suspicious_tld,
+        "domain_has_digits": domain_has_digits,
+        "domain_hyphen_count": domain_hyphen_count,
+        # 7. Suspicious
+        "phishing_keyword_count": phishing_keyword_count,
+        "brand_count": brand_count,
+        "has_suspicious_ext": has_suspicious_ext,
+        "brand_in_subdomain": brand_in_subdomain,
+        "suspicious_word_ratio": suspicious_word_ratio,
+        # 8. Path / query
+        "path_depth": path_depth,
+        "longest_path_token": longest_path_token,
+        "avg_path_token_len": avg_path_token_len,
+        "max_consecutive_digits": max_consecutive_digits,
+        "path_entropy": path_entropy,
+    }
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Public API
+# ═════════════════════════════════════════════════════════════════════════════
+
+class URLFeatureExtractor:
+    """Parallel URL feature extractor producing a DataFrame of 54 features."""
+
+    _NAMES = list(_extract_one("http://example.com").keys())
+
+    def __init__(self, n_jobs: int = -1):
+        self.n_jobs = n_jobs
+
+    @staticmethod
+    def feature_names() -> list[str]:
+        return list(URLFeatureExtractor._NAMES)
+
+    def transform(
+        self,
+        urls: pd.Series | list | np.ndarray,
+        verbose: bool = True,
+    ) -> pd.DataFrame:
+        """Extract features for a sequence of URLs.
+
+        Parameters
+        ----------
+        urls : array-like of str
+        verbose : bool
+            Print progress info.
+
+        Returns
+        -------
+        pd.DataFrame with len(urls) rows × 54 feature columns.
+        """
+        urls = list(urls)
+        if verbose:
+            print(f"  Extracting features for {len(urls):,} URLs (n_jobs={self.n_jobs}) …")
+
+        rows = Parallel(n_jobs=self.n_jobs, backend="loky", batch_size=2048)(
+            delayed(_extract_one)(u) for u in urls
+        )
+        df = pd.DataFrame(rows, columns=self._NAMES)
+        # Ensure float32 for memory efficiency
+        df = df.astype(np.float32)
+        if verbose:
+            print(f"  → {df.shape[0]:,} rows × {df.shape[1]} features")
+        return df
+
+
+def featurize_dataset(csv_path: str, url_col: str = "url", label_col: str = "type",
+                      n_jobs: int = -1) -> pd.DataFrame:
+    """Load a CSV, extract features, and attach URLs + labels.
+
+    Parameters
+    ----------
+    csv_path : str
+        Path to CSV with at least `url_col` and `label_col` columns.
+    url_col : str
+        Column containing URL strings.
+    label_col : str
+        Column containing class labels.
+    n_jobs : int
+        Parallelism for feature extraction.
+
+    Returns
+    -------
+    pd.DataFrame with columns: url, label, <54 features>
+    """
+    df_raw = pd.read_csv(csv_path)
+    extractor = URLFeatureExtractor(n_jobs=n_jobs)
+    feat_df = extractor.transform(df_raw[url_col], verbose=True)
+
+    feat_df.insert(0, "url", df_raw[url_col].values)
+    feat_df["label"] = df_raw[label_col].values
+    return feat_df