Initial APK scanner microservice deployment

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app/ ./app/
+COPY rules/ ./rules/
+COPY models/ ./models/
+COPY main.py .
+
+RUN useradd -m -u 1000 scanner && chown -R scanner /app
+USER scanner
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health')"
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "2"]

README.md

@@ -1,10 +1,22 @@
 ---
-title: Apk Scanner
-emoji: 🐨
-colorFrom: purple
-colorTo: indigo
+title: ShieldYONO APK Scanner
+emoji: 🛡️
+colorFrom: blue
+colorTo: red
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ShieldYONO APK Scanner
+
+FastAPI microservice for Android APK threat analysis.
+
+## Endpoints
+- `GET /health` — engine status
+- `POST /analyze` — upload APK for analysis (multipart/form-data: `file`, optional `package_name`, `app_label`)
+
+## Engines
+- **YARA** — signature-based malware rules (android_banker, otp_stealer, rat)
+- **Androguard** — static manifest + permission analysis
+- **ML classifier** — gradient-boosted model (disabled in free tier)

app/config.py

@@ -0,0 +1,107 @@
+"""
+ShieldYONO Threat Intelligence Backend
+config.py — Central configuration via Pydantic BaseSettings
+
+All values can be overridden via environment variables or a .env file.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import List
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # ── Application ───────────────────────────────────────────────────────────
+    APP_NAME: str = "ShieldYONO Threat Intelligence API"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+
+    # ── API ───────────────────────────────────────────────────────────────────
+    API_V1_PREFIX: str = "/api/v1"
+    ALLOWED_ORIGINS: List[str] = ["*"]
+
+    # ── PostgreSQL ─────────────────────────────────────────────────────────────
+    POSTGRES_HOST: str = "localhost"
+    POSTGRES_PORT: int = 5432
+    POSTGRES_DB: str = "shieldyono"
+    POSTGRES_USER: str = "shieldyono"
+    POSTGRES_PASSWORD: str = "shieldyono_secret"
+
+    @property
+    def DATABASE_URL(self) -> str:  # noqa: N802
+        return (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    @property
+    def SYNC_DATABASE_URL(self) -> str:  # noqa: N802
+        return (
+            f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    # ── Redis ─────────────────────────────────────────────────────────────────
+    REDIS_HOST: str = "localhost"
+    REDIS_PORT: int = 6379
+    REDIS_DB: int = 0
+    REDIS_PASSWORD: str = ""
+
+    @property
+    def REDIS_URL(self) -> str:  # noqa: N802
+        if self.REDIS_PASSWORD:
+            return f"redis://:{self.REDIS_PASSWORD}@{self.REDIS_HOST}:{self.REDIS_PORT}/{self.REDIS_DB}"
+        return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/{self.REDIS_DB}"
+
+    # ── Celery ────────────────────────────────────────────────────────────────
+    CELERY_TASK_SERIALIZER: str = "json"
+    CELERY_RESULT_SERIALIZER: str = "json"
+    CELERY_TASK_TRACK_STARTED: bool = True
+    CELERY_TASK_TIME_LIMIT: int = 300  # seconds
+
+    # ── File Upload ───────────────────────────────────────────────────────────
+    MAX_APK_SIZE_MB: int = 100
+    UPLOAD_DIR: str = "/tmp/shieldyono/uploads"
+
+    # ── MobSF ─────────────────────────────────────────────────────────────────
+    MOBSF_URL: str = "http://localhost:8000"
+    MOBSF_API_KEY: str = "mock_api_key"
+    MOBSF_ENABLED: bool = False  # Toggle to True when MobSF container is up
+
+    # ── ML Engine ─────────────────────────────────────────────────────────────
+    ML_MODEL_PATH: str = "models/apk_classifier.pkl"
+    ML_ENABLED: bool = False  # Toggle to True when real model is present
+
+    # ── Behaviour Intelligence Engine ─────────────────────────────────────────
+    BEHAVIOUR_MODEL_PATH: str = "models/behaviour_model.pkl"
+    # Falls back to ml/behaviour_intelligence/behaviour_model.pkl automatically in dev;
+    # copy that file to backend/models/ for production deployment.
+
+    # ── YARA ──────────────────────────────────────────────────────────────────
+    YARA_RULES_DIR: str = "rules"   # resolved relative to backend/ root by YaraEngine
+    YARA_ENABLED: bool = True
+
+    # ── APK Scanner microservice ──────────────────────────────────────────────
+    # Local docker-compose:  http://apk-scanner:7860
+    # HF Spaces production:  https://your-space.hf.space
+    APK_SCANNER_URL: str = ""
+
+    # ── Analysis Thresholds ───────────────────────────────────────────────────
+    MALWARE_PROBABILITY_THRESHOLD: float = 0.7
+    SUSPICIOUS_PROBABILITY_THRESHOLD: float = 0.4
+    HIGH_RISK_LOCAL_SCORE: float = 70.0
+
+    # ── Cache TTL (seconds) ───────────────────────────────────────────────────
+    ANALYSIS_CACHE_TTL: int = 3600  # 1 hour – same hash → cached result
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "case_sensitive": True}
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Cached singleton – import and call this everywhere."""
+    return Settings()

app/services/apk_intelligence/analyzer.py

@@ -0,0 +1,270 @@
+"""
+services/apk_intelligence/analyzer.py
+— Orchestrates all analysis engines for a single APK submission.
+
+This is the main entry point called by the API route and the Celery task.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Optional
+
+import aiofiles
+
+from app.config import get_settings
+from app.repositories.apk_repository import ApkRepository
+from app.services.apk_intelligence.engines.androguard_engine import run_androguard_analysis
+from app.services.apk_intelligence.engines.apkid_engine import run_apkid_analysis
+from app.services.apk_intelligence.engines.ml_engine import run_ml_analysis
+from app.services.apk_intelligence.engines.mobsf_client import run_mobsf_analysis
+from app.services.apk_intelligence.engines.yara_engine import run_yara_scan
+from app.services.apk_intelligence.models import (
+    ApkAnalysisRequest,
+    EngineResults,
+    ScanStep,
+    ThreatIntelligenceResponse,
+)
+from app.services.apk_intelligence.threat_explainer import run_threat_explanation
+from app.services.identity.impersonation_engine import run_impersonation_check
+from app.services.risk.fusion import fuse_results
+from app.utils import fire_and_forget
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+_apk_repo = ApkRepository()
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def _derive_apk_name(package_name: str) -> str:
+    """Derive a human-friendly app name from a reverse-DNS package name."""
+    parts = [p for p in package_name.split(".") if p]
+    if not parts:
+        return package_name
+    last = parts[-1].replace("_", " ")
+    return " ".join(w.capitalize() for w in last.split())
+
+
+def _build_scan_pipeline(
+    engine_results: EngineResults,
+    metadata: ApkAnalysisRequest,
+) -> list[ScanStep]:
+    """Build the per-engine scan steps for the Flutter UI timeline."""
+    steps: list[ScanStep] = []
+
+    # 1. Certificate Verification
+    cert_detail = (
+        f"Certificate {metadata.certificateHash[:16]}… verified"
+        if metadata.certificateHash
+        else "App signature checked"
+    )
+    steps.append(ScanStep(engine="Certificate Verification", status="PASSED", details=cert_detail))
+
+    # 2. Androguard
+    ag = engine_results.androguard
+    if ag.error:
+        steps.append(ScanStep(engine="Androguard", status="ERROR", details=ag.error[:80]))
+    else:
+        perm_count = len(ag.permissions) if ag.permissions else len(metadata.permissions)
+        detail = f"{perm_count} permissions analysed"
+        if ag.is_obfuscated:
+            detail += ", obfuscation detected"
+        if ag.dynamic_code_loading:
+            detail += ", dynamic code loading"
+        steps.append(ScanStep(engine="Androguard", status="COMPLETED", details=detail))
+
+    # 3. YARA
+    yara = engine_results.yara
+    if yara.error:
+        steps.append(ScanStep(engine="YARA", status="ERROR", details=yara.error[:80]))
+    elif yara.matched and yara.rule_names:
+        rules = ", ".join(yara.rule_names[:3])
+        suffix = f" (+{len(yara.rule_names) - 3} more)" if len(yara.rule_names) > 3 else ""
+        steps.append(ScanStep(engine="YARA", status="THREAT_FOUND", details=f"{rules}{suffix} matched"))
+    else:
+        steps.append(ScanStep(engine="YARA", status="COMPLETED", details="No malicious signatures matched"))
+
+    # 4. APKiD
+    apkid = engine_results.apkid
+    if apkid.error:
+        steps.append(ScanStep(engine="APKiD", status="ERROR", details=apkid.error[:80]))
+    elif apkid.is_packed:
+        packers = ", ".join(apkid.packers[:2])
+        steps.append(ScanStep(engine="APKiD", status="COMPLETED", details=f"Obfuscation detected: {packers}"))
+    else:
+        steps.append(ScanStep(engine="APKiD", status="COMPLETED", details="No packers or obfuscators detected"))
+
+    # 5. ML Model
+    ml = engine_results.ml
+    if ml.error:
+        steps.append(ScanStep(engine="ML Model", status="ERROR", details=ml.error[:80]))
+    else:
+        prob_pct = int(ml.malware_probability * 100)
+        detail = f"{prob_pct}% malware probability"
+        if ml.threat_family:
+            detail += f" (family: {ml.threat_family})"
+        steps.append(ScanStep(engine="ML Model", status="COMPLETED", details=detail))
+
+    # 6. MobSF (only when it actually ran)
+    mobsf = engine_results.mobsf
+    if mobsf.available:
+        if mobsf.error:
+            steps.append(ScanStep(engine="MobSF", status="ERROR", details=mobsf.error[:80]))
+        elif mobsf.score > 70:
+            steps.append(ScanStep(
+                engine="MobSF",
+                status="THREAT_FOUND",
+                details=f"High risk: {mobsf.score}/100 danger score",
+            ))
+        else:
+            steps.append(ScanStep(
+                engine="MobSF",
+                status="COMPLETED",
+                details=f"Static analysis: {mobsf.score}/100 danger score",
+            ))
+
+    return steps
+
+
+class APKAnalyzer:
+    """
+    Orchestrates multi-engine APK threat intelligence analysis.
+
+    Usage:
+        analyzer = APKAnalyzer()
+        result = await analyzer.analyze(apk_bytes, metadata)
+    """
+
+    async def analyze(
+        self,
+        apk_bytes: bytes,
+        metadata: ApkAnalysisRequest,
+        analysis_id: Optional[str] = None,
+    ) -> ThreatIntelligenceResponse:
+        """
+        Run all analysis engines concurrently and fuse into a final verdict.
+
+        Args:
+            apk_bytes:    Raw APK file content.
+            metadata:     Metadata from the Android SDK (package name, permissions, etc.).
+            analysis_id:  Optional UUID for tracing (auto-generated if omitted).
+
+        Returns:
+            ThreatIntelligenceResponse – wire-format compatible with the Android SDK.
+        """
+        analysis_id = analysis_id or str(uuid.uuid4())
+        logger.info(
+            "[%s] Starting analysis for package=%s, size=%d bytes",
+            analysis_id, metadata.packageName, len(apk_bytes),
+        )
+
+        # Save APK to a temp file (engines need a file path)
+        apk_path = await self._save_apk(apk_bytes, analysis_id)
+
+        try:
+            # Phase 1: engines that feed ML feature extraction
+            (
+                yara_result,
+                androguard_result,
+                apkid_result,
+            ) = await asyncio.gather(
+                run_yara_scan(apk_path),
+                run_androguard_analysis(apk_path, metadata.permissions),
+                run_apkid_analysis(apk_path),
+            )
+
+            # Phase 2: ML (uses phase-1 results) + independent engines concurrently
+            (
+                ml_result,
+                mobsf_result,
+                impersonation_result,
+            ) = await asyncio.gather(
+                run_ml_analysis(androguard_result, yara_result, apkid_result),
+                run_mobsf_analysis(apk_path, metadata.packageName),
+                run_impersonation_check(
+                    package_name=metadata.packageName,
+                    app_name=metadata.appName,
+                    certificate_hash=metadata.certificateHash,
+                ),
+            )
+
+            engine_results = EngineResults(
+                yara=yara_result,
+                androguard=androguard_result,
+                apkid=apkid_result,
+                ml=ml_result,
+                mobsf=mobsf_result,
+                impersonation=impersonation_result,
+            )
+
+            response = fuse_results(
+                engine_results=engine_results,
+                local_risk=metadata.localRisk,
+                package_name=metadata.packageName,
+            )
+
+            response.explanation = run_threat_explanation(engine_results, response)
+
+            # Populate extended UI fields (backward-compatible)
+            response.package_name = metadata.packageName
+            response.apk_name = metadata.appName or _derive_apk_name(metadata.packageName)
+            response.risk_score = response.malware_probability
+            response.scan_pipeline = _build_scan_pipeline(engine_results, metadata)
+            if response.explanation and response.explanation.analyst_summary.recommended_actions:
+                response.recommendations = list(
+                    response.explanation.analyst_summary.recommended_actions[:5]
+                )
+
+            logger.info(
+                "[%s] Analysis complete: verdict=%s, probability=%.3f, threat_category=%s",
+                analysis_id, response.verdict, response.malware_probability,
+                response.explanation.analyst_summary.threat_category,
+            )
+
+            fire_and_forget(_apk_repo.save_scan(metadata, response))
+
+            return response
+
+        except Exception as exc:
+            logger.exception("[%s] Analysis failed: %s", analysis_id, exc)
+            # Return an UNKNOWN verdict rather than crashing the endpoint
+            return ThreatIntelligenceResponse(
+                verdict="UNKNOWN",  # type: ignore[arg-type]
+                malware_probability=0.0,
+                yara_matches=[],
+                mobsf_score=-1,
+                threat_family=None,
+                explanations=[f"Analysis error: {exc}"],
+            )
+
+        finally:
+            # Always clean up temp file
+            await self._cleanup_apk(apk_path)
+
+    async def _save_apk(self, apk_bytes: bytes, analysis_id: str) -> Path:
+        """Persist APK bytes to a temp file and return the path."""
+        upload_dir = Path(settings.UPLOAD_DIR)
+        upload_dir.mkdir(parents=True, exist_ok=True)
+
+        apk_path = upload_dir / f"{analysis_id}.apk"
+        async with aiofiles.open(apk_path, "wb") as f:
+            await f.write(apk_bytes)
+
+        logger.debug("[%s] APK saved to %s", analysis_id, apk_path)
+        return apk_path
+
+    async def _cleanup_apk(self, apk_path: Path) -> None:
+        """Remove temp APK file after analysis."""
+        try:
+            if apk_path.exists():
+                apk_path.unlink()
+                logger.debug("Cleaned up %s", apk_path)
+        except Exception as exc:
+            logger.warning("Failed to clean up APK file %s: %s", apk_path, exc)

app/services/apk_intelligence/decision_engine.py

@@ -0,0 +1,138 @@
+"""
+services/apk_intelligence/decision_engine.py
+— Policy-based decision layer on top of the fused threat intelligence.
+
+The decision engine translates a ThreatIntelligenceResponse into an
+actionable recommendation for the banking app:
+  - BLOCK:   Do not allow the app to proceed; show a threat alert.
+  - WARN:    Allow with a strong warning to the user.
+  - MONITOR: Allow but flag for security team review.
+  - ALLOW:   No action required.
+"""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+from app.services.apk_intelligence.models import ThreatIntelligenceResponse, Verdict
+
+logger = logging.getLogger(__name__)
+
+
+class Action(str, Enum):
+    BLOCK = "BLOCK"
+    WARN = "WARN"
+    MONITOR = "MONITOR"
+    ALLOW = "ALLOW"
+
+
+class Decision(BaseModel):
+    """Policy decision for a scanned APK."""
+    action: Action
+    reason: str
+    risk_level: str  # "CRITICAL" | "HIGH" | "MEDIUM" | "LOW"
+    recommended_message: str  # User-facing message for the banking app
+
+
+class DecisionEngine:
+    """
+    Converts a ThreatIntelligenceResponse into a structured Decision.
+
+    Policy rules (evaluated in priority order):
+      1. MALICIOUS verdict → BLOCK
+      2. YARA match present → BLOCK (known malware signature)
+      3. Impersonation detected (in explanations) → BLOCK
+      4. SUSPICIOUS verdict → WARN
+      5. Malware probability > 0.4 → WARN
+      6. MobSF score > 80 → MONITOR
+      7. Otherwise → ALLOW
+    """
+
+    def decide(self, result: ThreatIntelligenceResponse) -> Decision:
+        """Evaluate policy rules and return the appropriate decision."""
+
+        # Rule 1: Confirmed malware
+        if result.verdict == Verdict.MALICIOUS:
+            family = result.threat_family or "unknown family"
+            return Decision(
+                action=Action.BLOCK,
+                reason=f"Confirmed malware detected: {family}",
+                risk_level="CRITICAL",
+                recommended_message=(
+                    "This application has been identified as malware "
+                    f"({family}). It has been blocked to protect your account."
+                ),
+            )
+
+        # Rule 2: YARA signature match
+        if result.yara_matches:
+            rules = ", ".join(result.yara_matches[:3])
+            return Decision(
+                action=Action.BLOCK,
+                reason=f"Known malware signature detected: {rules}",
+                risk_level="CRITICAL",
+                recommended_message=(
+                    "A known malicious pattern was detected in this application. "
+                    "It has been blocked for your security."
+                ),
+            )
+
+        # Rule 3: Banking app impersonation
+        if any("impersonat" in exp.lower() for exp in result.explanations):
+            return Decision(
+                action=Action.BLOCK,
+                reason="Banking app impersonation detected",
+                risk_level="HIGH",
+                recommended_message=(
+                    "This application appears to be impersonating a legitimate banking app. "
+                    "It has been blocked. Please download official apps from trusted stores only."
+                ),
+            )
+
+        # Rule 4: Suspicious verdict
+        if result.verdict == Verdict.SUSPICIOUS:
+            return Decision(
+                action=Action.WARN,
+                reason="Suspicious indicators detected",
+                risk_level="HIGH",
+                recommended_message=(
+                    "This application exhibits suspicious behaviour. "
+                    "We recommend removing it before using banking services."
+                ),
+            )
+
+        # Rule 5: High malware probability without confirmed verdict
+        if result.malware_probability > 0.4:
+            return Decision(
+                action=Action.WARN,
+                reason=f"Elevated malware probability ({result.malware_probability:.0%})",
+                risk_level="MEDIUM",
+                recommended_message=(
+                    "An application on your device has been flagged as potentially dangerous. "
+                    "Please review your installed apps."
+                ),
+            )
+
+        # Rule 6: High MobSF score (static analysis flags)
+        if result.mobsf_score > 80:
+            return Decision(
+                action=Action.MONITOR,
+                reason=f"High static analysis risk score ({result.mobsf_score}/100)",
+                risk_level="MEDIUM",
+                recommended_message=(
+                    "An application on your device has unusual permissions or code patterns. "
+                    "It is being monitored."
+                ),
+            )
+
+        # Rule 7: Clean
+        return Decision(
+            action=Action.ALLOW,
+            reason="No significant threats detected",
+            risk_level="LOW",
+            recommended_message="No threats detected. You may proceed safely.",
+        )

app/services/apk_intelligence/engines/androguard_engine.py

@@ -0,0 +1,373 @@
+"""
+engines/androguard_engine.py
+— Static analysis of APK structure using Androguard.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import hashlib
+import logging
+from pathlib import Path
+from typing import Optional
+
+from app.services.apk_intelligence.models import (
+    AndroguardResult,
+    ApkComponents,
+    ApkIdentity,
+    MlFeatures,
+    SecurityFeatures,
+)
+
+logger = logging.getLogger(__name__)
+
+_ANALYSIS_TIMEOUT = 60  # seconds
+
+_SMS_PERMISSIONS = frozenset({
+    "android.permission.READ_SMS",
+    "android.permission.RECEIVE_SMS",
+    "android.permission.SEND_SMS",
+})
+
+_HIGH_RISK_PERMISSIONS = frozenset({
+    "android.permission.READ_SMS",
+    "android.permission.SEND_SMS",
+    "android.permission.RECEIVE_SMS",
+    "android.permission.RECORD_AUDIO",
+    "android.permission.PROCESS_OUTGOING_CALLS",
+    "android.permission.BIND_ACCESSIBILITY_SERVICE",
+    "android.permission.BIND_DEVICE_ADMIN",
+})
+
+_SUSPICIOUS_RECEIVER_ACTIONS = frozenset({
+    "android.provider.Telephony.SMS_RECEIVED",
+    "android.provider.Telephony.SMS_DELIVER",
+    "android.intent.action.BOOT_COMPLETED",
+    "android.intent.action.MY_PACKAGE_REPLACED",
+    "android.net.conn.CONNECTIVITY_CHANGE",
+})
+
+_ANDROID_NS = "http://schemas.android.com/apk/res/android"
+
+
+class AndroguardEngine:
+    """
+    Static APK analysis using Androguard.
+
+    Runs synchronous Androguard in a thread-pool executor to remain async-compatible.
+    Degrades gracefully when Androguard is unavailable or the APK is corrupted —
+    it never propagates exceptions to the caller.
+    """
+
+    async def analyze(self, apk_path: Path) -> AndroguardResult:
+        """
+        Analyze an APK file and return structured intelligence.
+
+        Args:
+            apk_path: Path to the APK file on disk.
+
+        Returns:
+            AndroguardResult with identity, permissions, components, and security indicators.
+            On any failure the result carries a non-None ``error`` field.
+        """
+        if not apk_path.exists():
+            logger.warning("Androguard: APK file not found: %s", apk_path)
+            return AndroguardResult(error="APK file not found")
+
+        try:
+            loop = asyncio.get_running_loop()
+            return await asyncio.wait_for(
+                loop.run_in_executor(
+                    None,
+                    functools.partial(self._sync_analyze, apk_path),
+                ),
+                timeout=_ANALYSIS_TIMEOUT,
+            )
+        except asyncio.TimeoutError:
+            logger.error(
+                "Androguard: analysis timed out after %ds for %s",
+                _ANALYSIS_TIMEOUT, apk_path,
+            )
+            return AndroguardResult(error=f"Analysis timed out after {_ANALYSIS_TIMEOUT}s")
+        except Exception as exc:
+            logger.exception("Androguard: unexpected failure for %s", apk_path)
+            return AndroguardResult(error=str(exc))
+
+    # ── Synchronous core (runs in executor) ────────────────────────────────────
+
+    def _sync_analyze(self, apk_path: Path) -> AndroguardResult:
+        try:
+            from androguard.core.apk import APK  # type: ignore[import-untyped]
+        except ImportError:
+            logger.warning("Androguard not installed — returning mock result")
+            return _mock_result(apk_path)
+
+        logger.debug("Androguard: parsing %s", apk_path)
+
+        try:
+            apk = APK(str(apk_path))
+        except Exception as exc:
+            logger.warning("Androguard: cannot parse %s — %s", apk_path, exc)
+            return AndroguardResult(error=f"Invalid APK: {exc}")
+
+        identity = self._extract_identity(apk)
+        permissions = self._extract_permissions(apk)
+        components = self._extract_components(apk)
+        security_features, suspicious_activities = self._extract_security(
+            apk, permissions, components
+        )
+        ml_features = _build_ml_features(permissions, components)
+
+        perm_set = set(permissions)
+        is_obfuscated = _has_obfuscated_names(components)
+        native_code = bool(list(apk.get_libraries()))
+        dynamic_code_loading = (
+            "android.permission.REQUEST_INSTALL_PACKAGES" in perm_set
+            or sum(1 for _ in apk.get_dex_names()) > 1
+        )
+
+        logger.info(
+            "Androguard: pkg=%s perms=%d activities=%d services=%d receivers=%d "
+            "exported=%d obfuscated=%s native=%s",
+            identity.package,
+            len(permissions),
+            len(components.activities),
+            len(components.services),
+            len(components.receivers),
+            security_features.exported_count,
+            is_obfuscated,
+            native_code,
+        )
+
+        return AndroguardResult(
+            is_obfuscated=is_obfuscated,
+            native_code=native_code,
+            dynamic_code_loading=dynamic_code_loading,
+            suspicious_activities=suspicious_activities,
+            identity=identity,
+            permissions=permissions,
+            components=components,
+            security_features=security_features,
+            ml_features=ml_features,
+        )
+
+    # ── Identity ───────────────────────────────────────────────────────────────
+
+    def _extract_identity(self, apk) -> ApkIdentity:
+        return ApkIdentity(
+            package=_safe_str(apk.get_package()),
+            app_name=_safe_str(apk.get_app_name()),
+            version_name=_safe_str(apk.get_androidversion_name()),
+            version_code=_safe_str(apk.get_androidversion_code()),
+            certificate_sha256=self._extract_cert_sha256(apk),
+        )
+
+    def _extract_cert_sha256(self, apk) -> Optional[str]:
+        """
+        Try each signing scheme (V3 → V2 → V1) and return the SHA-256
+        fingerprint of the first certificate found.
+        """
+        # V3 / V31
+        for getter in (
+            getattr(apk, "get_certificates_der_v31", None),
+            getattr(apk, "get_certificates_der_v3", None),
+            getattr(apk, "get_certificates_der_v2", None),
+        ):
+            if getter is None:
+                continue
+            try:
+                certs = getter()
+                if certs:
+                    return hashlib.sha256(certs[0]).hexdigest()
+            except Exception:
+                continue
+
+        # V1 — iterate META-INF/*.RSA / *.DSA / *.EC signatures
+        try:
+            for sig_name in apk.get_signature_names():
+                raw = apk.get_certificate_der(sig_name)
+                if raw:
+                    return hashlib.sha256(raw).hexdigest()
+        except Exception:
+            pass
+
+        # Last resort: Certificate objects that expose a dump() method
+        try:
+            certs = apk.get_certificates()
+            if certs:
+                cert = certs[0]
+                for attr in ("sha256_fingerprint", "fingerprint"):
+                    val = getattr(cert, attr, None)
+                    if val and isinstance(val, str):
+                        return val.replace(":", "").lower()
+                if hasattr(cert, "dump"):
+                    return hashlib.sha256(cert.dump()).hexdigest()
+        except Exception:
+            pass
+
+        return None
+
+    # ── Permissions ────────────────────────────────────────────────────────────
+
+    def _extract_permissions(self, apk) -> list[str]:
+        try:
+            return list(apk.get_permissions() or [])
+        except Exception:
+            return []
+
+    # ── Components ─────────────────────────────────────────────────────────────
+
+    def _extract_components(self, apk) -> ApkComponents:
+        def _safe(fn) -> list[str]:
+            try:
+                return list(fn() or [])
+            except Exception:
+                return []
+
+        return ApkComponents(
+            activities=_safe(apk.get_activities),
+            services=_safe(apk.get_services),
+            receivers=_safe(apk.get_receivers),
+            providers=_safe(apk.get_providers),
+        )
+
+    # ── Security indicators ────────────────────────────────────────────────────
+
+    def _extract_security(
+        self,
+        apk,
+        permissions: list[str],
+        components: ApkComponents,
+    ) -> tuple[SecurityFeatures, list[str]]:
+        perm_set = set(permissions)
+        suspicious: list[str] = []
+
+        sms_access = bool(perm_set & _SMS_PERMISSIONS)
+        if sms_access:
+            suspicious.append(
+                f"SMS access: {', '.join(sorted(perm_set & _SMS_PERMISSIONS))}"
+            )
+
+        overlay = "android.permission.SYSTEM_ALERT_WINDOW" in perm_set
+        if overlay:
+            suspicious.append("SYSTEM_ALERT_WINDOW (overlay capability)")
+
+        accessibility = "android.permission.BIND_ACCESSIBILITY_SERVICE" in perm_set
+        if accessibility:
+            suspicious.append("BIND_ACCESSIBILITY_SERVICE (keylogger/screen-reader risk)")
+
+        if (
+            "android.permission.READ_SMS" in perm_set
+            and "android.permission.SEND_SMS" in perm_set
+        ):
+            suspicious.append("SMS read+send combination — OTP theft pattern")
+
+        if "android.permission.BIND_DEVICE_ADMIN" in perm_set:
+            suspicious.append("BIND_DEVICE_ADMIN — ransomware/stalkerware pattern")
+
+        exported_count, suspicious_receivers = self._parse_exported(apk, components)
+
+        return SecurityFeatures(
+            sms_access=sms_access,
+            overlay=overlay,
+            accessibility_service=accessibility,
+            exported_count=exported_count,
+            suspicious_receivers=suspicious_receivers,
+        ), suspicious
+
+    def _parse_exported(
+        self,
+        apk,
+        components: ApkComponents,
+    ) -> tuple[int, list[str]]:
+        """Count exported components and collect suspicious receiver action names."""
+        try:
+            tree = apk.get_android_manifest_xml()
+        except Exception:
+            total = (
+                len(components.activities)
+                + len(components.services)
+                + len(components.receivers)
+                + len(components.providers)
+            )
+            return total, []
+
+        exported_count = 0
+        suspicious_receivers: list[str] = []
+        app_elem = tree.find("application")
+        if app_elem is None:
+            return 0, []
+
+        for tag in ("activity", "service", "receiver", "provider"):
+            for elem in app_elem.iter(tag):
+                exported_attr = elem.get(f"{{{_ANDROID_NS}}}exported", "")
+                has_filter = elem.find("intent-filter") is not None
+                is_exported = exported_attr.lower() == "true" or (
+                    has_filter and exported_attr.lower() != "false"
+                )
+                if is_exported:
+                    exported_count += 1
+
+                if tag == "receiver":
+                    comp_name = elem.get(f"{{{_ANDROID_NS}}}name", "")
+                    for action_elem in elem.iter("action"):
+                        action = action_elem.get(f"{{{_ANDROID_NS}}}name", "")
+                        if action in _SUSPICIOUS_RECEIVER_ACTIONS:
+                            suspicious_receivers.append(comp_name or action)
+
+        return exported_count, list(set(suspicious_receivers))
+
+
+# ── Module-level helpers ───────────────────────────────────────────────────────
+
+def _safe_str(val: object) -> str:
+    return str(val) if val is not None else ""
+
+
+def _has_obfuscated_names(components: ApkComponents) -> bool:
+    """True if any component name ends with a 1-2 character class segment."""
+    all_names = components.activities + components.services + components.receivers
+    for fqn in all_names:
+        simple = fqn.lstrip("L").rstrip(";").replace("/", ".").rsplit(".", 1)[-1]
+        if 1 <= len(simple) <= 2 and simple.isalpha():
+            return True
+    return False
+
+
+def _build_ml_features(
+    permissions: list[str],
+    components: ApkComponents,
+) -> MlFeatures:
+    return MlFeatures(
+        dangerous_permission_count=sum(
+            1 for p in permissions if p in _HIGH_RISK_PERMISSIONS
+        ),
+        receiver_count=len(components.receivers),
+        service_count=len(components.services),
+    )
+
+
+def _mock_result(apk_path: Path) -> AndroguardResult:
+    """Minimal fallback result when Androguard is not installed."""
+    file_size = apk_path.stat().st_size if apk_path.exists() else 0
+    return AndroguardResult(
+        is_obfuscated=False,
+        native_code=file_size > 5 * 1024 * 1024,
+        dynamic_code_loading=False,
+        suspicious_activities=[],
+        error="androguard not installed — mock result",
+    )
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+_engine = AndroguardEngine()
+
+
+async def run_androguard_analysis(
+    apk_path: Path,
+    permissions: list[str],  # kept for backward-compat; ignored when Androguard runs
+) -> AndroguardResult:
+    """Entry-point called by APKAnalyzer; delegates to AndroguardEngine."""
+    return await _engine.analyze(apk_path)

