stackscan 2.1.0__py3-none-any.whl

stackscan/net/dns.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+_QUERY_TIMEOUT = 2.0
+_QUERY_LIFETIME = 3.0
+_EXTENDED_TYPES = ("CNAME", "MX", "NS", "TXT", "SOA", "CAA")
+_DNS_ATTEMPTS = 3
+
+
+@dataclass(frozen=True)
+class DnsResult:
+    host: str
+    ipv4: tuple[str, ...]
+    ipv6: tuple[str, ...]
+    cname: tuple[str, ...]
+    reverse_dns: dict[str, str]
+    mx: tuple[str, ...] = ()
+    ns: tuple[str, ...] = ()
+    txt: tuple[str, ...] = ()
+    soa: tuple[str, ...] = ()
+    caa: tuple[str, ...] = ()
+    resolver_available: bool = False
+    extras: dict[str, tuple[str, ...]] = field(default_factory=dict[str, tuple[str, ...]])
+
+
+def _addrinfo(host: str, family: int) -> list[str]:
+    for attempt in range(_DNS_ATTEMPTS):
+        try:
+            infos = socket.getaddrinfo(host, None, family=family, type=socket.SOCK_STREAM)
+        except socket.gaierror as exc:
+            if attempt + 1 < _DNS_ATTEMPTS and exc.errno in (socket.EAI_AGAIN, socket.EAI_FAIL):
+                continue
+            return []
+        except OSError:
+            return []
+        seen: list[str] = []
+        for info in infos:
+            addr = str(info[4][0])
+            if family == socket.AF_INET6 and _is_v4_mapped(addr):
+                continue
+            if addr not in seen:
+                seen.append(addr)
+        return seen
+    return []
+
+
+def _is_v4_mapped(addr: str) -> bool:
+    try:
+        parsed = ipaddress.ip_address(addr.split("%", 1)[0])
+    except ValueError:
+        return False
+    return isinstance(parsed, ipaddress.IPv6Address) and parsed.ipv4_mapped is not None
+
+
+def _reverse(ip: str) -> str | None:
+    try:
+        name, _, _ = socket.gethostbyaddr(ip)
+    except OSError:
+        return None
+    return name
+
+
+def _load_resolver() -> Any | None:
+    try:
+        from dns import resolver as _dns_resolver
+    except ImportError:
+        return None
+    return cast("Any", _dns_resolver)
+
+
+def _query(resolver: Any, host: str, rdtype: str) -> list[str]:
+    from dns import exception as _dns_exc  # type: ignore[import-untyped]
+
+    answers: Any = None
+    for attempt in range(_DNS_ATTEMPTS):
+        try:
+            answers = resolver.resolve(host, rdtype, raise_on_no_answer=False)
+            break
+        except (_dns_exc.Timeout, _dns_exc.DNSException) as exc:
+            if attempt + 1 < _DNS_ATTEMPTS and isinstance(exc, _dns_exc.Timeout):
+                continue
+            return []
+        except Exception:
+            return []
+    if answers is None:
+        return []
+    values: list[str] = []
+    for rdata in cast("list[Any]", answers):
+        text = _format_rdata(rdtype, rdata)
+        if text and text not in values:
+            values.append(text)
+    return values
+
+
+def _format_rdata(rdtype: str, rdata: Any) -> str:
+    if rdtype == "MX":
+        pref = getattr(rdata, "preference", "")
+        exchange = str(getattr(rdata, "exchange", "")).rstrip(".") or "."
+        return f"{pref} {exchange}".strip()
+    if rdtype in {"NS", "CNAME"}:
+        return str(getattr(rdata, "target", rdata)).rstrip(".")
+    if rdtype == "TXT":
+        strings = getattr(rdata, "strings", None)
+        if strings:
+            return "".join(
+                part.decode("utf-8", "replace") if isinstance(part, bytes) else str(part)
+                for part in cast("list[Any]", strings)
+            )
+        return str(rdata).strip('"')
+    if rdtype == "SOA":
+        mname = str(getattr(rdata, "mname", "")).rstrip(".")
+        rname = str(getattr(rdata, "rname", "")).rstrip(".")
+        serial = getattr(rdata, "serial", "")
+        return f"{mname} {rname} {serial}".strip()
+    if rdtype == "CAA":
+        flags = getattr(rdata, "flags", "")
+        tag = getattr(rdata, "tag", "")
+        value = getattr(rdata, "value", "")
+        if isinstance(tag, bytes):
+            tag = tag.decode("utf-8", "replace")
+        if isinstance(value, bytes):
+            value = value.decode("utf-8", "replace")
+        return f"{flags} {tag} {value}".strip()
+    return str(rdata).rstrip(".")
+
+
+def _extended_records(host: str) -> dict[str, tuple[str, ...]]:
+    resolver_mod = _load_resolver()
+    if resolver_mod is None:
+        return {}
+    resolver = resolver_mod.Resolver()
+    resolver.timeout = _QUERY_TIMEOUT
+    resolver.lifetime = _QUERY_LIFETIME
+    with ThreadPoolExecutor(max_workers=len(_EXTENDED_TYPES)) as pool:
+        futures = {
+            rdtype: pool.submit(_query, resolver, host, rdtype) for rdtype in _EXTENDED_TYPES
+        }
+        return {rdtype: tuple(future.result()) for rdtype, future in futures.items()}
+
+
+def resolve_host(host: str, *, reverse: bool = True) -> DnsResult:
+    ipv4 = tuple(_addrinfo(host, socket.AF_INET))
+    ipv6 = tuple(_addrinfo(host, socket.AF_INET6))
+    records = _extended_records(host)
+    reverse_map: dict[str, str] = {}
+    if reverse:
+        for ip in (*ipv4, *ipv6):
+            name = _reverse(ip)
+            if name:
+                reverse_map[ip] = name
+    return DnsResult(
+        host=host,
+        ipv4=ipv4,
+        ipv6=ipv6,
+        cname=records.get("CNAME", ()),
+        reverse_dns=reverse_map,
+        mx=records.get("MX", ()),
+        ns=records.get("NS", ()),
+        txt=records.get("TXT", ()),
+        soa=records.get("SOA", ()),
+        caa=records.get("CAA", ()),
+        resolver_available=bool(records),
+    )

