netscraper 0.1.0__py3-none-any.whl

netscraper/core/banner.py

@@ -0,0 +1,369 @@
+"""
+Startup banner + interactive mode menu for the NetScraper CLI.
+
+Adapted from a user-supplied NetScraper-style banner (figlet "ANSI Shadow"
+title, green->cyan gradient, tapered "signal bar" accents). Every line is
+centered on the *actual* terminal width (not just centered within its own
+box) so it looks right regardless of window size, and every single line
+goes through netscraper.core.theme so nothing prints in the terminal's default color.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+
+from netscraper.core.theme import c, title, accent, warn, ok, prompt, muted, RESET
+
+
+class ReturnToMainMenu(Exception):
+    """
+    Raised anywhere in the interactive flow (a sub-prompt, or mid-scan) to
+    bounce back to the top-level Individual/Bulk/Exit menu instead of
+    crashing or quitting the whole process. The only things that actually
+    end the process are choosing "Exit" at that top-level menu, or Ctrl-C
+    *at* that top-level menu -- everywhere else (entering a target, picking
+    check modes, or a scan that's actively running), Ctrl-C means "go back",
+    not "quit".
+    """
+    pass
+
+# ---------------------------------------------------------------- #
+#  Big block title -- figlet "ANSI Shadow" font, pre-rendered so this
+#  file has zero external dependencies. One color per row gives a
+#  green -> cyan "matrix scan" gradient.
+# ---------------------------------------------------------------- #
+TITLE = [
+    ("███╗   ██╗███████╗████████╗███████╗ ██████╗██████╗  █████╗ ██████╗ ███████╗██████╗ ", "br_green"),
+    ("████╗  ██║██╔════╝╚══██╔══╝██╔════╝██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗", "green"),
+    ("██╔██╗ ██║█████╗     ██║   ███████╗██║     ██████╔╝███████║██████╔╝█████╗  ██████╔╝", "green"),
+    ("██║╚██╗██║██╔══╝     ██║   ╚════██║██║     ██╔══██╗██╔══██║██╔═══╝ ██╔══╝  ██╔══██╗", "cyan"),
+    ("██║ ╚████║███████╗   ██║   ███████║╚██████╗██║  ██║██║  ██║██║     ███████╗██║  ██║", "cyan"),
+    ("╚═╝  ╚═══╝╚══════╝   ╚═╝   ╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝", "br_cyan"),
+]
+TAGLINE = "Automated Network Reconnaissance & Vulnerability Scanning Framework"
+WARNING = "For authorized penetration testing & research use only."
+CREDIT = "Made by Kav1n"
+
+# Ramp used to build the tapered "signal" bars that bookend the title.
+_RAMP = [" ", "░", "▒", "▓", "█"]
+_RAMP_COLOR = {1: "green", 2: "br_green", 3: "cyan", 4: "br_cyan"}
+
+
+def _signal_bar(width: int, taper: float = 0.6):
+    """A glow-style bar, brightest at center, fading to green at the
+    edges -- reads as a 'scan pulse' rather than any literal object."""
+    center = (width - 1) / 2 or 1
+    row = []
+    for i in range(width):
+        d = abs(i - center) / center
+        level = max(0.0, 1 - d / taper)
+        idx = min(4, int(level * 5))
+        row.append((_RAMP[idx], _RAMP_COLOR.get(idx)))
+    return row
+
+
+def _box_width() -> int:
+    return max(max(len(text) for text, _ in TITLE), len(TAGLINE) + 4) + 4
+
+
+def clear_screen() -> None:
+    os.system("cls" if os.name == "nt" else "clear")
+
+
+def _term_width() -> int:
+    try:
+        return shutil.get_terminal_size(fallback=(120, 40)).columns
+    except OSError:
+        return 120
+
+
+def print_banner() -> None:
+    box_width = _box_width()
+    bar_width = box_width - 12
+    term_width = _term_width()
+    # Centers the WHOLE box on the real terminal width -- not just text
+    # centered inside a box that itself sits flush-left.
+    margin = max(0, (term_width - (box_width + 2)) // 2)
+    pad = " " * margin
+
+    top = "╔" + "═" * box_width + "╗"
+    bottom = "╚" + "═" * box_width + "╝"
+
+    def emit(line: str) -> None:
+        print(pad + line)
+
+    def centered(text: str) -> tuple[int, int]:
+        gap = box_width - len(text)
+        left = gap // 2
+        return left, gap - left
+
+    def emit_plain() -> None:
+        emit("║" + " " * box_width + "║")
+
+    def emit_solid(text: str, color: str) -> None:
+        left, right = centered(text)
+        emit("║" + " " * left + c(text, color) + " " * right + "║")
+
+    def emit_bar() -> None:
+        cells = _signal_bar(bar_width)
+        plain = "".join(ch for ch, _ in cells)
+        left, right = centered(plain)
+        colored = "".join(c(ch, col) if col else " " for ch, col in cells)
+        emit("║" + " " * left + colored + " " * right + "║")
+
+    print()
+    emit(c(top, "border"))
+    emit_plain()
+    emit_bar()
+    emit_plain()
+    for text, color in TITLE:
+        emit_solid(text, color)
+    emit_plain()
+    emit_bar()
+    emit_plain()
+    emit_solid(TAGLINE, "white")
+    emit_plain()
+    emit_solid(WARNING, "yellow")
+    emit_plain()
+    emit(c(bottom, "border"))
+    print(_centered_line(muted(CREDIT)))
+    print()
+
+
+# ---------------------------------------------------------------- #
+#  Interactive mode menu
+# ---------------------------------------------------------------- #
+
+def _centered_line(text: str) -> str:
+    term_width = _term_width()
+    visible_len = len(text)
+    margin = max(0, (term_width - visible_len) // 2)
+    return " " * margin + text
+
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _visible_len(text: str) -> int:
+    """Length of `text` with ANSI color codes stripped out -- the color
+    codes themselves take up zero screen columns, so counting them (as
+    plain len() does) undercounts how much room is actually left, and by
+    a different amount on every line depending on how many colored spans
+    it has."""
+    return len(_ANSI_RE.sub("", text))
+
+
+def _emit_numbered_menu(lines: list[str]) -> None:
+    """
+    Prints a numbered list of menu `lines` (each may already contain ANSI
+    color codes) as ONE block sharing a single left margin, computed once
+    from the widest line's true visible width.
+
+    This is deliberately different from centering each line independently
+    (what _centered_line does, fine for a single standalone line): a
+    numbered list centered line-by-line staggers its "[1]"/"[2]"/... column
+    raggedly the moment descriptions differ in length, or in how many
+    colored spans they carry -- exactly the "why don't 1,2,3,4 line up"
+    problem this exists to fix. One shared margin keeps every option's
+    bracket in the same screen column, uniformly, regardless of how long
+    its description is.
+    """
+    term_width = _term_width()
+    max_visible = max((_visible_len(line) for line in lines), default=0)
+    margin = max(0, (term_width - max_visible) // 2)
+    pad = " " * margin
+    for line in lines:
+        print(pad + line)
+
+
+def prompt_mode() -> tuple[str, str]:
+    """
+    Shows the Individual / Bulk / Exit menu and collects the target source.
+    Returns (mode, value):
+      ("target",  "<ip/hostname/cidr>")   -- Individual Mode
+      ("targets", "<path/to/file.txt>")   -- Bulk Scanning
+
+    This is the one true top-level menu: choosing Exit here, or hitting
+    Ctrl-C/EOF *at this menu itself*, ends the process (SystemExit).
+    Anywhere past this point (the target/file sub-prompt), Ctrl-C/EOF or
+    empty input instead raises ReturnToMainMenu so the caller can loop back
+    here and show this same menu again, rather than quitting outright.
+    """
+    mode_entries = [
+        ("Individual Mode", "scan a single IP / hostname / CIDR subnet"),
+        ("Bulk Scanning", "scan a list of targets from a file"),
+        ("Exit", "quit the tool"),
+    ]
+    label_width = max(len(label) for label, _ in mode_entries)
+    menu_lines = [
+        accent(f"  [{i}]") + " " + c(label.ljust(label_width), "white") + muted("  -- " + desc)
+        for i, (label, desc) in enumerate(mode_entries, start=1)
+    ]
+    _emit_numbered_menu(menu_lines)
+    print()
+
+    choice = None
+    while choice not in ("1", "2", "3"):
+        try:
+            choice = input(_centered_line(prompt("  Select mode (1/2/3): "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            print(_centered_line(ok("Goodbye.")))
+            raise SystemExit(0)
+        if choice not in ("1", "2", "3"):
+            print(_centered_line(warn(f"Invalid choice '{choice}'") + muted(" -- enter 1, 2, or 3.")))
+
+    if choice == "3":
+        print(_centered_line(ok("Goodbye.")))
+        raise SystemExit(0)
+
+    if choice == "1":
+        try:
+            target = input(_centered_line(prompt("  Enter target (IP / hostname / CIDR subnet): "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            raise ReturnToMainMenu()
+        if not target:
+            print(_centered_line(warn("No target entered -- returning to the main menu.")))
+            raise ReturnToMainMenu()
+        print()
+        return "target", target
+
+    # choice == "2"
+    while True:
+        try:
+            path = input(_centered_line(prompt("  Enter path to targets file: "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            raise ReturnToMainMenu()
+        if not path:
+            print(_centered_line(warn("No file entered -- returning to the main menu.")))
+            raise ReturnToMainMenu()
+        if os.path.isfile(path):
+            print()
+            return "targets", path
+        print(_centered_line(warn(f"File not found: {path}") + muted("  -- try again, or Ctrl-C for the main menu")))
+
+
+def prompt_scan_modes(options: list[tuple[str, str]], allow_back: bool = False) -> list[str]:
+    """
+    Shows a numbered menu of check modes (e.g. TLS, SSH, SMB, ...) plus a
+    final "All checks" entry, and lets the user pick one or more -- by
+    number, comma-separated (e.g. "1,3,7"), or by typing "all".
+
+    options: [(mode_name, description), ...] in display order, where
+    description is what's actually printed for that line (callers build
+    this with the live port-scan counts baked in, e.g.
+    "TLS    -- 3/11 host(s) with the required port open").
+
+    allow_back=True adds one more entry after "All checks": "Back to main
+    menu (change target / subnet)". Picking it (by number, or typing
+    "back"/"b") raises ReturnToMainMenu, exactly like Ctrl-C does here --
+    used when this same target list's port scan is being reused for
+    another round of checks (run_one_scan's post-scan loop), so there's an
+    explicit, discoverable way to leave that loop and go pick a different
+    target/subnet, not just Ctrl-C. It can't be combined with real check
+    numbers in one comma-separated selection -- it only fires when it's
+    the ONLY thing typed.
+
+    Returns the chosen mode_name(s), always in the SAME order as `options`
+    (never the order the user typed them, and never duplicated), or every
+    mode_name if "all" was chosen. Loops on invalid input; Ctrl-C/EOF here
+    raises ReturnToMainMenu (bounces back to the top-level menu) rather than
+    quitting the process outright.
+    """
+    print(_centered_line(accent("Select which check(s) to run:")))
+    print()
+
+    all_index = len(options) + 1
+    back_index = all_index + 1 if allow_back else None
+    # Every bracketed number (1 through however many options there are,
+    # plus "All checks" and, when present, "Back to main menu") is
+    # right-aligned inside a common width, so "[1]" and "[14]" both end
+    # in the same screen column instead of the closing bracket drifting
+    # right by one character per extra digit.
+    num_width = len(str(back_index if allow_back else all_index))
+
+    menu_lines = [
+        accent(f"  [{i:>{num_width}}]") + " " + c(desc, "white")
+        for i, (_, desc) in enumerate(options, start=1)
+    ]
+    menu_lines.append(accent(f"  [{all_index:>{num_width}}]") + " " + c("All checks", "white"))
+    if allow_back:
+        menu_lines.append(
+            accent(f"  [{back_index:>{num_width}}]") + " " +
+            c("Back to main menu", "white") + muted("  -- change target / subnet")
+        )
+    _emit_numbered_menu(menu_lines)
+    print()
+
+    while True:
+        try:
+            raw = input(_centered_line(prompt(f"  Select mode(s) (e.g. 1,3 or 'all'): "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            raise ReturnToMainMenu()
+
+        if not raw:
+            print(_centered_line(warn("No selection entered") + muted(" -- try again, or Ctrl-C to quit")))
+            continue
+
+        low = raw.lower()
+        if allow_back and low in ("back", "b", str(back_index)):
+            print()
+            raise ReturnToMainMenu()
+        if low == "all" or low == str(all_index):
+            print()
+            return [name for name, _ in options]
+
+        chosen_indices = []
+        valid = True
+        for part in raw.split(","):
+            part = part.strip()
+            if not part.isdigit() or not (1 <= int(part) <= len(options)):
+                valid = False
+                break
+            chosen_indices.append(int(part))
+
+        if not valid or not chosen_indices:
+            hint = f"1-{all_index}, comma-separated, 'all'" + (", or 'back'" if allow_back else "")
+            print(_centered_line(warn(f"Invalid selection '{raw}'") + muted(f" -- enter number(s) {hint}.")))
+            continue
+
+        chosen_set = set(chosen_indices)
+        chosen_names = [name for i, (name, _) in enumerate(options, start=1) if i in chosen_set]
+        print()
+        return chosen_names
+
+
+def prompt_port_list(label: str, verb: str = "check") -> str:
+    """
+    Asks for the port(s) a mode with no fixed port of its own should use --
+    a single port ("80") or several, comma-separated ("80,81,443,8080").
+    Used by any check that has to ask (currently DIRSEARCH and CORS), right
+    after the user picks that mode, instead of the port being decided up
+    front like every other check.
+
+    label is the mode's display name ("DIRSEARCH", "CORS"); verb describes
+    what happens to those ports ("brute-force", "check") so the prompt
+    reads naturally for either.
+
+    Returns the raw string as typed -- parsing/validating it into real port
+    numbers is the caller's job (cli.py's _parse_port_list), same division
+    of responsibility as the rest of this file. Loops on empty input;
+    Ctrl-C/EOF raises ReturnToMainMenu rather than quitting the process
+    outright.
+    """
+    print(_centered_line(accent(f"{label} needs to know which port(s) to {verb}.")))
+    while True:
+        try:
+            raw = input(_centered_line(prompt("  Enter port(s) (e.g. 80 or 80,443,8080): "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            raise ReturnToMainMenu()
+        if not raw:
+            print(_centered_line(warn("No port(s) entered") + muted(" -- try again, or Ctrl-C for the main menu")))
+            continue
+        return raw

netscraper/core/cert_chain_parser.py

@@ -0,0 +1,51 @@
+"""
+Parses `openssl s_client -showcerts` raw output into a plain structure the
+rule engine can use. Only text-parses two things, both stable/documented:
+  - the "Verify return code: N (message)" line
+  - how many certificates the SERVER actually sent (not how many the local
+    trust store has) -- this is what lets us tell "the server forgot to
+    send its intermediate" (a real misconfig) apart from "the ultimate root
+    just isn't in this trust store" (a different, less actionable finding),
+    which a bare verify-code check alone can't distinguish.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+_VERIFY_RE = re.compile(r"Verify return code:\s*(\d+)\s*\(([^)]*)\)")
+_SUBJECT_RE = re.compile(r"^\s*subject=(.*)$", re.MULTILINE)
+_ISSUER_RE = re.compile(r"^\s*issuer=(.*)$", re.MULTILINE)
+
+
+@dataclass
+class ChainResult:
+    host: str
+    port: int
+    verify_code: Optional[int] = None
+    verify_message: str = ""
+    certs_sent: int = 0
+    leaf_subject: str = ""
+    leaf_issuer: str = ""
+    raw_text: str = ""
+
+
+def parse_chain_text(raw_text: str, host: str, port: int) -> ChainResult:
+    result = ChainResult(host=host, port=port, raw_text=raw_text)
+
+    m = _VERIFY_RE.search(raw_text)
+    if m:
+        result.verify_code = int(m.group(1))
+        result.verify_message = m.group(2).strip()
+
+    result.certs_sent = raw_text.count("-----BEGIN CERTIFICATE-----")
+
+    m = _SUBJECT_RE.search(raw_text)
+    if m:
+        result.leaf_subject = m.group(1).strip()
+    m = _ISSUER_RE.search(raw_text)
+    if m:
+        result.leaf_issuer = m.group(1).strip()
+
+    return result