app/services/apk_intelligence/engines/apkid_engine.py

@@ -0,0 +1,251 @@
+"""
+engines/apkid_engine.py
+— APKiD-based detection of packers, obfuscators, compilers and anti-analysis tricks.
+
+Uses real APKiD when installed; degrades gracefully to a byte-level fallback scanner
+when APKiD is absent or when the APK is corrupted. Never raises to the caller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+
+from app.services.apk_intelligence.models import APKidResult
+
+logger = logging.getLogger(__name__)
+
+_ASYNC_TIMEOUT = 60  # seconds — outer asyncio guard
+_APKID_TIMEOUT = 45  # seconds — passed to APKiD's own timeout
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="apkid")
+
+# ── Runtime feature flag ───────────────────────────────────────────────────────
+try:
+    import apkid as _apkid_mod  # noqa: F401
+    _APKID_AVAILABLE = True
+except ImportError:
+    _APKID_AVAILABLE = False
+
+# ── Byte-level signatures for fallback scanner ────────────────────────────────
+
+_PACKER_SIGS: list[tuple[str, bytes]] = [
+    ("Bangcle/SecShell",   b"bangcle"),
+    ("Bangcle/SecShell",   b"secshell"),
+    ("Qihoo360Protect",    b"qihoo"),
+    ("Qihoo360Protect",    b"360protect"),
+    ("DexProtector",       b"dexprotector"),
+    ("AppSealing",         b"appsealing"),
+    ("Jiagu",              b"jiagu"),
+    ("NagaProtector",      b"naga.protect"),
+    ("DexGuard",           b"dexguard"),
+    ("Tencent Legu",       b"com/tencent/legu"),
+    ("Baidu Protect",      b"com/baidu/protect"),
+    ("Ali Protect",        b"com/ali/mobisec"),
+    ("iDEA Shield",        b"com/idea/"),
+    ("Medusah",            b"medusah"),
+]
+
+_OBFUSCATOR_SIGS: list[tuple[str, bytes]] = [
+    ("ProGuard/R8",        b"proguard"),
+    ("ProGuard/R8",        b"proguard-project"),
+    ("Allatori",           b"allatori"),
+    ("DashO",              b"dasho"),
+    ("Zelix KlassMaster",  b"zelix"),
+    ("Stringer",           b"stringer"),
+    ("DexGuard",           b"dexguard"),
+]
+
+_ANTI_ANALYSIS_SIGS: list[tuple[str, bytes]] = [
+    ("emulator-check",  b"isemulator"),
+    ("emulator-check",  b"ro.product.model"),
+    ("emulator-check",  b"ro.hardware"),
+    ("emulator-check",  b"goldfish"),
+    ("emulator-check",  b"vbox86"),
+    ("emulator-check",  b"android.os.build"),
+    ("debugger-check",  b"isdebuggerconnected"),
+    ("debugger-check",  b"android.os.debug"),
+    ("debugger-check",  b"jdwp"),
+    ("anti-vm",         b"vmware"),
+    ("anti-vm",         b"virtualbox"),
+    ("anti-vm",         b"bluestacks"),
+    ("anti-vm",         b"noxplayer"),
+    ("anti-frida",      b"frida"),
+    ("anti-frida",      b"frida-gadget"),
+    ("anti-frida",      b"gum-js-loop"),
+    ("anti-frida",      b"frida_"),
+    ("root-check",      b"busybox"),
+    ("root-check",      b"/system/xbin/su"),
+]
+
+_COMPILER_SIGS: list[tuple[str, bytes]] = [
+    ("dx",       b"dx\x00"),
+    ("d8",       b"d8 ("),
+    ("r8",       b"r8 ("),
+    ("r8",       b"com.android.tools.r8"),
+    ("jack",     b"jack "),
+    ("dexmerge", b"dexmerge"),
+    ("kotlin",   b"kotlin/"),
+]
+
+
+# ── Engine class ───────────────────────────────────────────────────────────────
+
+class ApkidEngine:
+    """
+    Identify APK build and protection toolchains.
+
+    Runs synchronous APKiD (or the byte-level fallback) in a thread-pool executor
+    so the asyncio event loop is never blocked. Always returns an APKidResult —
+    never raises.
+    """
+
+    async def analyze(self, apk_path: Path) -> APKidResult:
+        if not apk_path.exists():
+            return APKidResult(error=f"APK not found: {apk_path}")
+
+        try:
+            result = await asyncio.wait_for(
+                asyncio.get_event_loop().run_in_executor(
+                    _executor,
+                    self._run_sync,
+                    apk_path,
+                ),
+                timeout=_ASYNC_TIMEOUT,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("APKiD timed out for %s", apk_path)
+            return APKidResult(error="APKiD analysis timed out")
+        except Exception as exc:
+            logger.exception("APKiD unexpected error for %s", apk_path)
+            return APKidResult(error=str(exc))
+
+        return result
+
+    # ── Sync dispatch ──────────────────────────────────────────────────────────
+
+    def _run_sync(self, apk_path: Path) -> APKidResult:
+        if _APKID_AVAILABLE:
+            try:
+                return self._run_real_apkid(apk_path)
+            except Exception as exc:
+                logger.warning("Real APKiD failed (%s), falling back to byte scanner", exc)
+
+        return self._run_fallback(apk_path)
+
+    # ── Real APKiD integration ─────────────────────────────────────────────────
+
+    def _run_real_apkid(self, apk_path: Path) -> APKidResult:
+        """
+        Call the real APKiD library.
+
+        APKiD returns {filename: {category: [rule_name, ...]}} where category is
+        one of: compiler, packer, obfuscator, anti_debug, anti_vm, anti_disassembly,
+        manipulator.  We aggregate across all DEX entries inside the APK.
+        """
+        # Late import — only reached when _APKID_AVAILABLE is True
+        from apkid.apkid import Scanner, Options  # type: ignore[import]
+        from apkid.rules import RulesManager      # type: ignore[import]
+
+        options = Options(timeout=_APKID_TIMEOUT, verbose=False)
+        rules = RulesManager().load()
+        scanner = Scanner(rules, options)
+
+        raw: dict[str, Any] = scanner.scan_list([str(apk_path)])
+
+        # Merge results across all DEX sections inside the APK
+        merged: dict[str, set[str]] = {}
+        for _fname, categories in raw.items():
+            if not isinstance(categories, dict):
+                continue
+            for cat, matches in categories.items():
+                merged.setdefault(cat, set()).update(
+                    m if isinstance(m, str) else str(m) for m in (matches or [])
+                )
+
+        packers     = sorted(merged.get("packer", set()))
+        obfuscators = sorted(merged.get("obfuscator", set()))
+        compilers   = sorted(merged.get("compiler", set()))
+
+        anti_cats = ("anti_debug", "anti_vm", "anti_disassembly", "manipulator")
+        anti_analysis = sorted(
+            t for cat in anti_cats for t in merged.get(cat, set())
+        )
+
+        return _build_result(packers, obfuscators, anti_analysis, compilers)
+
+    # ── Fallback byte scanner ──────────────────────────────────────────────────
+
+    def _run_fallback(self, apk_path: Path) -> APKidResult:
+        try:
+            content = apk_path.read_bytes().lower()
+        except Exception as exc:
+            return APKidResult(error=f"Could not read APK: {exc}")
+
+        packers       = _scan_unique(content, _PACKER_SIGS)
+        obfuscators   = _scan_unique(content, _OBFUSCATOR_SIGS)
+        compilers     = _scan_unique(content, _COMPILER_SIGS)
+        anti_analysis = _scan_unique(content, _ANTI_ANALYSIS_SIGS)
+
+        if not compilers:
+            # d8 is the default compiler for modern Android — mark when no other signal
+            compilers = ["d8"]
+
+        return _build_result(packers, obfuscators, anti_analysis, compilers)
+
+
+# ── Shared result builder + risk scorer ───────────────────────────────────────
+
+def _scan_unique(content: bytes, sigs: list[tuple[str, bytes]]) -> list[str]:
+    """Return deduplicated names for every signature that appears in content."""
+    seen: set[str] = set()
+    found: list[str] = []
+    for name, pattern in sigs:
+        if pattern in content and name not in seen:
+            seen.add(name)
+            found.append(name)
+    return found
+
+
+def _build_result(
+    packers: list[str],
+    obfuscators: list[str],
+    anti_analysis: list[str],
+    compilers: list[str],
+) -> APKidResult:
+    score = 0.0
+
+    if packers:
+        score += 0.4
+
+    if anti_analysis:
+        score += 0.3
+
+    # "heavy" obfuscation = more than one obfuscator tool detected
+    if len(obfuscators) > 1:
+        score += 0.2
+    elif obfuscators:
+        score += 0.1  # single obfuscator is common in legitimate apps
+
+    risk_score = round(min(score, 1.0), 4)
+
+    return APKidResult(
+        is_packed=bool(packers),
+        packers=packers,
+        obfuscators=obfuscators,
+        anti_analysis=anti_analysis,
+        compilers=compilers,
+        risk_score=risk_score,
+    )
+
+
+# ── Module-level convenience function (used by analyzer.py) ───────────────────
+
+_engine = ApkidEngine()
+
+
+async def run_apkid_analysis(apk_path: Path) -> APKidResult:
+    """Convenience wrapper kept for backward compatibility with analyzer.py."""
+    return await _engine.analyze(apk_path)

app/services/apk_intelligence/engines/ml_engine.py

@@ -0,0 +1,361 @@
+"""
+engines/ml_engine.py
+— ML-based malware probability scoring for APK files.
+
+Architecture:
+  MLFeatureExtractor  – converts engine results → fixed 20-dim float vector
+  MLModel             – wraps a joblib classifier; falls back to heuristic scoring
+  run_ml_analysis()   – async entry-point called by APKAnalyzer
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Optional
+
+from app.config import get_settings
+from app.services.apk_intelligence.models import (
+    AndroguardResult,
+    APKidResult,
+    MLResult,
+    YaraResult,
+)
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+_ML_TIMEOUT = 30  # seconds
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="ml")
+
+# ── Feature index (defines vector order and dimension) ────────────────────────
+
+FEATURE_NAMES: list[str] = [
+    # Permission features [0-6]
+    "perm_read_sms",
+    "perm_receive_sms",
+    "perm_send_sms",
+    "perm_system_alert_window",
+    "perm_camera",
+    "perm_record_audio",
+    "perm_access_fine_location",
+    # Component features [7-9]
+    "receiver_count",
+    "service_count",
+    "exported_component_count",
+    # Behaviour features [10-12]
+    "sms_access",
+    "overlay_detected",
+    "accessibility_service",
+    # YARA features [13-16]
+    "yara_match_count",
+    "banking_trojan_match",
+    "rat_match",
+    "otp_match",
+    # APKiD features [17-19]
+    "packed",
+    "obfuscation_count",
+    "anti_analysis_count",
+]
+
+FEATURE_DIM = len(FEATURE_NAMES)  # 20
+
+_PERM_READ_SMS    = "android.permission.READ_SMS"
+_PERM_RECEIVE_SMS = "android.permission.RECEIVE_SMS"
+_PERM_SEND_SMS    = "android.permission.SEND_SMS"
+_PERM_OVERLAY     = "android.permission.SYSTEM_ALERT_WINDOW"
+_PERM_CAMERA      = "android.permission.CAMERA"
+_PERM_AUDIO       = "android.permission.RECORD_AUDIO"
+_PERM_LOCATION    = "android.permission.ACCESS_FINE_LOCATION"
+
+_YARA_RULE_TO_FAMILY: dict[str, str] = {
+    "BANKING_TROJAN":       "BankingTrojan",
+    "REMOTE_ACCESS_TROJAN": "RAT",
+    "OTP_STEALER":          "OTPStealer",
+}
+
+
+# ── Feature extractor ─────────────────────────────────────────────────────────
+
+class MLFeatureExtractor:
+    """
+    Converts structured engine outputs into a fixed-length float feature vector.
+
+    The vector is always exactly ``FEATURE_DIM`` (20) elements regardless of
+    missing or error-state engine results — missing data maps to 0.0.
+    """
+
+    def extract(
+        self,
+        androguard: AndroguardResult,
+        yara: YaraResult,
+        apkid: APKidResult,
+    ) -> tuple[list[float], list[str]]:
+        """
+        Extract feature vector and report which features are active.
+
+        Returns:
+            (vector, active_features) where ``vector`` has length ``FEATURE_DIM``
+            and ``active_features`` lists every feature name with a non-zero value.
+        """
+        perm_set = frozenset(androguard.permissions)
+        sf   = androguard.security_features
+        comp = androguard.components
+
+        # ── Permission features ────────────────────────────────────────────────
+        perm_read_sms = 1.0 if _PERM_READ_SMS    in perm_set else 0.0
+        perm_recv_sms = 1.0 if _PERM_RECEIVE_SMS in perm_set else 0.0
+        perm_send_sms = 1.0 if _PERM_SEND_SMS    in perm_set else 0.0
+        perm_overlay  = 1.0 if _PERM_OVERLAY     in perm_set else 0.0
+        perm_camera   = 1.0 if _PERM_CAMERA      in perm_set else 0.0
+        perm_audio    = 1.0 if _PERM_AUDIO       in perm_set else 0.0
+        perm_location = 1.0 if _PERM_LOCATION    in perm_set else 0.0
+
+        # ── Component features ─────────────────────────────────────────────────
+        receiver_count  = float(len(comp.receivers)  if comp else 0)
+        service_count   = float(len(comp.services)   if comp else 0)
+        exported_count  = float(sf.exported_count    if sf   else 0)
+
+        # ── Behaviour features ─────────────────────────────────────────────────
+        sms_access    = 1.0 if sf and sf.sms_access            else 0.0
+        overlay_det   = 1.0 if sf and sf.overlay               else 0.0
+        accessibility = 1.0 if sf and sf.accessibility_service else 0.0
+
+        # ── YARA features ──────────────────────────────────────────────────────
+        rule_names    = set(yara.rule_names)
+        yara_count    = float(len(yara.matches))
+        banking_match = 1.0 if "BANKING_TROJAN"       in rule_names else 0.0
+        rat_match     = 1.0 if "REMOTE_ACCESS_TROJAN" in rule_names else 0.0
+        otp_match     = 1.0 if "OTP_STEALER"          in rule_names else 0.0
+
+        # ── APKiD features ─────────────────────────────────────────────────────
+        packed        = 1.0 if apkid.is_packed else 0.0
+        obf_count     = float(len(apkid.obfuscators))
+        anti_count    = float(len(apkid.anti_analysis))
+
+        vector: list[float] = [
+            perm_read_sms, perm_recv_sms, perm_send_sms,
+            perm_overlay,  perm_camera,   perm_audio,    perm_location,
+            receiver_count, service_count, exported_count,
+            sms_access,    overlay_det,   accessibility,
+            yara_count,    banking_match, rat_match,     otp_match,
+            packed,        obf_count,     anti_count,
+        ]
+
+        active = [FEATURE_NAMES[i] for i, v in enumerate(vector) if v != 0.0]
+        return vector, active
+
+
+# ── ML model wrapper ──────────────────────────────────────────────────────────
+
+class MLModel:
+    """
+    Wraps a joblib-persisted scikit-learn classifier.
+
+    Loads the model once at first use (lazy). Falls back to a calibrated
+    heuristic scorer when the model file is absent, unreadable, or raises.
+    """
+
+    def __init__(self, model_path: str) -> None:
+        self._path = Path(model_path)
+        self._clf = None
+        self._load_attempted = False
+
+    # ── Model loading ──────────────────────────────────────────────────────────
+
+    def _ensure_loaded(self) -> bool:
+        if self._load_attempted:
+            return self._clf is not None
+
+        self._load_attempted = True
+
+        if not self._path.exists():
+            logger.info(
+                "ML model not found at %s — heuristic fallback active", self._path
+            )
+            return False
+
+        try:
+            import joblib  # type: ignore[import]
+            self._clf = joblib.load(self._path)
+            logger.info("ML model loaded from %s", self._path)
+            return True
+        except Exception as exc:
+            logger.warning("Failed to load ML model from %s: %s", self._path, exc)
+            return False
+
+    # ── Inference ──────────────────────────────────────────────────────────────
+
+    def predict(self, vector: list[float]) -> tuple[float, float]:
+        """
+        Run inference and return (malware_probability, confidence), both in [0, 1].
+        """
+        if not self._ensure_loaded():
+            return self._heuristic_predict(vector)
+
+        try:
+            import numpy as np  # type: ignore[import]
+            X = np.array(vector, dtype=float).reshape(1, -1)
+            proba = self._clf.predict_proba(X)[0]
+            # class index 1 = malicious
+            prob = float(proba[1]) if len(proba) >= 2 else float(proba[0])
+            return round(prob, 4), 0.88
+        except Exception as exc:
+            logger.warning("predict_proba failed (%s), falling back to heuristic", exc)
+            return self._heuristic_predict(vector)
+
+    def _heuristic_predict(self, vector: list[float]) -> tuple[float, float]:
+        """
+        Calibrated heuristic scoring used when no trained model is present.
+
+        Weights are derived from known banking-malware behaviour patterns and
+        represent the relative contribution of each feature to malice probability.
+        """
+        weights: list[float] = [
+            # Permission features
+            0.12,   # READ_SMS
+            0.08,   # RECEIVE_SMS
+            0.10,   # SEND_SMS
+            0.12,   # SYSTEM_ALERT_WINDOW
+            0.02,   # CAMERA
+            0.03,   # RECORD_AUDIO
+            0.02,   # ACCESS_FINE_LOCATION
+            # Component features (additive per-component risk)
+            0.005,  # receiver_count
+            0.003,  # service_count
+            0.002,  # exported_component_count
+            # Behaviour features
+            0.15,   # sms_access
+            0.12,   # overlay_detected
+            0.15,   # accessibility_service
+            # YARA features
+            0.06,   # yara_match_count (per rule)
+            0.30,   # banking_trojan_match
+            0.25,   # rat_match
+            0.20,   # otp_match
+            # APKiD features
+            0.20,   # packed
+            0.05,   # obfuscation_count (per obfuscator)
+            0.04,   # anti_analysis_count (per technique)
+        ]
+
+        raw = sum(w * v for w, v in zip(weights, vector))
+        prob = round(min(raw, 1.0), 4)
+
+        signals = sum(1 for v in vector if v != 0.0)
+        confidence = round(min(0.40 + signals * 0.04, 0.82), 2)
+
+        return prob, confidence
+
+
+# ── Indicator builder ──────────────────────────────────────────────────────────
+
+def _build_indicators(
+    active_features: list[str],
+    yara: YaraResult,
+    apkid: APKidResult,
+) -> list[str]:
+    """Return up to 10 human-readable indicator strings for the MLResult."""
+    indicators: list[str] = []
+
+    # YARA matches are the most interpretable — list first
+    for match in yara.matches:
+        indicators.append(f"YARA:{match.rule} [{match.severity}]")
+
+    # APKiD packers
+    for pk in apkid.packers:
+        indicators.append(f"Packer:{pk}")
+
+    # APKiD anti-analysis techniques (one per category)
+    seen_aa: set[str] = set()
+    for aa in apkid.anti_analysis:
+        cat = aa.split("-")[0]
+        if cat not in seen_aa:
+            indicators.append(f"AntiAnalysis:{aa}")
+            seen_aa.add(cat)
+
+    # High-signal permission / behaviour features
+    _HIGH_SIGNAL = {
+        "perm_read_sms", "perm_send_sms", "perm_system_alert_window",
+        "sms_access", "overlay_detected", "accessibility_service",
+        "banking_trojan_match", "rat_match", "otp_match",
+    }
+    for feat in active_features:
+        if feat in _HIGH_SIGNAL:
+            indicators.append(f"Feature:{feat}")
+
+    return indicators[:10]
+
+
+def _infer_threat_family(yara: YaraResult) -> Optional[str]:
+    """Map the highest-severity YARA match to a threat family name."""
+    for rule in yara.rule_names:
+        if rule in _YARA_RULE_TO_FAMILY:
+            return _YARA_RULE_TO_FAMILY[rule]
+    return None
+
+
+# ── Module singletons ─────────────────────────────────────────────────────────
+
+_extractor = MLFeatureExtractor()
+_model     = MLModel(settings.ML_MODEL_PATH)
+
+
+# ── Synchronous core (runs in executor) ───────────────────────────────────────
+
+def _run_sync(
+    androguard: AndroguardResult,
+    yara: YaraResult,
+    apkid: APKidResult,
+) -> MLResult:
+    vector, active = _extractor.extract(androguard, yara, apkid)
+    prob, conf     = _model.predict(vector)
+    indicators     = _build_indicators(active, yara, apkid)
+    threat_family  = _infer_threat_family(yara)
+
+    return MLResult(
+        malware_probability=prob,
+        confidence=conf,
+        features_used=active,
+        top_indicators=indicators,
+        threat_family=threat_family,
+    )
+
+
+# ── Public entry-point ────────────────────────────────────────────────────────
+
+async def run_ml_analysis(
+    androguard: AndroguardResult,
+    yara: YaraResult,
+    apkid: APKidResult,
+) -> MLResult:
+    """
+    Async entry-point called by APKAnalyzer after the other engines complete.
+
+    Feature extraction and model inference run inside a thread-pool executor
+    so they never block the asyncio event loop. A hard timeout prevents the
+    pipeline stalling on a misbehaving model.
+
+    Returns:
+        MLResult — never raises; failures are captured in ``error``.
+    """
+    try:
+        result = await asyncio.wait_for(
+            asyncio.get_running_loop().run_in_executor(
+                _executor,
+                _run_sync,
+                androguard,
+                yara,
+                apkid,
+            ),
+            timeout=_ML_TIMEOUT,
+        )
+        return result
+    except asyncio.TimeoutError:
+        logger.error("ML inference timed out after %ds", _ML_TIMEOUT)
+        return MLResult(error=f"ML inference timed out after {_ML_TIMEOUT}s")
+    except Exception as exc:
+        logger.exception("ML inference unexpected failure")
+        return MLResult(error=str(exc))

