exploitsynth 0.3.0__py3-none-any.whl

exploitsynth/discover.py

@@ -0,0 +1,72 @@
+"""Local nmap discovery for `--via local` scans.
+
+When scanning through a tunnel, discovery runs on the *user's* machine (which is
+on the target network) — the cloud only does identification. We use a connect scan
+(-sT) so it never needs root.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import List, Optional
+
+
+class DiscoverError(RuntimeError):
+    pass
+
+
+def _port_args(spec: Optional[str]) -> List[str]:
+    """Translate a normalized port spec into nmap arguments (mirrors the worker)."""
+    if spec == "all":
+        return ["-p-"]
+    if spec == "top-100":
+        return ["--top-ports", "100"]
+    if not spec or spec == "top-1000":
+        return ["--top-ports", "1000"]
+    return ["-p", spec]  # explicit list/range, e.g. "22,80,100-150"
+
+
+def _parse_grepable(output: str) -> List[int]:
+    ports: set[int] = set()
+    for line in output.splitlines():
+        if "Ports:" not in line:
+            continue
+        _, _, rest = line.partition("Ports:")
+        for entry in rest.split(","):
+            parts = entry.strip().split("/")
+            if len(parts) >= 2 and parts[1] == "open":
+                try:
+                    ports.add(int(parts[0]))
+                except ValueError:
+                    pass
+    return sorted(ports)
+
+
+def discover_ports(ip: str, spec: Optional[str]) -> List[int]:
+    """Run a local nmap connect scan and return the open ports. Raises DiscoverError."""
+    if not shutil.which("nmap"):
+        raise DiscoverError(
+            "nmap is not installed — it's required for local discovery.\n"
+            "  Install it (e.g. `sudo apt install nmap`), or pass --ports to skip discovery."
+        )
+
+    timeout = 1200 if spec == "all" else 180
+    cmd = ["nmap", "-T4", "-sT", "-Pn", *_port_args(spec), "-oG", "-", ip]
+    try:
+        r = subprocess.run(cmd, capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise DiscoverError(f"nmap timed out after {timeout}s scanning {ip}.")
+    except OSError as e:
+        raise DiscoverError(f"could not run nmap: {e}")
+
+    if r.returncode != 0:
+        raise DiscoverError(f"nmap failed: {r.stderr.decode(errors='replace').strip()}")
+
+    ports = _parse_grepable(r.stdout.decode(errors="replace"))
+    if not ports:
+        raise DiscoverError(
+            f"no open ports found on {ip}.\n"
+            "  Confirm you can reach it from this machine (is your VPN connected?)."
+        )
+    return ports

exploitsynth/live.py

@@ -0,0 +1,179 @@
+"""Live terminal rendering of in-progress scans — the CLI twin of scan-live.tsx."""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from rich.console import Group, RenderableType
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .client import ApiError, Client
+from .output import out, err
+
+POLL_SECONDS = 2.0
+ACTIVE_STATES = {"queued", "nmap", "running"}
+
+_CONF_STYLE = {"high": "green", "medium": "yellow", "low": "red"}
+_STATUS_STYLE = {"done": "green", "error": "red", "canceled": "yellow"}
+
+
+def _seconds_left(deadline: Optional[str]) -> Optional[int]:
+    if not deadline:
+        return None
+    try:
+        dl = datetime.fromisoformat(deadline)
+    except ValueError:
+        return None
+    if dl.tzinfo is None:
+        dl = dl.replace(tzinfo=timezone.utc)
+    return max(0, int((dl - datetime.now(timezone.utc)).total_seconds()))
+
+
+def _is_active(status: str) -> bool:
+    return status in ACTIVE_STATES
+
+
+def _service_text(service: Optional[str]) -> Text:
+    if not service:
+        return Text("—", style="dim")
+    low = service.strip().lower()
+    if low.startswith("unknown") or low == "unidentified":
+        return Text(service, style="yellow")
+    return Text(service, style="white")
+
+
+def results_table(results: List[Dict[str, Any]]) -> Table:
+    table = Table(box=None, pad_edge=False, expand=False)
+    table.add_column("PORT", style="cyan", justify="right", no_wrap=True)
+    table.add_column("SERVICE", no_wrap=True)
+    table.add_column("VERSION")
+    table.add_column("CONF", no_wrap=True)
+    for r in sorted(results, key=lambda x: x.get("port", 0)):
+        conf = (r.get("confidence") or "").lower()
+        conf_text = Text(r.get("confidence") or "—", style=_CONF_STYLE.get(conf, "dim"))
+        table.add_row(
+            str(r.get("port", "?")),
+            _service_text(r.get("service")),
+            Text(r.get("version") or "—", style="white" if r.get("version") else "dim"),
+            conf_text,
+        )
+    return table
+
+
+def _in_progress_lines(scan: Dict[str, Any]) -> List[Text]:
+    progress: Dict[str, Any] = scan.get("port_progress") or {}
+    lines: List[Text] = []
+    for port in sorted(progress, key=lambda p: int(p)):
+        p = progress[port]
+        if p.get("status") == "done":
+            continue
+        line = Text()
+        line.append(f":{port}".ljust(8), style="cyan")
+        if p.get("status") == "analyzing":
+            left = _seconds_left(p.get("deadline"))
+            line.append("identifying… ", style="white")
+            if left is not None:
+                line.append(f"{left}s left" if left > 0 else "wrapping up…", style="dim")
+        else:
+            line.append("queued", style="dim")
+        lines.append(line)
+    return lines
+
+
+def _scan_panel(state: Dict[str, Any]) -> RenderableType:
+    scan = state["scan"]
+    results = state["results"]
+    status = scan.get("status", "?")
+    total = len(scan.get("ports") or [])
+    done = len({r.get("port") for r in results})
+
+    header = Text()
+    header.append(scan.get("ip", "?"), style="bold white")
+    header.append("  ")
+    if status == "done":
+        header.append("✓ done", style="bold green")
+    elif status == "error":
+        header.append(f"✗ {scan.get('error') or 'error'}", style="bold red")
+    elif status == "canceled":
+        header.append("✗ canceled", style="bold yellow")
+    else:
+        label = scan.get("stage_label") or status
+        prog = f"{done}/{total} ports" if total else label
+        header.append(f"● {prog}", style="bold yellow")
+
+    body: List[RenderableType] = [header]
+    if results:
+        body.append(results_table(results))
+    elif status == "done":
+        body.append(Text("No services identified.", style="dim"))
+
+    if _is_active(status):
+        ip_lines = _in_progress_lines(scan)
+        if ip_lines:
+            body.append(Text("in progress:", style="dim"))
+            body.extend(ip_lines)
+
+    if scan.get("summary"):
+        body.append(Text(scan["summary"], style="italic dim"))
+
+    return Panel(Group(*body), border_style="grey37", padding=(0, 1))
+
+
+def _render(states: List[Dict[str, Any]]) -> RenderableType:
+    return Group(*(_scan_panel(s) for s in states))
+
+
+def _init_states(scan_ids: List[str]) -> List[Dict[str, Any]]:
+    return [
+        {"id": sid, "scan": {"ip": sid[:8], "status": "queued", "ports": []}, "results": []}
+        for sid in scan_ids
+    ]
+
+
+def _poll_once(client: Client, states: List[Dict[str, Any]]) -> None:
+    for s in states:
+        if not _is_active(s["scan"].get("status", "")):
+            continue
+        try:
+            data = client.get_scan(s["id"])
+            s["scan"] = data["scan"]
+            s["results"] = data["results"]
+        except ApiError:
+            pass  # transient — keep last good state, retry next tick
+
+
+def _all_done(states: List[Dict[str, Any]]) -> bool:
+    return all(not _is_active(s["scan"].get("status", "")) for s in states)
+
+
+def follow_scans(client: Client, scan_ids: List[str]) -> List[Dict[str, Any]]:
+    """Interactive live view: render panels (to stderr) until all scans finish."""
+    states = _init_states(scan_ids)
+    with Live(_render(states), console=err, refresh_per_second=2, transient=False) as live:
+        while True:
+            _poll_once(client, states)
+            live.update(_render(states))
+            if _all_done(states):
+                break
+            time.sleep(POLL_SECONDS)
+    return states
+
+
+def poll_until_done(client: Client, scan_ids: List[str], show_progress: bool = True) -> List[Dict[str, Any]]:
+    """Non-interactive poll: no animation, just dots on stderr. For pipes / --json."""
+    states = _init_states(scan_ids)
+    while True:
+        _poll_once(client, states)
+        if show_progress:
+            err.print(".", end="")
+        if _all_done(states):
+            break
+        time.sleep(POLL_SECONDS)
+    if show_progress:
+        err.print("")
+    return states

exploitsynth/output.py

@@ -0,0 +1,57 @@
+"""Output plumbing: primary data to stdout, progress/notes to stderr, optional JSON.
+
+Rich's Console already honors ``NO_COLOR`` and drops styling when the stream isn't a
+TTY, so piping `exploitsynth ... | jq` (or into a file) stays clean automatically.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, NoReturn
+
+import typer
+from rich.console import Console
+
+# stdout = the thing you'd pipe (tables / JSON). stderr = progress + status notes.
+out = Console()
+err = Console(stderr=True)
+
+# Exit codes scripts can branch on.
+EXIT_ERROR = 1
+EXIT_NO_CREDITS = 3
+
+_json = False
+
+
+def set_json(enabled: bool) -> None:
+    global _json
+    _json = enabled
+
+
+def json_enabled() -> bool:
+    return _json
+
+
+def is_tty() -> bool:
+    """True only when both we and the user's terminal are interactive."""
+    return out.is_terminal and sys.stdin.isatty()
+
+
+def note(msg: str, style: str = "dim") -> None:
+    """A human status line — to stderr, and suppressed entirely in JSON mode."""
+    if not _json:
+        err.print(msg, style=style)
+
+
+def emit_json(obj: Any) -> None:
+    # Plain print (not Rich) so nothing wraps or injects markup into machine output.
+    print(json.dumps(obj, indent=2, default=str))
+
+
+def fail(msg: str, code: int = EXIT_ERROR) -> NoReturn:
+    if _json:
+        print(json.dumps({"ok": False, "error": msg}))
+    else:
+        err.print(f"error: {msg}", style="bold red")
+    raise typer.Exit(code=code)

