netscraper 0.1.0__py3-none-any.whl

netscraper/__init__.py

@@ -0,0 +1,9 @@
+"""
+NetScraper -- automated network pentest check orchestration.
+
+See cli.py for the entrypoint (installed as the `netscraper` console
+script) and README.md for full usage.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

netscraper/cli.py

@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""
+NetScraper -- CLI entrypoint.
+
+Runs vuln-first, not host-first: every check's required port (SSH/22,
+SMB/445, LDAP/389, ...) gets gated across the WHOLE target list up front,
+in one unified port scan (a fast parallel TCP connect check -- see
+core/port_gate.py), before anything else happens. That scan's real
+open/closed counts then drive an interactive menu -- TLS, SSH, SMB, ...,
+or All -- so you pick exactly the check(s) that actually apply to this
+target list instead of always running everything. Only after that does
+any real protocol-specific probe run, and only against hosts that actually
+answered on the relevant port -- a host without SMB open never gets an SMB
+check attempted; it's recorded as N/A, not scanned, not guessed at, and
+not lumped in with a "safe" result it didn't earn.
+
+Usage:
+  # Live scan (needs the relevant tools installed + real network reach).
+  # --output defaults to ./results if omitted. With no --modes flag, you'll
+  # be prompted to pick which check(s) to run once the port scan is done.
+  # After a scan finishes (or is interrupted with Ctrl-C), you're dropped
+  # back into the same Individual/Bulk/Exit main menu -- the tool only
+  # exits when you actually choose Exit there.
+  python3 cli.py --targets targets.txt
+
+  # Single target on the command line
+  python3 cli.py --target 192.168.1.10 --output ./results
+
+  # Skip the interactive picker and run specific check(s) non-interactively
+  python3 cli.py --targets targets.txt --modes tls,ssh
+
+  # Replay previously-captured output instead of hitting the network
+  # (used for testing / reprocessing evidence; see fixtures/)
+  python3 cli.py --targets targets_example.txt --output ./results --xml-dir ./fixtures
+
+Output layout (per check):
+  <output>/SSL_Scan/Expired_Certificate/<host>.png (+ .txt)
+  <output>/SSL_Scan/Deprecated_TLS_Protocols/<host>.png (+ .txt)
+  <output>/SSL_Scan/Weak_Ciphers/<host>.png (+ .txt)
+  <output>/SSL_Scan/Weak_Key_Strength/<host>.png (+ .txt)
+  <output>/SSL_Scan/Hostname_Mismatch/<host>.png (+ .txt)
+  <output>/SSL_Scan/Untrusted_Self_Signed/<host>.png (+ .txt)
+  <output>/SSL_Scan/Incomplete_Certificate_Chain/<host>.png (+ .txt)
+  <output>/SSL_Scan/Secure_POC/<host>.png (+ .txt)
+  <output>/SSH/Weak_Deprecated_Crypto/<host>.png (+ .txt)
+  <output>/SSH/Banner_Disclosure/<host>.png (+ .txt)
+  <output>/SSH/Secure_POC/<host>.png (+ .txt)
+  <output>/raw/<check>/<host>_<artifact>.txt   <- always saved, every check
+  <output>/summary.csv                          <- one row per (host, check)
+  <output>/PT_Scan_Report.xlsx                  <- styled Vulnerable/Not-
+                                                    Vulnerable report, one
+                                                    row per confirmed finding
+                                                    or clean (host, check)
+
+Every POC .png is the REAL captured tool output for that check (colors
+preserved where the tool has them), with a red box around the specific
+line(s) relevant to that finding. Nothing in the captured text is altered.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import secrets
+import sys
+import time
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from datetime import datetime, timezone
+from pathlib import Path
+
+from netscraper.core.targets import Target, expand_targets, load_targets_file
+from netscraper.core.port_gate import gate_targets, gate_targets_own_port
+from netscraper.core.families import FAMILIES
+from netscraper.core.concurrency import worker_count
+from netscraper.core.scan_worker import run_one_target_check
+from netscraper.core.excel_report import write_report
+from netscraper.core.banner import clear_screen, print_banner, prompt_mode, prompt_scan_modes, prompt_port_list, ReturnToMainMenu
+from netscraper.core.theme import title, accent, info, ok, bad, warn, err, muted, prompt, host as c_host
+
+
+def parse_args(argv=None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="NetScraper")
+    src = p.add_mutually_exclusive_group(required=False)
+    src.add_argument("--targets", help="Path to a targets file (IPs, hostnames, or CIDR subnets, one per line)")
+    src.add_argument("--target", help="A single IP, hostname, or CIDR subnet")
+    p.add_argument("--output", default="./results",
+                   help="Root output directory for POCs, raw evidence, and summary.csv (default: ./results). "
+                        "Each run gets its own uniquely-named subfolder under this root (see --no-run-id) so "
+                        "repeated scans never overwrite each other's evidence.")
+    p.add_argument("--no-run-id", action="store_true",
+                   help="Write directly into --output instead of a per-run unique subfolder (will overwrite "
+                        "a previous run's evidence at that same path -- use this only for scripted/CI use "
+                        "where you manage the output path yourself).")
+    p.add_argument("--xml-dir", default=None,
+                   help="Replay mode: read pre-captured evidence from this directory instead of scanning live")
+    p.add_argument("--timeout", type=int, default=90,
+                   help="Per-host, per-tool timeout in seconds (live mode only). A real live TLS "
+                        "scan tests dozens of cipher/protocol combos and can legitimately take longer "
+                        "than a quick local test, so this is intentionally generous; sslscan's own "
+                        "internal per-probe timeouts are separately capped so a single slow probe "
+                        "can't blow past this on its own (default: 90)")
+    p.add_argument("--modes", "--families", dest="families", default=None, metavar="MODES",
+                   help="Comma-separated check mode names to run (default: prompts interactively after the "
+                        "port scan, or 'all' if run non-interactively without this flag). Available: "
+                        + ",".join(f["name"] for f in FAMILIES))
+    p.add_argument("--port-gate-timeout", type=float, default=3.0,
+                   help="TCP connect timeout in seconds for the port-gate pre-check (default: 3.0)")
+    p.add_argument("--mode-pause", "--family-pause", dest="family_pause", type=int, default=5, metavar="SECONDS",
+                   help="Seconds to pause between checks during a LIVE scan, once one check "
+                        "finishes and before the next one starts (default: 5; ignored in --xml-dir replay mode, "
+                        "and skipped after the last check). Set to 0 to disable.")
+    p.add_argument("--dirsearch-ports", default=None, metavar="PORTS",
+                   help="Comma-separated port(s) for the DIRSEARCH mode to brute-force, e.g. 80,443,8080 "
+                        "(single port also accepted, e.g. 80). DIRSEARCH has no fixed port like every other "
+                        "check, so this is required if --modes/--families includes 'dirsearch' for a scripted "
+                        "run; in the interactive picker, you're simply asked for it right after choosing that "
+                        "mode if this isn't given up front.")
+    p.add_argument("--dirsearch-timeout", type=int, default=300, metavar="SECONDS",
+                   help="Overall wall-clock budget in seconds for one DIRSEARCH brute-force run against a "
+                        "single host:port (default: 300). Kept separate from --timeout since a real "
+                        "directory/file brute-force legitimately takes a lot longer than the other checks.")
+    p.add_argument("--cors-ports", default=None, metavar="PORTS",
+                   help="Comma-separated port(s) for the CORS mode to probe, e.g. 80,443,8080 (single port "
+                        "also accepted, e.g. 443). CORS has no fixed port like every other check, so this is "
+                        "required if --modes/--families includes 'cors' for a scripted run; in the interactive "
+                        "picker, you're simply asked for it right after choosing that mode if this isn't given "
+                        "up front.")
+    return p.parse_args(argv)
+
+
+def _parse_port_list(raw: str) -> list[int]:
+    """Turns "80" or "80,81,443,8080" into a de-duplicated, order-preserving
+    list of real port numbers (1-65535); silently skips anything that
+    isn't a valid port instead of erroring, so one typo doesn't blow up an
+    otherwise-good list -- the caller checks for an empty result instead."""
+    ports: list[int] = []
+    seen = set()
+    for token in raw.split(","):
+        token = token.strip()
+        if not token.isdigit():
+            continue
+        value = int(token)
+        if 1 <= value <= 65535 and value not in seen:
+            seen.add(value)
+            ports.append(value)
+    return ports
+
+
+# Any check with no fixed port of its own (currently DIRSEARCH and CORS)
+# needs its --xxx-ports CLI flag and the "check" verb used in its interactive
+# prompt looked up by family name -- kept in one small table instead of
+# scattering per-family if/elif chains through _resolve_prompt_gated_ports.
+_PROMPT_GATED_FAMILIES = {
+    "dirsearch": {"cli_attr": "dirsearch_ports", "flag_name": "--dirsearch-ports", "verb": "brute-force"},
+    "cors": {"cli_attr": "cors_ports", "flag_name": "--cors-ports", "verb": "check"},
+}
+
+
+def _resolve_prompt_gated_ports(args: argparse.Namespace, targets: list, families: list, port_scan: dict) -> int:
+    """
+    Some checks (DIRSEARCH, CORS, ...) have no fixed port like every other
+    check -- the port(s) to use are only known once the user says so,
+    either via that family's --xxx-ports flag up front or, in the
+    interactive picker, right after choosing the mode. For every such
+    family that was actually selected, this fills in port_scan[name] with a
+    real quick TCP gate across every (host, chosen port) combination from
+    the target list -- the exact same kind of pre-check every other family
+    gets, just computed later because the ports weren't known until now.
+
+    Returns 0 on success (including "no prompt-gated family was selected,
+    nothing to do"), or 1 if a family had to be dropped because no valid
+    port(s) could be resolved for a scripted run -- matching run_one_scan's
+    own exit-code convention. Can raise ReturnToMainMenu (from
+    prompt_port_list, interactive-only) -- deliberately left to propagate
+    untouched, same as prompt_scan_modes.
+    """
+    for name, spec in _PROMPT_GATED_FAMILIES.items():
+        if not any(f["name"] == name for f in families):
+            continue
+
+        label = name.upper()
+        cli_ports = getattr(args, spec["cli_attr"])
+
+        if cli_ports:
+            ports = _parse_port_list(cli_ports)
+            if not ports:
+                print(err(f"[!] {spec['flag_name']}={cli_ports!r} has no valid port number(s)."), file=sys.stderr)
+                return 1
+        elif args.families:
+            # Scripted run (--modes/--families given) with this family
+            # included, but nothing to prompt for -- there's no interactive
+            # session here.
+            print(err(f"[!] --modes includes '{name}' but no {spec['flag_name']} was given."), file=sys.stderr)
+            return 1
+        else:
+            while True:
+                raw = prompt_port_list(label, spec["verb"])  # may raise ReturnToMainMenu -- let it through untouched
+                ports = _parse_port_list(raw)
+                if ports:
+                    break
+                print(warn(f"[!] No valid port number(s) found in '{raw}' -- try again."))
+
+        unique_hosts = list(dict.fromkeys(t.host for t in targets))
+        check_targets = [Target(host=h, port=p) for h in unique_hosts for p in ports]
+
+        print("\n" + info("[+] ") + accent(f"Quick port scan for {label} ") +
+              c_host(f"({', '.join(str(p) for p in ports)}) across {len(unique_hosts)} host(s) ..."))
+        if args.xml_dir:
+            qualifying = {t: True for t in check_targets}
+        else:
+            qualifying = gate_targets_own_port(check_targets, timeout=args.port_gate_timeout)
+        open_count = sum(1 for v in qualifying.values() if v)
+        print(muted(f"    {label:<6}        : ") + c_host(f"{open_count}/{len(check_targets)} host:port combo(s) open"))
+
+        port_scan[name] = {"targets": check_targets, "qualifying": qualifying, "is_udp": False}
+
+    return 0
+
+
+def run_one_scan(args: argparse.Namespace) -> int:
+    """
+    Runs one target list's worth of scanning (target load -> unified port
+    scan -> mode selection -> per-check execution -> summary.csv +
+    PT_Scan_Report.xlsx) and returns an exit code.
+
+    Every check's per-host work runs across several hosts AT ONCE, in a
+    process pool sized automatically from this machine's own RAM/CPU (see
+    core/concurrency.py) -- fully automatic, with no flag or prompt
+    exposed for it anywhere. This is what keeps a 60-200 host target list
+    from taking as long as scanning every host one at a time; see
+    execute_families() below and core/scan_worker.py for how each host's
+    work is packaged up for a worker process and how results stream back
+    as each one finishes.
+
+    In interactive use (no --modes/--families given), the mode-selection
+    step is a loop, not a one-shot: after a chosen check (or several)
+    finishes running against this target list, the SAME check menu comes
+    back up so you can run another one against the SAME hosts without
+    re-entering the target/subnet from scratch -- summary.csv and
+    PT_Scan_Report.xlsx accumulate across every round in this same output
+    folder. "Back to main menu" (an explicit numbered option, or Ctrl-C,
+    same as ever) is how you actually leave to scan something else. A
+    scripted run (--modes/--families given) is unchanged: it runs that
+    fixed set once and returns.
+
+    Two things are caught here so a scan never just dies mid-run:
+    - A Ctrl-C that lands *during* the actual scanning (anywhere from the
+      port scan onward) never crashes with a traceback: whatever results
+      were already collected are still written out (partial progress is
+      never silently thrown away), then ReturnToMainMenu is raised so the
+      caller (main()) can decide what "going back" means -- looping to the
+      interactive menu, or just exiting cleanly for a scripted run.
+    - Any OTHER unexpected exception during scanning (a POC-render hiccup,
+      a resource issue under a big target list, anything not already
+      turned into a clean per-host ERROR row) is likewise caught, partial
+      results are saved the same way, and control returns to the menu
+      instead of the whole process crashing and losing everything that had
+      already completed. A per-target failure in POC rendering or evidence
+      writing is caught even more locally, inside execute_families() below,
+      so ONE bad screenshot only costs that one host/check an ERROR row,
+      not the rest of the scan.
+    A ReturnToMainMenu raised by prompt_scan_modes()/prompt_port_list()
+    themselves (i.e. deliberate navigation, not a real error) is
+    deliberately let straight through untouched, never treated as a crash.
+    """
+    if args.targets:
+        targets = load_targets_file(args.targets)
+    else:
+        targets = expand_targets([args.target])
+
+    if not targets:
+        print(err("[!] No valid targets found."), file=sys.stderr)
+        return 1
+
+    # If --modes/--families was given, only scan ports for that subset (no
+    # point port-scanning checks that were never going to run); otherwise
+    # scan ports for every check up front so the mode-selection menu below
+    # can show real, live open/closed counts for every option.
+    if args.families:
+        wanted = set(n.strip().lower() for n in args.families.split(","))
+        scan_universe = [f for f in FAMILIES if f["name"] in wanted]
+        if not scan_universe:
+            print(err(f"[!] No matching check modes for --modes={args.families}"), file=sys.stderr)
+            return 1
+    else:
+        scan_universe = FAMILIES
+
+    # Every run gets its own uniquely-named evidence folder (timestamp + a
+    # short random suffix so two runs started in the same second never
+    # collide) instead of always writing into the same fixed "results/" --
+    # that way a tester can run multiple scans (different targets, or a
+    # re-test after remediation) without one run silently overwriting the
+    # previous one's POCs/raw evidence. --no-run-id opts back out of this
+    # for scripted/CI use where the caller manages the output path itself.
+    run_id = datetime.now().strftime("%Y%m%d_%H%M%S") + "_" + secrets.token_hex(3)
+    output_root = Path(args.output) if args.no_run_id else Path(args.output) / f"scan_{run_id}"
+    summary_rows = []  # host, port, check, status, findings -- for summary.csv
+    excel_rows = []  # (vulnerability, host_str, "Vulnerable"/"Not Vulnerable") -- for PT_Scan_Report.xlsx
+
+    print(title("=" * 60))
+    print(info("[+] ") + accent("Target list loaded: ") + c_host(f"{len(targets)} IP/host(es) to scan"))
+    print(info("[+] ") + accent("Scan type: ") + (warn("REPLAY from " + args.xml_dir) if args.xml_dir else ok("LIVE")))
+    print(info("[+] ") + accent("Results folder: ") + c_host(str(output_root)))
+    print(title("=" * 60))
+
+    def finalize(interrupted: bool) -> int:
+        output_root.mkdir(parents=True, exist_ok=True)
+        summary_path = output_root / "summary.csv"
+        with open(summary_path, "w", newline="", encoding="utf-8") as fh:
+            writer = csv.writer(fh)
+            writer.writerow(["host", "port", "check", "status", "findings"])
+            writer.writerows(summary_rows)
+
+        report_path = output_root / "PT_Scan_Report.xlsx"
+        write_report(excel_rows, report_path)
+
+        if interrupted:
+            print(warn("[!] Partial results saved -- ") + accent("Summary: ") + c_host(str(summary_path)) +
+                  warn(" | ") + accent("Report: ") + c_host(str(report_path)))
+        else:
+            print("\n" + ok("[+] Done.") + " Summary: " + accent(str(summary_path)) +
+                  " | Report: " + accent(str(report_path)))
+        return 0
+
+    try:
+        # --- Unified port scan ---------------------------------------- #
+        # Every check that needs a TCP port (SSH/22, SMB/445, LDAP/389,
+        # RPC/445, MSSQL/1433, FTP/21, HTTP/80, TLS's own per-target port)
+        # gets gated ONCE here, up front, across the whole target list --
+        # instead of re-discovering "is this port even open" check-by-check
+        # with a pause in between. This also means the mode-selection menu
+        # below can show real open-port counts, so you can pick exactly the
+        # check(s) that actually apply to this target list instead of
+        # guessing.
+        print("\n" + info("[+] ") + accent("Scanning required ports across ") +
+              c_host(f"{len(targets)} target(s)") + accent(" ..."))
+        port_scan: dict = {}
+        for family in scan_universe:
+            name = family["name"]
+            gate_port = family["gate_port"]
+
+            # DIRSEARCH has no fixed port at all -- the user only supplies
+            # one (or several) after actually choosing this mode, so there's
+            # nothing to gate here yet. _resolve_prompt_gated_ports() fills
+            # port_scan["dirsearch"] in for real once that's known.
+            if gate_port == "prompt":
+                port_scan[name] = {"targets": [], "qualifying": {}, "is_udp": False, "deferred": True}
+                print(muted(f"    {name.upper():<6}        : port(s) chosen after you select this mode"))
+                continue
+
+            # A check whose gate_port is "udp:<port>" (e.g. DNS, SNMP) has
+            # no TCP pre-check at all -- there's nothing meaningful to
+            # "nc -z" for a UDP-only service, so every host is handed
+            # straight to the real protocol probe during the actual scan,
+            # and that probe's own success/timeout IS the gate.
+            is_udp = isinstance(gate_port, str) and gate_port.startswith("udp:")
+            fixed_port = int(gate_port.split(":", 1)[1]) if is_udp else gate_port
+
+            if is_udp or fixed_port is not None:
+                # Fixed-port check (e.g. SSH always on 22): the port a
+                # target string specified was almost certainly meant for a
+                # different check (TLS's own-port override), so probe
+                # host:<gate_port> instead, de-duplicated by host first --
+                # otherwise the same "192.168.1.10" entered once for TLS
+                # and once for a custom port would get re-probed for SSH
+                # twice for no reason.
+                unique_hosts = list(dict.fromkeys(t.host for t in targets))
+                check_targets = [Target(host=h, port=fixed_port) for h in unique_hosts]
+            else:
+                check_targets = targets
+
+            if is_udp:
+                qualifying = {t: True for t in check_targets}
+            elif args.xml_dir:
+                # In replay mode there's no real network to gate against --
+                # every target is treated as qualifying, and the replay
+                # fixture itself is the source of truth for what's
+                # "available".
+                qualifying = {t: True for t in check_targets}
+            else:
+                qualifying = (
+                    gate_targets(check_targets, fixed_port, timeout=args.port_gate_timeout)
+                    if fixed_port is not None
+                    else gate_targets_own_port(check_targets, timeout=args.port_gate_timeout)
+                )
+
+            port_scan[name] = {"targets": check_targets, "qualifying": qualifying, "is_udp": is_udp}
+
+            label = name.upper()
+            if is_udp:
+                print(muted(f"    {label:<6} (UDP)  : checked directly during the scan (no TCP pre-check possible)"))
+            else:
+                open_count = sum(1 for v in qualifying.values() if v)
+                print(muted(f"    {label:<6}        : ") + c_host(f"{open_count}/{len(check_targets)} host(s) open"))
+
+        def build_mode_options() -> list[tuple[str, str]]:
+            options = []
+            for family in FAMILIES:
+                info_row = port_scan[family["name"]]
+                if info_row.get("deferred"):
+                    desc = f"{family['name'].upper():<6} -- {family.get('deferred_desc', 'pick port(s) after selecting')}"
+                elif info_row["is_udp"]:
+                    desc = f"{family['name'].upper():<6} -- UDP service, checked directly"
+                else:
+                    open_count = sum(1 for v in info_row["qualifying"].values() if v)
+                    desc = (f"{family['name'].upper():<6} -- {open_count}/{len(info_row['targets'])} host(s) "
+                            f"with the required port open")
+                options.append((family["name"], desc))
+            return options
+
+        def execute_families(families: list, pool: ProcessPoolExecutor) -> None:
+            """
+            Runs the given families' checks against the already-gated
+            target list, appending to summary_rows/excel_rows and writing
+            every POC/evidence file as it goes.
+
+            Every qualifying (host, check) pair for the CURRENT family is
+            handed to the shared worker process pool at once -- this is
+            the actual "split the IP list into batches and scan several at
+            the same time" behavior: several hosts' real checks run
+            simultaneously, in independent worker processes, instead of
+            one at a time. Results are collected as each host finishes
+            (netscraper.core.scan_worker.run_one_target_check does the real work and
+            returns a plain-data dict -- nothing shared, so results from
+            many workers merge safely here regardless of completion
+            order), and each host's line prints the moment it's done --
+            so progress is visibly streaming in throughout, never a long
+            silent gap followed by everything appearing at once.
+
+            A per-target failure -- the check's own run() reporting
+            status="error", an unexpected exception from POC rendering or
+            evidence writing, or even a worker process dying outright --
+            is turned into this one host/check's own ERROR row inside
+            run_one_target_check (or, for an outright worker crash, right
+            here) instead of ever taking down the rest of the batch.
+            """
+            for family_index, family in enumerate(families):
+                name = family["name"]
+                folder_name = family["folder"]
+                precomputed = port_scan[name]
+                family_targets = precomputed["targets"]
+                qualifying = precomputed["qualifying"]
+                is_udp_family = precomputed["is_udp"]
+                render_this = family.get("render_poc", True)
+                # DIRSEARCH's real brute-force run legitimately takes a lot
+                # longer than the other checks' quick probes -- give it its
+                # own, more generous wall-clock budget instead of the shared
+                # --timeout.
+                run_timeout = args.dirsearch_timeout if name == "dirsearch" else args.timeout
+
+                print("\n" + info("[+] ") + "Mode: " + accent(name.upper()))
+                if is_udp_family:
+                    print(muted(f"    UDP-based service -- no TCP pre-check; the real protocol probe determines "
+                                f"reachability for each of {len(family_targets)} host(s)"))
+                else:
+                    open_count = sum(1 for v in qualifying.values() if v)
+                    print(info(f"    {open_count}/{len(family_targets)} host(s) have the required port open"))
+
+                jobs = []
+                for target in family_targets:
+                    if not qualifying.get(target):
+                        summary_rows.append([target.host, target.port, name, "N/A", "port not open"])
+                        continue
+                    jobs.append({
+                        "family_name": name, "host": target.host, "port": target.port,
+                        "xml_dir": args.xml_dir, "run_timeout": run_timeout,
+                        "output_root": str(output_root), "folder": folder_name,
+                        "render_this": render_this,
+                    })
+
+                if jobs:
+                    print(muted(f"    [*] {len(jobs)} host(s) queued -- scanning in parallel ..."))
+                    futures = {pool.submit(run_one_target_check, job): job for job in jobs}
+                    done_count = 0
+                    for future in as_completed(futures):
+                        done_count += 1
+                        job = futures[future]
+                        try:
+                            result = future.result()
+                        except Exception as exc:  # noqa: BLE001
+                            # The worker process itself died (as opposed to
+                            # the check inside it failing cleanly, which
+                            # run_one_target_check already turns into a
+                            # normal ERROR result) -- still record it as
+                            # this one host/check's own ERROR row instead
+                            # of losing the rest of the batch over it.
+                            host_str = f"{job['host']}:{job['port']}"
+                            print(muted("    [*] ") + c_host(host_str) + muted(" ... ") +
+                                  err(f"ERROR (worker crashed: {exc})") + muted(f"  ({done_count}/{len(jobs)})"))
+                            summary_rows.append([job["host"], job["port"], name, "ERROR", f"worker crashed: {exc}"])
+                            continue
+                        summary_rows.extend(result["summary_rows"])
+                        excel_rows.extend(result["excel_rows"])
+                        print(result["line"] + muted(f"  ({done_count}/{len(jobs)})"))
+
+                if args.family_pause > 0 and not args.xml_dir and family_index < len(families) - 1:
+                    print("\n" + info("[+] ") + f"{accent(name.upper())} mode complete. " +
+                          muted(f"Pausing {args.family_pause}s before the next mode ..."))
+                    time.sleep(args.family_pause)
+
+        # Host-level parallelism: several hosts' checks run at once, in
+        # independent worker processes, instead of one host at a time --
+        # this is what actually makes a 60-200 host target list come back
+        # fast instead of taking as long as running every host in series.
+        # Sized automatically from this machine's own RAM/CPU (see
+        # core/concurrency.py) -- there is deliberately no flag or prompt
+        # for this anywhere; it just happens the moment a target list is
+        # given. Must be a PROCESS pool, not a thread pool: sslscan/
+        # ssh-audit's pty capture (core/terminal_capture.py) uses
+        # os.fork() directly, which is unsafe from multiple threads in one
+        # process, and Playwright's sync API is single-thread-only -- a
+        # process pool sidesteps both since every worker is a fully
+        # independent OS process. One pool is created ONCE for the whole
+        # run (reused across every check and every round of the
+        # interactive menu below) so each worker's own lazily-launched
+        # Chromium (see netscraper.core.poc_renderer.get_process_browser(), used
+        # inside core/scan_worker.py) gets reused for every POC that
+        # worker ever renders, not relaunched per check.
+        pool_size = worker_count(len(targets))
+        print("\n" + info("[+] ") + accent("Parallel scan workers: ") +
+              c_host(f"{pool_size} (auto-sized for this machine)"))
+        pool = ProcessPoolExecutor(max_workers=pool_size)
+        try:
+            if args.families:
+                # --- Choose which check(s) to actually run (scripted) --- #
+                families = scan_universe
+                print("\n" + info("[+] ") + accent("Modes queued (from --modes): ") +
+                      c_host(f"{len(families)} ({', '.join(f['name'].upper() for f in families)})"))
+
+                rc = _resolve_prompt_gated_ports(args, targets, families, port_scan)
+                if rc != 0:
+                    return rc
+
+                execute_families(families, pool)
+            else:
+                # --- Interactive picker, looping on this same target list --- #
+                # After finishing one round of checks, offer the same menu
+                # again instead of forcing a trip all the way back through
+                # Individual/Bulk/file re-entry just to run one more check
+                # against the SAME hosts -- e.g. TLS first, then SSH, then
+                # SMB, all without re-entering the target list each time.
+                # "Back to main menu" (or Ctrl-C, same as ever) is how you
+                # actually leave to scan something else.
+                while True:
+                    print()
+                    options = build_mode_options()
+                    chosen_names = prompt_scan_modes(options, allow_back=True)  # may raise ReturnToMainMenu
+                    families = [f for f in FAMILIES if f["name"] in chosen_names]
+                    print(info("[+] ") + accent("Modes selected: ") +
+                          c_host(f"{len(families)} ({', '.join(f['name'].upper() for f in families)})"))
+
+                    rc = _resolve_prompt_gated_ports(args, targets, families, port_scan)
+                    if rc != 0:
+                        print(err("[!] Nothing to run for that selection -- pick again."))
+                        continue
+
+                    execute_families(families, pool)
+                    finalize(interrupted=False)  # keep summary.csv/xlsx current after every round
+                    print("\n" + info("[+] ") +
+                          accent(f"{len(families)} mode(s) complete against this target list.") +
+                          muted(" Pick another check, or 'back' for the main menu."))
+        finally:
+            # cancel_futures=True drops anything still queued but not yet
+            # started (relevant on a Ctrl-C/error path -- no point starting
+            # new worker tasks once we're on our way out); wait=True still
+            # lets whatever's already RUNNING in a worker right now finish
+            # cleanly rather than killing those processes mid-check, so a
+            # scan never leaves orphaned worker processes behind.
+            pool.shutdown(wait=True, cancel_futures=True)
+
+    except KeyboardInterrupt:
+        print("\n" + warn("[!] Scan interrupted by user (Ctrl-C)."))
+        finalize(interrupted=True)
+        raise ReturnToMainMenu()
+    except ReturnToMainMenu:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        # Something we didn't anticipate blew up mid-scan (e.g. a resource
+        # exhaustion issue, an unhandled tool edge case) -- never lose
+        # already-collected results over it the way a bare traceback would.
+        # Save what we have, say plainly what happened, and bounce back to
+        # the menu (or exit cleanly for a scripted run) instead of a hard
+        # crash taking the whole process down mid-scan.
+        print("\n" + err(f"[!] Unexpected error during the scan: {exc}"))
+        finalize(interrupted=True)
+        raise ReturnToMainMenu()
+
+    return finalize(interrupted=False)
+
+
+def main(argv=None) -> int:
+    args = parse_args(argv)
+    interactive = not args.targets and not args.target
+
+    if not interactive:
+        # Scripted/automated use (--targets or --target given up front):
+        # run exactly once and exit, same as before -- no menu loop, since
+        # there's no interactive session to loop back into. A Ctrl-C mid-
+        # scan still saves partial results (see run_one_scan) instead of
+        # crashing; there's just nothing to return to afterward, so it's
+        # reported as an interrupted run rather than looped.
+        clear_screen()
+        print_banner()
+        try:
+            return run_one_scan(args)
+        except ReturnToMainMenu:
+            return 130
+
+    # Interactive use (bare `python3 cli.py`, or with only --modes/--output/
+    # etc. given but no target source): loop on the main menu until the
+    # user explicitly chooses Exit (or Ctrl-C's at that menu itself) --
+    # every other Ctrl-C, and every completed scan, bounces back here
+    # instead of quitting the process.
+    while True:
+        clear_screen()
+        print_banner()
+        mode, value = prompt_mode()  # raises SystemExit on Exit / Ctrl-C here
+
+        run_args = argparse.Namespace(**vars(args))
+        if mode == "targets":
+            run_args.targets = value
+            run_args.target = None
+        else:
+            run_args.target = value
+            run_args.targets = None
+
+        try:
+            run_one_scan(run_args)
+        except ReturnToMainMenu:
+            pass  # a message was already printed; fall through to the menu again
+
+        print("\n" + info("[+] ") + accent("Returning to the main menu ..."))
+
+
+if __name__ == "__main__":
+    sys.exit(main())