app/services/apk_intelligence/engines/mobsf_client.py

@@ -0,0 +1,299 @@
+"""
+engines/mobsf_client.py
+— MobSF (Mobile Security Framework) REST API client.
+
+MobSF runs as a separate Docker container. This client handles the three-step
+REST flow (upload → scan → report) and degrades gracefully when MobSF is
+offline, misconfigured, or disabled — the verdict pipeline is never blocked.
+
+Enable with: MOBSF_ENABLED=true, MOBSF_URL=http://localhost:8000, MOBSF_API_KEY=<key>
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from app.config import get_settings
+from app.services.apk_intelligence.models import MobSFResult
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+# Per-step timeouts (MobSF scan can take up to ~90 s on a loaded machine)
+_UPLOAD_TIMEOUT = httpx.Timeout(120.0, connect=10.0)
+_SCAN_TIMEOUT   = httpx.Timeout(300.0, connect=10.0)
+_REPORT_TIMEOUT = httpx.Timeout(30.0,  connect=10.0)
+
+# Outer asyncio guard: if the whole flow exceeds this, return a fallback result
+_ANALYSIS_TIMEOUT = 420  # seconds
+
+# Permissions that are strongly associated with banking malware behaviour
+_MALWARE_PERMISSION_KEYWORDS: frozenset[str] = frozenset({
+    "READ_SMS",
+    "SEND_SMS",
+    "RECEIVE_SMS",
+    "RECORD_AUDIO",
+    "ACCESS_FINE_LOCATION",
+    "BIND_ACCESSIBILITY_SERVICE",
+    "BIND_DEVICE_ADMIN",
+    "READ_CALL_LOG",
+    "PROCESS_OUTGOING_CALLS",
+    "SYSTEM_ALERT_WINDOW",
+    "REQUEST_INSTALL_PACKAGES",
+    "CHANGE_NETWORK_STATE",
+    "RECEIVE_BOOT_COMPLETED",
+})
+
+# Severity labels that indicate a meaningful finding
+_HIGH_SEVERITIES: frozenset[str] = frozenset({"HIGH", "WARNING", "CRITICAL", "DANGER"})
+
+
+class MobSFClient:
+    """
+    Async client for the MobSF REST API v3.x.
+
+    Three public methods map directly to MobSF endpoints:
+        upload_apk  → POST /api/v1/upload
+        start_scan  → POST /api/v1/scan
+        get_report  → POST /api/v1/report_json
+
+    ``analyze`` orchestrates all three and parses the result into a
+    ``MobSFResult``. All exceptions from the HTTP layer propagate up so the
+    caller (``analyze``) can catch them uniformly and return a safe fallback.
+    """
+
+    def __init__(self) -> None:
+        self._base_url = settings.MOBSF_URL.rstrip("/")
+        self._headers  = {"Authorization": settings.MOBSF_API_KEY}
+
+    # ── Public methods (one per MobSF endpoint) ────────────────────────────────
+
+    async def upload_apk(self, apk_path: Path) -> str:
+        """
+        Upload the APK to MobSF.
+
+        Returns:
+            file_hash (str) — MobSF's internal identifier for this APK.
+
+        Raises:
+            httpx.HTTPStatusError  on 4xx/5xx responses.
+            httpx.ConnectError     when MobSF is unreachable.
+            httpx.TimeoutException on upload timeout.
+        """
+        async with httpx.AsyncClient(
+            timeout=_UPLOAD_TIMEOUT, headers=self._headers
+        ) as client:
+            with apk_path.open("rb") as f:
+                resp = await client.post(
+                    f"{self._base_url}/api/v1/upload",
+                    files={"file": (apk_path.name, f, "application/octet-stream")},
+                )
+            resp.raise_for_status()
+            return str(resp.json()["hash"])
+
+    async def start_scan(self, file_hash: str, file_name: str = "") -> None:
+        """
+        Trigger a MobSF static analysis scan for the uploaded APK.
+
+        Raises:
+            httpx.HTTPStatusError  on 4xx/5xx responses.
+            httpx.TimeoutException when scan acknowledgement times out.
+        """
+        async with httpx.AsyncClient(
+            timeout=_SCAN_TIMEOUT, headers=self._headers
+        ) as client:
+            resp = await client.post(
+                f"{self._base_url}/api/v1/scan",
+                data={
+                    "hash":      file_hash,
+                    "scan_type": "apk",
+                    "file_name": file_name,
+                },
+            )
+            resp.raise_for_status()
+
+    async def get_report(self, file_hash: str) -> dict[str, Any]:
+        """
+        Fetch the JSON analysis report for a completed MobSF scan.
+
+        Returns:
+            Raw MobSF report as a dict.
+
+        Raises:
+            httpx.HTTPStatusError  on 4xx/5xx responses.
+            httpx.TimeoutException when report fetch times out.
+        """
+        async with httpx.AsyncClient(
+            timeout=_REPORT_TIMEOUT, headers=self._headers
+        ) as client:
+            resp = await client.post(
+                f"{self._base_url}/api/v1/report_json",
+                data={"hash": file_hash},
+            )
+            resp.raise_for_status()
+            return dict(resp.json())
+
+    # ── Full analysis orchestrator ─────────────────────────────────────────────
+
+    async def analyze(self, apk_path: Path) -> MobSFResult:
+        """
+        Run the complete upload → scan → report flow and return a parsed result.
+
+        Never raises — all network errors are caught and returned as a
+        ``MobSFResult`` with ``available=False`` and the error message set.
+        """
+        try:
+            file_hash = await self.upload_apk(apk_path)
+            logger.debug("MobSF upload complete, hash=%s", file_hash)
+
+            await self.start_scan(file_hash, apk_path.name)
+            logger.debug("MobSF scan started for hash=%s", file_hash)
+
+            report = await self.get_report(file_hash)
+            logger.info("MobSF report received for hash=%s", file_hash)
+
+            return self._parse_report(report)
+
+        except httpx.ConnectError as exc:
+            logger.warning("MobSF unreachable at %s: %s", self._base_url, exc)
+            return MobSFResult(available=False, error=f"MobSF unreachable: {exc}")
+
+        except httpx.TimeoutException as exc:
+            logger.warning("MobSF request timed out: %s", exc)
+            return MobSFResult(available=False, error=f"MobSF timed out: {exc}")
+
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            body   = exc.response.text[:200]
+            logger.error("MobSF HTTP %s error: %s", status, body)
+            return MobSFResult(available=False, error=f"MobSF HTTP {status}")
+
+        except Exception as exc:
+            logger.exception("MobSF unexpected failure")
+            return MobSFResult(available=False, error=str(exc))
+
+    # ── Report parser ──────────────────────────────────────────────────────────
+
+    def _parse_report(self, report: dict[str, Any]) -> MobSFResult:
+        """
+        Convert a raw MobSF JSON report into a structured ``MobSFResult``.
+
+        MobSF ``security_score`` convention: **higher = safer** (0–100).
+        We invert this to a danger ``score`` and ``risk_score`` so downstream
+        fusion logic can treat higher values as more dangerous — matching the
+        convention documented in the Android SDK wire format.
+        """
+        # ── Security score ─────────────────────────────────────────────────────
+        raw_score = report.get("security_score")
+        if raw_score is None:
+            raw_score = report.get("appsec", {}).get("security_score")
+        if raw_score is not None:
+            security_score: float | None = float(raw_score)
+            danger_score = int(100 - security_score)
+            risk_score   = round(max(100 - security_score, 0) / 100.0, 4)
+        else:
+            security_score = None
+            danger_score   = -1
+            risk_score     = 0.0
+
+        # ── Trackers ───────────────────────────────────────────────────────────
+        trackers: list[str] = [
+            t.get("name", "Unknown Tracker")
+            for t in report.get("trackers", {}).get("trackers", [])
+            if isinstance(t, dict)
+        ]
+
+        # ── Permissions ────────────────────────────────────────────────────────
+        raw_perms = report.get("permissions", {})
+        all_permissions: list[str] = list(raw_perms.keys()) if isinstance(raw_perms, dict) else []
+        malware_permissions: list[str] = [
+            p for p in all_permissions
+            if any(kw in p for kw in _MALWARE_PERMISSION_KEYWORDS)
+        ]
+
+        # ── Findings ───────────────────────────────────────────────────────────
+        findings: list[str] = []
+
+        # Manifest analysis (MobSF v3.x: list of dicts)
+        for item in report.get("manifest_analysis", []):
+            if not isinstance(item, dict):
+                continue
+            title    = item.get("title") or item.get("rule") or ""
+            severity = str(item.get("severity", "")).upper()
+            if title and severity in _HIGH_SEVERITIES:
+                findings.append(f"[Manifest:{severity}] {title}")
+
+        # Code analysis (MobSF v3.x: dict of {rule_id: {severity, ...}})
+        for rule_id, detail in report.get("code_analysis", {}).items():
+            if not isinstance(detail, dict):
+                continue
+            severity = str(detail.get("severity", "")).upper()
+            if severity in _HIGH_SEVERITIES:
+                findings.append(f"[Code:{severity}] {rule_id}")
+
+        # appsec findings (older MobSF format / some v3 builds)
+        for item in report.get("appsec", {}).get("findings", []):
+            if not isinstance(item, dict):
+                continue
+            title    = item.get("title") or item.get("description") or ""
+            severity = str(item.get("severity", "")).upper()
+            if title:
+                findings.append(f"[AppSec:{severity}] {title}")
+
+        return MobSFResult(
+            available=True,
+            score=danger_score,
+            security_score=security_score,
+            risk_score=risk_score,
+            findings=findings[:20],   # cap to keep API response manageable
+            trackers=trackers,
+            permissions=all_permissions,
+            malware_permissions=malware_permissions,
+        )
+
+
+# ── Module singleton ──────────────────────────────────────────────────────────
+
+_client = MobSFClient()
+
+
+# ── Public entry-point ────────────────────────────────────────────────────────
+
+async def run_mobsf_analysis(
+    apk_path: Path,
+    package_name: str,  # kept for API compatibility; not used by real client
+) -> MobSFResult:
+    """
+    Async entry-point called by APKAnalyzer.
+
+    Returns immediately with an empty result when ``MOBSF_ENABLED=False``.
+    When enabled, delegates to ``MobSFClient.analyze`` wrapped in a hard
+    ``asyncio.wait_for`` timeout so the verdict pipeline is never blocked.
+
+    Returns:
+        MobSFResult — never raises.
+    """
+    if not settings.MOBSF_ENABLED:
+        return MobSFResult()
+
+    try:
+        return await asyncio.wait_for(
+            _client.analyze(apk_path),
+            timeout=_ANALYSIS_TIMEOUT,
+        )
+    except asyncio.TimeoutError:
+        logger.error(
+            "MobSF analysis timed out after %ds for %s", _ANALYSIS_TIMEOUT, apk_path
+        )
+        return MobSFResult(
+            available=False,
+            error=f"MobSF analysis timed out after {_ANALYSIS_TIMEOUT}s",
+        )
+    except Exception as exc:
+        logger.exception("run_mobsf_analysis unexpected failure")
+        return MobSFResult(available=False, error=str(exc))

app/services/apk_intelligence/engines/yara_engine.py

@@ -0,0 +1,284 @@
+"""
+engines/yara_engine.py
+— YARA rule scanning for APK binaries.
+
+Rules are loaded once at module import (application startup) from the
+``rules/`` directory adjacent to the ``backend/`` root.  All scanning
+runs in a thread-pool executor so the async event loop is never blocked.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import time
+from pathlib import Path
+from typing import Optional
+
+from app.config import get_settings
+from app.services.apk_intelligence.models import YaraMatch, YaraResult
+
+logger = logging.getLogger(__name__)
+
+# yara-python is an optional dependency; fall back gracefully if absent.
+try:
+    import yara as _yara  # type: ignore[import-untyped]
+    _YARA_AVAILABLE = True
+except ImportError:
+    _yara = None  # type: ignore[assignment]
+    _YARA_AVAILABLE = False
+
+_SCAN_TIMEOUT_SEC = 25    # yara.Rules.match() internal timeout
+_ASYNC_TIMEOUT_SEC = 30   # asyncio.wait_for() outer timeout
+
+# Severity → numeric weight used for risk_score calculation
+_SEVERITY_WEIGHT: dict[str, float] = {
+    "CRITICAL": 1.0,
+    "HIGH":     0.8,
+    "MEDIUM":   0.5,
+    "LOW":      0.2,
+}
+
+# The backend/ root is four parents above this file:
+# engines/yara_engine.py → engines/ → apk_intelligence/ → services/ → app/ → backend/
+_BACKEND_ROOT = Path(__file__).parents[4]
+
+
+def _resolve_rules_dir(config_path: str) -> Path:
+    """Return an absolute Path for the YARA rules directory."""
+    p = Path(config_path)
+    if p.is_absolute():
+        return p
+    # Prefer backend-root-relative resolution (works in Docker and local dev)
+    candidate = _BACKEND_ROOT / p
+    if candidate.exists():
+        return candidate
+    return Path.cwd() / p
+
+
+class YaraEngine:
+    """
+    Loads compiled YARA rules at construction and scans APKs asynchronously.
+
+    A single module-level instance is created at import time so rules are
+    compiled exactly once per worker process.
+    """
+
+    def __init__(self, rules_dir: Optional[Path] = None) -> None:
+        settings = get_settings()
+        self._rules_dir: Path = rules_dir or _resolve_rules_dir(settings.YARA_RULES_DIR)
+        self._compiled: object = None   # yara.Rules once loaded
+        self._load_error: Optional[str] = None
+        self._rule_count: int = 0
+        self._load_rules()
+
+    # ── Rule loading ───────────────────────────────────────────────────────────
+
+    def _load_rules(self) -> None:
+        if not _YARA_AVAILABLE:
+            self._load_error = "yara-python not installed"
+            logger.warning("YaraEngine: yara-python not installed — scans will return empty results")
+            return
+
+        if not self._rules_dir.exists():
+            self._load_error = f"Rules directory not found: {self._rules_dir}"
+            logger.warning("YaraEngine: %s", self._load_error)
+            return
+
+        rule_files: dict[str, str] = {
+            f.stem: str(f)
+            for f in sorted(self._rules_dir.glob("*.yar"))
+        }
+        if not rule_files:
+            self._load_error = f"No .yar files found in {self._rules_dir}"
+            logger.warning("YaraEngine: %s", self._load_error)
+            return
+
+        try:
+            self._compiled = _yara.compile(filepaths=rule_files)
+            self._rule_count = len(rule_files)
+            logger.info(
+                "YaraEngine: loaded %d rule file(s) from %s: %s",
+                self._rule_count,
+                self._rules_dir,
+                list(rule_files.keys()),
+            )
+        except Exception as exc:
+            self._load_error = f"Failed to compile YARA rules: {exc}"
+            logger.error("YaraEngine: %s", self._load_error)
+
+    # ── Public async interface ─────────────────────────────────────────────────
+
+    async def analyze(self, apk_path: Path) -> YaraResult:
+        """
+        Scan an APK file against all loaded YARA rules.
+
+        Args:
+            apk_path: Path to the APK on disk.
+
+        Returns:
+            YaraResult — never raises; errors are captured in the ``error`` field.
+        """
+        if not apk_path.exists():
+            logger.warning("YaraEngine: APK not found: %s", apk_path)
+            return YaraResult(error="APK file not found")
+
+        if self._compiled is None:
+            logger.debug("YaraEngine: no compiled rules (%s) — returning empty result", self._load_error)
+            return YaraResult(error=self._load_error)
+
+        try:
+            loop = asyncio.get_running_loop()
+            return await asyncio.wait_for(
+                loop.run_in_executor(
+                    None,
+                    functools.partial(self._sync_scan, apk_path),
+                ),
+                timeout=_ASYNC_TIMEOUT_SEC,
+            )
+        except asyncio.TimeoutError:
+            logger.error(
+                "YaraEngine: async timeout after %ds for %s",
+                _ASYNC_TIMEOUT_SEC, apk_path,
+            )
+            return YaraResult(error=f"Scan timed out after {_ASYNC_TIMEOUT_SEC}s")
+        except Exception as exc:
+            logger.exception("YaraEngine: unexpected error scanning %s", apk_path)
+            return YaraResult(error=str(exc))
+
+    # ── Synchronous scan (runs inside thread-pool executor) ───────────────────
+
+    def _extract_scan_buffer(self, apk_path: Path) -> bytes:
+        """
+        Build a flat byte buffer of decompressed APK content for YARA to scan.
+
+        APK files are ZIP archives where DEX and manifest entries are almost
+        always DEFLATE-compressed. YARA scanning the raw .apk file sees only
+        compressed bytes and can never match plaintext strings. We decompress
+        the key entries (classes*.dex + AndroidManifest.xml) and concatenate
+        them so that YARA's string matchers work against real plaintext content.
+
+        Falls back to raw file bytes if the file is not a valid ZIP.
+        """
+        import zipfile
+
+        try:
+            with zipfile.ZipFile(apk_path, "r") as zf:
+                parts: list[bytes] = []
+                for info in zf.infolist():
+                    name = info.filename
+                    if (
+                        name == "AndroidManifest.xml"
+                        or name.startswith("classes") and name.endswith(".dex")
+                        or name.endswith(".smali")
+                    ):
+                        try:
+                            parts.append(zf.read(name))
+                        except Exception:
+                            pass
+                if parts:
+                    return b"\n".join(parts)
+        except Exception:
+            pass
+
+        return apk_path.read_bytes()
+
+    def _sync_scan(self, apk_path: Path) -> YaraResult:
+        t0 = time.perf_counter()
+
+        scan_data = self._extract_scan_buffer(apk_path)
+
+        try:
+            raw_matches = self._compiled.match(  # type: ignore[union-attr]
+                data=scan_data,
+                timeout=_SCAN_TIMEOUT_SEC,
+            )
+        except _yara.TimeoutError:
+            elapsed = time.perf_counter() - t0
+            logger.error(
+                "YaraEngine: YARA timeout after %.1fs for %s",
+                elapsed, apk_path,
+            )
+            return YaraResult(
+                scan_time=round(elapsed, 3),
+                error=f"YARA scan timed out after {_SCAN_TIMEOUT_SEC}s",
+            )
+        except _yara.Error as exc:
+            elapsed = time.perf_counter() - t0
+            logger.warning("YaraEngine: scan error for %s — %s", apk_path, exc)
+            return YaraResult(
+                scan_time=round(elapsed, 3),
+                error=str(exc),
+            )
+        except Exception as exc:
+            elapsed = time.perf_counter() - t0
+            logger.exception("YaraEngine: unexpected scan error for %s", apk_path)
+            return YaraResult(
+                scan_time=round(elapsed, 3),
+                error=str(exc),
+            )
+
+        elapsed = time.perf_counter() - t0
+
+        matches = [_convert_match(m) for m in raw_matches]
+        rule_names = [m.rule for m in matches]
+        risk_score = _compute_risk_score(matches)
+
+        if matches:
+            logger.info(
+                "YaraEngine: %d match(es) in %.3fs for %s — %s",
+                len(matches), elapsed, apk_path.name,
+                [f"{m.rule}({m.severity})" for m in matches],
+            )
+        else:
+            logger.debug("YaraEngine: no matches in %.3fs for %s", elapsed, apk_path.name)
+
+        return YaraResult(
+            matched=bool(matches),
+            rule_names=rule_names,
+            matches=matches,
+            risk_score=round(risk_score, 4),
+            scan_time=round(elapsed, 3),
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _convert_match(m: object) -> YaraMatch:
+    """Convert a yara.Match object to our YaraMatch model."""
+    meta: dict = getattr(m, "meta", {}) or {}
+    return YaraMatch(
+        rule=getattr(m, "rule", "unknown"),
+        severity=str(meta.get("severity", "MEDIUM")).upper(),
+        description=str(meta.get("description", "")),
+        tags=list(getattr(m, "tags", []) or []),
+    )
+
+
+def _compute_risk_score(matches: list[YaraMatch]) -> float:
+    """
+    Aggregate severity weights into a single 0.0–1.0 risk score.
+    Starts at the highest individual severity and adds 10% per additional match.
+    """
+    if not matches:
+        return 0.0
+    weights = sorted(
+        [_SEVERITY_WEIGHT.get(m.severity, 0.5) for m in matches],
+        reverse=True,
+    )
+    base = weights[0]
+    extra = sum(w * 0.10 for w in weights[1:])
+    return min(base + extra, 1.0)
+
+
+# ── Module-level singleton (loaded at import / startup) ───────────────────────
+
+_engine = YaraEngine()
+
+
+# ── Public API (backward-compatible wrapper) ──────────────────────────────────
+
+async def run_yara_scan(apk_path: Path) -> YaraResult:
+    """Entry-point called by APKAnalyzer; delegates to the module-level YaraEngine."""
+    return await _engine.analyze(apk_path)

app/services/apk_intelligence/models.py

@@ -0,0 +1,348 @@
+"""
+services/apk_intelligence/models.py
+— Pydantic schemas for APK analysis request/response.
+
+These are the wire-format types used by the REST API layer.
+They MUST match the Android SDK ThreatIntelligenceResult exactly.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+class Verdict(str, Enum):
+    """Mirrors com.sbi.shieldyono.network.CloudVerdict"""
+    CLEAN = "CLEAN"
+    SUSPICIOUS = "SUSPICIOUS"
+    MALICIOUS = "MALICIOUS"
+    UNKNOWN = "UNKNOWN"
+
+
+# ── Request ───────────────────────────────────────────────────────────────────
+
+class ApkAnalysisRequest(BaseModel):
+    """
+    Metadata fields sent alongside the APK binary as multipart form fields.
+    Maps to com.sbi.shieldyono.network.ApkAnalysisRequest in the Android SDK.
+    """
+    packageName: str = Field(..., description="Fully-qualified package name from APK manifest")
+    appName: Optional[str] = Field(None, description="Human-readable app label")
+    certificateHash: Optional[str] = Field(None, description="SHA-256 of the signing certificate (hex)")
+    permissions: List[str] = Field(default_factory=list, description="Permissions declared in the APK manifest")
+    localRisk: float = Field(0.0, ge=0.0, le=100.0, description="Local risk score (0–100) from the SDK")
+
+    @field_validator("permissions", mode="before")
+    @classmethod
+    def parse_permissions(cls, v: object) -> List[str]:
+        """Accept comma-separated string or list (multipart encoding quirk)."""
+        if isinstance(v, str):
+            return [p.strip() for p in v.split(",") if p.strip()]
+        return v or []
+
+
+# ── Engine Results (internal) ──────────────────────────────────────────────────
+
+class YaraMatch(BaseModel):
+    rule: str
+    severity: str = "MEDIUM"
+    description: str = ""
+    tags: List[str] = Field(default_factory=list)
+
+
+class YaraResult(BaseModel):
+    matched: bool = False
+    rule_names: List[str] = Field(default_factory=list)  # kept for fusion.py compat
+    matches: List["YaraMatch"] = Field(default_factory=list)
+    risk_score: float = 0.0
+    scan_time: float = 0.0
+    error: Optional[str] = None
+
+
+class ApkIdentity(BaseModel):
+    package: str = ""
+    app_name: str = ""
+    version_name: str = ""
+    version_code: str = ""
+    certificate_sha256: Optional[str] = None
+
+
+class ApkComponents(BaseModel):
+    activities: List[str] = Field(default_factory=list)
+    services: List[str] = Field(default_factory=list)
+    receivers: List[str] = Field(default_factory=list)
+    providers: List[str] = Field(default_factory=list)
+
+
+class SecurityFeatures(BaseModel):
+    sms_access: bool = False
+    overlay: bool = False
+    accessibility_service: bool = False
+    exported_count: int = 0
+    suspicious_receivers: List[str] = Field(default_factory=list)
+
+
+class MlFeatures(BaseModel):
+    dangerous_permission_count: int = 0
+    receiver_count: int = 0
+    service_count: int = 0
+
+
+class AndroguardResult(BaseModel):
+    # Core flags consumed by fusion.py
+    is_obfuscated: bool = False
+    native_code: bool = False
+    dynamic_code_loading: bool = False
+    suspicious_activities: List[str] = Field(default_factory=list)
+    error: Optional[str] = None
+
+    # Rich structured output from real Androguard analysis
+    identity: Optional[ApkIdentity] = None
+    permissions: List[str] = Field(default_factory=list)
+    components: Optional[ApkComponents] = None
+    security_features: Optional[SecurityFeatures] = None
+    ml_features: Optional[MlFeatures] = None
+
+
+class APKidResult(BaseModel):
+    is_packed: bool = False
+    packers: List[str] = Field(default_factory=list)
+    obfuscators: List[str] = Field(default_factory=list)
+    anti_analysis: List[str] = Field(default_factory=list)
+    compilers: List[str] = Field(default_factory=list)
+    risk_score: float = Field(0.0, ge=0.0, le=1.0)
+    error: Optional[str] = None
+
+
+class MLResult(BaseModel):
+    malware_probability: float = 0.0
+    threat_family: Optional[str] = None
+    confidence: float = 0.0
+    features_used: List[str] = Field(default_factory=list)
+    top_indicators: List[str] = Field(default_factory=list)
+    error: Optional[str] = None
+
+
+class MobSFResult(BaseModel):
+    available: bool = False
+    score: int = -1                          # danger score 0-100 (lower=safer); -1=not run
+    security_score: Optional[float] = None  # raw MobSF score (higher=safer)
+    risk_score: float = 0.0                  # normalised danger 0.0-1.0
+    findings: List[str] = Field(default_factory=list)
+    trackers: List[str] = Field(default_factory=list)
+    permissions: List[str] = Field(default_factory=list)
+    malware_permissions: List[str] = Field(default_factory=list)
+    error: Optional[str] = None
+
+
+class ImpersonationResult(BaseModel):
+    is_impersonating: bool = False
+    impersonated_bank: Optional[str] = None
+    similarity_score: float = 0.0
+
+
+class EngineResults(BaseModel):
+    """Aggregated raw results from all analysis engines (internal use)."""
+    yara: YaraResult = Field(default_factory=YaraResult)
+    androguard: AndroguardResult = Field(default_factory=AndroguardResult)
+    apkid: APKidResult = Field(default_factory=APKidResult)
+    ml: MLResult = Field(default_factory=MLResult)
+    mobsf: MobSFResult = Field(default_factory=MobSFResult)
+    impersonation: ImpersonationResult = Field(default_factory=ImpersonationResult)
+
+
+class ScanStep(BaseModel):
+    """One step in the visible scan pipeline sent to the Flutter UI."""
+    engine: str = Field(..., description="Engine or step name shown to the user")
+    status: str = Field(
+        ...,
+        description="PASSED | COMPLETED | THREAT_FOUND | ERROR | SKIPPED",
+    )
+    details: str = Field("", description="Short human-readable detail for this step")
+
+
+# ── API Response (matches Android SDK ThreatIntelligenceResult) ────────────────
+
+class ThreatIntelligenceResponse(BaseModel):
+    """
+    Wire-format response from POST /api/v1/apk/analyze.
+    Field names and JSON keys MUST match the SDK @SerializedName annotations.
+    """
+    verdict: Verdict = Field(..., description="Overall verdict for this APK")
+    malware_probability: float = Field(
+        ..., ge=0.0, le=1.0,
+        description="ML probability that this APK is malware (0.0–1.0)",
+        serialization_alias="malware_probability",
+    )
+    yara_matches: List[str] = Field(
+        default_factory=list,
+        description="YARA rule names that matched the APK",
+        serialization_alias="yara_matches",
+    )
+    mobsf_score: int = Field(
+        -1,
+        description="MobSF static-analysis score (0–100, lower=safer; -1=not run)",
+        serialization_alias="mobsf_score",
+    )
+    threat_family: Optional[str] = Field(
+        None,
+        description="Identified malware family / threat cluster name",
+        serialization_alias="threat_family",
+    )
+    explanations: List[str] = Field(
+        default_factory=list,
+        description="Human-readable explanations for the verdict",
+    )
+    explanation: Optional["ThreatExplanation"] = Field(
+        None,
+        description="Full explainable threat report (user + analyst views)",
+    )
+
+    # ── Extended fields for Flutter UI (backward-compatible, all have defaults) ──
+    apk_name: Optional[str] = Field(None, description="Human-readable app or file name")
+    package_name: Optional[str] = Field(None, description="APK package identifier")
+    risk_score: float = Field(0.0, ge=0.0, le=1.0, description="Fused risk score 0.0–1.0")
+    scan_pipeline: List[ScanStep] = Field(
+        default_factory=list,
+        description="Per-engine scan steps with statuses for the UI timeline",
+    )
+    recommendations: List[str] = Field(
+        default_factory=list,
+        description="Ordered remediation and investigation recommendations",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Status / Task wrappers ────────────────────────────────────────────────────
+
+class AnalysisStatus(str, Enum):
+    QUEUED = "QUEUED"
+    PROCESSING = "PROCESSING"
+    COMPLETE = "COMPLETE"
+    FAILED = "FAILED"
+
+
+class AnalysisTaskResponse(BaseModel):
+    """Returned immediately when an async task is queued."""
+    task_id: str
+    status: AnalysisStatus = AnalysisStatus.QUEUED
+    message: str = "APK queued for analysis"
+
+
+class ErrorResponse(BaseModel):
+    error: str
+    detail: Optional[str] = None
+
+
+# ── Threat Explanation models ─────────────────────────────────────────────────
+
+class RiskFactor(BaseModel):
+    """A single contributing factor to the threat assessment."""
+    factor: str       # Human-readable name, e.g. "OTP interception capability"
+    impact: int       # Relative weight 0-100
+    evidence: str     # Specific evidence string
+    severity: str     # CRITICAL | HIGH | MEDIUM | LOW
+    engine: str       # Which engine detected this signal
+    signal_id: str    # Machine-readable identifier for deduplication / mapping
+
+
+class UserMessage(BaseModel):
+    """Plain-English output for end users — no security jargon."""
+    title: str        # e.g. "Dangerous App Detected"
+    body: str         # 2-3 sentences a non-technical user can act on
+    action: str       # Single imperative sentence: what to do right now
+    severity: str     # CRITICAL | HIGH | MEDIUM | LOW | SAFE
+
+
+class AttackVector(BaseModel):
+    """One technique an attacker can use via this app."""
+    name: str                         # e.g. "OTP Theft"
+    mitre_id: str                     # e.g. "T1636.004"
+    mitre_name: str                   # Full technique name
+    description: str                  # How the attack works in this context
+    enabled_by: List[str]             # Which signals enable this vector
+
+
+class AnalystSummary(BaseModel):
+    """Technical output for security analysts and incident responders."""
+    threat_category: str              # Primary class: BankingTrojan | RAT | OTPStealer | Impersonator | Adware | Unknown
+    attack_vectors: List[AttackVector]
+    ioc_summary: str                  # Indicators of compromise, one paragraph
+    confidence: str                   # HIGH | MEDIUM | LOW
+    recommended_actions: List[str]    # Ordered investigation / remediation steps
+    engine_score_breakdown: dict      # {"ml": 0.72, "yara": 1.0, ...}
+    analyst_notes: List[str]          # Raw engine signals not captured elsewhere
+
+
+class TechnicalDetails(BaseModel):
+    """Full structured data for analyst dashboards and SIEM integration."""
+    # Verdict
+    verdict: str
+    fused_risk_score: float
+    malware_probability: float
+
+    # Permissions
+    dangerous_permissions: List[str]
+    permission_risk_map: dict         # permission → plain-English risk
+
+    # ML
+    ml_confidence: float
+    active_ml_features: List[str]
+    ml_threat_family: Optional[str]
+
+    # YARA
+    yara_matched_rules: List[str]
+    yara_severities: dict             # rule_name → severity
+
+    # APKiD
+    packers: List[str]
+    obfuscators: List[str]
+    anti_analysis_techniques: List[str]
+    compilers: List[str]
+
+    # Androguard static
+    is_obfuscated: bool
+    has_native_code: bool
+    has_dynamic_code_loading: bool
+    exported_component_count: int
+    suspicious_receivers: List[str]
+    component_counts: dict            # {"activities": n, "services": n, ...}
+
+    # MobSF
+    mobsf_danger_score: int           # -1 = not run
+    mobsf_trackers: List[str]
+    mobsf_malware_permissions: List[str]
+    mobsf_findings: List[str]
+
+    # Identity / impersonation
+    certificate_mismatch: bool
+    impersonated_bank: Optional[str]
+    impersonation_similarity: float
+
+
+class ThreatExplanation(BaseModel):
+    """
+    Complete explainable threat report.
+
+    Contains two audience-specific views:
+      user_message    — plain English for end users
+      analyst_summary — technical detail for security teams
+    """
+    # Core fields (match the user-requested schema)
+    summary: str
+    risk_breakdown: List[RiskFactor]  # Sorted by impact descending
+    technical_details: TechnicalDetails
+    user_message: UserMessage
+
+    # Extended fields
+    verdict: str
+    overall_risk_score: int           # 0-100
+    threat_family: Optional[str]
+    analyst_summary: AnalystSummary
+    generated_at: str                 # ISO-8601 UTC

app/services/apk_intelligence/threat_explainer.py

@@ -0,0 +1,1009 @@
+"""
+threat_explainer.py  —  Explainable Threat Intelligence Engine.
+
+Consumes raw outputs from all six analysis engines and produces a structured
+ThreatExplanation containing:
+
+  1. user_message     — plain English, non-technical, action-oriented
+  2. analyst_summary  — technical detail with MITRE ATT&CK mappings,
+                        IOC summary, attack vectors, recommended actions
+
+  Plus:
+    summary           — one-sentence narrative of the primary threat
+    risk_breakdown    — ordered list of contributing risk factors with impact
+    technical_details — full structured data for SIEM / dashboards
+
+Architecture
+────────────
+  EngineResults + ThreatIntelligenceResponse
+          │
+  ThreatExplanationEngine.explain()
+          │
+    ┌─────┴──────────────────────────┐
+    │  _extract_risk_factors()       │  one method per engine
+    │  _normalize_impacts()          │  scale to 100-point total
+    │  _generate_summary()           │  priority-chain narrative
+    │  _build_technical_details()    │  structured data harvest
+    │  _build_user_message()         │  severity-gated plain text
+    │  _build_analyst_summary()      │  attack vectors + MITRE
+    └────────────────────────────────┘
+          │
+    ThreatExplanation
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+from app.services.apk_intelligence.models import (
+    AnalystSummary,
+    APKidResult,
+    AndroguardResult,
+    AttackVector,
+    EngineResults,
+    ImpersonationResult,
+    MLResult,
+    MobSFResult,
+    RiskFactor,
+    TechnicalDetails,
+    ThreatExplanation,
+    ThreatIntelligenceResponse,
+    UserMessage,
+    Verdict,
+    YaraResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ── MITRE ATT&CK Mobile mappings ─────────────────────────────────────────────
+
+_MITRE = {
+    "sms_read":         ("T1636.004", "Protected User Data: SMS Messages"),
+    "overlay":          ("T1411",     "Input Prompt"),
+    "accessibility":    ("T1418",     "Software Discovery"),
+    "dynamic_code":     ("T1407",     "Download New Code at Runtime"),
+    "packer":           ("T1406",     "Obfuscated Files or Information"),
+    "anti_analysis":    ("T1523",     "Evade Analysis Environment"),
+    "audio_capture":    ("T1429",     "Capture Audio"),
+    "location":         ("T1430",     "Location Tracking"),
+    "impersonation":    ("T1517",     "Access Notifications"),
+    "credential_theft": ("T1417",     "Input Capture"),
+}
+
+# ── Permission risk catalogue ─────────────────────────────────────────────────
+
+_PERM_RISK: dict[str, str] = {
+    "android.permission.READ_SMS":
+        "Reads all SMS messages — allows OTP code interception",
+    "android.permission.RECEIVE_SMS":
+        "Intercepts incoming SMS before delivery — enables silent OTP theft",
+    "android.permission.SEND_SMS":
+        "Sends SMS without user interaction — can forward OTPs or incur charges",
+    "android.permission.SYSTEM_ALERT_WINDOW":
+        "Draws over other apps — enables phishing overlay on banking UI",
+    "android.permission.RECORD_AUDIO":
+        "Accesses microphone — can record calls and ambient audio",
+    "android.permission.ACCESS_FINE_LOCATION":
+        "Tracks precise GPS location continuously",
+    "android.permission.CAMERA":
+        "Accesses camera — can capture photos or video silently",
+    "android.permission.BIND_ACCESSIBILITY_SERVICE":
+        "Full UI control — reads screen content, simulates touches, keylogger risk",
+    "android.permission.BIND_DEVICE_ADMIN":
+        "Device administrator — prevents removal, can wipe device",
+    "android.permission.REQUEST_INSTALL_PACKAGES":
+        "Installs additional APKs silently — dropper capability",
+    "android.permission.READ_CALL_LOG":
+        "Reads call history — privacy violation",
+    "android.permission.PROCESS_OUTGOING_CALLS":
+        "Intercepts and redirects outgoing calls",
+}
+
+_HIGH_RISK_PERMS = frozenset(_PERM_RISK)
+
+
+# ── Main engine ───────────────────────────────────────────────────────────────
+
+class ThreatExplanationEngine:
+    """
+    Generates a ThreatExplanation from raw engine results.
+
+    Stateless — safe to share as a module-level singleton.
+    """
+
+    def explain(
+        self,
+        engine_results: EngineResults,
+        fused: ThreatIntelligenceResponse,
+    ) -> ThreatExplanation:
+        factors = self._extract_risk_factors(engine_results, fused)
+        factors = self._normalize_impacts(factors)
+
+        summary  = self._generate_summary(factors, fused, engine_results)
+        tech     = self._build_technical_details(engine_results, fused)
+        user_msg = self._build_user_message(fused, factors)
+        analyst  = self._build_analyst_summary(engine_results, fused, factors, tech)
+
+        return ThreatExplanation(
+            summary=summary,
+            risk_breakdown=sorted(factors, key=lambda f: f.impact, reverse=True),
+            technical_details=tech,
+            user_message=user_msg,
+            verdict=fused.verdict.value if hasattr(fused.verdict, "value") else str(fused.verdict),
+            overall_risk_score=min(100, int(round(fused.malware_probability * 100))),
+            threat_family=fused.threat_family,
+            analyst_summary=analyst,
+            generated_at=datetime.now(timezone.utc).isoformat(),
+        )
+
+    # ── Risk factor extraction ─────────────────────────────────────────────────
+
+    def _extract_risk_factors(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+    ) -> list[RiskFactor]:
+        factors: list[RiskFactor] = []
+        factors += self._factors_impersonation(r.impersonation)
+        factors += self._factors_yara(r.yara)
+        factors += self._factors_androguard(r.androguard)
+        factors += self._factors_apkid(r.apkid)
+        factors += self._factors_ml(r.ml)
+        factors += self._factors_mobsf(r.mobsf)
+        return factors
+
+    def _factors_impersonation(self, imp: ImpersonationResult) -> list[RiskFactor]:
+        if not imp.is_impersonating:
+            return []
+        bank = imp.impersonated_bank or "a trusted banking app"
+        sim  = imp.similarity_score
+        factors = [
+            RiskFactor(
+                factor="Banking app impersonation",
+                impact=45 if sim >= 0.90 else 30,
+                evidence=f"Package / app name matches {bank} with {sim:.0%} similarity",
+                severity="CRITICAL" if sim >= 0.90 else "HIGH",
+                engine="identity",
+                signal_id="impersonation_detected",
+            ),
+        ]
+        if sim >= 0.80:
+            factors.append(RiskFactor(
+                factor="Certificate mismatch",
+                impact=40,
+                evidence=f"APK claims to be {bank} but signing certificate does not match the official app",
+                severity="CRITICAL",
+                engine="identity",
+                signal_id="cert_mismatch",
+            ))
+        return factors
+
+    def _factors_yara(self, yara: YaraResult) -> list[RiskFactor]:
+        factors: list[RiskFactor] = []
+        rule_meta = {
+            "BANKING_TROJAN":       (35, "CRITICAL", "Banking trojan signature matched in DEX/manifest (credential harvesting, overlay attack, or known family string)"),
+            "OTP_STEALER":          (30, "CRITICAL", "OTP stealer signature matched — SMS interception API calls and permission strings detected"),
+            "REMOTE_ACCESS_TROJAN": (30, "CRITICAL", "Remote access trojan signature matched — accessibility abuse and/or screen-capture APIs detected"),
+        }
+        for match in yara.matches:
+            meta = rule_meta.get(match.rule)
+            if meta:
+                impact, severity, evidence = meta
+            else:
+                impact, severity, evidence = (20, match.severity, f"YARA rule {match.rule} matched")
+            factors.append(RiskFactor(
+                factor=f"Known malware signature: {match.rule}",
+                impact=impact,
+                evidence=evidence,
+                severity=severity,
+                engine="yara",
+                signal_id=f"yara_{match.rule.lower()}",
+            ))
+        return factors
+
+    def _factors_androguard(self, ag: AndroguardResult) -> list[RiskFactor]:
+        if ag.error and not ag.permissions:
+            return []
+        factors: list[RiskFactor] = []
+        perm_set = frozenset(ag.permissions)
+        sf = ag.security_features
+
+        # OTP interception (READ + RECEIVE together = definitive theft chain)
+        sms_read    = "android.permission.READ_SMS"    in perm_set
+        sms_receive = "android.permission.RECEIVE_SMS" in perm_set
+        sms_send    = "android.permission.SEND_SMS"    in perm_set
+
+        if sms_read or sms_receive:
+            evidence_parts = []
+            if sms_read:    evidence_parts.append("READ_SMS")
+            if sms_receive: evidence_parts.append("RECEIVE_SMS")
+            if sms_send:    evidence_parts.append("SEND_SMS")
+            factors.append(RiskFactor(
+                factor="OTP interception capability",
+                impact=25 if (sms_read and sms_receive) else 15,
+                evidence=f"{' + '.join(evidence_parts)} permission(s) detected — can silently read incoming one-time passwords",
+                severity="HIGH",
+                engine="androguard",
+                signal_id="sms_access",
+            ))
+
+        # Overlay attack
+        if "android.permission.SYSTEM_ALERT_WINDOW" in perm_set:
+            factors.append(RiskFactor(
+                factor="Overlay attack capability",
+                impact=20,
+                evidence="SYSTEM_ALERT_WINDOW allows drawing a fake login screen over the real banking app",
+                severity="HIGH",
+                engine="androguard",
+                signal_id="overlay_capability",
+            ))
+
+        # Accessibility abuse
+        if "android.permission.BIND_ACCESSIBILITY_SERVICE" in perm_set:
+            factors.append(RiskFactor(
+                factor="Accessibility service abuse",
+                impact=25,
+                evidence="BIND_ACCESSIBILITY_SERVICE enables reading screen content, simulating taps, and keylogging without user awareness",
+                severity="HIGH",
+                engine="androguard",
+                signal_id="accessibility_abuse",
+            ))
+
+        # Device admin (ransomware / stalkerware indicator)
+        if "android.permission.BIND_DEVICE_ADMIN" in perm_set:
+            factors.append(RiskFactor(
+                factor="Device administrator privilege",
+                impact=30,
+                evidence="BIND_DEVICE_ADMIN — app requests admin rights, enabling lock, wipe, and uninstall prevention",
+                severity="CRITICAL",
+                engine="androguard",
+                signal_id="device_admin",
+            ))
+
+        # Dropper capability
+        if "android.permission.REQUEST_INSTALL_PACKAGES" in perm_set:
+            factors.append(RiskFactor(
+                factor="Silent APK installation",
+                impact=20,
+                evidence="REQUEST_INSTALL_PACKAGES enables downloading and installing additional malware without user prompts",
+                severity="HIGH",
+                engine="androguard",
+                signal_id="dropper_capability",
+            ))
+
+        # Obfuscation from Androguard heuristic
+        if ag.is_obfuscated:
+            factors.append(RiskFactor(
+                factor="Code obfuscation",
+                impact=15,
+                evidence="Component class names are 1-2 characters — aggressive obfuscation to defeat static analysis",
+                severity="MEDIUM",
+                engine="androguard",
+                signal_id="obfuscated_names",
+            ))
+
+        # Dynamic code loading
+        if ag.dynamic_code_loading:
+            factors.append(RiskFactor(
+                factor="Dynamic code loading",
+                impact=15,
+                evidence="DexClassLoader / multiple DEX files detected — downloads and executes code at runtime",
+                severity="HIGH",
+                engine="androguard",
+                signal_id="dynamic_code_loading",
+            ))
+
+        # Suspicious broadcast receivers
+        if sf and sf.suspicious_receivers:
+            factors.append(RiskFactor(
+                factor="Suspicious broadcast receivers",
+                impact=10,
+                evidence=f"Receivers listening to high-risk actions: {', '.join(sf.suspicious_receivers[:3])}",
+                severity="MEDIUM",
+                engine="androguard",
+                signal_id="suspicious_receivers",
+            ))
+
+        # High exported component count
+        if sf and sf.exported_count > 5:
+            factors.append(RiskFactor(
+                factor="Excessive exported components",
+                impact=8,
+                evidence=f"{sf.exported_count} exported components — unusually large attack surface",
+                severity="LOW",
+                engine="androguard",
+                signal_id="exported_components",
+            ))
+
+        return factors
+
+    def _factors_apkid(self, apkid: APKidResult) -> list[RiskFactor]:
+        if apkid.error:
+            return []
+        factors: list[RiskFactor] = []
+
+        if apkid.packers:
+            names = ", ".join(apkid.packers)
+            factors.append(RiskFactor(
+                factor="Binary packing / runtime protection",
+                impact=20,
+                evidence=f"Packer detected: {names} — hides malicious code from static scanners",
+                severity="HIGH",
+                engine="apkid",
+                signal_id="packer_detected",
+            ))
+
+        if apkid.anti_analysis:
+            techniques = ", ".join(apkid.anti_analysis[:4])
+            factors.append(RiskFactor(
+                factor="Anti-analysis techniques",
+                impact=15,
+                evidence=f"Evasion techniques: {techniques}",
+                severity="HIGH",
+                engine="apkid",
+                signal_id="anti_analysis",
+            ))
+
+        if len(apkid.obfuscators) > 1:
+            names = ", ".join(apkid.obfuscators)
+            factors.append(RiskFactor(
+                factor="Multiple obfuscation layers",
+                impact=12,
+                evidence=f"Multiple obfuscators: {names} — layered obfuscation unusual in legitimate apps",
+                severity="MEDIUM",
+                engine="apkid",
+                signal_id="multi_obfuscator",
+            ))
+        elif apkid.obfuscators:
+            factors.append(RiskFactor(
+                factor="Code obfuscation",
+                impact=5,
+                evidence=f"Obfuscator: {apkid.obfuscators[0]}",
+                severity="LOW",
+                engine="apkid",
+                signal_id="single_obfuscator",
+            ))
+
+        return factors
+
+    def _factors_ml(self, ml: MLResult) -> list[RiskFactor]:
+        if ml.error or ml.malware_probability < 0.30:
+            return []
+        prob = ml.malware_probability
+        if prob >= 0.80:
+            severity, impact = "CRITICAL", 35
+        elif prob >= 0.60:
+            severity, impact = "HIGH", 25
+        else:
+            severity, impact = "MEDIUM", 15
+
+        family_str = f" ({ml.threat_family})" if ml.threat_family else ""
+        evidence = (
+            f"Trained classifier assigns {prob:.0%} malware probability{family_str} "
+            f"based on: {', '.join(ml.top_indicators[:3]) or 'feature vector analysis'}"
+        )
+        return [RiskFactor(
+            factor="ML malware classification",
+            impact=impact,
+            evidence=evidence,
+            severity=severity,
+            engine="ml",
+            signal_id="ml_malware_probability",
+        )]
+
+    def _factors_mobsf(self, mobsf: MobSFResult) -> list[RiskFactor]:
+        if not mobsf.available or mobsf.score < 0 or mobsf.error:
+            return []
+        factors: list[RiskFactor] = []
+
+        if mobsf.score > 70:
+            factors.append(RiskFactor(
+                factor="High static analysis risk score",
+                impact=_clamp(int((mobsf.score - 50) / 2), 5, 20),
+                evidence=f"MobSF danger score {mobsf.score}/100 — multiple static security issues",
+                severity="HIGH" if mobsf.score > 80 else "MEDIUM",
+                engine="mobsf",
+                signal_id="mobsf_high_score",
+            ))
+
+        if mobsf.malware_permissions:
+            factors.append(RiskFactor(
+                factor="Malware-associated permissions",
+                impact=15,
+                evidence=f"MobSF flagged {len(mobsf.malware_permissions)} permission(s) as malware-associated: "
+                         f"{', '.join(mobsf.malware_permissions[:3])}",
+                severity="HIGH",
+                engine="mobsf",
+                signal_id="mobsf_malware_permissions",
+            ))
+
+        if len(mobsf.trackers) > 2:
+            factors.append(RiskFactor(
+                factor="Embedded privacy trackers",
+                impact=5 + min(len(mobsf.trackers), 3) * 2,
+                evidence=f"{len(mobsf.trackers)} advertising/analytics trackers: {', '.join(mobsf.trackers[:3])}",
+                severity="LOW",
+                engine="mobsf",
+                signal_id="privacy_trackers",
+            ))
+
+        return factors
+
+    # ── Impact normalisation ───────────────────────────────────────────────────
+
+    def _normalize_impacts(self, factors: list[RiskFactor]) -> list[RiskFactor]:
+        """
+        Scale factor impacts so the top factor always reads clearly.
+        Raw impacts already use a 0-100 scale; we leave them as-is because
+        each factor is independent — their sum can exceed 100 legitimately.
+        """
+        return factors
+
+    # ── Narrative summary ─────────────────────────────────────────────────────
+
+    def _generate_summary(
+        self,
+        factors: list[RiskFactor],
+        fused: ThreatIntelligenceResponse,
+        r: EngineResults,
+    ) -> str:
+        imp  = r.impersonation
+        yara = r.yara
+        ml   = r.ml
+        ag   = r.androguard
+        sf   = ag.security_features
+
+        # 1. Impersonation — highest priority narrative
+        if imp.is_impersonating and imp.similarity_score >= 0.70:
+            bank = imp.impersonated_bank or "a legitimate banking app"
+            if imp.similarity_score >= 0.90:
+                return (
+                    f"This application is almost certainly impersonating {bank}. "
+                    f"It uses an identical package name or display name but is signed by an unknown developer, "
+                    f"indicating a credential-phishing or session-hijacking attack."
+                )
+            return (
+                f"This application appears to impersonate {bank}. "
+                f"Its name and package are deceptively similar to the genuine app but the signing certificate does not match."
+            )
+
+        # 2. YARA hard matches — known malware family
+        if "BANKING_TROJAN" in yara.rule_names:
+            family = ml.threat_family or "banking trojan"
+            return (
+                f"This application contains signatures matching a known {family}. "
+                f"It is engineered to steal banking credentials through phishing overlays, "
+                f"credential harvesting forms, or known command-and-control infrastructure."
+            )
+
+        if "OTP_STEALER" in yara.rule_names:
+            return (
+                "This application is designed to intercept one-time passwords (OTPs). "
+                "It registers as an SMS receiver to silently read incoming verification codes "
+                "and forward them to a remote attacker, bypassing two-factor authentication."
+            )
+
+        if "REMOTE_ACCESS_TROJAN" in yara.rule_names:
+            return (
+                "This application contains a remote access trojan (RAT). "
+                "It abuses Android accessibility services or screen-capture APIs to give an attacker "
+                "full remote control of the device, including access to banking sessions."
+            )
+
+        # 3. Capability cluster — OTP theft without confirmed YARA match
+        has_sms     = sf and sf.sms_access
+        has_overlay = sf and sf.overlay
+        has_acc     = sf and sf.accessibility_service
+        if ml.malware_probability > 0.60:
+            if has_sms and has_overlay:
+                return (
+                    "This application combines SMS interception with overlay attack capability — "
+                    "the hallmark of banking malware. It can display fake login screens over your bank app "
+                    "and steal entered credentials alongside incoming OTP codes."
+                )
+            if has_sms:
+                return (
+                    "This application has a high probability of being banking malware. "
+                    "It requests SMS read permissions to intercept OTP codes sent by your bank, "
+                    "combined with other malicious indicators detected by multiple engines."
+                )
+            if has_acc:
+                return (
+                    "This application abuses Android Accessibility Services — a common RAT technique. "
+                    "It can read screen content, simulate touches, and log keystrokes "
+                    "without any visible indication to the user."
+                )
+
+        # 4. Evasion-heavy but no confirmed payload
+        if r.apkid.is_packed and r.apkid.anti_analysis:
+            return (
+                "This application employs advanced evasion techniques including binary packing "
+                "and anti-analysis tricks. While no specific malware signature was matched, "
+                "this combination is characteristic of professionally developed malware."
+            )
+
+        # 5. Suspicious but no confirmed malware
+        if fused.verdict == Verdict.SUSPICIOUS or str(fused.verdict) == "SUSPICIOUS":
+            return (
+                "This application exhibits multiple suspicious characteristics. "
+                "No known malware signature was matched, but the combination of permissions, "
+                "code structure, and behaviour patterns warrants caution."
+            )
+
+        # 6. Clean
+        return (
+            "No significant malware indicators were detected in this application. "
+            "It does not appear to pose a direct threat to banking security."
+        )
+
+    # ── Technical details ─────────────────────────────────────────────────────
+
+    def _build_technical_details(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+    ) -> TechnicalDetails:
+        ag = r.androguard
+        sf = ag.security_features
+        comp = ag.components
+
+        dangerous_perms = [p for p in ag.permissions if p in _HIGH_RISK_PERMS]
+        perm_risk_map = {p: _PERM_RISK[p] for p in dangerous_perms if p in _PERM_RISK}
+
+        yara_severities = {m.rule: m.severity for m in r.yara.matches}
+
+        verdict_str = fused.verdict.value if hasattr(fused.verdict, "value") else str(fused.verdict)
+
+        return TechnicalDetails(
+            verdict=verdict_str,
+            fused_risk_score=round(fused.malware_probability, 4),
+            malware_probability=round(r.ml.malware_probability, 4),
+
+            dangerous_permissions=dangerous_perms,
+            permission_risk_map=perm_risk_map,
+
+            ml_confidence=round(r.ml.confidence, 4),
+            active_ml_features=r.ml.features_used,
+            ml_threat_family=r.ml.threat_family,
+
+            yara_matched_rules=fused.yara_matches,
+            yara_severities=yara_severities,
+
+            packers=r.apkid.packers,
+            obfuscators=r.apkid.obfuscators,
+            anti_analysis_techniques=r.apkid.anti_analysis,
+            compilers=r.apkid.compilers,
+
+            is_obfuscated=ag.is_obfuscated,
+            has_native_code=ag.native_code,
+            has_dynamic_code_loading=ag.dynamic_code_loading,
+            exported_component_count=sf.exported_count if sf else 0,
+            suspicious_receivers=sf.suspicious_receivers if sf else [],
+            component_counts={
+                "activities": len(comp.activities) if comp else 0,
+                "services":   len(comp.services)   if comp else 0,
+                "receivers":  len(comp.receivers)  if comp else 0,
+                "providers":  len(comp.providers)  if comp else 0,
+            },
+
+            mobsf_danger_score=r.mobsf.score,
+            mobsf_trackers=r.mobsf.trackers,
+            mobsf_malware_permissions=r.mobsf.malware_permissions,
+            mobsf_findings=r.mobsf.findings[:5],
+
+            certificate_mismatch=r.impersonation.is_impersonating,
+            impersonated_bank=r.impersonation.impersonated_bank,
+            impersonation_similarity=round(r.impersonation.similarity_score, 4),
+        )
+
+    # ── User-facing message ───────────────────────────────────────────────────
+
+    def _build_user_message(
+        self,
+        fused: ThreatIntelligenceResponse,
+        factors: list[RiskFactor],
+    ) -> UserMessage:
+        verdict = fused.verdict.value if hasattr(fused.verdict, "value") else str(fused.verdict)
+        prob = fused.malware_probability
+        top = factors[0] if factors else None
+
+        if verdict == "MALICIOUS" or prob >= 0.75:
+            return UserMessage(
+                title="Dangerous App Detected",
+                body=(
+                    "An app installed on your device has been identified as malware. "
+                    "It may be attempting to steal your banking credentials, "
+                    "intercept your OTP codes, or take control of your device."
+                ),
+                action="Delete this app immediately and change your banking passwords.",
+                severity="CRITICAL",
+            )
+
+        if verdict == "SUSPICIOUS" or prob >= 0.45:
+            top_str = f" It has been flagged for: {top.factor.lower()}." if top else ""
+            return UserMessage(
+                title="Suspicious App Warning",
+                body=(
+                    "An app on your device shows signs of suspicious behavior."
+                    + top_str +
+                    " We recommend removing it before performing any banking transactions."
+                ),
+                action="Remove this app and scan your device with a trusted security tool.",
+                severity="HIGH",
+            )
+
+        if prob >= 0.25:
+            return UserMessage(
+                title="App Flagged for Review",
+                body=(
+                    "An app on your device has some unusual characteristics. "
+                    "It may not be malicious, but we recommend caution when using banking services."
+                ),
+                action="Avoid banking transactions while this app is installed. Consider removing it.",
+                severity="MEDIUM",
+            )
+
+        return UserMessage(
+            title="Device Appears Safe",
+            body=(
+                "This app passed all security checks. "
+                "No malware patterns, suspicious permissions, or known malware signatures were detected."
+            ),
+            action="No action required. Continue using your banking app normally.",
+            severity="SAFE",
+        )
+
+    # ── Analyst summary ───────────────────────────────────────────────────────
+
+    def _build_analyst_summary(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+        factors: list[RiskFactor],
+        tech: TechnicalDetails,
+    ) -> AnalystSummary:
+        threat_category = self._classify_threat(r, fused)
+        attack_vectors  = self._map_attack_vectors(r, factors)
+        ioc_summary     = self._build_ioc_summary(r, fused, tech)
+        confidence      = self._assess_confidence(r, fused)
+        actions         = self._recommended_actions(r, fused, threat_category)
+        notes           = self._analyst_notes(r, fused, factors)
+
+        score_breakdown = {
+            "ml":            round(r.ml.malware_probability, 4),
+            "yara":          round(r.yara.risk_score, 4),
+            "apkid":         round(r.apkid.risk_score, 4),
+            "mobsf":         round(r.mobsf.risk_score, 4),
+            "impersonation": round(r.impersonation.similarity_score, 4),
+            "fused":         round(fused.malware_probability, 4),
+        }
+
+        return AnalystSummary(
+            threat_category=threat_category,
+            attack_vectors=attack_vectors,
+            ioc_summary=ioc_summary,
+            confidence=confidence,
+            recommended_actions=actions,
+            engine_score_breakdown=score_breakdown,
+            analyst_notes=notes,
+        )
+
+    def _classify_threat(self, r: EngineResults, fused: ThreatIntelligenceResponse) -> str:
+        if r.impersonation.is_impersonating:
+            return "BankingImpersonator"
+        if "BANKING_TROJAN" in r.yara.rule_names or r.ml.threat_family == "BankingTrojan":
+            return "BankingTrojan"
+        if "OTP_STEALER" in r.yara.rule_names or r.ml.threat_family == "OTPStealer":
+            return "OTPStealer"
+        if "REMOTE_ACCESS_TROJAN" in r.yara.rule_names or r.ml.threat_family == "RAT":
+            return "RAT"
+        if fused.threat_family:
+            return fused.threat_family
+        sf = r.androguard.security_features
+        if sf and (sf.sms_access or sf.overlay):
+            return "SuspectedBankingMalware"
+        if r.apkid.is_packed or r.apkid.anti_analysis:
+            return "PackedMalware"
+        verdict = fused.verdict.value if hasattr(fused.verdict, "value") else str(fused.verdict)
+        if verdict in ("MALICIOUS", "SUSPICIOUS"):
+            return "UnclassifiedMalware"
+        return "Benign"
+
+    def _map_attack_vectors(
+        self,
+        r: EngineResults,
+        factors: list[RiskFactor],
+    ) -> list[AttackVector]:
+        vectors: list[AttackVector] = []
+        sf = r.androguard.security_features
+        perm_set = frozenset(r.androguard.permissions)
+
+        if sf and sf.sms_access:
+            enabled = [p for p in ["android.permission.READ_SMS", "android.permission.RECEIVE_SMS"]
+                       if p in perm_set]
+            mid, mname = _MITRE["sms_read"]
+            vectors.append(AttackVector(
+                name="OTP Theft via SMS",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    "The app registers as an SMS broadcast receiver. Incoming OTP/2FA codes "
+                    "sent by the bank via SMS are read silently and can be exfiltrated to a C2 server, "
+                    "bypassing two-factor authentication."
+                ),
+                enabled_by=enabled,
+            ))
+
+        if sf and sf.overlay:
+            mid, mname = _MITRE["overlay"]
+            vectors.append(AttackVector(
+                name="Phishing Overlay Attack",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    "SYSTEM_ALERT_WINDOW allows rendering a window above any other app. "
+                    "The malware detects when the user opens a banking app and overlays a pixel-perfect "
+                    "fake login screen to capture credentials."
+                ),
+                enabled_by=["android.permission.SYSTEM_ALERT_WINDOW"],
+            ))
+
+        if sf and sf.accessibility_service:
+            mid, mname = _MITRE["accessibility"]
+            vectors.append(AttackVector(
+                name="Accessibility-Based Keylogging",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    "BIND_ACCESSIBILITY_SERVICE grants full UI tree access. "
+                    "The malware can read all text fields (including password boxes), "
+                    "simulate user input, and take actions on behalf of the user invisibly."
+                ),
+                enabled_by=["android.permission.BIND_ACCESSIBILITY_SERVICE"],
+            ))
+
+        if r.androguard.dynamic_code_loading:
+            mid, mname = _MITRE["dynamic_code"]
+            vectors.append(AttackVector(
+                name="Dynamic Payload Delivery",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    "The app downloads and executes additional DEX code at runtime. "
+                    "Initial APK may appear benign; the malicious payload is retrieved after installation, "
+                    "evading static analysis at install time."
+                ),
+                enabled_by=["DexClassLoader detected"],
+            ))
+
+        if r.apkid.is_packed:
+            mid, mname = _MITRE["packer"]
+            vectors.append(AttackVector(
+                name="Evasion via Binary Packing",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    f"Packer(s) detected: {', '.join(r.apkid.packers)}. "
+                    "The DEX payload is encrypted and decrypted at runtime, hiding malicious code "
+                    "from signature-based scanners and static analysis tools."
+                ),
+                enabled_by=r.apkid.packers,
+            ))
+
+        if r.impersonation.is_impersonating:
+            mid, mname = _MITRE["impersonation"]
+            bank = r.impersonation.impersonated_bank or "target bank"
+            vectors.append(AttackVector(
+                name="Banking App Impersonation",
+                mitre_id=mid,
+                mitre_name=mname,
+                description=(
+                    f"App spoofs the identity of {bank} by mimicking its package name, "
+                    f"display name, or icon. Users who install this app believing it to be genuine "
+                    f"will hand credentials directly to the attacker."
+                ),
+                enabled_by=[f"impersonation_similarity={r.impersonation.similarity_score:.0%}"],
+            ))
+
+        return vectors
+
+    def _build_ioc_summary(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+        tech: TechnicalDetails,
+    ) -> str:
+        parts: list[str] = []
+
+        if fused.yara_matches:
+            parts.append(f"YARA rules matched: {', '.join(fused.yara_matches)}.")
+
+        if r.impersonation.is_impersonating:
+            parts.append(
+                f"Identity: impersonating {r.impersonation.impersonated_bank or 'unknown bank'} "
+                f"(similarity {r.impersonation.similarity_score:.0%}, certificate mismatch confirmed)."
+            )
+
+        if tech.dangerous_permissions:
+            parts.append(
+                f"Dangerous permissions ({len(tech.dangerous_permissions)}): "
+                + ", ".join(p.replace("android.permission.", "") for p in tech.dangerous_permissions[:5])
+                + ("..." if len(tech.dangerous_permissions) > 5 else "") + "."
+            )
+
+        if r.apkid.packers:
+            parts.append(f"Packers: {', '.join(r.apkid.packers)}.")
+
+        if r.apkid.anti_analysis:
+            parts.append(f"Anti-analysis: {', '.join(r.apkid.anti_analysis[:4])}.")
+
+        if r.ml.threat_family:
+            parts.append(f"ML-inferred family: {r.ml.threat_family} (p={r.ml.malware_probability:.2f}).")
+
+        if r.mobsf.trackers:
+            parts.append(f"Embedded trackers: {', '.join(r.mobsf.trackers[:4])}.")
+
+        return " ".join(parts) if parts else "No definitive IOCs identified."
+
+    def _assess_confidence(self, r: EngineResults, fused: ThreatIntelligenceResponse) -> str:
+        signals = sum([
+            bool(r.yara.rule_names),
+            bool(r.impersonation.is_impersonating),
+            r.ml.malware_probability > 0.6,
+            bool(r.apkid.packers or r.apkid.anti_analysis),
+            bool(r.mobsf.available and r.mobsf.score > 70),
+        ])
+        if signals >= 3:
+            return "HIGH"
+        if signals >= 2:
+            return "MEDIUM"
+        return "LOW"
+
+    def _recommended_actions(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+        threat_category: str,
+    ) -> list[str]:
+        verdict = fused.verdict.value if hasattr(fused.verdict, "value") else str(fused.verdict)
+        actions: list[str] = []
+
+        if verdict == "MALICIOUS":
+            actions += [
+                "BLOCK: Immediately prevent the user from proceeding with banking transactions.",
+                "ALERT: Display critical threat notification with instructions to uninstall the app.",
+                "REPORT: Submit APK hash and package name to your threat intelligence platform.",
+                "ESCALATE: Flag the user account for security review if credentials may be compromised.",
+            ]
+        elif verdict == "SUSPICIOUS":
+            actions += [
+                "WARN: Display prominent warning before allowing any banking transaction.",
+                "LOG: Record the package name, certificate hash, and analysis ID for SOC review.",
+                "MONITOR: Increase transaction monitoring for this user session.",
+            ]
+        else:
+            actions += [
+                "ALLOW: No immediate action required.",
+                "LOG: Record clean verdict for audit trail.",
+            ]
+
+        if r.impersonation.is_impersonating:
+            bank = r.impersonation.impersonated_bank or "the target bank"
+            actions.append(
+                f"NOTIFY: Coordinate with {bank} security team — active impersonation campaign detected."
+            )
+
+        if r.yara.rule_names:
+            actions.append(
+                "FORENSICS: Extract DEX files and submit to sandbox for dynamic analysis."
+            )
+
+        if r.apkid.is_packed:
+            actions.append(
+                "UNPACK: Use unpacking tools (e.g., DexDump, jadx) to recover the original DEX payload for deeper analysis."
+            )
+
+        return actions
+
+    def _analyst_notes(
+        self,
+        r: EngineResults,
+        fused: ThreatIntelligenceResponse,
+        factors: list[RiskFactor],
+    ) -> list[str]:
+        notes: list[str] = []
+
+        if r.ml.error:
+            notes.append(f"ML engine error — ML signal unavailable: {r.ml.error}")
+        if r.androguard.error:
+            notes.append(f"Androguard error — static analysis partial: {r.androguard.error}")
+        if not r.mobsf.available:
+            notes.append("MobSF not available — static risk score absent from fusion.")
+        if r.apkid.error:
+            notes.append(f"APKiD error — packer detection limited: {r.apkid.error}")
+
+        if r.androguard.native_code:
+            notes.append(
+                "Native .so libraries present — dynamic analysis recommended; "
+                "static DEX inspection covers only part of the attack surface."
+            )
+
+        if not r.yara.rule_names and fused.malware_probability > 0.5:
+            notes.append(
+                "No YARA rule matched despite elevated ML probability — "
+                "may be a new or mutated variant not covered by current signatures; consider updating YARA rules."
+            )
+
+        if r.ml.confidence < 0.60:
+            notes.append(
+                f"ML confidence is low ({r.ml.confidence:.0%}) — "
+                "heuristic fallback active; retrain model with more samples of this category."
+            )
+
+        return notes
+
+
+# ── Helper ─────────────────────────────────────────────────────────────────────
+
+def _clamp(value: int, lo: int, hi: int) -> int:
+    return max(lo, min(hi, value))
+
+
+# ── Module singleton + entry point ─────────────────────────────────────────────
+
+_engine = ThreatExplanationEngine()
+
+
+def run_threat_explanation(
+    engine_results: EngineResults,
+    fused: ThreatIntelligenceResponse,
+) -> ThreatExplanation:
+    """
+    Synchronous entry-point called by analyzer.py after risk fusion.
+
+    CPU-only (no I/O) — safe to call from the asyncio event loop directly.
+    """
+    try:
+        return _engine.explain(engine_results, fused)
+    except Exception as exc:
+        logger.exception("ThreatExplanationEngine failed: %s", exc)
+        # Return a minimal explanation rather than breaking the response
+        return ThreatExplanation(
+            summary="Explanation generation failed — see raw engine results.",
+            risk_breakdown=[],
+            technical_details=TechnicalDetails(
+                verdict=str(fused.verdict),
+                fused_risk_score=fused.malware_probability,
+                malware_probability=0.0,
+                dangerous_permissions=[], permission_risk_map={},
+                ml_confidence=0.0, active_ml_features=[], ml_threat_family=None,
+                yara_matched_rules=fused.yara_matches, yara_severities={},
+                packers=[], obfuscators=[], anti_analysis_techniques=[], compilers=[],
+                is_obfuscated=False, has_native_code=False, has_dynamic_code_loading=False,
+                exported_component_count=0, suspicious_receivers=[], component_counts={},
+                mobsf_danger_score=-1, mobsf_trackers=[], mobsf_malware_permissions=[],
+                mobsf_findings=[], certificate_mismatch=False, impersonated_bank=None,
+                impersonation_similarity=0.0,
+            ),
+            user_message=UserMessage(
+                title="Analysis Incomplete",
+                body="A partial analysis was completed. Please retry or contact support.",
+                action="Proceed with caution.",
+                severity="MEDIUM",
+            ),
+            verdict=str(fused.verdict),
+            overall_risk_score=int(fused.malware_probability * 100),
+            threat_family=fused.threat_family,
+            analyst_summary=AnalystSummary(
+                threat_category="Unknown",
+                attack_vectors=[],
+                ioc_summary=f"Explanation error: {exc}",
+                confidence="LOW",
+                recommended_actions=["Review raw engine results manually."],
+                engine_score_breakdown={},
+                analyst_notes=[f"Exception: {exc}"],
+            ),
+            generated_at=datetime.now(timezone.utc).isoformat(),
+        )