stackscan/net/fingerprint.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+
+_BANNER_SIGNATURES: tuple[tuple[re.Pattern[str], str, str], ...] = (
+    (re.compile("SSH-\\d+\\.\\d+-OpenSSH[_-]([\\w.]+)", re.I), "ssh", "OpenSSH"),
+    (re.compile("SSH-\\d+\\.\\d+-Dropbear[_-]?([\\w.]+)?", re.I), "ssh", "Dropbear"),
+    (re.compile("220[- ].*ProFTPD (\\d[\\w.]+)", re.I), "ftp", "ProFTPD"),
+    (re.compile("220[- ].*\\(?vsFTPd (\\d[\\w.]+)\\)?", re.I), "ftp", "vsftpd"),
+    (re.compile("220[- ].*Pure-FTPd", re.I), "ftp", "Pure-FTPd"),
+    (re.compile("220[- ].*FileZilla Server (\\d[\\w.]+)", re.I), "ftp", "FileZilla"),
+    (re.compile("220[- ].*Exim (\\d[\\w.]+)", re.I), "smtp", "Exim"),
+    (re.compile("220[- ].*Postfix", re.I), "smtp", "Postfix"),
+    (re.compile("220[- ].*Sendmail (\\d[\\w.]+)", re.I), "smtp", "Sendmail"),
+    (re.compile("\\+OK.*Dovecot", re.I), "pop3", "Dovecot"),
+    (re.compile("\\* OK.*Dovecot", re.I), "imap", "Dovecot"),
+    (re.compile("^-ERR|^\\+PONG|^\\$\\d", re.I), "redis", "Redis"),
+    (re.compile("RFB (\\d+\\.\\d+)", re.I), "vnc", "VNC"),
+)
+_HTTP_SERVER_RE = re.compile("^server:\\s*(.+?)\\s*$", re.I | re.M)
+_SERVER_TOKEN_RE = re.compile("([A-Za-z][A-Za-z0-9._+-]*?)/([\\w.]+)")
+
+
+def fingerprint_banner(banner: str) -> tuple[str | None, str | None, str | None]:
+    for pattern, service, product in _BANNER_SIGNATURES:
+        match = pattern.search(banner)
+        if match:
+            version = match.group(1) if match.groups() else None
+            return (service, product, version)
+    return (None, None, None)
+
+
+def fingerprint_http(raw_response: str) -> tuple[str | None, str | None]:
+    match = _HTTP_SERVER_RE.search(raw_response)
+    if not match:
+        return (None, None)
+    server = match.group(1).strip()
+    token = _SERVER_TOKEN_RE.search(server)
+    if token:
+        return (token.group(1), token.group(2))
+    return (server, None)