exploitsynth/parsers/__init__.py

@@ -0,0 +1,59 @@
+"""Import-file parsing: nmap XML (-oX) and .nessus exports → unidentified open ports.
+
+Port of websites/scanner_agent/lib/parsers/. The key signal we extract is which
+open ports the scanner did NOT identify — those are what the agent works on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+# Service names that mean "the scanner didn't really identify this".
+UNIDENTIFIED_NAMES = {"", "unknown", "tcpwrapped", "?", "general", "unrecognized"}
+
+
+@dataclass
+class ImportedPort:
+    port: int
+    protocol: str
+    service: Optional[str]
+    version: Optional[str]
+    identified: bool
+
+
+@dataclass
+class ImportedHost:
+    ip: str
+    ports: List[ImportedPort]
+
+
+@dataclass
+class ParseResult:
+    format: str  # "nmap" | "nessus"
+    hosts: List[ImportedHost]
+
+
+def is_identified_name(name: Optional[str], has_version: bool) -> bool:
+    if has_version:
+        return True
+    if not name:
+        return False
+    return name.strip().lower() not in UNIDENTIFIED_NAMES
+
+
+def count_unidentified(hosts: List[ImportedHost]) -> int:
+    return sum(1 for h in hosts for p in h.ports if not p.identified)
+
+
+def parse_scan_file(contents: str) -> ParseResult:
+    """Detect format from the file head and parse accordingly."""
+    from .nmap import parse_nmap_xml
+    from .nessus import parse_nessus
+
+    head = contents[:2000]
+    if "<NessusClientData" in head:
+        return ParseResult(format="nessus", hosts=parse_nessus(contents))
+    if "<nmaprun" in head:
+        return ParseResult(format="nmap", hosts=parse_nmap_xml(contents))
+    raise ValueError("Unrecognised file. Provide nmap XML (-oX) or a .nessus export.")

exploitsynth/parsers/nessus.py

@@ -0,0 +1,55 @@
+"""Parse a .nessus export (NessusClientData_v2). Port of lib/parsers/nessus.ts."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+from xml.etree.ElementTree import Element  # type only
+
+import defusedxml.ElementTree as ET  # XXE / billion-laughs safe
+from defusedxml.common import DefusedXmlException
+
+from . import ImportedHost, ImportedPort, is_identified_name
+
+
+def parse_nessus(xml: str) -> List[ImportedHost]:
+    try:
+        root = ET.fromstring(xml)
+    except (ET.ParseError, DefusedXmlException) as e:
+        raise ValueError(f"Could not parse .nessus file: {e}")
+
+    hosts: List[ImportedHost] = []
+    for report_host in root.iter("ReportHost"):
+        ip = _host_ip(report_host)
+        if not ip:
+            continue
+
+        # Merge items per (protocol, port): prefer an identified name.
+        by_port: Dict[str, ImportedPort] = {}
+        for item in report_host.findall("ReportItem"):
+            try:
+                port = int(item.get("port", ""))
+            except ValueError:
+                continue
+            if port == 0:  # host-level finding
+                continue
+            protocol = item.get("protocol", "tcp")
+            name = (item.get("svc_name") or "").strip() or None
+
+            key = f"{protocol}/{port}"
+            identified = is_identified_name(name, False)
+            existing = by_port.get(key)
+            if existing is None or (not existing.identified and identified):
+                by_port[key] = ImportedPort(port, protocol, name, None, identified)
+
+        if by_port:
+            ports = sorted(by_port.values(), key=lambda p: p.port)
+            hosts.append(ImportedHost(ip, ports))
+
+    return hosts
+
+
+def _host_ip(report_host: Element) -> Optional[str]:
+    for tag in report_host.findall("./HostProperties/tag"):
+        if tag.get("name") == "host-ip" and tag.text:
+            return tag.text.strip()
+    return report_host.get("name")