app/services/identity/bank_registry.py

@@ -0,0 +1,160 @@
+"""
+identity/bank_registry.py
+— Registry of legitimate Indian bank apps and their signing certificates.
+
+Used by the impersonation engine to detect fake banking apps
+masquerading as legitimate ones.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class BankAppProfile:
+    """Immutable profile for a legitimate Indian banking application."""
+    bank_name: str
+    official_package: str
+    cert_sha256: Optional[str]                   # hex, lowercase; None = not yet enrolled
+    alt_packages: tuple[str, ...] = field(default_factory=tuple)
+    display_names: tuple[str, ...] = field(default_factory=tuple)
+
+
+# ── Indian Banking App Registry ───────────────────────────────────────────────
+# cert_sha256 values are placeholders — replace with real certs in production.
+BANK_REGISTRY: list[BankAppProfile] = [
+    BankAppProfile(
+        bank_name="State Bank of India",
+        official_package="com.sbi.lotusintouch",
+        cert_sha256="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
+        alt_packages=("com.sbi.mobile", "in.sbi.mobile"),
+        display_names=("YONO SBI", "SBI YONO", "State Bank of India", "SBI Anywhere"),
+    ),
+    BankAppProfile(
+        bank_name="HDFC Bank",
+        official_package="com.snapwork.hdfc",
+        cert_sha256="b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
+        alt_packages=("com.hdfc.bank",),
+        display_names=("HDFC Bank MobileBanking", "HDFC Bank"),
+    ),
+    BankAppProfile(
+        bank_name="ICICI Bank",
+        official_package="com.csam.icici.bank.imobile",
+        cert_sha256="c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
+        alt_packages=("com.icici.mbanking",),
+        display_names=("iMobile Pay", "ICICI Bank"),
+    ),
+    BankAppProfile(
+        bank_name="Axis Bank",
+        official_package="com.axis.mobile",
+        cert_sha256="d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5",
+        alt_packages=(),
+        display_names=("Axis Mobile", "Axis Bank"),
+    ),
+    BankAppProfile(
+        bank_name="Kotak Mahindra Bank",
+        official_package="com.msf.kbank.mobile",
+        cert_sha256="e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
+        alt_packages=(),
+        display_names=("Kotak Mobile Banking", "Kotak811"),
+    ),
+    BankAppProfile(
+        bank_name="Punjab National Bank",
+        official_package="com.Version1.androPNBpr",
+        cert_sha256=None,
+        alt_packages=("com.pnb.mobile",),
+        display_names=("PNB ONE", "Punjab National Bank"),
+    ),
+    BankAppProfile(
+        bank_name="Bank of Baroda",
+        official_package="com.baroda.mpassbook",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("bob World", "Bank of Baroda"),
+    ),
+    BankAppProfile(
+        bank_name="Canara Bank",
+        official_package="com.canarabank.mobility",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("Canara ai1", "Canara Bank"),
+    ),
+    BankAppProfile(
+        bank_name="Union Bank of India",
+        official_package="com.infrasoft.uboi",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("Union Bank Mobile Banking",),
+    ),
+    BankAppProfile(
+        bank_name="Indian Bank",
+        official_package="com.IndianBank.mPassbook",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("IndOASIS", "Indian Bank"),
+    ),
+    BankAppProfile(
+        bank_name="Google Pay",
+        official_package="com.google.android.apps.nbu.paisa.user",
+        cert_sha256="f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7",
+        alt_packages=(),
+        display_names=("Google Pay", "GPay"),
+    ),
+    BankAppProfile(
+        bank_name="PhonePe",
+        official_package="com.phonepe.app",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("PhonePe", "PhonePe - UPI, Payments"),
+    ),
+    BankAppProfile(
+        bank_name="Paytm",
+        official_package="net.one97.paytm",
+        cert_sha256=None,
+        alt_packages=(),
+        display_names=("Paytm", "Paytm-UPI, Money Transfer"),
+    ),
+]
+
+# ── Lookup structures (built at import time) ───────────────────────────────────
+_PACKAGE_TO_BANK: dict[str, BankAppProfile] = {}
+_CERT_TO_BANK: dict[str, BankAppProfile] = {}
+_DISPLAYNAME_TO_BANK: dict[str, BankAppProfile] = {}
+
+for _profile in BANK_REGISTRY:
+    _PACKAGE_TO_BANK[_profile.official_package.lower()] = _profile
+    for _alt in _profile.alt_packages:
+        _PACKAGE_TO_BANK[_alt.lower()] = _profile
+    if _profile.cert_sha256:
+        _CERT_TO_BANK[_profile.cert_sha256.lower()] = _profile
+    for _name in _profile.display_names:
+        _DISPLAYNAME_TO_BANK[_name.lower()] = _profile
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+def is_official_package(package_name: str) -> bool:
+    """Return True if package_name is an official banking app package."""
+    return package_name.lower() in _PACKAGE_TO_BANK
+
+
+def get_bank_by_package(package_name: str) -> Optional[BankAppProfile]:
+    """Return the BankAppProfile for a known official package, or None."""
+    return _PACKAGE_TO_BANK.get(package_name.lower())
+
+
+def get_bank_by_cert(cert_sha256: str) -> Optional[BankAppProfile]:
+    """Return the BankAppProfile that owns a given signing certificate."""
+    return _CERT_TO_BANK.get(cert_sha256.lower())
+
+
+def find_bank_by_display_name(display_name: str) -> Optional[BankAppProfile]:
+    """Return a BankAppProfile if the display name matches a known bank."""
+    return _DISPLAYNAME_TO_BANK.get(display_name.lower())
+
+
+def all_official_packages() -> set[str]:
+    """Return the complete set of all known official bank package names."""
+    return set(_PACKAGE_TO_BANK.keys())

app/services/identity/impersonation_engine.py

@@ -0,0 +1,186 @@
+"""
+identity/impersonation_engine.py
+— Detects apps that impersonate legitimate Indian banking applications.
+
+Detection strategy:
+  1. Certificate mismatch:    Package matches official but certificate differs.
+  2. Name similarity:         App name closely resembles a known bank app name.
+  3. Package squatting:       Package name is a close variant of an official one.
+  4. Icon hash comparison:    (stub — requires image processing in production)
+"""
+
+from __future__ import annotations
+
+import difflib
+import logging
+import re
+from typing import Optional
+
+from app.services.apk_intelligence.models import ImpersonationResult
+from app.services.identity.bank_registry import (
+    BANK_REGISTRY,
+    all_official_packages,
+    find_bank_by_display_name,
+    get_bank_by_cert,
+    get_bank_by_package,
+    is_official_package,
+)
+
+logger = logging.getLogger(__name__)
+
+# Similarity threshold: above this → flag as impersonation attempt
+_NAME_SIMILARITY_THRESHOLD = 0.72
+_PACKAGE_SIMILARITY_THRESHOLD = 0.80
+
+
+async def run_impersonation_check(
+    package_name: str,
+    app_name: Optional[str],
+    certificate_hash: Optional[str],
+) -> ImpersonationResult:
+    """
+    Check whether an APK is impersonating a legitimate banking app.
+
+    Returns ImpersonationResult with impersonation flag, target bank, and similarity score.
+    """
+    try:
+        # 1. Official package + wrong certificate (clone attack)
+        cert_result = _check_cert_mismatch(package_name, certificate_hash)
+        if cert_result.is_impersonating:
+            return cert_result
+
+        # 2. Display name similarity attack
+        if app_name:
+            name_result = _check_name_similarity(app_name)
+            if name_result.is_impersonating:
+                return name_result
+
+        # 3. Package name squatting
+        pkg_result = _check_package_squatting(package_name)
+        if pkg_result.is_impersonating:
+            return pkg_result
+
+        return ImpersonationResult(is_impersonating=False)
+
+    except Exception as exc:
+        logger.exception("Impersonation check failed for %s", package_name)
+        return ImpersonationResult(is_impersonating=False)
+
+
+def _check_cert_mismatch(
+    package_name: str,
+    certificate_hash: Optional[str],
+) -> ImpersonationResult:
+    """
+    If the package name matches an official bank app but the certificate
+    does NOT match the registered cert → very high confidence impersonation.
+    """
+    if not is_official_package(package_name):
+        return ImpersonationResult(is_impersonating=False)
+
+    profile = get_bank_by_package(package_name)
+    if profile is None:
+        return ImpersonationResult(is_impersonating=False)
+
+    # If we have a registered cert and it doesn't match → clone
+    if profile.cert_sha256 and certificate_hash:
+        if profile.cert_sha256.lower() != certificate_hash.lower():
+            logger.warning(
+                "Certificate mismatch for %s: expected %s, got %s",
+                package_name, profile.cert_sha256[:16] + "...", certificate_hash[:16] + "...",
+            )
+            return ImpersonationResult(
+                is_impersonating=True,
+                impersonated_bank=profile.bank_name,
+                similarity_score=0.97,  # Near-certain clone
+            )
+
+    # Package matches but no cert registered → suspicious but not confirmed
+    if not profile.cert_sha256:
+        return ImpersonationResult(
+            is_impersonating=False,
+            similarity_score=0.50,
+        )
+
+    return ImpersonationResult(is_impersonating=False)
+
+
+def _check_name_similarity(app_name: str) -> ImpersonationResult:
+    """
+    Use sequence matching to detect display names that closely resemble
+    known banking app names (e.g. "SBlMobile" vs "SBIAnywhere").
+    """
+    # Collect all official display names for comparison
+    all_display_names: list[tuple[str, str]] = []  # (bank_name, display_name)
+    for profile in BANK_REGISTRY:
+        for dname in profile.display_names:
+            all_display_names.append((profile.bank_name, dname))
+
+    best_score = 0.0
+    best_bank: Optional[str] = None
+
+    for bank_name, official_name in all_display_names:
+        score = difflib.SequenceMatcher(
+            None,
+            _normalise(app_name),
+            _normalise(official_name),
+        ).ratio()
+
+        if score > best_score:
+            best_score = score
+            best_bank = bank_name
+
+    if best_score >= _NAME_SIMILARITY_THRESHOLD:
+        # Extra check: if the name matches but the package wasn't flagged,
+        # this is a display-name spoofing attack
+        logger.info(
+            "Display name '%s' is %.0f%% similar to %s apps",
+            app_name, best_score * 100, best_bank,
+        )
+        return ImpersonationResult(
+            is_impersonating=True,
+            impersonated_bank=best_bank,
+            similarity_score=round(best_score, 3),
+        )
+
+    return ImpersonationResult(is_impersonating=False)
+
+
+def _check_package_squatting(package_name: str) -> ImpersonationResult:
+    """
+    Detect typosquatting / package squatting: package names that are
+    near-identical to official ones (e.g. com.sbi.yono vs com.sbi.lotusintouch).
+    """
+    official_packages = all_official_packages()
+    best_score = 0.0
+    best_pkg: Optional[str] = None
+
+    normed = _normalise_pkg(package_name)
+
+    for official_pkg in official_packages:
+        score = difflib.SequenceMatcher(
+            None, normed, _normalise_pkg(official_pkg)
+        ).ratio()
+        if score > best_score:
+            best_score = score
+            best_pkg = official_pkg
+
+    if best_score >= _PACKAGE_SIMILARITY_THRESHOLD and best_pkg:
+        profile = get_bank_by_package(best_pkg)
+        return ImpersonationResult(
+            is_impersonating=True,
+            impersonated_bank=profile.bank_name if profile else best_pkg,
+            similarity_score=round(best_score, 3),
+        )
+
+    return ImpersonationResult(is_impersonating=False)
+
+
+def _normalise(text: str) -> str:
+    """Lower-case, strip non-alphanumeric for string comparison."""
+    return re.sub(r"[^a-z0-9]", "", text.lower())
+
+
+def _normalise_pkg(pkg: str) -> str:
+    """Normalise package name by removing dots and lower-casing."""
+    return pkg.lower().replace(".", "")

app/utils.py

@@ -0,0 +1,27 @@
+"""app/utils.py — Shared async helpers."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Coroutine, Any
+
+logger = logging.getLogger(__name__)
+
+
+def fire_and_forget(coro: Coroutine[Any, Any, Any]) -> None:
+    """Schedule a coroutine as a non-blocking background task.
+
+    Exceptions inside the coroutine are logged but never propagate —
+    a storage failure must never break a security response.
+    """
+    async def _guarded() -> None:
+        try:
+            await coro
+        except Exception as exc:
+            logger.warning("Background DB write failed (non-critical): %s", exc)
+
+    try:
+        asyncio.get_running_loop().create_task(_guarded())
+    except RuntimeError:
+        # No running event loop (e.g., pure-sync unit tests) — skip silently.
+        pass