netscraper/core/cert_chain_rules.py

@@ -0,0 +1,97 @@
+"""
+Rule engine for the cert-chain-of-trust family (#12 Untrusted/Self-Signed,
+#13 Incomplete Certificate Chain). Both read the same ChainResult; which
+one fires (if any) depends on the verify code AND how many certificates the
+server actually sent -- that second part is what keeps "server forgot the
+intermediate" (genuinely incomplete chain) distinct from "chain is complete
+but the root just isn't trusted here" (an untrusted-CA situation, bucketed
+with self-signed since both are fundamentally "a client won't trust this").
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from netscraper.core.cert_chain_parser import ChainResult
+from netscraper.core.rules import Finding
+
+SELF_SIGNED_CODES = {18, 19}         # X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT / SELF_SIGNED_CERT_IN_CHAIN
+ISSUER_UNKNOWN_CODES = {2, 20, 21}   # unable to get issuer cert (locally / at all) / unable to verify first cert
+
+
+def check_self_signed_or_untrusted(result: ChainResult) -> Optional[Finding]:
+    if result.verify_code is None or result.verify_code == 0:
+        return None
+
+    if result.verify_code in SELF_SIGNED_CODES:
+        return Finding(
+            rule_id="self_signed_certificate",
+            label="Untrusted / Self-Signed SSL Certificate",
+            folder_name="Untrusted_Self_Signed",
+            severity="medium",
+            evidence_lines=[
+                f"Subject: {result.leaf_subject}",
+                f"Issuer:  {result.leaf_issuer}",
+                f"Verify return code: {result.verify_code} ({result.verify_message})",
+                "--> Certificate is self-signed (subject and issuer match; not issued by a trusted CA)",
+            ],
+            highlight_regex=re.compile(r"Verify return code:|^\s*(subject|issuer)=", re.IGNORECASE),
+        )
+
+    if result.verify_code in ISSUER_UNKNOWN_CODES and result.certs_sent >= 2:
+        # Server DID send a chain (leaf + at least one intermediate) -- the
+        # problem is the ultimate root isn't in this trust store, not that
+        # the server left something out. Bucketed with self-signed since
+        # both mean "a normal client will show a trust warning here."
+        return Finding(
+            rule_id="untrusted_ca",
+            label="Certificate Signed by Untrusted/Unknown CA",
+            folder_name="Untrusted_Self_Signed",
+            severity="medium",
+            evidence_lines=[
+                f"Subject: {result.leaf_subject}",
+                f"Issuer:  {result.leaf_issuer}",
+                f"Certificates sent by server: {result.certs_sent}",
+                f"Verify return code: {result.verify_code} ({result.verify_message})",
+                "--> Chain was sent, but does not resolve to a CA trusted by a standard client",
+            ],
+            highlight_regex=re.compile(r"Verify return code:|^\s*(subject|issuer)=", re.IGNORECASE),
+        )
+
+    return None
+
+
+def check_incomplete_chain(result: ChainResult) -> Optional[Finding]:
+    if result.verify_code is None or result.verify_code == 0:
+        return None
+    if result.verify_code in ISSUER_UNKNOWN_CODES and result.certs_sent <= 1:
+        return Finding(
+            rule_id="incomplete_certificate_chain",
+            label="Incomplete SSL/TLS Certificate Chain",
+            folder_name="Incomplete_Certificate_Chain",
+            severity="medium",
+            evidence_lines=[
+                f"Subject: {result.leaf_subject}",
+                f"Issuer:  {result.leaf_issuer}",
+                f"Certificates sent by server: {result.certs_sent} (leaf only, no intermediate)",
+                f"Verify return code: {result.verify_code} ({result.verify_message})",
+                "--> Server did not send the intermediate certificate(s) needed to build a trust chain",
+            ],
+            highlight_regex=re.compile(r"Verify return code:|^\s*(subject|issuer)=", re.IGNORECASE),
+        )
+    return None
+
+
+RULES = [
+    check_self_signed_or_untrusted,
+    check_incomplete_chain,
+]
+
+
+def evaluate(result: ChainResult) -> List[Finding]:
+    findings = []
+    for rule in RULES:
+        finding = rule(result)
+        if finding:
+            findings.append(finding)
+    return findings

netscraper/core/cert_chain_runner.py

@@ -0,0 +1,73 @@
+"""
+Runs `openssl s_client -showcerts` against a target to determine trust-chain
+status: self-signed, incomplete chain, or fully trusted. Unlike sslscan,
+openssl s_client's output is never colorized, so a plain subprocess capture
+is enough -- no pty needed here, and its output is already both
+human-readable AND has a stable, well-documented "Verify return code: N
+(message)" line we can parse directly (see openssl-verify(1) for the full
+X509_V_ERR_* code list). One invocation gives us everything.
+
+Verification uses the SYSTEM's default trust store (no -CAfile override),
+matching what a normal client/browser would decide. Note: in a sandboxed
+environment where outbound TLS is intercepted (see README), this check is
+only meaningful against loopback/local targets or when run from a real
+network position -- an intercepting proxy's own CA will make every
+external host look untrusted regardless of the real target's actual
+certificate.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from netscraper.core.targets import Target
+
+
+class CertChainError(RuntimeError):
+    def __init__(self, target: Target, message: str):
+        super().__init__(message)
+        self.target = target
+
+
+def run_live(target: Target, timeout: int = 20) -> str:
+    cmd = [
+        "openssl", "s_client",
+        "-connect", f"{target.host}:{target.port}",
+        "-servername", target.host,
+        "-showcerts",
+    ]
+    try:
+        proc = subprocess.run(
+            cmd,
+            input="",
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CertChainError(target, f"openssl s_client timed out after {timeout}s") from exc
+
+    output = (proc.stdout or "") + (proc.stderr or "")
+    if "Verify return code" not in output:
+        raise CertChainError(
+            target,
+            f"openssl s_client produced no usable output (exit={proc.returncode})",
+        )
+    return output
+
+
+def run_replay(target: Target, xml_dir: str) -> str:
+    candidate = Path(xml_dir) / f"{target.label}_chain.txt"
+    if not candidate.exists():
+        candidate = Path(xml_dir) / f"{target.host}_chain.txt"
+    if not candidate.exists():
+        raise CertChainError(
+            target, f"No captured cert-chain output found for {target.host} in {xml_dir}"
+        )
+    return candidate.read_text(encoding="utf-8")
+
+
+def get_chain_text(target: Target, xml_dir: str | None, timeout: int = 20) -> str:
+    if xml_dir:
+        return run_replay(target, xml_dir)
+    return run_live(target, timeout=timeout)

netscraper/core/concurrency.py

@@ -0,0 +1,98 @@
+"""
+Works out how many hosts to scan at once -- automatically, with no flag or
+prompt exposed anywhere. The whole point of this module is that a caller
+just asks worker_count() and gets back a safe, real number; there is no
+"ask the user" path at all.
+
+Why this exists: a target list of dozens/hundreds of hosts run one host at
+a time (the original design) means the wall-clock cost of a check scales
+linearly with the target list size -- fine for 5 hosts, painfully slow for
+64 or 200. Running several hosts' worth of the SAME check at once (a
+process pool -- see core/scan_worker.py for why it must be *processes*,
+not threads) cuts that wall-clock time roughly in proportion to how many
+run in parallel. But running too many at once on a modest machine (each
+worker can spin up its own Chromium for POC rendering, plus whatever
+external tool -- sslscan, nmap, dirsearch -- that check shells out to)
+risks starving the machine instead of actually finishing faster. So the
+number of workers is derived from the machine's own resources, not a
+fixed constant and never something the user is asked to set.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+
+# Rough per-worker memory budget. Each worker can, at its peak, be holding
+# open one Chromium instance (POC rendering) alongside whatever external
+# process a check shells out to (sslscan/nmap/dirsearch/curl/...) --
+# 1.5 GB/worker is a conservative real-world number for that combination
+# that still lets an 8 GB box comfortably run several workers at once
+# without swapping.
+_GB_PER_WORKER = 1.5
+
+# Absolute floor/ceiling regardless of what the machine reports. Below 2,
+# "parallel" isn't buying anything meaningful; above 8 the user's own
+# guidance ("maybe eight, six") is the target ceiling -- more workers than
+# that mostly just means more processes contending for the same network
+# link and the same target host's own connection limits, not real extra
+# throughput.
+_MIN_WORKERS = 2
+_MAX_WORKERS = 8
+
+
+def _total_ram_gb() -> float | None:
+    """
+    Best-effort total system RAM in GiB. Returns None if it can't be
+    determined on this platform -- the caller falls back to a safe
+    default rather than guessing.
+    """
+    # Linux: os.sysconf exposes page size * total pages directly, no
+    # subprocess needed.
+    try:
+        pages = os.sysconf("SC_PHYS_PAGES")
+        page_size = os.sysconf("SC_PAGE_SIZE")
+        if pages > 0 and page_size > 0:
+            return (pages * page_size) / (1024 ** 3)
+    except (ValueError, OSError, AttributeError):
+        pass
+
+    # macOS: no SC_PHYS_PAGES: ask sysctl directly instead.
+    try:
+        out = subprocess.run(
+            ["sysctl", "-n", "hw.memsize"], capture_output=True, text=True, timeout=2
+        )
+        if out.returncode == 0 and out.stdout.strip().isdigit():
+            return int(out.stdout.strip()) / (1024 ** 3)
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+    return None
+
+
+def worker_count(target_count: int | None = None) -> int:
+    """
+    Returns how many hosts to scan at once for a single check, clamped to
+    [_MIN_WORKERS, _MAX_WORKERS]. Never higher than the number of targets
+    actually queued (no point launching 8 workers for 3 hosts), and never
+    higher than the CPU count either (more workers than cores just means
+    context-switch overhead, not real parallelism).
+
+    Formula: total RAM / _GB_PER_WORKER, rounded down -- e.g. an 8 GB box
+    lands around 5, a 16 GB box around 8 (the middle of the user's own
+    "six, eight" guidance for machines in that 8-16 GB range). If RAM
+    can't be detected at all, assumes a conservative 8 GB baseline rather
+    than either refusing to parallelize or guessing high.
+    """
+    ram_gb = _total_ram_gb()
+    if ram_gb is None:
+        ram_gb = 8.0
+
+    ram_based = int(ram_gb // _GB_PER_WORKER)
+    cpu_based = os.cpu_count() or _MAX_WORKERS
+
+    count = max(_MIN_WORKERS, min(_MAX_WORKERS, ram_based, cpu_based))
+
+    if target_count is not None and target_count > 0:
+        count = min(count, target_count)
+
+    return max(1, count)