exploitsynth/parsers/nmap.py

@@ -0,0 +1,55 @@
+"""Parse nmap XML (-oX). Port of lib/parsers/nmap.ts."""
+
+from __future__ import annotations
+
+from typing import List
+
+import defusedxml.ElementTree as ET  # XXE / billion-laughs safe
+from defusedxml.common import DefusedXmlException
+
+from . import ImportedHost, ImportedPort, is_identified_name
+
+
+def parse_nmap_xml(xml: str) -> List[ImportedHost]:
+    try:
+        root = ET.fromstring(xml)
+    except (ET.ParseError, DefusedXmlException) as e:
+        raise ValueError(f"Could not parse nmap XML: {e}")
+
+    hosts: List[ImportedHost] = []
+    for host in root.iter("host"):
+        addrs = host.findall("address")
+        ip_node = next((a for a in addrs if a.get("addrtype") == "ipv4"), addrs[0] if addrs else None)
+        ip = ip_node.get("addr") if ip_node is not None else None
+        if not ip:
+            continue
+
+        ports: List[ImportedPort] = []
+        for port in host.findall("./ports/port"):
+            state = port.find("state")
+            if state is None or state.get("state") != "open":
+                continue
+            try:
+                portid = int(port.get("portid", ""))
+            except ValueError:
+                continue
+            protocol = port.get("protocol", "tcp")
+
+            svc = port.find("service")
+            name = svc.get("name") if svc is not None else None
+            product = svc.get("product") if svc is not None else None
+            version = svc.get("version") if svc is not None else None
+            method = svc.get("method") if svc is not None else None  # "probed" | "table"
+
+            version_str = " ".join(x for x in (product, version) if x) or None
+            # Identified only if probed (not a port-table guess) with a real name.
+            probed = method == "probed"
+            identified = probed and is_identified_name(name, bool(version_str))
+
+            ports.append(ImportedPort(portid, protocol, name, version_str, identified))
+
+        if ports:
+            ports.sort(key=lambda p: p.port)
+            hosts.append(ImportedHost(ip, ports))
+
+    return hosts