main.py

@@ -0,0 +1,101 @@
+"""
+APK Scanner Microservice
+Stateless — no DB, no Redis. Receives APK → analyzes → returns JSON.
+Deploys to Hugging Face Spaces (port 7860) or any container host.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from typing import List, Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.gzip import GZipMiddleware
+
+from app.config import get_settings
+from app.services.apk_intelligence.analyzer import APKAnalyzer
+from app.services.apk_intelligence.models import (
+    ApkAnalysisRequest,
+    ThreatIntelligenceResponse,
+)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+)
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+app = FastAPI(title="ShieldYONO APK Scanner", version="1.0.0")
+app.add_middleware(GZipMiddleware, minimum_size=1000)
+
+_analyzer = APKAnalyzer()
+
+
+def _parse_permissions(raw: str | None) -> List[str]:
+    if not raw:
+        return []
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, list):
+            return parsed
+    except (json.JSONDecodeError, TypeError):
+        pass
+    return [p.strip() for p in raw.split(",") if p.strip()]
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {
+        "status": "healthy",
+        "service": "apk-scanner",
+        "engines": {
+            "androguard": True,
+            "yara": settings.YARA_ENABLED,
+            "ml": settings.ML_ENABLED,
+            "impersonation": True,
+        },
+    }
+
+
+@app.post("/analyze", response_model=ThreatIntelligenceResponse)
+async def analyze(
+    file: UploadFile = File(...),
+    package_name: str = Form(...),
+    app_label: Optional[str] = Form(None),
+    cert_hash: Optional[str] = Form(None),
+    permissions: Optional[str] = Form(None),
+    local_risk_score: float = Form(0.0),
+) -> ThreatIntelligenceResponse:
+    analysis_id = str(uuid.uuid4())
+
+    if not file.filename or not file.filename.lower().endswith(".apk"):
+        raise HTTPException(status_code=400, detail="File must have .apk extension.")
+
+    apk_bytes = await file.read()
+    max_bytes = settings.MAX_APK_SIZE_MB * 1024 * 1024
+    if len(apk_bytes) > max_bytes:
+        raise HTTPException(status_code=413, detail=f"APK exceeds {settings.MAX_APK_SIZE_MB} MB limit.")
+    if len(apk_bytes) == 0:
+        raise HTTPException(status_code=400, detail="Empty APK file.")
+
+    metadata = ApkAnalysisRequest(
+        packageName=package_name,
+        appName=app_label,
+        certificateHash=cert_hash,
+        permissions=_parse_permissions(permissions),
+        localRisk=local_risk_score,
+    )
+
+    logger.info("[%s] Analyzing %s (%d bytes)", analysis_id, package_name, len(apk_bytes))
+    return await _analyzer.analyze(
+        apk_bytes=apk_bytes,
+        metadata=metadata,
+        analysis_id=analysis_id,
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

models/apk_classifier.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:61fdabe2dad75047eba99ead79b66e0a3d1d0ee1f332668ea59adfc8e49556d0
+size 907450

requirements.txt

@@ -0,0 +1,18 @@
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+pydantic>=2.7.0
+pydantic-settings>=2.3.0
+python-multipart>=0.0.9
+httpx>=0.27.0
+aiofiles>=23.2.1
+cryptography>=42.0.0
+
+# ── Heavy analysis engines ────────────────────────────────────────────────────
+androguard>=4.1.4
+yara-python>=4.5.0
+# apkid>=2.1.5          # uncomment when available
+
+# ── ML classifier (uncomment when model is ready) ─────────────────────────────
+# joblib>=1.4.0
+# scikit-learn>=1.4.0
+# numpy>=1.26.0

rules/android_banker.yar

@@ -0,0 +1,64 @@
+/*
+ * android_banker.yar — ShieldYONO Android Malware Signatures
+ *
+ * Detects banking trojans: credential harvesting, overlay attacks,
+ * and known malware family byte-strings found in DEX or asset files.
+ *
+ * Severity: CRITICAL
+ */
+
+rule BANKING_TROJAN
+{
+    meta:
+        severity    = "CRITICAL"
+        description = "Banking trojan — credential harvesting, overlay attack, or known family"
+        author      = "ShieldYONO Security"
+        reference   = "Android.Banker"
+        date        = "2024-01-01"
+
+    strings:
+        // ── Known banking trojan family identifiers ──────────────────────────
+        // These strings appear in DEX string pools or embedded asset paths
+        $fam_bankbot    = "bankbot"    ascii nocase
+        $fam_cerberus   = "cerberus"   ascii nocase
+        $fam_flubot     = "flubot"     ascii nocase
+        $fam_sharkbot   = "sharkbot"   ascii nocase
+        $fam_eventbot   = "eventbot"   ascii nocase
+        $fam_anubis     = "anubis_c2"  ascii nocase
+        $fam_godfather  = "godfather"  ascii nocase
+        $fam_octo       = "octo.panel" ascii nocase
+        $fam_joker      = "joker.payload" ascii nocase
+
+        // ── Credential harvesting field names in layout XML or DEX ───────────
+        $cred_card      = "cardNumber"     ascii
+        $cred_cvv       = "inputCvv"       ascii
+        $cred_expiry    = "expiryDate"     ascii
+        $cred_pin       = "enterPin"       ascii
+        $cred_pass_et   = "etPassword"     ascii
+        $cred_pass_edit = "editPassword"   ascii
+        $cred_pass_hint = "passwordHint"   ascii
+
+        // ── Overlay / screen-draw permission ────────────────────────────────
+        // wide catches UTF-16 in binary AXML manifest; ascii catches DEX string pool
+        $overlay_perm   = "SYSTEM_ALERT_WINDOW"     ascii wide
+        $overlay_type   = "TYPE_APPLICATION_OVERLAY" ascii
+        $overlay_draw   = "drawOverApps"             ascii
+
+        // ── Fake login UI indicators ─────────────────────────────────────────
+        $fake_login1    = "fakeLoginActivity"  ascii nocase
+        $fake_login2    = "overlayActivity"    ascii nocase
+        $fake_login3    = "phishingWebView"    ascii nocase
+
+    condition:
+        // Definitive family string hit
+        1 of ($fam_*)
+        or
+        // Credential field cluster — genuine banking trojans harvest many fields
+        3 of ($cred_*)
+        or
+        // Overlay permission paired with any credential field
+        (1 of ($overlay_*) and 1 of ($cred_*))
+        or
+        // Explicit fake-login string
+        1 of ($fake_login*)
+}

rules/otp_stealer.yar

@@ -0,0 +1,53 @@
+/*
+ * otp_stealer.yar — ShieldYONO Android Malware Signatures
+ *
+ * Detects APKs that read, intercept, or forward SMS messages,
+ * a hallmark of OTP-stealing banking malware.
+ *
+ * Severity: HIGH
+ */
+
+rule OTP_STEALER
+{
+    meta:
+        severity    = "HIGH"
+        description = "SMS interception and OTP theft — reads or forwards one-time passwords"
+        author      = "ShieldYONO Security"
+        reference   = "Android.Banker.OTPStealer"
+        date        = "2024-01-01"
+
+    strings:
+        // Permission strings — stored as UTF-16 LE in binary AXML manifest,
+        // so match both ascii (DEX string pool) and wide (AXML binary format)
+        $p_read    = "READ_SMS"    ascii wide
+        $p_receive = "RECEIVE_SMS" ascii wide
+        $p_send    = "SEND_SMS"    ascii wide
+
+        // Android SMS API class and content-provider URI (DEX string pool, ASCII)
+        $api_class  = "SmsMessage"             ascii
+        $api_body   = "getMessageBody"         ascii
+        $api_addr   = "getOriginatingAddress"  ascii
+        $api_uri    = "content://sms"          ascii
+
+        // Smali class descriptor for SMS broadcast receiver (DEX)
+        $smali_sms  = "Landroid/telephony/SmsMessage;" ascii
+
+        // OTP-related keyword literals often present in stealer DEX string pools
+        $kw_otp1  = "otp"              ascii nocase
+        $kw_otp2  = "one-time"         ascii nocase
+        $kw_otp3  = "otpCode"          ascii
+        $kw_otp4  = "verificationCode" ascii
+
+    condition:
+        // Two or more SMS permission strings (wide catches binary AXML)
+        (2 of ($p_*))
+        or
+        // SMS API usage combined with any permission string
+        (1 of ($api_*) and 1 of ($p_*))
+        or
+        // Direct OTP keyword combined with SMS permission
+        (1 of ($kw_*) and 1 of ($p_*))
+        or
+        // Pure DEX: two SMS API strings — sufficient without permission match
+        (2 of ($api_*, $smali_sms))
+}

rules/rat.yar

@@ -0,0 +1,58 @@
+/*
+ * rat.yar — ShieldYONO Android Malware Signatures
+ *
+ * Detects Remote Access Trojans (RATs): accessibility service abuse,
+ * screen capture, and remote shell / command-and-control patterns.
+ *
+ * Severity: HIGH
+ */
+
+rule REMOTE_ACCESS_TROJAN
+{
+    meta:
+        severity    = "HIGH"
+        description = "Remote Access Trojan — accessibility abuse, screen capture, or remote commands"
+        author      = "ShieldYONO Security"
+        reference   = "Android.RAT"
+        date        = "2024-01-01"
+
+    strings:
+        // ── Accessibility service abuse ──────────────────────────────────────
+        // Permission stored as UTF-16 in binary AXML; wide catches that encoding
+        $acc_perm       = "BIND_ACCESSIBILITY_SERVICE"  ascii wide
+        // Class and callback method names found in DEX
+        $acc_service    = "AccessibilityService"        ascii
+        $acc_event      = "onAccessibilityEvent"        ascii
+        $acc_action     = "performGlobalAction"         ascii
+        $acc_node       = "AccessibilityNodeInfo"       ascii
+
+        // ── Screen capture / remote viewing ─────────────────────────────────
+        $screen_proj    = "MediaProjection"             ascii
+        $screen_vdisp   = "createVirtualDisplay"        ascii
+        $screen_cap     = "screencap"                   ascii nocase
+
+        // ── Remote shell / command execution ────────────────────────────────
+        // Use exact Smali descriptor to avoid matching RuntimeException
+        $cmd_runtime    = "Ljava/lang/Runtime;"         ascii
+        $cmd_exec       = "getRuntime"                  ascii
+        $cmd_shell      = "/system/bin/sh"              ascii
+        $cmd_builder    = "ProcessBuilder"              ascii
+
+        // ── C2 / remote command channel indicators ───────────────────────────
+        $c2_cmd         = "sendCommand"  ascii
+        $c2_exec        = "executeCmd"   ascii
+        $c2_socket      = "connectToC2"  ascii
+
+    condition:
+        // BIND_ACCESSIBILITY_SERVICE permission (wide = binary AXML, ascii = DEX string pool)
+        $acc_perm
+        or
+        // Accessibility callback method + service class — rules out compat-lib stub matches
+        ($acc_event and 1 of ($acc_service, $acc_action, $acc_node))
+        or
+        // Screen capture combined with accessibility or shell access
+        (1 of ($screen_*) and (1 of ($acc_*) or 1 of ($cmd_*)))
+        or
+        // Remote shell with C2 indicator
+        (2 of ($cmd_*) and 1 of ($c2_*))
+}