printerxpl-forge 6.2.0__py3-none-any.whl

src/utils/exploit_manager.py

@@ -0,0 +1,805 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PrinterXPL-Forge — Exploit Manager
+================================
+Loads, indexes, matches and executes exploits from the xpl/ directory.
+
+Directory structure expected:
+  xpl/
+  ├── index.json           # Auto-regenerated master index
+  ├── edb-15631/
+  │   ├── metadata.json    # Exploit metadata
+  │   └── exploit.py       # check() + run() functions
+  ├── custom/
+  │   ├── TEMPLATE.py      # Reference template
+  │   └── my_exploit.py    # User-created exploit
+  └── ...
+
+Exploit contract (exploit.py must export):
+  - check(host, port, timeout) -> bool   # non-destructive vulnerability check
+  - run(host, port, timeout, **opts) -> dict   # exploit execution
+  - METADATA = {...}  (optional — falls back to metadata.json)
+
+Integration points:
+  - Called by vuln_scanner / banner_grabber to show matched exploits on scan
+  - Called by main.py for --xpl-list, --xpl-run, --xpl-check, --xpl-update
+"""
+# Author    : Andre Henrique (@mrhenrike)
+# GitHub    : https://github.com/mrhenrike
+# LinkedIn  : https://linkedin.com/in/mrhenrike
+# X/Twitter : https://x.com/mrhenrike
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+import os
+import re
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+_log = logging.getLogger(__name__)
+
+# ── Paths ──────────────────────────────────────────────────────────────────────
+# xpl/ sits at project root (one level above src/)
+_SRC_DIR  = Path(__file__).resolve().parent.parent          # src/
+_ROOT_DIR = _SRC_DIR.parent                                  # project root
+XPL_DIR   = _ROOT_DIR / 'xpl'
+INDEX_FILE = XPL_DIR / 'index.json'
+
+# Severity sort order
+_SEV_ORDER = {'critical': 0, 'high': 1, 'medium': 2, 'low': 3, 'info': 4}
+
+# ANSI colours
+_RED  = '\033[1;31m'
+_YEL  = '\033[1;33m'
+_GRN  = '\033[0;32m'
+_CYN  = '\033[1;36m'
+_DIM  = '\033[2;37m'
+_RST  = '\033[0m'
+_SEV_CLR = {
+    'critical': '\033[1;31m',
+    'high':     '\033[0;31m',
+    'medium':   '\033[1;33m',
+    'low':      '\033[1;34m',
+    'info':     '\033[2;37m',
+}
+
+
+# ── Data model ────────────────────────────────────────────────────────────────
+
+@dataclass
+class Exploit:
+    """Loaded exploit module with metadata."""
+    id:               str
+    path:             Path
+    metadata:         Dict          = field(default_factory=dict)
+
+    # Callable attributes set after load
+    _check_fn:        Optional[Callable] = field(default=None, repr=False)
+    _run_fn:          Optional[Callable] = field(default=None, repr=False)
+
+    @property
+    def title(self) -> str:
+        return self.metadata.get('title', self.id)
+
+    @property
+    def cve(self) -> str:
+        return self.metadata.get('cve', '')
+
+    @property
+    def severity(self) -> str:
+        return self.metadata.get('severity', 'info')
+
+    @property
+    def cvss(self) -> float:
+        try:
+            return float(self.metadata.get('cvss', 0))
+        except (TypeError, ValueError):
+            return 0.0
+
+    @property
+    def vendors(self) -> List[str]:
+        return self.metadata.get('vendor', [])
+
+    @property
+    def model_patterns(self) -> List[str]:
+        return self.metadata.get('model_patterns', [])
+
+    @property
+    def category(self) -> str:
+        return self.metadata.get('category', '')
+
+    @property
+    def protocol(self) -> str:
+        return self.metadata.get('protocol', '')
+
+    @property
+    def port(self) -> int:
+        return int(self.metadata.get('port', 0))
+
+    @property
+    def requires(self) -> List[str]:
+        return self.metadata.get('requires', [])
+
+    @property
+    def tags(self) -> List[str]:
+        return self.metadata.get('tags', [])
+
+    @property
+    def source_url(self) -> str:
+        return self.metadata.get('url', '')
+
+    def check(self, host: str, port: int = None,
+              timeout: float = 8) -> bool:
+        """Run the non-destructive vulnerability check."""
+        if not self._check_fn:
+            return False
+        p = port or self.port
+        try:
+            return bool(self._check_fn(host, p, timeout))
+        except Exception as exc:
+            _log.debug("[%s] check() error: %s", self.id, exc)
+            return False
+
+    def run(self, host: str, port: int = None, timeout: float = 15,
+            dry_run: bool = True, **kwargs) -> Dict:
+        """Execute the exploit."""
+        if not self._run_fn:
+            return {'success': False, 'error': 'exploit.py not loaded', 'evidence': ''}
+        p = port or self.port
+        try:
+            return self._run_fn(host, p, timeout, dry_run=dry_run, **kwargs)
+        except Exception as exc:
+            return {'success': False, 'error': str(exc)[:120], 'evidence': ''}
+
+
+# ── Loader ────────────────────────────────────────────────────────────────────
+
+def _load_metadata(directory: Path) -> Dict:
+    """Load metadata.json from an exploit directory."""
+    meta_path = directory / 'metadata.json'
+    if meta_path.exists():
+        try:
+            with open(meta_path, encoding='utf-8') as f:
+                return json.load(f)
+        except Exception as exc:
+            _log.warning("metadata.json error in %s: %s", directory.name, exc)
+    return {}
+
+
+def _load_module(directory: Path) -> Tuple[Optional[Callable], Optional[Callable], Dict]:
+    """
+    Dynamically import exploit.py from directory.
+
+    Returns: (check_fn, run_fn, embedded_metadata)
+    """
+    py_path = directory / 'exploit.py'
+    if not py_path.exists():
+        return None, None, {}
+
+    try:
+        spec = importlib.util.spec_from_file_location(
+            f'xpl_{directory.name}', py_path
+        )
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+        check_fn = getattr(mod, 'check', None)
+        run_fn   = getattr(mod, 'run',   None)
+        meta     = getattr(mod, 'METADATA', {})
+        return check_fn, run_fn, meta
+    except Exception as exc:
+        _log.warning("Failed to load %s: %s", py_path, exc)
+        return None, None, {}
+
+
+def load_all_exploits(source_filter: str = None) -> List[Exploit]:
+    """
+    Discover and load all exploits from xpl/ directory tree.
+
+    Scans:
+    - Direct subdirectories of xpl/ (edb-15631/, etc.)
+    - xpl/custom/   — standalone .py exploits (user-created)
+    - xpl/msf/      — Metasploit-ported modules
+    - xpl/research/ — original research / PoC modules
+
+    Args:
+        source_filter: if set, only load exploits where metadata['source'] matches
+                       one of: 'exploit-db', 'metasploit', 'research', 'custom'
+
+    Returns list of loaded Exploit instances, sorted by severity.
+    """
+    if not XPL_DIR.exists():
+        _log.warning("xpl/ directory not found at %s", XPL_DIR)
+        return []
+
+    exploits: List[Exploit] = []
+
+    # ── Category subfolders (msf/, research/) ─────────────────────────────────
+    _CATEGORY_DIRS = {'msf', 'research'}
+
+    for item in sorted(XPL_DIR.iterdir()):
+        if not item.is_dir() or item.name.startswith('.'):
+            continue
+
+        # standalone .py exploits (custom/)
+        if item.name == 'custom':
+            for sub in sorted(item.iterdir()):
+                if sub.is_file() and sub.suffix == '.py' and not sub.name.startswith('_'):
+                    _load_single_py_exploit(sub, exploits)
+            continue
+
+        # category subdirectory (msf/, research/) — recurse one level
+        if item.name in _CATEGORY_DIRS:
+            for sub_dir in sorted(item.iterdir()):
+                if not sub_dir.is_dir() or sub_dir.name.startswith('.'):
+                    continue
+                _load_dir_exploit(sub_dir, exploits)
+            continue
+
+        # Standard edb-XXXXX/ directory
+        _load_dir_exploit(item, exploits)
+
+    # Filter by source if requested
+    if source_filter:
+        sf = source_filter.lower()
+        exploits = [x for x in exploits
+                    if x.metadata.get('source', '').lower() == sf]
+
+    return sorted(exploits, key=lambda x: _SEV_ORDER.get(x.severity, 99))
+
+
+def _load_dir_exploit(directory: Path, exploits: list) -> None:
+    """Load a standard directory-based exploit (metadata.json + exploit.py)."""
+    meta_file = directory / 'metadata.json'
+    py_file   = directory / 'exploit.py'
+    if not meta_file.exists() and not py_file.exists():
+        return
+
+    meta                      = _load_metadata(directory)
+    check_fn, run_fn, emb_meta = _load_module(directory)
+    merged_meta               = {**meta, **emb_meta} if emb_meta else meta
+
+    exploit_id = merged_meta.get('id', directory.name.upper())
+    xpl = Exploit(
+        id=exploit_id,
+        path=directory,
+        metadata=merged_meta,
+        _check_fn=check_fn,
+        _run_fn=run_fn,
+    )
+    exploits.append(xpl)
+    _log.debug("Loaded exploit: %s", exploit_id)
+
+
+def _load_single_py_exploit(py_path: Path, exploits: list) -> None:
+    """Load a standalone .py exploit file (custom/ style)."""
+    try:
+        spec = importlib.util.spec_from_file_location(f'xpl_custom_{py_path.stem}', py_path)
+        mod  = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+        meta     = getattr(mod, 'METADATA', {})
+        check_fn = getattr(mod, 'check', None)
+        run_fn   = getattr(mod, 'run',   None)
+
+        if not meta and not check_fn:
+            return  # Skip files without the required interface
+
+        exploit_id = meta.get('id', py_path.stem.upper())
+        xpl = Exploit(
+            id=exploit_id,
+            path=py_path.parent,
+            metadata=meta,
+            _check_fn=check_fn,
+            _run_fn=run_fn,
+        )
+        exploits.append(xpl)
+    except Exception as exc:
+        _log.debug("Custom exploit load error %s: %s", py_path.name, exc)
+
+
+# ── Matcher ───────────────────────────────────────────────────────────────────
+
+def match_exploits(
+    exploits:   List[Exploit],
+    make:       str = '',
+    model:      str = '',
+    firmware:   str = '',
+    open_ports: List[int] = None,
+    langs:      List[str] = None,
+    cves:       List[str] = None,
+) -> List[Exploit]:
+    """
+    Filter exploits matching a specific printer fingerprint.
+
+    Matching criteria (ANY match = included):
+      - CVE match against known CVE list
+      - Vendor/make name match (case-insensitive)
+      - Model pattern regex match
+      - Port requirement satisfied
+      - Language requirement satisfied
+      - Firmware pattern match
+
+    Returns sorted list of matched exploits (critical first).
+    """
+    ports = set(open_ports or [])
+    langs_upper = {l.upper() for l in (langs or [])}
+    cves_upper  = {c.upper() for c in (cves  or [])}
+    target_str  = f"{make} {model} {firmware}".lower()
+
+    matched = []
+    for xpl in exploits:
+        score = 0
+
+        # CVE match
+        if xpl.cve and xpl.cve.upper() in cves_upper:
+            score += 10
+
+        # Vendor match
+        vendors_lower = [v.lower() for v in xpl.vendors]
+        if make.lower() and any(v in make.lower() or make.lower() in v
+                                for v in vendors_lower if v):
+            score += 5
+
+        # Model pattern match
+        for pat in xpl.model_patterns:
+            if pat and re.search(pat, target_str, re.I):
+                score += 3
+                break
+
+        # Firmware pattern match
+        for pat in xpl.metadata.get('firmware_patterns', []):
+            if pat and re.search(pat, firmware, re.I):
+                score += 2
+                break
+
+        # Port requirement match
+        req_ports_met = True
+        for req in xpl.requires:
+            if req.startswith('port:'):
+                p = int(req.split(':')[1])
+                if p not in ports:
+                    req_ports_met = False
+                    break
+            elif req.startswith('lang:'):
+                lang = req.split(':')[1].upper()
+                if lang not in langs_upper:
+                    score = max(score - 1, 0)  # penalise but don't exclude
+
+        if not req_ports_met:
+            continue
+
+        # If vendors specified but none match, still include if port matches
+        if xpl.vendors and score == 0 and ports & {xpl.port}:
+            score = 1  # low-confidence match
+
+        # No vendor specified = generic (matches anything with right port)
+        if not xpl.vendors and ports & {xpl.port}:
+            score = max(score, 1)
+
+        if score > 0:
+            matched.append((score, xpl))
+
+    # Sort: higher score first, then severity
+    matched.sort(key=lambda x: (-x[0], _SEV_ORDER.get(x[1].severity, 99)))
+    return [x[1] for x in matched]
+
+
+# ── Printer ───────────────────────────────────────────────────────────────────
+
+_SRC_BADGE = {
+    'metasploit':  '\033[1;35m[MSF]\033[0m',
+    'exploit-db':  '\033[1;34m[EDB]\033[0m',
+    'research':    '\033[1;33m[RES]\033[0m',
+    'custom':      '\033[1;32m[USR]\033[0m',
+    'nvd':         '\033[1;36m[NVD]\033[0m',
+}
+
+
+def print_exploit_list(exploits: List[Exploit], title: str = 'Available Exploits') -> None:
+    """Pretty-print a list of exploits to stdout."""
+    if not exploits:
+        print(f"  {_DIM}No exploits found.{_RST}")
+        return
+
+    # Group by source for summary
+    by_source: Dict[str, int] = {}
+    for x in exploits:
+        s = x.metadata.get('source', 'unknown')
+        by_source[s] = by_source.get(s, 0) + 1
+
+    print(f"\n  {_CYN}{'='*72}{_RST}")
+    print(f"  {_CYN}{title} ({len(exploits)}){_RST}")
+    src_summary = '  '.join(
+        f"{_SRC_BADGE.get(s, f'[{s}]')} {n}"
+        for s, n in sorted(by_source.items())
+    )
+    print(f"  {src_summary}")
+    print(f"  {_CYN}{'='*72}{_RST}")
+    print(f"  {'SRC':<6} {'ID':<30} {'SEV':<10} {'CVSS':<6} {'CAT':<16} TITLE")
+    print(f"  {'-'*72}")
+    for xpl in exploits:
+        sev_clr = _SEV_CLR.get(xpl.severity, _DIM)
+        cve_str = f"[{xpl.cve}]" if xpl.cve else ''
+        src     = xpl.metadata.get('source', '?')
+        badge   = _SRC_BADGE.get(src, f'[{src[:3].upper()}]')
+        print(f"  {badge} {_GRN}{xpl.id:<30}{_RST} "
+              f"{sev_clr}{xpl.severity:<10}{_RST} "
+              f"{xpl.cvss:<6.1f} "
+              f"{xpl.category:<16} "
+              f"{xpl.title[:35]}")
+        if cve_str:
+            print(f"  {'':6} {'':30} {_DIM}{cve_str}{_RST}")
+    print()
+
+
+def print_matched_exploits(matched: List[Exploit], target: str) -> None:
+    """Print matched exploits for a scanned target (compact format for --scan output)."""
+    if not matched:
+        return
+
+    print(f"\n  {_RED}{'!'*3} EXPLOITS AVAILABLE FOR {target} {'!'*3}{_RST}")
+    print(f"  {'-'*65}")
+    for xpl in matched[:10]:
+        sev_clr = _SEV_CLR.get(xpl.severity, _DIM)
+        cve_str = f"  CVE: {xpl.cve}" if xpl.cve else ''
+        ref_str = f"  {_DIM}{xpl.source_url[:55]}{_RST}" if xpl.source_url else ''
+        print(f"  {sev_clr}[{xpl.severity.upper()}]{_RST} {_GRN}{xpl.id}{_RST}  {xpl.title}")
+        if cve_str:
+            print(f"  {_DIM}{cve_str}{_RST}")
+        if ref_str:
+            print(ref_str)
+        print(f"  {_DIM}Run: python src/main.py {target} --xpl-run {xpl.id} --dry{_RST}")
+        print()
+
+
+def print_run_result(result: Dict, exploit_id: str) -> None:
+    """Print the result of running an exploit."""
+    success   = result.get('success', False)
+    evidence  = result.get('evidence', '')
+    error     = result.get('error', '')
+    creds     = result.get('credentials', [])
+    files     = result.get('files', [])
+    vuln      = result.get('vulnerable', success)
+
+    icon = f"{_RED}[EXPLOITED]{_RST}" if (success and not result.get('dry_run')) else (
+           f"{_YEL}[VULN]{_RST}"     if vuln else
+           f"{_GRN}[OK / NOT VULN]{_RST}")
+
+    print(f"\n  {icon} {exploit_id}")
+    if evidence:
+        print(f"  Evidence:")
+        for line in evidence.strip().splitlines():
+            print(f"    {line}")
+    if creds:
+        print(f"\n  {_RED}Credentials / Sensitive Data:{_RST}")
+        for c in creds[:10]:
+            print(f"    {c}")
+    if files:
+        print(f"\n  Files ({len(files)}):")
+        for f in files[:15]:
+            print(f"    {f.get('type','?'):5} {f.get('path','?')}")
+    if error:
+        print(f"  {_DIM}Error: {error}{_RST}")
+    print()
+
+
+# ── Update / download ─────────────────────────────────────────────────────────
+
+def update_index(exploits: List[Exploit]) -> None:
+    """Regenerate xpl/index.json from loaded exploits."""
+    index = {
+        '_comment':   'PrinterXPL-Forge exploit index. Auto-regenerated by --xpl-update.',
+        '_version':   '2.0',
+        '_generated': time.strftime('%Y-%m-%d'),
+        'exploits':   [
+            {
+                'id':       x.id,
+                'source':   x.metadata.get('source', 'unknown'),
+                'path':     str(x.path.relative_to(XPL_DIR)),
+                'cve':      x.cve,
+                'title':    x.title,
+                'severity': x.severity,
+                'vendor':   x.vendors,
+                'category': x.category,
+                'port':     x.port,
+                'protocol': x.protocol,
+                'cvss':     x.cvss,
+                'url':      x.source_url,
+            }
+            for x in exploits
+        ],
+    }
+    with open(INDEX_FILE, 'w', encoding='utf-8') as f:
+        json.dump(index, f, indent=2)
+    # Print breakdown by source
+    by_src: Dict[str, int] = {}
+    for x in exploits:
+        s = x.metadata.get('source', 'unknown')
+        by_src[s] = by_src.get(s, 0) + 1
+    src_str = ', '.join(f'{s}:{n}' for s, n in sorted(by_src.items()))
+    print(f"  {_GRN}[+]{_RST} index.json updated — {len(exploits)} exploits [{src_str}]")
+
+
+def fetch_exploit_db_raw(edb_id: str, output_dir: Path = None) -> Optional[Path]:
+    """
+    Download a raw exploit from ExploitDB by ID.
+
+    Creates xpl/edb-{id}/ directory and saves the raw file.
+    Returns the path to the saved file, or None on failure.
+    """
+    try:
+        import requests
+        import urllib3
+        urllib3.disable_warnings()
+
+        url = f"https://www.exploit-db.com/raw/{edb_id}"
+        r   = requests.get(url, timeout=20, verify=False,
+                           headers={'User-Agent': 'PrinterXPL-Forge/3.15'})
+        if r.status_code != 200:
+            print(f"  {_YEL}[!]{_RST} EDB-{edb_id}: HTTP {r.status_code}")
+            return None
+
+        save_dir = output_dir or (XPL_DIR / f'edb-{edb_id}')
+        save_dir.mkdir(parents=True, exist_ok=True)
+
+        # Determine extension from content
+        content = r.text
+        ext = '.rb' if 'Msf::' in content else '.py' if 'import ' in content else '.txt'
+        out = save_dir / f'raw_edb-{edb_id}{ext}'
+        out.write_text(content, encoding='utf-8')
+
+        print(f"  {_GRN}[+]{_RST} EDB-{edb_id}: saved to {out}")
+        return out
+    except Exception as exc:
+        print(f"  {_YEL}[!]{_RST} EDB-{edb_id}: download failed — {exc}")
+        return None
+
+
+# ── Convenience API ───────────────────────────────────────────────────────────
+
+def get_matched_for_target(
+    make:          str,
+    model:         str,
+    firmware:      str = '',
+    open_ports:    List[int] = None,
+    langs:         List[str] = None,
+    cves:          List[str] = None,
+    source_filter: str = None,
+) -> List[Exploit]:
+    """
+    One-shot: load all exploits and return those matching the target.
+
+    Called from banner_grabber / vuln_scanner / scan pipeline.
+
+    Args:
+        source_filter: optionally restrict to 'metasploit', 'exploit-db',
+                       'research', or 'custom'.
+    """
+    all_exploits = load_all_exploits(source_filter=source_filter)
+    return match_exploits(
+        all_exploits,
+        make=make, model=model, firmware=firmware,
+        open_ports=open_ports, langs=langs, cves=cves,
+    )
+
+
+def list_by_source(source: str) -> List[Exploit]:
+    """Return all exploits matching a specific source label."""
+    return load_all_exploits(source_filter=source)
+
+
+# ── Auto Exploit ───────────────────────────────────────────────────────────────
+
+from dataclasses import dataclass as _dc, field as _field
+
+
+@_dc
+class AutoExploitResult:
+    """Result of an auto_exploit() run for a single exploit module."""
+    exploit:    Exploit
+    vulnerable: bool
+    ran:        bool        = False
+    result:     Dict        = _field(default_factory=dict)
+    params:     Dict        = _field(default_factory=dict)  # pre-filled params used
+
+
+def auto_exploit(
+    host:          str,
+    *,
+    make:          str       = '',
+    model:         str       = '',
+    firmware:      str       = '',
+    open_ports:    List[int] = None,
+    langs:         List[str] = None,
+    cves:          List[str] = None,
+    serial:        str       = '',
+    mac:           str       = '',
+    source_filter: str       = None,
+    custom_xpl_path: str     = None,
+    dry_run:       bool      = True,
+    check_limit:   int       = 8,
+    run_top_n:     int       = 1,
+    timeout:       float     = 10.0,
+    verbose:       bool      = True,
+) -> List[AutoExploitResult]:
+    """
+    Automatic exploit selection, verification, and execution.
+
+    Algorithm:
+      1. Load all available exploits (or from custom_xpl_path if provided).
+      2. Match against the target fingerprint (make/model/firmware/ports/cves).
+      3. Sort candidates by CVSS score descending.
+      4. Run check() on the top `check_limit` candidates (non-destructive).
+      5. For confirmed-vulnerable exploits, pre-fill all required parameters
+         (host, port, serial, mac, vendor) automatically.
+      6. Execute run() on the top `run_top_n` confirmed exploits (dry-run by default).
+      7. Return ordered list of AutoExploitResult.
+
+    Args:
+        host:           Target IP or hostname.
+        make:           Vendor name from fingerprint (e.g. 'Epson').
+        model:          Model string from fingerprint (e.g. 'L3250 Series').
+        firmware:       Firmware version string.
+        open_ports:     List of open ports detected during scan.
+        langs:          Printer languages supported (e.g. ['PJL', 'PS']).
+        cves:           Known CVEs from NVD scan.
+        serial:         Device serial number (from --bf-serial or scan).
+        mac:            Device MAC address (from --bf-mac or scan).
+        source_filter:  Restrict to 'exploit-db', 'metasploit', 'research', 'custom'.
+        custom_xpl_path: Path to a custom exploit .py file to force-use.
+        dry_run:        If True, run() is called in dry-run mode (no destructive actions).
+        check_limit:    Maximum number of candidates to probe with check().
+        run_top_n:      Execute run() on this many top confirmed-vulnerable exploits.
+        timeout:        Socket timeout for check/run calls.
+        verbose:        Print progress to stdout.
+
+    Returns:
+        List of AutoExploitResult, ordered by CVSS descending.
+        Only entries where vulnerable=True and ran=True have result populated.
+    """
+    results: List[AutoExploitResult] = []
+
+    # ── Step 1 & 2: load and match ──────────────────────────────────────────
+    if custom_xpl_path:
+        from pathlib import Path as _Path
+        candidates: List[Exploit] = []
+        _load_single_py_exploit(_Path(custom_xpl_path), candidates)
+        if not candidates:
+            if verbose:
+                print(f"  {_YEL}[!]{_RST} Could not load custom exploit from {custom_xpl_path}")
+            return []
+    else:
+        all_xpls   = load_all_exploits(source_filter=source_filter)
+        candidates = match_exploits(
+            all_xpls,
+            make=make, model=model, firmware=firmware,
+            open_ports=open_ports, langs=langs, cves=cves,
+        )
+
+    if not candidates:
+        if verbose:
+            print(f"  {_DIM}[auto-exploit] No matching exploits found for {make} {model}{_RST}")
+        return []
+
+    if verbose:
+        print(f"\n  {_CYN}{'='*65}{_RST}")
+        print(f"  {_CYN}AUTO EXPLOIT — {host}{_RST}")
+        print(f"  Target  : {make} {model} {firmware}".strip())
+        print(f"  Matched : {len(candidates)} exploit(s)")
+        print(f"  Mode    : {'DRY-RUN' if dry_run else 'LIVE'}")
+        print(f"  {_CYN}{'='*65}{_RST}")
+
+    # ── Step 3: sort by CVSS ────────────────────────────────────────────────
+    candidates.sort(key=lambda x: (-x.cvss, _SEV_ORDER.get(x.severity, 99)))
+
+    # ── Step 4: check() — verify vulnerability ──────────────────────────────
+    confirmed: List[Exploit] = []
+    probed = 0
+    for xpl in candidates:
+        if probed >= check_limit:
+            break
+        probed += 1
+
+        port = xpl.port or (open_ports[0] if open_ports else 9100)
+        sev_clr = _SEV_CLR.get(xpl.severity, _DIM)
+
+        if verbose:
+            print(f"  {_DIM}[check]{_RST} {sev_clr}{xpl.severity.upper():<8}{_RST} "
+                  f"CVSS {xpl.cvss:<5.1f} {_GRN}{xpl.id}{_RST}  {xpl.title[:40]}")
+
+        vuln = xpl.check(host, port=port, timeout=timeout)
+
+        result_entry = AutoExploitResult(
+            exploit    = xpl,
+            vulnerable = vuln,
+            params     = _prefill_params(xpl, host, port, serial, mac, make),
+        )
+
+        if verbose:
+            icon = f"{_RED}[VULN]{_RST}" if vuln else f"{_GRN}[NOT VULN]{_RST}"
+            print(f"         {icon}")
+
+        results.append(result_entry)
+        if vuln:
+            confirmed.append(xpl)
+
+    # ── Step 5 & 6: run() on top confirmed ──────────────────────────────────
+    run_count = 0
+    for res in results:
+        if not res.vulnerable:
+            continue
+        if run_count >= run_top_n:
+            break
+        run_count += 1
+
+        xpl   = res.exploit
+        port  = res.params.get('port', xpl.port or 9100)
+        extra = {k: v for k, v in res.params.items() if k not in ('host', 'port')}
+
+        if verbose:
+            mode_str = f"{_YEL}DRY-RUN{_RST}" if dry_run else f"{_RED}LIVE{_RST}"
+            print(f"\n  {mode_str} Running {_GRN}{xpl.id}{_RST} against {host}:{port}")
+
+        run_result = xpl.run(host, port=port, timeout=timeout, dry_run=dry_run, **extra)
+        res.ran    = True
+        res.result = run_result
+        print_run_result(run_result, xpl.id)
+
+    if verbose and not any(r.vulnerable for r in results):
+        print(f"\n  {_GRN}[OK]{_RST} No confirmed vulnerabilities in the top {probed} checked exploits.")
+
+    return results
+
+
+def _prefill_params(xpl: Exploit, host: str, port: int,
+                    serial: str, mac: str, make: str) -> Dict:
+    """
+    Build the kwargs dict to pass to exploit run(), pre-filling known values.
+
+    Maps standard exploit.requires keys (serial, mac, vendor) to values
+    extracted from fingerprint / CLI arguments.
+    """
+    params: Dict = {
+        'host':   host,
+        'port':   port or xpl.port or 9100,
+    }
+    requires = xpl.requires or []
+    for req in requires:
+        if req == 'serial' and serial:
+            params['serial'] = serial
+        elif req == 'mac' and mac:
+            params['mac'] = mac
+        elif req == 'vendor' and make:
+            params['vendor'] = make.lower()
+    return params
+
+
+def print_auto_exploit_summary(results: List[AutoExploitResult]) -> None:
+    """Print a summary table of all auto-exploit results."""
+    if not results:
+        return
+    vuln_count = sum(1 for r in results if r.vulnerable)
+    ran_count  = sum(1 for r in results if r.ran)
+
+    print(f"\n  {_CYN}{'='*65}{_RST}")
+    print(f"  {_CYN}AUTO EXPLOIT SUMMARY{_RST}")
+    print(f"  Checked    : {len(results)} exploit(s)")
+    print(f"  Vulnerable : {_RED if vuln_count else _GRN}{vuln_count}{_RST}")
+    print(f"  Executed   : {ran_count}")
+    print(f"  {_CYN}{'='*65}{_RST}")
+    print(f"  {'EXPLOIT':<30} {'CVSS':<6} {'VULN':<8} {'RAN':<5} STATUS")
+    print(f"  {'-'*65}")
+    for r in sorted(results, key=lambda x: -x.exploit.cvss):
+        vuln_icon = f"{_RED}YES{_RST}" if r.vulnerable else f"{_GRN}no{_RST}"
+        ran_icon  = "YES" if r.ran else "no"
+        status    = r.result.get('output', '')[:30] if r.result else ''
+        print(f"  {r.exploit.id:<30} {r.exploit.cvss:<6.1f} {vuln_icon:<8} {ran_icon:<5} {status}")
+    print()