stackscan/net/geo.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, cast
+
+
+class GeoProvider:
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        env_path = os.environ.get("STACKSCAN_GEOIP_DB")
+        resolved = db_path or env_path
+        self._db_path = Path(resolved) if resolved else None
+        self._reader: Any = None
+        self._unavailable = False
+
+    @property
+    def enabled(self) -> bool:
+        return self._db_path is not None and self._db_path.is_file()
+
+    def _ensure_reader(self) -> Any:
+        if self._reader is not None or self._unavailable:
+            return self._reader
+        if not self.enabled:
+            self._unavailable = True
+            return None
+        try:
+            from geoip2 import database as _geoip_db
+        except ImportError:
+            self._unavailable = True
+            return None
+        try:
+            self._reader = cast("Any", _geoip_db).Reader(str(self._db_path))
+        except Exception:
+            self._unavailable = True
+            return None
+        return self._reader
+
+    def lookup(self, ip: str) -> dict[str, str]:
+        reader: Any = self._ensure_reader()
+        if reader is None:
+            return {}
+        try:
+            response: Any = reader.city(ip)
+        except Exception:
+            return {}
+        out: dict[str, str] = {}
+        country = getattr(getattr(response, "country", None), "iso_code", None)
+        country_name = getattr(getattr(response, "country", None), "name", None)
+        city = getattr(getattr(response, "city", None), "name", None)
+        if isinstance(country, str):
+            out["country_code"] = country
+        if isinstance(country_name, str):
+            out["country"] = country_name
+        if isinstance(city, str):
+            out["city"] = city
+        return out
+
+
+def lookup_geo(
+    ips: tuple[str, ...], provider: GeoProvider | None = None
+) -> dict[str, dict[str, str]]:
+    provider = provider or GeoProvider()
+    if not provider.enabled:
+        return {}
+    result: dict[str, dict[str, str]] = {}
+    for ip in ips:
+        data = provider.lookup(ip)
+        if data:
+            result[ip] = data
+    return result

stackscan/net/ipinfo.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+from typing import Any, cast
+
+from stackscan.types import IpInfo
+
+_IPWHO_URL = "https://ipwho.is/"
+_CDN_KEYWORDS = (
+    "cloudflare",
+    "fastly",
+    "akamai",
+    "cloudfront",
+    "amazon",
+    "aws",
+    "google",
+    "microsoft",
+    "azure",
+    "incapsula",
+    "imperva",
+    "sucuri",
+    "stackpath",
+    "cdn77",
+    "bunny",
+    "keycdn",
+    "limelight",
+    "edgecast",
+    "gcore",
+    "edgio",
+    "verizon",
+)
+
+
+def _is_public(ip: str) -> bool:
+    try:
+        parsed = ipaddress.ip_address(ip.split("%", 1)[0])
+    except ValueError:
+        return False
+    return not (parsed.is_private or parsed.is_loopback or parsed.is_link_local)
+
+
+def _looks_like_cdn(*values: str | None) -> bool:
+    blob = " ".join(v.lower() for v in values if v)
+    return any(keyword in blob for keyword in _CDN_KEYWORDS)
+
+
+async def enrich_ips(
+    ips: tuple[str, ...],
+    *,
+    timeout: float = 10.0,
+    workers: int = 5,
+    sources: dict[str, str] | None = None,
+) -> list[IpInfo]:
+    import aiohttp
+
+    targets = [ip for ip in dict.fromkeys(ips) if _is_public(ip)]
+    if not targets:
+        return []
+    sources = sources or {}
+    semaphore = asyncio.Semaphore(max(workers, 1))
+    client_timeout = aiohttp.ClientTimeout(total=timeout)
+    async with aiohttp.ClientSession(timeout=client_timeout) as session:
+
+        async def lookup(ip: str) -> IpInfo | None:
+            async with semaphore:
+                try:
+                    async with session.get(
+                        f"{_IPWHO_URL}{ip}", headers={"User-Agent": "stackscan"}
+                    ) as resp:
+                        if resp.status != 200:
+                            return None
+                        data = cast("dict[str, Any]", await resp.json())
+                except (aiohttp.ClientError, TimeoutError, ValueError, OSError):
+                    return None
+            if not data.get("success"):
+                return None
+            connection = cast("dict[str, Any]", data.get("connection") or {})
+            asn = connection.get("asn")
+            org = connection.get("org")
+            isp = connection.get("isp")
+            return IpInfo(
+                ip=ip,
+                country=data.get("country"),
+                city=data.get("city"),
+                org=org,
+                isp=isp,
+                asn=f"AS{asn}" if asn else None,
+                is_cdn=_looks_like_cdn(org, isp),
+                source=sources.get(ip, ""),
+            )
+
+        results = await asyncio.gather(*(lookup(ip) for ip in targets))
+    return [info for info in results if info is not None]