exploitsynth/ports.py

@@ -0,0 +1,63 @@
+"""Port-spec validation. Port of lib/ports.ts."""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+# Friendly aliases people type → canonical spec the API expects.
+SCOPE_ALIASES = {
+    "top100": "top-100",
+    "top-100": "top-100",
+    "top1000": "top-1000",
+    "top-1000": "top-1000",
+    "all": "all",
+}
+
+_PORT_RE = re.compile(r"^(\d{1,5})(?:-(\d{1,5}))?$")
+
+
+class PortError(ValueError):
+    pass
+
+
+def normalize_scope(s: str) -> str:
+    """Map an alias (top1000) to the canonical spec (top-1000), or validate a port list."""
+    key = s.strip().lower()
+    if key in SCOPE_ALIASES:
+        return SCOPE_ALIASES[key]
+    return validate_port_list(s)  # treat as a raw port list / range
+
+
+def validate_port_list(text: str) -> str:
+    """Validate "22,80,443,100-150"; return the normalised spec or raise PortError."""
+    tokens = [t.strip() for t in text.split(",") if t.strip()]
+    if not tokens:
+        raise PortError("Enter at least one port or range.")
+    out: List[str] = []
+    for t in tokens:
+        m = _PORT_RE.match(t)
+        if not m:
+            raise PortError(f"Invalid port: {t}")
+        a = int(m.group(1))
+        b = int(m.group(2)) if m.group(2) is not None else a
+        if not (1 <= a <= 65535) or not (1 <= b <= 65535):
+            raise PortError(f"Out of range (1-65535): {t}")
+        if b < a:
+            raise PortError(f"Reversed range: {t}")
+        out.append(f"{a}-{b}" if m.group(2) is not None else f"{a}")
+    return ",".join(out)
+
+
+def parse_port_list(text: str) -> List[int]:
+    """Expand a validated port list/range into individual ints."""
+    spec = validate_port_list(text)
+    ports: List[int] = []
+    for t in spec.split(","):
+        if "-" in t:
+            a, b = (int(x) for x in t.split("-"))
+            ports.extend(range(a, b + 1))
+        else:
+            ports.append(int(t))
+    # Dedupe, preserve order.
+    return list(dict.fromkeys(ports))

