driftmux 1.0__py3-none-any.whl

driftmux/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.3.0"

driftmux/cli.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pyfiglet
+
+from driftmux.engine import DriftmuxEngine, ScanConfig
+from driftmux.renderers.console import render_console
+from driftmux.utils import ensure_dir, read_hosts, write_csv, write_json, write_markdown
+
+
+def banner() -> None:
+    click.echo(pyfiglet.figlet_format("Driftmux"))
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--host-file", type=click.Path(exists=True, dir_okay=False), help="File with one host per line")
+@click.option("--host", help="Single host or URL to scan")
+@click.option("--ports", help="Port selection for nmap, for example 1-1000 or 80,443,6443")
+@click.option("--nmap-script", help="Nmap NSE scripts to run, for example vulners or default,vulners")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json", "csv", "markdown"], case_sensitive=False),
+    default="json",
+)
+@click.option("--timeout", type=int, default=600, show_default=True, help="Timeout per external scanner")
+@click.option("--http-only", is_flag=True, help="Prefer HTTP targets for web scanners")
+@click.option("--https-only", is_flag=True, help="Prefer HTTPS targets for web scanners")
+@click.option("--output-dir", default="reports", show_default=True, help="Directory for generated reports")
+@click.option("--log-dir", default="logs", show_default=True, help="Directory for scan logs")
+@click.option("--deep-wordpress", is_flag=True, help="Enable Plecost deep mode for WordPress")
+@click.option(
+    "--profile",
+    "nuclei_profile",
+    type=click.Choice(["passive", "fast", "deep"], case_sensitive=False),
+    default="fast",
+    show_default=True,
+    help="Scan profile. passive disables Nuclei; fast/deep run Nuclei.",
+)
+@click.option(
+    "--vuln-backend",
+    type=click.Choice(["none", "nvd"], case_sensitive=False),
+    default="none",
+    show_default=True,
+    help="Passive vulnerability backend.",
+)
+@click.option(
+    "--min-cvss",
+    type=float,
+    default=0.0,
+    show_default=True,
+    help="Minimum CVSS score for passive vulnerability findings.",
+)
+@click.option(
+    "--nvd-api-key",
+    default=None,
+    help="NVD API key. If omitted, Driftmux also checks the NVD_API_KEY environment variable.",
+)
+@click.option(
+    "--nvd-cache",
+    default="~/.cache/driftmux/nvd.sqlite",
+    show_default=True,
+    help="SQLite cache path for NVD responses.",
+)
+@click.option(
+    "--nvd-cache-ttl-hours",
+    type=int,
+    default=168,
+    show_default=True,
+    help="How long cached NVD responses remain valid.",
+)
+def main(
+    host_file: str | None,
+    host: str | None,
+    ports: str | None,
+    nmap_script: str | None,
+    output_format: str,
+    timeout: int,
+    http_only: bool,
+    https_only: bool,
+    output_dir: str,
+    log_dir: str,
+    deep_wordpress: bool,
+    nuclei_profile: str,
+    vuln_backend: str,
+    min_cvss: float,
+    nvd_api_key: str | None,
+    nvd_cache: str,
+    nvd_cache_ttl_hours: int,
+) -> None:
+    if not host and not host_file:
+        raise click.UsageError("Provide --host or --host-file")
+
+    if http_only and https_only:
+        raise click.UsageError("Use only one of --http-only or --https-only")
+
+    banner()
+
+    scheme = "auto"
+
+    if http_only:
+        scheme = "http"
+    elif https_only:
+        scheme = "https"
+
+    config = ScanConfig(
+        ports=ports,
+        nmap_script=nmap_script,
+        timeout=timeout,
+        web_scheme=scheme,
+        nuclei_profile=nuclei_profile.lower(),
+        output_format=output_format.lower(),
+        output_dir=output_dir,
+        log_dir=log_dir,
+        deep_wordpress=deep_wordpress,
+        vuln_backend=vuln_backend.lower(),
+        min_cvss=min_cvss,
+        nvd_api_key=nvd_api_key,
+        nvd_cache=nvd_cache,
+        nvd_cache_ttl_hours=nvd_cache_ttl_hours,
+    )
+
+    hosts = read_hosts(host_file=host_file, host=host)
+
+    engine = DriftmuxEngine(config)
+    results = engine.scan_hosts(hosts)
+
+    ensure_dir(output_dir)
+
+    out_base = Path(output_dir) / "driftmux-report"
+
+    if config.output_format == "json":
+        path = write_json(out_base.with_suffix(".json"), results)
+    elif config.output_format == "csv":
+        path = write_csv(out_base.with_suffix(".csv"), results)
+    elif config.output_format == "markdown":
+        path = write_markdown(out_base.with_suffix(".md"), results)
+    else:
+        path = None
+
+    render_console(results)
+
+    if path:
+        click.echo(f"\nSaved report to {path}")
+
+
+if __name__ == "__main__":
+    main()