stackscan/net/ports.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import shutil
+from typing import Any, cast
+
+from stackscan.net.fingerprint import fingerprint_banner, fingerprint_http
+from stackscan.types import Port, PortScan
+
+COMMON_PORTS: dict[int, tuple[str, str]] = {
+    21: ("ftp", "banner"),
+    22: ("ssh", "banner"),
+    23: ("telnet", "banner"),
+    25: ("smtp", "banner"),
+    53: ("domain", "none"),
+    80: ("http", "http"),
+    110: ("pop3", "banner"),
+    111: ("rpcbind", "none"),
+    135: ("msrpc", "none"),
+    139: ("netbios-ssn", "none"),
+    143: ("imap", "banner"),
+    443: ("https", "http"),
+    445: ("microsoft-ds", "none"),
+    465: ("smtps", "banner"),
+    554: ("rtsp", "rtsp"),
+    587: ("submission", "banner"),
+    631: ("ipp", "http"),
+    993: ("imaps", "none"),
+    995: ("pop3s", "none"),
+    1433: ("ms-sql", "none"),
+    1723: ("pptp", "none"),
+    1883: ("mqtt", "banner"),
+    2082: ("cpanel", "http"),
+    2083: ("cpanel-ssl", "http"),
+    2222: ("ssh-alt", "banner"),
+    3000: ("http-dev", "http"),
+    3306: ("mysql", "banner"),
+    3389: ("ms-wbt-server", "none"),
+    5432: ("postgresql", "none"),
+    5900: ("vnc", "banner"),
+    5985: ("wsman", "none"),
+    6379: ("redis", "banner"),
+    7547: ("cwmp", "http"),
+    8000: ("http-alt", "http"),
+    8080: ("http-proxy", "http"),
+    8081: ("http-alt", "http"),
+    8443: ("https-alt", "http"),
+    8554: ("rtsp-alt", "rtsp"),
+    8888: ("http-alt", "http"),
+    9000: ("http-alt", "http"),
+    9200: ("elasticsearch", "http"),
+    11211: ("memcached", "none"),
+    27017: ("mongodb", "none"),
+}
+_BANNER_BYTES = 512
+
+
+def nmap_available() -> bool:
+    return shutil.which("nmap") is not None
+
+
+def default_ports() -> tuple[int, ...]:
+    return tuple(sorted(COMMON_PORTS))
+
+
+async def scan_ports(
+    host: str,
+    *,
+    ports: tuple[int, ...] | None = None,
+    timeout: float = 2.0,
+    prefer_nmap: bool = True,
+    workers: int = 100,
+) -> PortScan:
+    targets = ports or default_ports()
+    if prefer_nmap and nmap_available():
+        result = await asyncio.to_thread(_run_nmap, host, targets)
+        if result is not None:
+            return result
+    return await _connect_scan(host, targets, timeout, workers)
+
+
+def _run_nmap(host: str, ports: tuple[int, ...]) -> PortScan | None:
+    try:
+        import nmap
+    except ImportError:
+        return None
+    try:
+        scanner = cast("Any", nmap).PortScanner()
+        port_arg = ",".join(str(p) for p in ports)
+        scanner.scan(host, port_arg, arguments="-Pn -sV --version-light -T4")
+    except Exception:
+        return None
+    found: list[Port] = []
+    try:
+        hosts = cast("list[str]", scanner.all_hosts())
+    except Exception:
+        return None
+    for scanned in hosts:
+        tcp = cast("dict[int, dict[str, Any]]", scanner[scanned].get("tcp", {}))
+        for number, info in tcp.items():
+            if info.get("state") != "open":
+                continue
+            product = info.get("product") or None
+            version = info.get("version") or None
+            extra = info.get("extrainfo") or None
+            if extra and version:
+                version = f"{version} ({extra})"
+            found.append(
+                Port(
+                    port=int(number),
+                    protocol="tcp",
+                    state="open",
+                    service=info.get("name") or None,
+                    product=product,
+                    version=version,
+                    host=host,
+                )
+            )
+    found.sort(key=lambda p: p.port)
+    return PortScan(scanner="nmap", ports=tuple(found))
+
+
+async def _connect_scan(
+    host: str, ports: tuple[int, ...], timeout: float, workers: int
+) -> PortScan:
+    semaphore = asyncio.Semaphore(max(workers, 1))
+
+    async def probe(port: int) -> Port | None:
+        async with semaphore:
+            return await _probe_port(host, port, timeout)
+
+    results = await asyncio.gather(*(probe(port) for port in ports))
+    open_ports = tuple(sorted((p for p in results if p is not None), key=lambda p: p.port))
+    note = "pure-Python connect scan (install nmap + python-nmap for full -sV detection)"
+    return PortScan(scanner="connect", ports=open_ports, note=note)
+
+
+async def _probe_port(host: str, port: int, timeout: float) -> Port | None:
+    service, probe = COMMON_PORTS.get(port, ("unknown", "banner"))
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(host, port), timeout=timeout
+        )
+    except (TimeoutError, OSError):
+        return None
+    product: str | None = None
+    version: str | None = None
+    try:
+        if probe == "banner":
+            banner = await _read(reader, timeout)
+            if banner:
+                svc, product, version = fingerprint_banner(banner)
+                service = svc or service
+                if not product:
+                    version = banner[:80]
+        elif probe == "http":
+            product, version = await _http_probe(host, port, reader, writer, timeout)
+        elif probe == "rtsp":
+            product, version = await _rtsp_probe(host, port, reader, writer, timeout)
+    finally:
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except (TimeoutError, OSError):
+            pass
+    return Port(
+        port=port,
+        protocol="tcp",
+        state="open",
+        service=service,
+        product=product,
+        version=version,
+        host=host,
+    )
+
+
+async def _read(reader: asyncio.StreamReader, timeout: float) -> str | None:
+    try:
+        data = await asyncio.wait_for(reader.read(_BANNER_BYTES), timeout=min(timeout, 2.5))
+    except (TimeoutError, OSError):
+        return None
+    if not data:
+        return None
+    return data.decode("utf-8", "replace").strip() or None
+
+
+async def _http_probe(
+    host: str, port: int, reader: asyncio.StreamReader, writer: asyncio.StreamWriter, timeout: float
+) -> tuple[str | None, str | None]:
+    request = (
+        f"GET / HTTP/1.0\r\nHost: {host}\r\nUser-Agent: stackscan\r\nConnection: close\r\n\r\n"
+    )
+    try:
+        writer.write(request.encode("ascii", "ignore"))
+        await asyncio.wait_for(writer.drain(), timeout=min(timeout, 2.5))
+    except (TimeoutError, OSError):
+        return (None, None)
+    raw = await _read(reader, timeout)
+    if not raw:
+        return (None, None)
+    return fingerprint_http(raw)
+
+
+async def _rtsp_probe(
+    host: str, port: int, reader: asyncio.StreamReader, writer: asyncio.StreamWriter, timeout: float
+) -> tuple[str | None, str | None]:
+    request = f"OPTIONS rtsp://{host}:{port} RTSP/1.0\r\nCSeq: 1\r\nUser-Agent: stackscan\r\n\r\n"
+    try:
+        writer.write(request.encode("ascii", "ignore"))
+        await asyncio.wait_for(writer.drain(), timeout=min(timeout, 2.5))
+    except (TimeoutError, OSError):
+        return (None, None)
+    raw = await _read(reader, timeout)
+    if not raw:
+        return (None, None)
+    server = fingerprint_http(raw)
+    if server != (None, None):
+        return server
+    return ("RTSP", None)