exploitsynth/targets.py

@@ -0,0 +1,55 @@
+"""Expand a free-form target string into host IPs. Port of lib/targets.ts."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from typing import List
+
+MAX_HOSTS_PER_SCAN = 16
+
+
+class TargetError(ValueError):
+    """Raised when a target string can't be parsed or expands too wide."""
+
+
+def expand_targets(text: str) -> List[str]:
+    """
+    Accept single IPs, CIDR ranges (10.0.0.0/24), and comma/space/newline lists.
+    Drops network + broadcast for ranges larger than /31, mirroring the web app.
+    Deduped, order-preserving. Raises TargetError on bad input or > MAX_HOSTS.
+    """
+    tokens = [t for t in re.split(r"[\s,]+", text.strip()) if t]
+    if not tokens:
+        raise TargetError("Enter at least one target.")
+
+    seen: dict[str, None] = {}  # ordered set
+
+    def add(ip: str) -> None:
+        if ip not in seen:
+            seen[ip] = None
+        if len(seen) > MAX_HOSTS_PER_SCAN:
+            raise TargetError(f"Too many hosts (max {MAX_HOSTS_PER_SCAN} per scan).")
+
+    for token in tokens:
+        if "/" in token:
+            try:
+                net = ipaddress.ip_network(token, strict=False)
+            except ValueError:
+                raise TargetError(f"Invalid CIDR: {token}")
+            if net.version != 4:
+                raise TargetError(f"Only IPv4 is supported: {token}")
+            # /31 and /32 have no network/broadcast to drop.
+            hosts = net.hosts() if net.prefixlen < 31 else net
+            for ip in hosts:
+                add(str(ip))
+        else:
+            try:
+                ip = ipaddress.ip_address(token)
+            except ValueError:
+                raise TargetError(f"Invalid IP: {token}")
+            if ip.version != 4:
+                raise TargetError(f"Only IPv4 is supported: {token}")
+            add(token)
+
+    return list(seen.keys())