driftmux/engine.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from driftmux.planner import build_scan_plan
+from driftmux.models import HostScanResult
+from driftmux.scanners.nmap import NmapScanner
+from driftmux.scanners.nuclei import NucleiScanner
+from driftmux.scanners.nvd import NvdConfig, NvdCveScanner
+from driftmux.scanners.plecost import PlecostScanner
+
+
+WEB_PORTS = {
+    80,
+    81,
+    443,
+    444,
+    591,
+    593,
+    8000,
+    8008,
+    8080,
+    8081,
+    8088,
+    8443,
+    8888,
+    9443,
+}
+
+
+def is_web_candidate(service) -> bool:
+    svc = (getattr(service, "service", "") or "").lower()
+    product = (getattr(service, "product", "") or "").lower()
+    port = int(getattr(service, "port", 0) or 0)
+
+    if "http" in svc or "https" in svc:
+        return True
+
+    if any(x in product for x in ("apache", "nginx", "tomcat", "jetty", "nextcloud")):
+        return True
+
+    if port in WEB_PORTS:
+        return True
+
+    return False
+
+
+def guess_scheme(service, configured_scheme: str) -> str:
+    if configured_scheme in {"http", "https"}:
+        return configured_scheme
+
+    port = int(getattr(service, "port", 0) or 0)
+
+    if port in {443, 8443, 9443}:
+        return "https"
+
+    if port in {80, 81, 8000, 8008, 8080, 8081, 8088, 8888}:
+        return "http"
+
+    return "auto"
+
+
+@dataclass(slots=True)
+class ScanConfig:
+    ports: str | None = None
+    nmap_script: str | None = None
+    timeout: int = 120
+    web_scheme: str = "auto"
+    nuclei_profile: str = "fast"
+    output_format: str = "json"
+    output_dir: str = "reports"
+    log_dir: str = "logs"
+    deep_wordpress: bool = False
+
+    # NVD backend
+    vuln_backend: str = "none"
+    min_cvss: float = 0.0
+    nvd_api_key: str | None = None
+    nvd_cache: str = "~/.cache/driftmux/nvd.sqlite"
+    nvd_cache_ttl_hours: int = 168
+
+
+class DriftmuxEngine:
+    def __init__(self, config: ScanConfig):
+        self.config = config
+
+        self.nmap = NmapScanner(
+            timeout=config.timeout,
+            ports=config.ports,
+            nmap_script=config.nmap_script,
+        )
+
+        self.nvd = NvdCveScanner(
+            NvdConfig(
+                enabled=config.vuln_backend == "nvd",
+                api_key=config.nvd_api_key,
+                min_cvss=config.min_cvss,
+                cache_path=config.nvd_cache,
+                cache_ttl_hours=config.nvd_cache_ttl_hours,
+                timeout=max(20, min(config.timeout, 60)),
+            )
+        )
+
+        self.nuclei = NucleiScanner(
+            timeout=max(config.timeout, 180),
+            profile=getattr(config, "nuclei_profile", "fast"),
+        )
+
+        self.plecost = PlecostScanner(
+            timeout=max(config.timeout, 180),
+            mode=config.web_scheme,
+            deep=config.deep_wordpress,
+        )
+
+    def scan_host(self, host: str) -> HostScanResult:
+        discovery = self.nmap.scan(host)
+
+        final = HostScanResult(
+            host=host,
+            services=discovery.services.copy(),
+            findings=discovery.findings.copy(),
+            errors=discovery.errors.copy(),
+            metadata=discovery.metadata.copy(),
+        )
+
+        final.metadata["config"] = {
+            "ports": self.config.ports,
+            "nmap_script": self.config.nmap_script,
+            "timeout": self.config.timeout,
+            "web_scheme": self.config.web_scheme,
+            "nuclei_profile": self.config.nuclei_profile,
+            "vuln_backend": self.config.vuln_backend,
+            "min_cvss": self.config.min_cvss,
+            "deep_wordpress": self.config.deep_wordpress,
+        }
+
+        if self.config.vuln_backend == "nvd":
+            nvd_result = self.nvd.scan(host, discovery.services)
+            final.findings.extend(nvd_result.findings)
+            final.errors.extend(nvd_result.errors)
+            final.metadata.update(nvd_result.metadata)
+
+        if self.config.nuclei_profile != "passive":
+            self._run_nuclei(host, discovery, final)
+
+        self._run_plecost(host, discovery, final)
+
+        return final
+
+    def _run_nuclei(
+            self,
+            host: str,
+            discovery: HostScanResult,
+            final: HostScanResult,
+        ) -> None:
+            plan = build_scan_plan(
+                host=host,
+                services=discovery.services,
+                passive_findings=final.findings,
+                scheme=self.config.web_scheme,
+                profile=self.config.nuclei_profile,
+            )
+
+            nuclei_result = self.nuclei.scan_many(
+                host=host,
+                targets=plan.nuclei_targets,
+            )
+
+            final.findings.extend(nuclei_result.findings)
+            final.errors.extend(nuclei_result.errors)
+
+    def _run_plecost(
+        self,
+        host: str,
+        discovery: HostScanResult,
+        final: HostScanResult,
+    ) -> None:
+        wp_done = False
+
+        for service in discovery.services:
+            if not wp_done and self.plecost.maybe_wordpress(host, service):
+                plecost_result = self.plecost.scan(host, service)
+                final.findings.extend(plecost_result.findings)
+                final.errors.extend(plecost_result.errors)
+                final.metadata.update(plecost_result.metadata)
+                wp_done = True
+
+        if not wp_done and self.plecost.maybe_wordpress(host):
+            plecost_result = self.plecost.scan(host)
+            final.findings.extend(plecost_result.findings)
+            final.errors.extend(plecost_result.errors)
+            final.metadata.update(plecost_result.metadata)
+
+    def scan_hosts(self, hosts: Iterable[str]) -> list[HostScanResult]:
+        return [self.scan_host(host) for host in hosts]

