exploitsynth 0.3.0__py3-none-any.whl

exploitsynth/__init__.py

@@ -0,0 +1,3 @@
+"""ExploitSynth scanner CLI."""
+
+__version__ = "0.3.0"

exploitsynth/__main__.py

@@ -0,0 +1,4 @@
+from exploitsynth.cli import app
+
+if __name__ == "__main__":
+    app()

exploitsynth/cli.py

@@ -0,0 +1,436 @@
+"""ExploitSynth CLI — `exploitsynth scan ...` from your terminal."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import typer
+from rich.table import Table
+from rich.text import Text
+
+from . import __version__, config, output
+from . import tunnel as tunnel_mod
+from .client import ApiError, Client
+from .discover import DiscoverError, discover_ports
+from .live import follow_scans, poll_until_done, results_table
+from .output import out, err
+from .parsers import count_unidentified, parse_scan_file
+from .ports import PortError, normalize_scope, parse_port_list
+from .targets import TargetError, expand_targets, MAX_HOSTS_PER_SCAN
+
+# Typer reflows the epilog into one paragraph, so keep it to links. Worked examples
+# live in each command's docstring (e.g. `exploitsynth scan --help`).
+EPILOG = "Docs: https://scan.exploitsynth.com/docs  ·  Issues: https://github.com/exploitsynth/cli/issues"
+
+app = typer.Typer(
+    help="ExploitSynth — AI port identification for ports your scanner couldn't fingerprint.",
+    epilog=EPILOG,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+# A short flag people will mistype as a global; documented in --help instead.
+JSON_OPT = typer.Option(False, "--json", help="Emit machine-readable JSON on stdout.")
+
+
+def _client() -> Client:
+    try:
+        return Client()
+    except ApiError as e:
+        output.fail(str(e))
+
+
+# ─────────────────────────── login ───────────────────────────
+@app.command()
+def login(
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="Your sk_ API key (prompted if omitted)."),
+    base_url: Optional[str] = typer.Option(None, "--url", help="Override API base URL (self-hosting)."),
+):
+    """Store an API key (in ~/.config/exploitsynth/config.json) and verify it."""
+    key = api_key or typer.prompt("API key", hide_input=True)
+    key = key.strip()
+    if not key:
+        output.fail("Empty API key.")
+
+    # Verify before saving — a quick authenticated call.
+    try:
+        Client(api_key=key, base_url=base_url).list_scans(limit=1)
+    except ApiError as e:
+        output.fail(f"Key rejected: {e}")
+
+    path = config.save_api_key(key, base_url)
+    out.print(Text(f"✓ Saved. Authenticated against {config.get_base_url()}", style="green"))
+    out.print(Text(f"  {path}", style="dim"))
+
+
+# ─────────────────────────── scan ────────────────────────────
+def _targets_from_import(path: Path) -> List[Dict[str, Any]]:
+    try:
+        contents = path.read_text(errors="replace")
+    except OSError as e:
+        output.fail(f"Could not read {path}: {e}")
+    try:
+        result = parse_scan_file(contents)
+    except ValueError as e:
+        output.fail(str(e))
+
+    total_unident = count_unidentified(result.hosts)
+    if total_unident == 0:
+        output.fail(
+            f"{path.name}: every open port was already identified by {result.format} — "
+            "nothing for the agent to do."
+        )
+
+    targets: List[Dict[str, Any]] = []
+    for host in result.hosts:
+        ports = [p.port for p in host.ports if not p.identified]
+        if ports:
+            targets.append({"ip": host.ip, "ports": ports})
+    if len(targets) > MAX_HOSTS_PER_SCAN:
+        output.fail(f"Import covers {len(targets)} hosts (max {MAX_HOSTS_PER_SCAN} per scan).")
+
+    output.note(
+        f"Imported {result.format}: {total_unident} unidentified port(s) "
+        f"across {len(targets)} host(s)."
+    )
+    return targets
+
+
+def _read_target_source(target: Optional[str], targets_file: Optional[Path]) -> Optional[str]:
+    """Resolve targets from a file (-iL), stdin ('-'), or the literal argument."""
+    if targets_file:
+        try:
+            return targets_file.read_text(errors="replace")
+        except OSError as e:
+            output.fail(f"Could not read {targets_file}: {e}")
+    if target == "-":
+        return sys.stdin.read()
+    return target
+
+
+def _spec_cost(spec: str) -> int:
+    """Credit cost of a discovery scope — mirrors specCost() in lib/credits.ts."""
+    if spec == "top-100":
+        return 100
+    if spec == "top-1000":
+        return 1000
+    if spec == "all":
+        return 65535
+    m = re.match(r"^(\d+)-(\d+)$", spec)
+    if m:
+        return int(m.group(2)) - int(m.group(1)) + 1
+    return 1000
+
+
+def _estimate_cost(targets: List[Dict[str, Any]], port_spec: Optional[str]) -> int:
+    return sum(
+        len(t["ports"]) if t.get("ports") else _spec_cost(port_spec or "top-1000")
+        for t in targets
+    )
+
+
+@app.command()
+def scan(
+    target: Optional[str] = typer.Argument(
+        None, help="IP, CIDR (10.0.0.0/28), or list. Use '-' to read targets from stdin."
+    ),
+    ports: Optional[str] = typer.Option(
+        None, "--ports", "-p", help="Known-open ports to identify directly, e.g. 22,80,9929."
+    ),
+    scope: Optional[str] = typer.Option(
+        None, "--scope", "-s", help="Discovery scope: top100 | top1000 | all, or a range like 1-1000."
+    ),
+    targets_file: Optional[Path] = typer.Option(
+        None, "-iL", "--targets-file", help="Read newline/comma-separated targets from a file."
+    ),
+    nessus: Optional[Path] = typer.Option(None, "--nessus", help=".nessus export — import its unidentified ports."),
+    nmap: Optional[Path] = typer.Option(None, "--nmap", help="nmap -oX XML — import its unidentified ports."),
+    via: Optional[str] = typer.Option(
+        None, "--via", help="Egress vantage point. 'local' scans through this machine (private/firewalled targets)."
+    ),
+    project: Optional[str] = typer.Option(None, "--project", help="Project/engagement name (created if missing)."),
+    label: Optional[str] = typer.Option(None, "--label", "-l", help="Optional scan label."),
+    timeout: int = typer.Option(300, "--timeout", "-t", help="Per-port agent budget, seconds (30–600)."),
+    slow: bool = typer.Option(False, "--slow", help="Run one agent at a time (default: three)."),
+    follow: bool = typer.Option(True, "--follow/--no-follow", help="Stream live progress (default on)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the credit-cost confirmation."),
+    json_output: bool = JSON_OPT,
+):
+    """Start a scan. Give a TARGET (or '-'/-iL for a list), or import with --nessus / --nmap.
+
+    Examples:
+      exploitsynth scan 203.0.113.9 --ports 22,80,9929
+      cat hosts.txt | exploitsynth scan - --scope top100
+      exploitsynth scan 10.129.45.12 --via local   # private target, over a tunnel
+    """
+    output.set_json(json_output)
+    if nessus and nmap:
+        output.fail("Use one of --nessus or --nmap, not both.")
+
+    # `--via local`: discovery runs on this machine and probes egress through a
+    # reverse tunnel out of here, so the cloud can reach private/firewalled targets.
+    via_local = False
+    if via is not None:
+        if via.strip().lower() != "local":
+            output.fail("Only `--via local` is supported today (named connectors coming soon).")
+        via_local = True
+        if not follow:
+            output.fail("`--via local` streams results live — it can't be used with --no-follow.")
+        if nessus or nmap:
+            output.fail("`--via local` scans a live network — it can't be combined with --nessus/--nmap.")
+
+    targets: List[Dict[str, Any]] = []
+    port_spec: Optional[str] = None
+
+    if nessus or nmap:
+        if target or ports or targets_file:
+            output.note("note: ignoring TARGET/--ports/-iL when importing a file.")
+        targets = _targets_from_import(nessus or nmap)  # type: ignore[arg-type]
+    else:
+        if target and targets_file:
+            output.fail("Use a TARGET or -iL FILE, not both.")
+        source = _read_target_source(target, targets_file)
+        if not source or not source.strip():
+            output.fail("Provide a TARGET, '-' for stdin, -iL FILE, or import with --nessus / --nmap.")
+        try:
+            ips = expand_targets(source)
+        except TargetError as e:
+            output.fail(str(e))
+        if ports:
+            try:
+                port_list = parse_port_list(ports)
+            except PortError as e:
+                output.fail(str(e))
+            targets = [{"ip": ip, "ports": port_list} for ip in ips]
+        elif via_local:
+            # Discovery runs locally (we're on the target network); the cloud only
+            # identifies. Each host ends up with an explicit open-port list.
+            try:
+                spec = normalize_scope(scope or "top-1000")
+            except PortError as e:
+                output.fail(str(e))
+            output.note(f"Discovering open ports locally on {len(ips)} host(s)…", style="dim")
+            for ip in ips:
+                try:
+                    found = discover_ports(ip, spec)
+                except DiscoverError as e:
+                    output.fail(str(e))
+                shown = ", ".join(map(str, found[:12])) + (" …" if len(found) > 12 else "")
+                output.note(f"  {ip}: {len(found)} open — {shown}")
+                targets.append({"ip": ip, "ports": found})
+        else:
+            # Discovery: nmap finds the open ports first, agent identifies them.
+            try:
+                port_spec = normalize_scope(scope or "top-1000")
+            except PortError as e:
+                output.fail(str(e))
+            targets = [{"ip": ip} for ip in ips]
+
+    client = _client()
+
+    # Cost preview + confirmation (skipped for --yes, --json, or non-interactive shells).
+    cost = _estimate_cost(targets, port_spec)
+    balance: Optional[int] = None
+    try:
+        balance = client.get_account()["credits"]
+    except ApiError:
+        pass
+    bal_txt = f" (balance: {balance})" if balance is not None else ""
+    output.note(f"This scan will use ~{cost} credits{bal_txt}.", style="yellow")
+    if not yes and output.is_tty() and not typer.confirm("Continue?", default=True):
+        output.note("Aborted.")
+        raise typer.Exit(0)
+
+    # `--via local`: open the reverse tunnel before submitting, and keep it up until
+    # the scan finishes. The tunnel only lives while this process runs.
+    tunnel: Optional[tunnel_mod.Tunnel] = None
+    if via_local:
+        output.note("Opening tunnel from this machine…", style="dim")
+        try:
+            tunnel = tunnel_mod.Tunnel(client).open()
+        except ApiError as e:
+            output.fail(str(e))
+
+    try:
+        try:
+            scan_ids = client.create_scan(
+                targets,
+                port_spec=port_spec,
+                label=label,
+                max_workers=1 if slow else 3,
+                timeout_sec=timeout,
+                project=project,
+                tunnel_id=tunnel.id if tunnel else None,
+            )
+        except ApiError as e:
+            code = output.EXIT_NO_CREDITS if e.status == 402 else output.EXIT_ERROR
+            output.fail(str(e), code=code)
+
+        if not scan_ids:
+            output.fail("Server accepted the request but returned no scan id.")
+
+        output.note(f"Started {len(scan_ids)} scan(s)  ·  project: {project or 'Default'}", style="bold green")
+        for sid in scan_ids:
+            output.note(f"  {sid}")
+
+        if not follow:
+            if json_output:
+                output.emit_json({"scan_ids": scan_ids})
+            else:
+                output.note("Run `exploitsynth show <id>` to view results.")
+            return
+
+        # Animate only for an interactive terminal; otherwise poll quietly and dump results.
+        if json_output or not output.is_tty():
+            states = poll_until_done(client, scan_ids, show_progress=not json_output)
+            if json_output:
+                output.emit_json([{"scan": s["scan"], "results": s["results"]} for s in states])
+            else:
+                for s in states:
+                    if s["results"]:
+                        out.print(results_table(s["results"]))
+                    else:
+                        out.print(Text("No services identified.", style="dim"))
+        else:
+            follow_scans(client, scan_ids)
+    finally:
+        if tunnel:
+            tunnel.close()
+
+
+# ─────────────────────────── scans (list) ─────────────────────
+@app.command(name="scans")
+def list_scans(
+    project: Optional[str] = typer.Option(None, "--project", help="Filter by project name."),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max rows."),
+    json_output: bool = JSON_OPT,
+):
+    """List recent scans.
+
+    Example:
+      exploitsynth scans --json | jq '.[] | {id, status}'
+    """
+    output.set_json(json_output)
+    client = _client()
+    try:
+        rows = client.list_scans(project=project, limit=limit)
+    except ApiError as e:
+        output.fail(str(e))
+
+    if json_output:
+        output.emit_json(rows)
+        return
+
+    if not rows:
+        output.note("No scans yet.")
+        return
+
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID", style="dim", no_wrap=True)
+    table.add_column("TARGET", style="cyan", no_wrap=True)
+    table.add_column("STATUS", no_wrap=True)
+    table.add_column("PORTS", justify="right")
+    table.add_column("LABEL", style="dim")
+    for r in rows:
+        status = r.get("status", "?")
+        style = {"done": "green", "error": "red", "canceled": "yellow"}.get(status, "yellow")
+        table.add_row(
+            str(r.get("id", ""))[:8],
+            r.get("ip", "?"),
+            Text(status, style=style),
+            str(len(r.get("ports") or [])),
+            r.get("label") or "",
+        )
+    out.print(table)
+
+
+# ─────────────────────────── show ────────────────────────────
+@app.command()
+def show(
+    scan_id: str = typer.Argument(..., help="Scan id (full UUID)."),
+    reasoning: bool = typer.Option(False, "--reasoning", "-r", help="Include the agent's reasoning per port."),
+    json_output: bool = JSON_OPT,
+):
+    """Show one scan's results."""
+    output.set_json(json_output)
+    client = _client()
+    try:
+        data = client.get_scan(scan_id)
+    except ApiError as e:
+        output.fail(str(e))
+
+    if json_output:
+        output.emit_json(data)
+        return
+
+    scan = data["scan"]
+    results = data["results"]
+
+    header = Text()
+    header.append(scan.get("ip", "?"), style="bold white")
+    header.append(f"   {scan.get('status', '?')}", style="dim")
+    out.print(header)
+
+    if not results:
+        out.print(Text("No services identified.", style="dim"))
+    else:
+        out.print(results_table(results))
+
+        if reasoning:
+            for r in sorted(results, key=lambda x: x.get("port", 0)):
+                if r.get("extra_info"):
+                    out.print(Text(f"\n:{r.get('port')} — {r.get('extra_info')}", style="dim"))
+
+    if scan.get("summary"):
+        out.print(Text("\nSummary", style="bold"))
+        out.print(Text(scan["summary"], style="dim"))
+
+
+# ─────────────────────────── credits ─────────────────────────
+@app.command()
+def credits(json_output: bool = JSON_OPT):
+    """Show your credit balance."""
+    output.set_json(json_output)
+    client = _client()
+    try:
+        acct = client.get_account()
+    except ApiError as e:
+        output.fail(str(e))
+
+    if json_output:
+        output.emit_json(acct)
+        return
+    out.print(Text(f"{acct['credits']} credits", style="bold") + Text(f"   ·   {acct['used']} used", style="dim"))
+
+
+# ─────────────────────────── cancel ──────────────────────────
+@app.command()
+def cancel(
+    scan_id: str = typer.Argument(..., help="Scan id (full UUID)."),
+    json_output: bool = JSON_OPT,
+):
+    """Cancel a queued or running scan."""
+    output.set_json(json_output)
+    client = _client()
+    try:
+        status = client.cancel_scan(scan_id)
+    except ApiError as e:
+        output.fail(str(e))
+
+    if json_output:
+        output.emit_json({"ok": True, "scan_id": scan_id, "status": status})
+        return
+    out.print(Text(f"✓ Scan {status}", style="green"))
+
+
+@app.command()
+def version():
+    """Print the CLI version."""
+    out.print(f"exploitsynth {__version__}")
+
+
+if __name__ == "__main__":
+    app()