stackscan/net/resolver.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import socket
+
+import aiohttp
+from aiohttp.abc import AbstractResolver, ResolveResult
+from aiohttp.resolver import ThreadedResolver
+
+
+class FallbackResolver(AbstractResolver):
+    def __init__(self) -> None:
+        self._system = ThreadedResolver()
+
+    async def resolve(
+        self, host: str, port: int = 0, family: socket.AddressFamily = socket.AddressFamily.AF_INET
+    ) -> list[ResolveResult]:
+        try:
+            return await self._system.resolve(host, port, family)
+        except OSError:
+            results = await self._fallback(host, port, family)
+            if results:
+                return results
+            raise
+
+    async def _fallback(
+        self, host: str, port: int, family: socket.AddressFamily
+    ) -> list[ResolveResult]:
+        if family not in (socket.AddressFamily.AF_INET, socket.AF_UNSPEC):
+            return []
+        try:
+            from stackscan.net.subdomains import resolve_many
+
+            resolved = await resolve_many([host], 3.0, 100)
+        except Exception:
+            return []
+        addresses = resolved.get(host, ())
+        return [
+            ResolveResult(
+                hostname=host,
+                host=address,
+                port=port,
+                family=socket.AF_INET,
+                proto=0,
+                flags=socket.AI_NUMERICHOST,
+            )
+            for address in addresses
+        ]
+
+    async def close(self) -> None:
+        await self._system.close()
+
+
+def build_connector() -> aiohttp.TCPConnector:
+    return aiohttp.TCPConnector(resolver=FallbackResolver())