driftmux/logging.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+
+class COLOR:
+    RED = ""
+    GREEN = ""
+    YELLOW = ""
+    BLUE = ""
+    MAGENTA = ""
+    CYAN = ""
+    RESET = ""
+    BOLD = ""
+
+
+def get_logger(host: str, output_dir: str = "logs", level: int = logging.INFO) -> logging.Logger:
+    logger_name = f"driftmux.{host}"
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(level)
+    logger.propagate = False
+
+    if logger.handlers:
+        return logger
+
+    log_dir = Path(output_dir)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    safe_host = host.replace(":", "_").replace("/", "_")
+    logfile = log_dir / f"{safe_host}.log"
+
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+
+    file_handler = logging.FileHandler(logfile, encoding="utf-8")
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    return logger
+
+
+def close_logger(logger: Optional[logging.Logger]) -> None:
+    if logger is None:
+        return
+    for handler in list(logger.handlers):
+        handler.close()
+        logger.removeHandler(handler)

driftmux/models.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+
+SEVERITY_ORDER = {"critical": 5, "high": 4, "medium": 3, "low": 2, "info": 1, "unknown": 0}
+
+@dataclass(slots=True)
+class ToolError:
+    scanner: str
+    message: str
+    host: Optional[str] = None
+    details: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class OpenPort:
+    port: int
+    protocol: str
+    state: str
+    service: str
+    product: str = ""
+    version: str = ""
+    extrainfo: str = ""
+    tunnel: str = ""
+    cpes: List[str] = field(default_factory=list)
+    classifications: List[str] = field(default_factory=list)
+
+    def endpoint(self) -> str:
+        return f"{self.port}/{self.protocol}"
+
+    def detected_version(self) -> str:
+        return self.version or self.extrainfo or "unknown"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class Finding:
+    scanner: str
+    host: str
+    title: str
+    severity: str = "info"
+    description: str = ""
+    evidence: str = ""
+    confidence: str = "medium"
+    port: Optional[int] = None
+    service: Optional[str] = None
+    detected_version: Optional[str] = None
+    reference: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def normalized_severity(self) -> str:
+        value = (self.severity or "unknown").lower()
+        return value if value in SEVERITY_ORDER else "unknown"
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload = asdict(self)
+        payload["severity"] = self.normalized_severity()
+        return payload
+
+
+@dataclass(slots=True)
+class HostScanResult:
+    host: str
+    services: List[OpenPort] = field(default_factory=list)
+    findings: List[Finding] = field(default_factory=list)
+    errors: List[ToolError] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def add_error(self, scanner: str, message: str, details: Optional[str] = None) -> None:
+        self.errors.append(ToolError(scanner=scanner, host=self.host, message=message, details=details))
+
+    def max_severity(self) -> str:
+        if not self.findings:
+            return "unknown"
+        return max((f.normalized_severity() for f in self.findings), key=lambda x: SEVERITY_ORDER.get(x, 0))
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "host": self.host,
+            "metadata": self.metadata,
+            "summary": {
+                "services": len(self.services),
+                "findings": len(self.findings),
+                "errors": len(self.errors),
+                "max_severity": self.max_severity(),
+            },
+            "services": [s.to_dict() for s in self.services],
+            "findings": [f.to_dict() for f in self.findings],
+            "errors": [e.to_dict() for e in self.errors],
+        }