exploitsynth/client.py

@@ -0,0 +1,128 @@
+"""Thin httpx wrapper over the ExploitSynth /api/v1 endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from . import config
+
+
+class ApiError(Exception):
+    """A non-2xx response or transport failure, with a human-readable message.
+
+    ``status`` is the HTTP status code when there was a response (None on transport
+    failure), so callers can branch on it — e.g. 402 → out of credits.
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+
+class Client:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        self.api_key = api_key or config.get_api_key()
+        self.base_url = (base_url or config.get_base_url()).rstrip("/")
+        if not self.api_key:
+            raise ApiError(
+                "No API key. Run `exploitsynth login`, or set EXPLOITSYNTH_API_KEY."
+            )
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            timeout=30.0,
+        )
+
+    # -- lifecycle -------------------------------------------------------
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- internals -------------------------------------------------------
+    def _request(self, method: str, path: str, **kw) -> Dict[str, Any]:
+        try:
+            r = self._http.request(method, path, **kw)
+        except httpx.HTTPError as e:
+            raise ApiError(f"Could not reach {self.base_url}: {e}")
+        try:
+            data = r.json()
+        except ValueError:
+            raise ApiError(f"{r.status_code}: unexpected non-JSON response.", status=r.status_code)
+        if r.status_code >= 400 or not data.get("ok", True):
+            raise ApiError(
+                data.get("error") or f"Request failed ({r.status_code}).",
+                status=r.status_code,
+            )
+        return data
+
+    # -- endpoints -------------------------------------------------------
+    def create_scan(
+        self,
+        targets: List[Dict[str, Any]],
+        *,
+        port_spec: Optional[str] = None,
+        label: Optional[str] = None,
+        max_workers: Optional[int] = None,
+        timeout_sec: Optional[int] = None,
+        project: Optional[str] = None,
+        tunnel_id: Optional[str] = None,
+    ) -> List[str]:
+        """POST /api/v1/scan. Returns the created scan ids (one per host)."""
+        body: Dict[str, Any] = {"targets": targets}
+        if port_spec:
+            body["port_spec"] = port_spec
+        if label:
+            body["label"] = label
+        if max_workers is not None:
+            body["max_workers"] = max_workers
+        if timeout_sec is not None:
+            body["timeout_sec"] = timeout_sec
+        if project:
+            body["project"] = project
+        if tunnel_id:
+            body["tunnel_id"] = tunnel_id
+        data = self._request("POST", "/api/v1/scan", json=body)
+        return data.get("scan_ids") or ([data["scan_id"]] if data.get("scan_id") else [])
+
+    def get_scan(self, scan_id: str) -> Dict[str, Any]:
+        """GET /api/v1/scan/:id → {scan, results}."""
+        data = self._request("GET", f"/api/v1/scan/{scan_id}")
+        return {"scan": data["scan"], "results": data.get("results", [])}
+
+    def list_scans(self, project: Optional[str] = None, limit: int = 20) -> List[Dict[str, Any]]:
+        params: Dict[str, Any] = {"limit": limit}
+        if project:
+            params["project"] = project
+        data = self._request("GET", "/api/v1/scan", params=params)
+        return data.get("scans", [])
+
+    def get_account(self) -> Dict[str, Any]:
+        """GET /api/v1/account → {credits, used}."""
+        data = self._request("GET", "/api/v1/account")
+        return {"credits": data.get("credits", 0), "used": data.get("used", 0)}
+
+    def cancel_scan(self, scan_id: str) -> str:
+        """DELETE /api/v1/scan/:id → the new status ('canceled')."""
+        data = self._request("DELETE", f"/api/v1/scan/{scan_id}")
+        return data.get("status", "canceled")
+
+    def open_tunnel(self) -> Dict[str, Any]:
+        """POST /api/v1/tunnel → {tunnel_id, chisel_url, port, auth} for `--via local`."""
+        data = self._request("POST", "/api/v1/tunnel")
+        return {
+            "tunnel_id": data["tunnel_id"],
+            "chisel_url": data["chisel_url"],
+            "port": data["port"],
+            "auth": data.get("auth", ""),
+        }
+
+    def close_tunnel(self, tunnel_id: str) -> None:
+        """DELETE /api/v1/tunnel/:id — free the tunnel slot."""
+        self._request("DELETE", f"/api/v1/tunnel/{tunnel_id}")

exploitsynth/config.py

@@ -0,0 +1,53 @@
+"""Config resolution: API key + base URL from env or ~/.config/exploitsynth/config.json."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_BASE_URL = "https://scan.exploitsynth.com"
+
+ENV_KEY = "EXPLOITSYNTH_API_KEY"
+ENV_URL = "EXPLOITSYNTH_API_URL"
+
+
+def _config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "exploitsynth" / "config.json"
+
+
+def _read_file() -> dict:
+    path = _config_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def get_api_key() -> Optional[str]:
+    """Env var wins over the saved config file."""
+    return os.environ.get(ENV_KEY) or _read_file().get("api_key")
+
+
+def get_base_url() -> str:
+    return os.environ.get(ENV_URL) or _read_file().get("base_url") or DEFAULT_BASE_URL
+
+
+def save_api_key(key: str, base_url: Optional[str] = None) -> Path:
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = _read_file()
+    data["api_key"] = key
+    if base_url:
+        data["base_url"] = base_url
+    path.write_text(json.dumps(data, indent=2))
+    # Key is a secret — lock the file down to the owner.
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    return path