rimscan-cli 1.0.0__py3-none-any.whl

rimscan_cli/recon/_common.py

@@ -0,0 +1,62 @@
+"""Small helpers shared by the recon modules, the scanner and the CLI."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from typing import Iterable
+
+__all__ = [
+    "HOST_LABEL",
+    "all_public",
+    "is_public_address",
+    "is_valid_hostname",
+    "normalize_domain",
+    "normalize_name",
+]
+
+HOST_LABEL = re.compile(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?")
+
+
+def normalize_name(name: str) -> str:
+    """Lowercase a DNS name and strip whitespace and leading/trailing dots."""
+    return name.strip().lower().strip(".")
+
+
+def is_valid_hostname(name: str) -> bool:
+    """True if every label is a valid LDH label and the whole name fits in 253 characters."""
+    return len(name) <= 253 and all(HOST_LABEL.fullmatch(label) for label in name.split("."))
+
+
+def normalize_domain(value: str) -> str:
+    """Return a lowercase ASCII hostname, or raise ValueError if `value` is not a domain name."""
+    domain = value.strip().lower().rstrip(".")
+    if not domain or any(char in domain for char in "/:@ ?#"):
+        raise ValueError("domain must be a bare hostname such as example.com (no scheme, path, port or user)")
+    try:
+        ipaddress.ip_address(domain)
+    except ValueError:
+        pass
+    else:
+        raise ValueError("IP addresses are not supported; pass a domain name")
+    try:
+        domain = domain.encode("idna").decode("ascii")
+    except UnicodeError:
+        raise ValueError(f"{value!r} is not a valid domain name") from None
+    if len(domain.split(".")) < 2 or not is_valid_hostname(domain):
+        raise ValueError(f"{value!r} is not a valid domain name")
+    return domain
+
+
+def is_public_address(value: str) -> bool:
+    """True for a globally routable IP address (not loopback, private, link-local, ...)."""
+    try:
+        return ipaddress.ip_address(value).is_global
+    except ValueError:
+        return False
+
+
+def all_public(addresses: Iterable[str]) -> bool:
+    """True if there is at least one address and every one of them is globally routable."""
+    addresses = list(addresses)
+    return bool(addresses) and all(is_public_address(address) for address in addresses)

rimscan_cli/recon/_http.py

@@ -0,0 +1,65 @@
+"""Shared HTTP session: one honest User-Agent and one retry policy."""
+
+from __future__ import annotations
+
+import re
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from rimscan_cli import __version__
+
+USER_AGENT = f"rimscan-cli/{__version__} (+https://rimscan.cloud)"
+
+_CHARSET = re.compile(r"charset=\s*[\"']?([\w.:-]+)", re.IGNORECASE)
+
+
+def make_session(retries: int = 2) -> requests.Session:
+    """Build a session. Pass ``retries=0`` when each request must be sent at most once.
+
+    A server-supplied ``Retry-After`` header is ignored: urllib3 would sleep for as long as
+    the server asks (the request timeout does not cover that sleep), so a scanned host could
+    stall a worker thread for hours. Retries use the short exponential backoff instead.
+    """
+    retry = Retry(
+        total=retries,
+        backoff_factor=1.0,
+        status_forcelist=(429, 500, 502, 503, 504),
+        allowed_methods=("GET", "HEAD"),
+        raise_on_status=False,
+        respect_retry_after_header=False,
+    )
+    session = requests.Session()
+    session.headers["User-Agent"] = USER_AGENT
+    session.max_redirects = 5
+    adapter = HTTPAdapter(max_retries=retry, pool_maxsize=20)
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+    return session
+
+
+def _declared_charset(response: requests.Response) -> str:
+    """Charset from the Content-Type header, or UTF-8.
+
+    ``response.encoding`` is not used: for ``text/*`` without a charset, requests guesses
+    ISO-8859-1, which garbles the non-Latin fingerprints and secrets we match against.
+    """
+    headers = getattr(response, "headers", None) or {}
+    match = _CHARSET.search(headers.get("Content-Type", ""))
+    return match.group(1).strip("\"'") if match else "utf-8"
+
+
+def read_capped(response: requests.Response, limit: int) -> str:
+    """Read at most `limit` bytes of a streamed response and decode them."""
+    body = bytearray()
+    for chunk in response.iter_content(chunk_size=16 * 1024):
+        body.extend(chunk)
+        if len(body) >= limit:
+            break
+    response.close()
+    data = bytes(body[:limit])
+    try:
+        return data.decode(_declared_charset(response), errors="replace")
+    except LookupError:
+        return data.decode("utf-8", errors="replace")

rimscan_cli/recon/cert_audit.py

@@ -0,0 +1,131 @@
+"""TLS certificate checks: validity, expiry and protocol support."""
+
+from __future__ import annotations
+
+import functools
+import logging
+import socket
+import ssl
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import List, Optional, Sequence
+
+import certifi
+
+from rimscan_cli.recon._common import normalize_name
+from rimscan_cli.recon.severity import Severity
+
+__all__ = ["CertAuditFinding", "CertAuditor", "CertSeverity", "MAX_HOSTS"]
+
+# Kept so existing imports keep working; there is a single Severity enum.
+CertSeverity = Severity
+
+logger = logging.getLogger(__name__)
+
+MAX_HOSTS = 100
+
+# OpenSSL X509_V_ERR_* codes reported by ssl.SSLCertVerificationError.verify_code.
+_VERIFY_FINDINGS = {
+    10: ("expired", Severity.CRITICAL, "Certificate has expired"),
+    9: ("not_yet_valid", Severity.HIGH, "Certificate is not yet valid"),
+    18: ("self_signed", Severity.HIGH, "Certificate is self-signed"),
+    19: ("self_signed", Severity.HIGH, "Certificate chain ends in an untrusted self-signed root"),
+    20: ("untrusted_chain", Severity.HIGH, "Certificate issuer is not trusted (missing intermediate or unknown CA)"),
+    21: ("untrusted_chain", Severity.HIGH, "Certificate chain is incomplete"),
+    62: ("hostname_mismatch", Severity.HIGH, "Certificate does not match the hostname"),
+}
+
+_PROTOCOL_REASONS = ("UNSUPPORTED_PROTOCOL", "NO_PROTOCOLS_AVAILABLE", "PROTOCOL_VERSION")
+
+
+@dataclass
+class CertAuditFinding:
+    check: str
+    severity: Severity
+    hostname: str
+    detail: str
+    expires: Optional[str] = None
+
+
+@functools.lru_cache(maxsize=1)
+def _context() -> ssl.SSLContext:
+    """A client context whose results do not depend on the Python version or the OS.
+
+    - the CA bundle is certifi's, so a slim image without ca-certificates does not
+      report every host as untrusted;
+    - TLS 1.2 is the floor on every Python version, so the "protocol" check is stable;
+    - strict X.509 checking (default since Python 3.13) is off, so the same certificate
+      gives the same verdict on 3.10 and 3.13.
+
+    The context is built once (loading the CA bundle is slow) and shared by all handshakes.
+    """
+    context = ssl.create_default_context(cafile=certifi.where())
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.verify_flags &= ~ssl.VERIFY_X509_STRICT
+    return context
+
+
+class CertAuditor:
+    def __init__(self, timeout: float = 5.0, max_workers: int = 10):
+        self.timeout = timeout
+        self.max_workers = max_workers
+
+    def _handshake(self, hostname: str, port: int) -> dict:
+        context = _context()
+        with socket.create_connection((hostname, port), timeout=self.timeout) as sock:
+            with context.wrap_socket(sock, server_hostname=hostname) as tls:
+                return tls.getpeercert() or {}
+
+    def audit_host(self, hostname: str, port: int = 443) -> List[CertAuditFinding]:
+        hostname = normalize_name(hostname)
+        try:
+            cert = self._handshake(hostname, port)
+        except ssl.SSLCertVerificationError as exc:
+            check, severity, detail = _VERIFY_FINDINGS.get(
+                exc.verify_code, ("invalid", Severity.HIGH, f"Certificate failed verification: {exc.verify_message}")
+            )
+            return [CertAuditFinding(check, severity, hostname, detail)]
+        except ssl.SSLError as exc:
+            reason = getattr(exc, "reason", "") or ""
+            if any(marker in reason for marker in _PROTOCOL_REASONS):
+                return [CertAuditFinding(
+                    "protocol", Severity.HIGH, hostname, "Server does not support TLS 1.2 or newer"
+                )]
+            logger.debug("%s: TLS handshake failed (%s)", hostname, reason)
+            return []
+        except OSError as exc:
+            # No listener on 443, filtered port, DNS failure: the host simply has no HTTPS.
+            logger.debug("%s: connection failed (%s)", hostname, type(exc).__name__)
+            return []
+        return self._check_expiry(hostname, cert)
+
+    @staticmethod
+    def _check_expiry(hostname: str, cert: dict) -> List[CertAuditFinding]:
+        not_after = cert.get("notAfter")
+        if not not_after:
+            return []
+        try:
+            expires = datetime.fromtimestamp(ssl.cert_time_to_seconds(not_after), tz=timezone.utc)
+        except (ValueError, OverflowError, OSError):
+            logger.debug("%s: unreadable notAfter %r", hostname, not_after)
+            return []
+        days_left = (expires - datetime.now(timezone.utc)).days
+        if days_left <= 14:
+            severity = Severity.HIGH
+        elif days_left <= 30:
+            severity = Severity.MEDIUM
+        else:
+            return []
+        return [CertAuditFinding(
+            "expiring", severity, hostname, f"Certificate expires in {days_left} days", expires.isoformat()
+        )]
+
+    def audit_many(self, hostnames: Sequence[str], max_hosts: int = MAX_HOSTS) -> List[CertAuditFinding]:
+        hosts = list(dict.fromkeys(hostnames))
+        if len(hosts) > max_hosts:
+            logger.warning("Certificate audit limited to %d of %d hosts", max_hosts, len(hosts))
+            hosts = hosts[:max_hosts]
+        with ThreadPoolExecutor(max_workers=self.max_workers) as pool:
+            results = pool.map(self.audit_host, hosts)
+        return [finding for host_findings in results for finding in host_findings]

rimscan_cli/recon/dns_audit.py

@@ -0,0 +1,196 @@
+"""DNS misconfiguration checks: SPF, DMARC and zone-transfer exposure."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+import dns.exception
+import dns.query
+import dns.rcode
+import dns.resolver
+
+from rimscan_cli.recon._common import is_public_address, normalize_name
+from rimscan_cli.recon.severity import Severity
+
+__all__ = ["DNSAuditFinding", "DNSAuditor", "AuditSeverity"]
+
+# Kept so existing imports keep working; there is a single Severity enum.
+AuditSeverity = Severity
+
+_SPF_ALL = re.compile(r"^([+\-~?]?)all$", re.IGNORECASE)
+_DMARC_START = re.compile(r"^v=dmarc1\s*(?:;|$)", re.IGNORECASE)
+
+
+def _is_spf(record: str) -> bool:
+    text = record.strip().lower()
+    return text == "v=spf1" or text.startswith("v=spf1 ")
+
+
+def _dmarc_tag(record: str, tag: str) -> Optional[str]:
+    match = re.search(rf"(?:^|;)\s*{re.escape(tag)}\s*=\s*(\w+)", record, re.IGNORECASE)
+    return match.group(1).lower() if match else None
+
+
+@dataclass
+class DNSAuditFinding:
+    check: str
+    severity: Severity
+    domain: str
+    detail: str
+    record: str = ""
+
+
+class DNSAuditor:
+    def __init__(self, timeout: float = 5.0, nameservers: Optional[Sequence[str]] = None):
+        self.timeout = timeout
+        self.resolver = dns.resolver.Resolver()
+        self.resolver.timeout = timeout
+        self.resolver.lifetime = timeout
+        if nameservers:
+            self.resolver.nameservers = list(nameservers)
+        # Lookups that failed (timeout, SERVFAIL, ...). A failed lookup produces no finding,
+        # so callers use this to tell "clean" apart from "could not check".
+        self.errors: List[str] = []
+
+    def audit(self, domain: str, include_zone_transfer: bool = False) -> List[DNSAuditFinding]:
+        domain = normalize_name(domain)
+        self.errors = []
+        findings = self.check_spf(domain) + self.check_dmarc(domain)
+        if include_zone_transfer:
+            findings += self.check_zone_transfer(domain)
+        return findings
+
+    def _txt_records(self, name: str) -> Optional[List[str]]:
+        """TXT strings at `name`; [] if none exist, None if the lookup itself failed."""
+        try:
+            answers = self.resolver.resolve(name, "TXT")
+        except (dns.resolver.NoAnswer, dns.resolver.NXDOMAIN):
+            return []
+        except dns.exception.DNSException:
+            self.errors.append(f"TXT lookup for {name} failed")
+            return None
+        return [b"".join(rdata.strings).decode("utf-8", "replace") for rdata in answers]
+
+    def check_spf(self, domain: str) -> List[DNSAuditFinding]:
+        records = self._txt_records(domain)
+        if records is None:
+            return []
+        spf_records = [r for r in records if _is_spf(r)]
+        if not spf_records:
+            return [DNSAuditFinding("spf", Severity.MEDIUM, domain, "No SPF record found")]
+        if len(spf_records) > 1:
+            return [DNSAuditFinding(
+                "spf", Severity.HIGH, domain,
+                "Multiple SPF records; receivers treat this as a permanent error", spf_records[0],
+            )]
+
+        spf = spf_records[0]
+        tokens = spf.split()[1:]
+        for token in tokens:
+            match = _SPF_ALL.match(token)
+            if not match:
+                continue
+            qualifier = match.group(1) or "+"
+            if qualifier in "+?":
+                return [DNSAuditFinding(
+                    "spf", Severity.HIGH, domain,
+                    f"SPF allows any sender ({token.lower()})", spf,
+                )]
+            if qualifier == "~":
+                return [DNSAuditFinding(
+                    "spf", Severity.MEDIUM, domain, "SPF soft-fail policy (~all)", spf
+                )]
+            return []
+        # RFC 7208: without an "all" mechanism, redirect= supplies the policy instead.
+        if any(token.lower().startswith("redirect=") for token in tokens):
+            return []
+        return [DNSAuditFinding(
+            "spf", Severity.MEDIUM, domain, "SPF record has no terminating 'all' mechanism", spf
+        )]
+
+    def check_dmarc(self, domain: str) -> List[DNSAuditFinding]:
+        """Look for DMARC at the domain, then at each parent (subdomains inherit the policy).
+
+        Parents are walked down to two labels because there is no public-suffix list here.
+        """
+        labels = domain.split(".")
+        candidates = [".".join(labels[i:]) for i in range(max(len(labels) - 1, 1))]
+
+        record = ""
+        found_at = domain
+        for name in candidates:
+            records = self._txt_records(f"_dmarc.{name}")
+            if records is None:
+                return []
+            matching = [r for r in records if _DMARC_START.match(r.strip())]
+            if matching:
+                record, found_at = matching[0], name
+                break
+        else:
+            return [DNSAuditFinding("dmarc", Severity.HIGH, domain, "No DMARC record found")]
+
+        policy = _dmarc_tag(record, "p") or "none"
+        suffix = ""
+        if found_at != domain:
+            policy = _dmarc_tag(record, "sp") or policy
+            suffix = f" (inherited from {found_at})"
+        if policy == "none":
+            return [DNSAuditFinding(
+                "dmarc", Severity.HIGH, domain, f"DMARC policy is p=none (monitoring only){suffix}", record
+            )]
+        if policy == "quarantine":
+            return [DNSAuditFinding(
+                "dmarc", Severity.MEDIUM, domain, f"DMARC policy is p=quarantine{suffix}", record
+            )]
+        return []
+
+    def check_zone_transfer(self, domain: str) -> List[DNSAuditFinding]:
+        """Ask each nameserver for an AXFR and stop reading after the first reply message.
+
+        A failed NS or nameserver-address lookup is recorded in `errors`, so a run that could
+        not test a nameserver is reported as incomplete instead of looking clean. A
+        nameserver's A records are used; if it has none, its AAAA records are tried.
+        """
+        try:
+            nameservers = self.resolver.resolve(domain, "NS")
+        except (dns.resolver.NoAnswer, dns.resolver.NXDOMAIN):
+            return []
+        except dns.exception.DNSException:
+            self.errors.append(f"NS lookup for {domain} failed; zone transfer not checked")
+            return []
+
+        findings: List[DNSAuditFinding] = []
+        for ns in nameservers:
+            ns_host = str(ns.target).rstrip(".")
+            for address in self._nameserver_addresses(ns_host):
+                if not is_public_address(address):
+                    continue  # never send a transfer request to an internal address
+                if self._axfr_allowed(address, domain):
+                    findings.append(DNSAuditFinding(
+                        "zone_transfer", Severity.CRITICAL, domain,
+                        f"Zone transfer (AXFR) allowed on {ns_host} ({address})", ns_host,
+                    ))
+                    break
+        return findings
+
+    def _nameserver_addresses(self, ns_host: str) -> List[str]:
+        """A records of a nameserver, or its AAAA records when it has no A record."""
+        for rdtype in ("A", "AAAA"):
+            try:
+                return [str(a) for a in self.resolver.resolve(ns_host, rdtype)]
+            except (dns.resolver.NoAnswer, dns.resolver.NXDOMAIN):
+                continue
+            except dns.exception.DNSException:
+                self.errors.append(f"{rdtype} lookup for nameserver {ns_host} failed; zone transfer not checked on it")
+                return []
+        return []
+
+    def _axfr_allowed(self, address: str, domain: str) -> bool:
+        try:
+            for message in dns.query.xfr(address, domain, lifetime=self.timeout):
+                return message.rcode() == dns.rcode.NOERROR and bool(message.answer)
+        except (dns.exception.DNSException, OSError, EOFError):
+            return False
+        return False

rimscan_cli/recon/enumeration.py

@@ -0,0 +1,192 @@
+"""Subdomain enumeration from public passive-DNS and certificate-transparency sources."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+import time
+from typing import Callable, Dict, Iterable, List, Optional, Set
+from urllib.parse import urlparse
+
+from rimscan_cli.recon._common import is_valid_hostname, normalize_name
+from rimscan_cli.recon._http import make_session, read_capped
+from rimscan_cli.recon.resolver import DNSResolver
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["SubdomainEnumerator", "DEFAULT_SOURCES", "BRUTEFORCE_WORDLIST"]
+
+DEFAULT_SOURCES = ("crt.sh", "certspotter", "otx", "rapiddns", "wayback", "anubis")
+
+BRUTEFORCE_WORDLIST = (
+    "www", "mail", "ftp", "dev", "staging", "api", "admin", "test", "portal", "vpn",
+    "app", "blog", "shop", "cdn", "static", "assets", "beta", "demo", "internal",
+    "secure", "cloud", "docs", "support", "help", "status", "monitor", "git",
+    "gitlab", "jenkins", "jira", "backup", "old", "new", "m", "mobile", "webmail",
+    "smtp", "ns1", "ns2", "db", "dashboard", "auth", "sso", "login", "stage",
+    "uat", "qa", "preview",
+)
+
+_WAYBACK_MAX_BYTES = 25 * 1024 * 1024
+# crt.sh answers with one JSON array for the whole domain, which can be huge. Past this size
+# the body is cut off, the JSON no longer parses, and the source is reported as failed
+# instead of the whole array being held in memory.
+_CRTSH_MAX_BYTES = 50 * 1024 * 1024
+_RAPIDDNS_LINK = re.compile(r'target="_blank">([^<]+)</a>')
+
+
+class SubdomainEnumerator:
+    def __init__(self, domain: str, timeout: float = 10.0):
+        self.domain = normalize_name(domain)
+        self.timeout = (min(timeout, 5.0), timeout)
+        self.session = make_session()
+        self.source_status: Dict[str, str] = {}
+        self._sources: Dict[str, Callable[[], Set[str]]] = {
+            "crt.sh": self.from_crtsh,
+            "certspotter": self.from_certspotter,
+            "otx": self.from_otx,
+            "rapiddns": self.from_rapiddns,
+            "wayback": self.from_wayback,
+            "anubis": self.from_anubis,
+        }
+
+    # -- helpers -----------------------------------------------------------
+
+    def _accept(self, name: str) -> Optional[str]:
+        """Normalize a candidate; return it only if it is a valid subdomain of the target."""
+        name = normalize_name(name)
+        if name.startswith("*."):
+            name = name[2:]
+        if not name.endswith("." + self.domain) or not is_valid_hostname(name):
+            return None
+        return name
+
+    def _collect(self, names: Iterable[str]) -> Set[str]:
+        return {valid for valid in map(self._accept, names) if valid}
+
+    def _get_json(self, url: str, **kwargs):
+        response = self.session.get(url, timeout=self.timeout, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+    # -- sources -----------------------------------------------------------
+
+    def from_crtsh(self) -> Set[str]:
+        response = self.session.get(
+            f"https://crt.sh/?q=%25.{self.domain}&output=json", timeout=self.timeout, stream=True
+        )
+        response.raise_for_status()
+        data = json.loads(read_capped(response, _CRTSH_MAX_BYTES))
+        return self._collect(
+            name for entry in data for name in entry.get("name_value", "").split("\n")
+        )
+
+    def from_certspotter(self, max_pages: int = 5) -> Set[str]:
+        url = "https://api.certspotter.com/v1/issuances"
+        params = {"domain": self.domain, "include_subdomains": "true", "expand": "dns_names"}
+        names: Set[str] = set()
+        for _ in range(max_pages):
+            response = self.session.get(url, params=params, timeout=self.timeout)
+            response.raise_for_status()
+            page = response.json()
+            if not page:
+                break
+            for issuance in page:
+                names |= self._collect(issuance.get("dns_names", []))
+            params["after"] = page[-1]["id"]
+        return names
+
+    def from_otx(self) -> Set[str]:
+        data = self._get_json(
+            f"https://otx.alienvault.com/api/v1/indicators/domain/{self.domain}/passive_dns"
+        )
+        return self._collect(record.get("hostname", "") for record in data.get("passive_dns", []))
+
+    def from_rapiddns(self) -> Set[str]:
+        response = self.session.get(
+            f"https://rapiddns.io/subdomain/{self.domain}", params={"full": 1}, timeout=self.timeout
+        )
+        response.raise_for_status()
+        return self._collect(_RAPIDDNS_LINK.findall(response.text))
+
+    def from_anubis(self) -> Set[str]:
+        return self._collect(self._get_json(f"https://jldc.me/anubis/subdomains/{self.domain}"))
+
+    def from_wayback(self) -> Set[str]:
+        response = self.session.get(
+            "https://web.archive.org/cdx/search/cdx",
+            params={
+                "url": f"*.{self.domain}", "output": "json", "fl": "original",
+                "collapse": "urlkey", "limit": 100000,
+            },
+            timeout=self.timeout,
+            stream=True,
+        )
+        response.raise_for_status()
+        rows = json.loads(read_capped(response, _WAYBACK_MAX_BYTES))
+        hosts = (urlparse(row[0] if "//" in row[0] else "//" + row[0]).hostname or "" for row in rows[1:] if row)
+        return self._collect(hosts)
+
+    def from_bruteforce(self, resolver: DNSResolver, wordlist: Iterable[str] = BRUTEFORCE_WORDLIST) -> Set[str]:
+        """Resolve common prefixes. The resolver must already have run wildcard detection."""
+        candidates = [f"{word.strip().lower()}.{self.domain}" for word in wordlist if word.strip()]
+        return {r.hostname for r in resolver.resolve_many(candidates) if r.is_live}
+
+    # -- orchestration -----------------------------------------------------
+
+    def run(
+        self,
+        sources: Optional[List[str]] = None,
+        source_timeout: float = 60.0,
+        on_source_done: Optional[Callable[[str, int, str], None]] = None,
+    ) -> Set[str]:
+        """Query the selected sources concurrently and return the subdomains found.
+
+        A slow or failing source never blocks the others; its outcome is recorded in
+        `source_status`. The target domain itself is not included in the result.
+
+        Each source runs in a daemon thread, so one that is still stuck after
+        `source_timeout` cannot keep the interpreter alive at exit. Any exception a source
+        raises (including a malformed response) is contained to that source.
+        """
+        chosen = list(sources) if sources else list(DEFAULT_SOURCES)
+        unknown = [name for name in chosen if name not in self._sources]
+        if unknown:
+            raise ValueError(f"unknown source(s): {', '.join(unknown)}")
+
+        results: Dict[str, Set[str]] = {}
+        errors: Dict[str, BaseException] = {}
+
+        def worker(name: str) -> None:
+            try:
+                results[name] = set(self._sources[name]())
+            except Exception as exc:  # noqa: BLE001 - one bad source must not stop the scan
+                errors[name] = exc
+
+        threads = {
+            name: threading.Thread(target=worker, args=(name,), name=f"enum-{name}", daemon=True)
+            for name in chosen
+        }
+        for thread in threads.values():
+            thread.start()
+        deadline = time.monotonic() + source_timeout
+        for thread in threads.values():
+            thread.join(max(0.0, deadline - time.monotonic()))
+
+        found: Set[str] = set()
+        for name in chosen:
+            names: Set[str] = set()
+            if threads[name].is_alive():
+                self.source_status[name] = "timed out"
+            elif name in errors:
+                self.source_status[name] = f"failed ({type(errors[name]).__name__})"
+                logger.debug("%s failed", name, exc_info=errors[name])
+            else:
+                names = results.get(name, set())
+                self.source_status[name] = "ok"
+            found |= names
+            if on_source_done:
+                on_source_done(name, len(names), self.source_status[name])
+        return found