driftmux/parsers/nmap.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import List
+
+from driftmux.models import Finding, HostScanResult, OpenPort
+
+
+class NmapXmlParser:
+    @staticmethod
+    def parse(xml_text: str, host: str) -> HostScanResult:
+        result = HostScanResult(host=host)
+        root = ET.fromstring(xml_text)
+        for host_node in root.findall("host"):
+            for port in host_node.findall("ports/port"):
+                state_el = port.find("state")
+                state = state_el.get("state", "unknown") if state_el is not None else "unknown"
+                if state != "open":
+                    continue
+                service_el = port.find("service")
+                service = OpenPort(
+                    port=int(port.get("portid", 0)),
+                    protocol=port.get("protocol", "tcp"),
+                    state=state,
+                    service=(service_el.get("name", "unknown") if service_el is not None else "unknown"),
+                    product=(service_el.get("product", "") if service_el is not None else ""),
+                    version=(service_el.get("version", "") if service_el is not None else ""),
+                    extrainfo=(service_el.get("extrainfo", "") if service_el is not None else ""),
+                    tunnel=(service_el.get("tunnel", "") if service_el is not None else ""),
+                    cpes=[
+                        cpe.text.strip()
+                        for cpe in port.findall("service/cpe")
+                        if cpe.text and cpe.text.strip()
+                    ],                
+                )
+                service.classifications = classify_service(service)
+                result.services.append(service)
+
+                for script_el in port.findall("script"):
+                    result.findings.append(
+                        Finding(
+                            scanner="nmap",
+                            host=host,
+                            title=f"Nmap script result: {script_el.get('id', 'script')}",
+                            severity="info",
+                            description=script_el.get("output", ""),
+                            evidence=script_el.get("output", ""),
+                            confidence="medium",
+                            port=service.port,
+                            service=service.service,
+                            detected_version=service.version or None,
+                        )
+                    )
+        return result
+
+
+def classify_service(service: OpenPort) -> List[str]:
+    text = " ".join(
+        part.lower() for part in [service.service, service.product, service.version, service.extrainfo, " ".join(service.cpes)] if part
+    )
+    labels: list[str] = []
+    if any(token in text for token in ["http", "https", "ssl/http", "apache", "nginx", "iis"]):
+        labels.append("http")
+    if "apache" in text:
+        labels.append("apache-httpd")
+    if "nginx" in text:
+        labels.append("nginx")
+    if any(token in text for token in ["kubernetes", "kube-apiserver", "kubelet", "etcd", "openshift"]):
+        labels.append("kubernetes")
+    if "wordpress" in text:
+        labels.append("wordpress")
+    if service.service.lower() == "ssh" or "openssh" in text:
+        labels.append("ssh")
+    # preserve order
+    dedup: list[str] = []
+    for label in labels:
+        if label not in dedup:
+            dedup.append(label)
+    return dedup