findssh 2.0.1__tar.gz → 2.1.0__tar.gz

{findssh-2.0.1/src/findssh.egg-info → findssh-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: findssh
-Version: 2.0.1
+Version: 2.1.0
 Summary: find open servers on IPv4 subnet such as SSH
 Keywords: port-scan,ssh
 Classifier: Development Status :: 5 - Production/Stable
@@ -18,29 +18,28 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Security
 Classifier: Topic :: System :: Networking
 Classifier: Topic :: Utilities
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
-Provides-Extra: lint
-Requires-Dist: flake8; extra == "lint"
-Requires-Dist: flake8-bugbear; extra == "lint"
-Requires-Dist: flake8-builtins; extra == "lint"
-Requires-Dist: flake8-blind-except; extra == "lint"
-Requires-Dist: mypy; extra == "lint"
+Requires-Dist: pytest-asyncio; extra == "tests"
+Requires-Dist: mypy; extra == "tests"
+Dynamic: license-file
 
 # Find SSH servers (without NMAP)
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3336467.svg)](https://doi.org/10.5281/zenodo.3336467)
-![ci](https://github.com/scivision/findssh/workflows/ci/badge.svg)
-[![PyPI Download stats](http://pepy.tech/badge/findssh)](http://pepy.tech/project/findssh)
+[![ci](https://github.com/scivision/findssh/actions/workflows/ci.yml/badge.svg)](https://github.com/scivision/findssh/actions/workflows/ci.yml)
+[![PyPI Download stats](https://pepy.tech/badge/findssh)](https://pepy.tech/project/findssh)
 
 Platform-independently find SSH servers (or other services with open ports) on an IPv4 subnet in pure Python WITHOUT NMAP.
 Scan entire IPv4 subnet in less than 1 second using Python standard library `asyncio`  coroutines and a single thread.
 
-The default
-[asyncio coroutine](https://docs.python.org/3/library/asyncio.html)
+The findssh
+[asyncio](https://docs.python.org/3/library/asyncio.html)
+coroutine
+[TaskGroup](https://docs.python.org/3/library/asyncio-task.html#task-groups)
 uses a single thread and is more than 10x faster than
 [concurrent.futures.ThreadPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html).
 
@@ -55,7 +54,7 @@ or from this repo:
 ```sh
 git clone https://github.com/scivision/findssh
 
-pip install -e findssh
+pip install -e ./findssh
 ```
 
 ## Usage
@@ -76,6 +75,12 @@ or use project script e.g. from [pipx](https://github.com/pypa/pipx):
 findssh
 ```
 
+For example, to scan your local subnet for SSH servers:
+
+```sh
+findssh -p 22 192.168.1.0
+```
+
 * `-s`  check the string from the server to attempt to verify the correct service has been found
 * `-t` timeout per server (seconds)  useful for high latency connection
 * `-b` baseip (check other subnet besides your own)

{findssh-2.0.1 → findssh-2.1.0}/README.md

@@ -1,14 +1,16 @@
 # Find SSH servers (without NMAP)
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3336467.svg)](https://doi.org/10.5281/zenodo.3336467)
-![ci](https://github.com/scivision/findssh/workflows/ci/badge.svg)
-[![PyPI Download stats](http://pepy.tech/badge/findssh)](http://pepy.tech/project/findssh)
+[![ci](https://github.com/scivision/findssh/actions/workflows/ci.yml/badge.svg)](https://github.com/scivision/findssh/actions/workflows/ci.yml)
+[![PyPI Download stats](https://pepy.tech/badge/findssh)](https://pepy.tech/project/findssh)
 
 Platform-independently find SSH servers (or other services with open ports) on an IPv4 subnet in pure Python WITHOUT NMAP.
 Scan entire IPv4 subnet in less than 1 second using Python standard library `asyncio`  coroutines and a single thread.
 
-The default
-[asyncio coroutine](https://docs.python.org/3/library/asyncio.html)
+The findssh
+[asyncio](https://docs.python.org/3/library/asyncio.html)
+coroutine
+[TaskGroup](https://docs.python.org/3/library/asyncio-task.html#task-groups)
 uses a single thread and is more than 10x faster than
 [concurrent.futures.ThreadPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html).
 
@@ -23,7 +25,7 @@ or from this repo:
 ```sh
 git clone https://github.com/scivision/findssh
 
-pip install -e findssh
+pip install -e ./findssh
 ```
 
 ## Usage
@@ -44,6 +46,12 @@ or use project script e.g. from [pipx](https://github.com/pypa/pipx):
 findssh
 ```
 
+For example, to scan your local subnet for SSH servers:
+
+```sh
+findssh -p 22 192.168.1.0
+```
+
 * `-s`  check the string from the server to attempt to verify the correct service has been found
 * `-t` timeout per server (seconds)  useful for high latency connection
 * `-b` baseip (check other subnet besides your own)

{findssh-2.0.1 → findssh-2.1.0}/pyproject.toml

@@ -24,14 +24,13 @@ classifiers = [
   "Topic :: Utilities"
 ]
 dynamic = ["readme", "version"]
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 
 [project.scripts]
 findssh = "findssh.__main__:main"
 
 [project.optional-dependencies]
-tests = ["pytest"]
-lint = ["flake8", "flake8-bugbear", "flake8-builtins", "flake8-blind-except", "mypy"]
+tests = ["pytest", "pytest-asyncio", "mypy"]
 
 [tool.setuptools.dynamic]
 readme = {file = ["README.md"], content-type = "text/markdown"}
@@ -41,8 +40,6 @@ version = {attr = "findssh.__version__"}
 line-length = 90
 
 [tool.mypy]
-files = ["src"]
-strict_optional = false
-allow_redefinition = true
-show_error_context = false
-show_column_numbers = true
+files = ["."]
+install_types = true
+exclude = ["^build([/\\\\]|$)"]

findssh-2.1.0/src/findssh/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+import socket
+import ipaddress
+
+from .coro import get_hosts, discover_services
+
+__all__ = ["get_hosts", "discover_services", "address2net", "get_lan_ip"]
+
+__version__ = "2.1.0"
+
+
+def get_lan_ip() -> ipaddress.IPv4Address | ipaddress.IPv6Address:
+    """
+    get IP address of currently used LAN interface
+    ref: https://stackoverflow.com/a/23822431
+    """
+
+    name = socket.gethostname()
+    host = socket.gethostbyname(name)
+
+    return ipaddress.ip_address(host)
+
+
+def address2net(
+    addr: ipaddress.IPv4Address | ipaddress.IPv6Address, mask: str = "24"
+) -> ipaddress.IPv4Network | ipaddress.IPv6Network:
+
+    if isinstance(addr, (ipaddress.IPv4Address, ipaddress.IPv6Address)):
+        return ipaddress.ip_network(f"{addr}/{mask}", strict=False)
+
+    raise TypeError(f"Unsupported address type: {type(addr).__name__} (value: {addr})")

findssh-2.1.0/src/findssh/__main__.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+scans IPv4 subnet for SSH servers on Port 22 or other server ports.
+Useful for machines that don't/can't have NMAP installed (e.g. Windows),
+  and device does not have Avahi server.
+I wanted to make it as cross-platform as possible,
+  where the user would have only basic Python installed (Windows)
+
+Note:
+timeout value bare minimum is 0.15 seconds for LAN,
+suggest using higher values say 0.25 or 0.35 to allow for network / CPU delays
+Wifi timeout should be 1 second or more
+"""
+
+import asyncio
+import logging
+import ipaddress as ip
+from argparse import ArgumentParser
+
+from . import get_lan_ip, address2net, discover_services
+from . import coro
+from . import threadpool
+
+PORT = 22
+TIMEOUT = 1.0
+
+# Default ports for known services
+DEFAULT_SERVICE_PORTS = {
+    "ssh": 22,
+    "http": 80,
+    "https": 443,
+    "dns": 53,
+}
+
+
+def parse_services(services_str: str) -> dict[str, int | list[int]]:
+    """
+    Parse service specification string.
+
+    Format: "service[:port[,port,...]]" (space-separated)
+    Examples:
+        "ssh" → {"ssh": 22}
+        "ssh:22" → {"ssh": 22}
+        "http:80,443" → {"http": [80, 443]}
+        "ssh http:80,443" → {"ssh": 22, "http": [80, 443]}
+        "ssh:2222 http:8080,8443" → {"ssh": 2222, "http": [8080, 8443]}
+    """
+    result: dict[str, int | list[int]] = {}
+
+    for spec in services_str.split():
+        if ":" in spec:
+            service_name, ports_str = spec.split(":", 1)
+            ports_list = [int(p.strip()) for p in ports_str.split(",")]
+            if len(ports_list) == 1:
+                result[service_name] = ports_list[0]
+            else:
+                result[service_name] = ports_list
+        else:
+            # Use default port for service
+            service_name = spec
+            if service_name in DEFAULT_SERVICE_PORTS:
+                result[service_name] = DEFAULT_SERVICE_PORTS[service_name]
+            else:
+                raise ValueError(
+                    f"Unknown service: {service_name}. Use service:port format."
+                )
+
+    if not result:
+        raise ValueError("No services specified")
+
+    return result
+
+
+def main():
+    p = ArgumentParser("scan for hosts with open port, without NMAP")
+
+    # Single port mode (original behavior)
+    p.add_argument("-p", "--port", help="single port to try", default=PORT, type=int)
+    p.add_argument(
+        "-s", "--service", default="", help="string to match to qualify detections"
+    )
+
+    # Multi-service mode (new feature)
+    p.add_argument(
+        "--services",
+        help=(
+            "discover multiple services. Format: 'service[:port[,port,...]]' (space-separated). "
+            "Examples: 'ssh', 'ssh http:80,443', 'ssh:2222 http:8080'. "
+            "Defaults: ssh=22, http=80, https=443, dns=53"
+        ),
+        type=str,
+        default="",
+    )
+
+    p.add_argument(
+        "-t",
+        "--timeout",
+        help="timeout to wait for server. Must be finite or will hang.",
+        type=float,
+        default=TIMEOUT,
+    )
+    p.add_argument("-b", "--baseip", help="set a specific subnet to scan")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument(
+        "-threadpool", help="use threadpool instead of asyncio", action="store_true"
+    )
+    P = p.parse_args()
+
+    ll = logging.DEBUG if P.verbose else logging.INFO
+    logging.basicConfig(level=ll)
+
+    if not P.baseip:
+        ownip = get_lan_ip()
+        print("own address", ownip)
+    else:
+        ownip = ip.ip_address(P.baseip)
+
+    net = address2net(ownip)
+    print("searching", net)
+
+    # Multi-service discovery mode
+    if P.services:
+        if P.threadpool:
+            print(
+                "Warning: threadpool not supported for multi-service discovery, using asyncio"
+            )
+
+        try:
+            service_ports = parse_services(P.services)
+        except ValueError as e:
+            print(f"Error parsing services: {e}")
+            return
+
+        print(f"discovering services: {', '.join(service_ports.keys())}")
+        results = asyncio.run(discover_services(net, service_ports, P.timeout))
+
+        # Display results
+        print()
+        for service_name in sorted(results.keys()):
+            hosts = results[service_name]
+            print(f"{service_name}:")
+            if hosts:
+                for host, banner in hosts:
+                    print(f"  {host}: {banner}")
+            else:
+                print("  (none found)")
+
+    # Original single-port mode
+    else:
+        if P.threadpool:
+            for host in threadpool.get_hosts(
+                net,
+                P.port,
+                P.timeout,
+                P.service,
+            ):
+                print(host)
+        else:
+            asyncio.run(coro.get_hosts(net, P.port, P.timeout, P.service))
+
+
+if __name__ == "__main__":
+    main()

{findssh-2.0.1 → findssh-2.1.0}/src/findssh/base.py

@@ -1,26 +1,31 @@
-from __future__ import annotations
 import ipaddress as ip
 import socket
-import typing as T
+import logging
+import collections.abc
 
+HostResult = tuple[ip.IPv4Address, str]
 
-def get_service(b: bytes, service: str | None = None) -> str:
+
+def get_service(b: bytes, service: str | None = None) -> str | None:
     """
     splitlines is in case the ASCII/UTF8 response is less than 32 bytes,
     hoping server sends a \r\n
     """
 
-    svc_txt = b.splitlines()[0].decode("utf-8", errors="ignore")
-    # %% optional service validation
-    if service and service not in svc_txt.lower():
-        return None
+    if lines := b.splitlines():
+        svc_txt = lines[0].decode("utf-8", errors="ignore")
+        # %% optional service validation
+        if service and service not in svc_txt.lower():
+            return None
+
+        return svc_txt
 
-    return svc_txt
+    return None
 
 
 def is_port_open(
     host: ip.IPv4Address, port: int, timeout: float, service: str | None = None
-) -> tuple[ip.IPv4Address, str]:
+) -> HostResult | None:
     """
     is a port open? Without coroutines.
     """
@@ -36,9 +41,12 @@ def is_port_open(
             return None
 
         try:
+            # If recv returns empty bytes, the connection was closed by the remote host.
+            # This does not necessarily mean the port is closed, but no service banner was received.
             if not (resp := s.recv(32)):
                 return None
-        except (socket.timeout, ConnectionError):
+        except (socket.timeout, ConnectionError) as err:
+            logging.debug("Socket error: %s", err)
             return None
 
     if svc_txt := get_service(resp, service):
@@ -49,9 +57,11 @@ def is_port_open(
 
 def get_hosts_seq(
     net: ip.IPv4Network, port: int, timeout: float, service: str | None = None
-) -> T.Iterable[tuple[ip.IPv4Address, str]]:
+) -> collections.abc.Iterable[HostResult]:
     """
-    find hosts sequentially (no parallelism or concurrency)
+    Yields hosts in the network that have the specified port open and
+    match the service (if provided),
+    sequentially (no parallelism or concurrency).
     """
 
     for host in net.hosts():

findssh-2.1.0/src/findssh/coro.py

@@ -0,0 +1,250 @@
+"""
+this method uses Python asyncio coroutines and is significantly faster and leaner,
+here using only ONE thread total, instead of the slower one-thread-per-address
+threadpool.py method
+"""
+
+import logging
+import ipaddress as ip
+import asyncio
+from collections.abc import Mapping
+
+from .base import HostResult, get_service
+from .http import is_http_response, get_http_service
+
+__all__ = ["get_hosts", "discover_services"]
+
+
+async def get_hosts(
+    net: ip.IPv4Network,
+    port: int,
+    timeout: float,
+    service: str | None = None,
+    max_concurrent: int = 100,
+) -> list[HostResult]:
+    """
+    Timeout must be finite otherwise non-existant hosts are waited for forever
+
+    use of Semaphore limits number of concurrent connections to avoid
+    overloading system with large nets
+    100 is a reasonable default for most systems
+    """
+
+    if max_concurrent < 1:
+        raise ValueError(f"max_concurrent must be >= 1, got {max_concurrent}")
+
+    hosts: list[HostResult] = []
+    host_queue: asyncio.Queue[ip.IPv4Address] = asyncio.Queue()
+    for host in net.hosts():
+        host_queue.put_nowait(host)
+
+    async def worker() -> None:
+        while True:
+            try:
+                host = host_queue.get_nowait()
+            except asyncio.QueueEmpty:
+                return
+
+            if result := await waiter(host, port, service, timeout):
+                logging.info("Found host: %s", result)
+                hosts.append(result)
+
+    worker_count = min(max_concurrent, max(1, host_queue.qsize()))
+    async with asyncio.TaskGroup() as tg:
+        for _ in range(worker_count):
+            tg.create_task(worker())
+
+    return hosts
+
+
+async def waiter(
+    host: ip.IPv4Address, port: int, service: str | None, timeout: float
+) -> HostResult | None:
+    try:
+        async with asyncio.timeout(timeout):
+            return await is_port_open(host, port, service)
+    except TimeoutError:
+        return None
+
+
+async def is_port_open(
+    host: ip.IPv4Address, port: int, service: str | None
+) -> HostResult | None:
+    """
+    https://docs.python.org/3/library/asyncio-stream.html#asyncio.open_connection
+    """
+    host_str = host.exploded
+
+    try:
+        reader, writer = await asyncio.open_connection(host_str, port)
+        if not (b := await reader.read(32)):
+            return None
+    except OSError as err:  # to avoid flake8 error OSError has ConnectionError
+        logging.debug("Error connecting to %s:%s - %s", host_str, port, err)
+        return None
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except (NameError, OSError):
+            pass
+
+    if svc_txt := get_service(b, service):
+        return host, svc_txt
+
+    return None
+
+
+async def discover_services(
+    net: ip.IPv4Network,
+    service_ports: Mapping[str, int | list[int]],
+    timeout: float,
+    max_concurrent: int = 100,
+) -> dict[str, list[HostResult]]:
+    """
+    Discover multiple services (e.g., SSH, HTTP) across a network in a single pass.
+
+    Scans a subnet for multiple services simultaneously, using a worker pool pattern
+    with asyncio.TaskGroup to efficiently parallelize connections across all hosts
+    and ports.
+
+    Args:
+        net: IPv4Network to scan (e.g., IPv4Network('192.168.1.0/24'))
+        service_ports: Mapping of service names to port(s)
+                      Examples:
+                        - {"ssh": 22, "http": 80}
+                        - {"ssh": 22, "http": [80, 443]}
+                        - {"dns": 53, "ssh": 22}
+        timeout: Connection timeout in seconds (must be finite)
+        max_concurrent: Maximum number of concurrent connections (default: 100)
+
+    Returns:
+        Dictionary mapping service names to lists of (IPv4Address, banner_text) tuples
+        Example: {
+            "ssh": [(IPv4Address('192.168.1.1'), 'OpenSSH_8.0...'), ...],
+            "http": [(IPv4Address('192.168.1.3'), 'HTTP/1.1 200 OK'), ...]
+        }
+
+    Raises:
+        ValueError: If max_concurrent < 1
+    """
+    if max_concurrent < 1:
+        raise ValueError(f"max_concurrent must be >= 1, got {max_concurrent}")
+
+    # Normalize service_ports to dict[service_name, list[int]]
+    normalized_ports: dict[str, list[int]] = {}
+    for service_name, ports in service_ports.items():
+        if isinstance(ports, int):
+            normalized_ports[service_name] = [ports]
+        elif isinstance(ports, list):
+            normalized_ports[service_name] = ports
+        else:
+            raise TypeError(
+                f"Port for service '{service_name}' must be int or list[int], "
+                f"got {type(ports).__name__}"
+            )
+
+    # Build work queue: (host, port, service_name) tuples
+    work_queue: asyncio.Queue[tuple[ip.IPv4Address, int, str]] = asyncio.Queue()
+    for host in net.hosts():
+        for service_name, ports in normalized_ports.items():
+            for port in ports:
+                work_queue.put_nowait((host, port, service_name))
+
+    # Results dict
+    results: dict[str, list[HostResult]] = {svc: [] for svc in normalized_ports}
+
+    async def worker() -> None:
+        """Worker coroutine: process work queue items until empty."""
+        while True:
+            try:
+                host, port, service_name = work_queue.get_nowait()
+            except asyncio.QueueEmpty:
+                return
+
+            if result := await discover_waiter(host, port, service_name, timeout):
+                logging.info("Found %s host: %s", service_name, result)
+                results[service_name].append(result)
+
+    # Calculate worker count based on queue size and max_concurrent
+    worker_count = min(max_concurrent, max(1, work_queue.qsize()))
+
+    # Run workers concurrently
+    async with asyncio.TaskGroup() as tg:
+        for _ in range(worker_count):
+            tg.create_task(worker())
+
+    return results
+
+
+async def discover_waiter(
+    host: ip.IPv4Address, port: int, service_name: str, timeout: float
+) -> HostResult | None:
+    """
+    Attempt to connect to a service on a host with timeout.
+
+    Routes service validation based on service type.
+    """
+    try:
+        async with asyncio.timeout(timeout):
+            return await discover_is_port_open(host, port, service_name)
+    except TimeoutError:
+        return None
+
+
+async def discover_is_port_open(
+    host: ip.IPv4Address, port: int, service_name: str
+) -> HostResult | None:
+    """
+    Check if a port is open and identify the service.
+
+    Routes to service-specific validators:
+    - "http": sends HTTP GET request, then validates response headers
+    - "ssh": expects SSH banner (service name validation)
+    - others: accepts any response as valid (generic port detection)
+    """
+    host_str = host.exploded
+
+    try:
+        reader, writer = await asyncio.open_connection(host_str, port)
+
+        # For HTTP, send a GET request; for others, just read the banner
+        if service_name.lower() == "http":
+            # Send minimal HTTP request to trigger server response
+            http_request = b"GET / HTTP/1.0\r\n\r\n"
+            writer.write(http_request)
+            await writer.drain()
+
+        if not (b := await reader.read(32)):
+            return None
+    except OSError as err:
+        logging.debug("Error connecting to %s:%s - %s", host_str, port, err)
+        return None
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except (NameError, OSError):
+            pass
+
+    # Route to service-specific validation
+    match service_name.lower():
+        case "http":
+            if is_http_response(b):
+                if svc_txt := get_http_service(b):
+                    return host, svc_txt
+        case "ssh":
+            # SSH service: validate "SSH-" banner
+            if svc_txt := get_service(b, "ssh"):
+                return host, svc_txt
+        case _:
+            # Generic service: accept any response
+            if b and len(b) > 0:
+                try:
+                    svc_txt = b.decode("utf-8", errors="ignore").splitlines()[0].strip()
+                    if svc_txt:
+                        return host, svc_txt
+                except Exception:
+                    pass
+
+    return None

findssh-2.1.0/src/findssh/http.py

@@ -0,0 +1,60 @@
+"""
+HTTP server detection utilities.
+
+Provides functions to identify and validate HTTP service responses.
+"""
+
+import logging
+
+
+def is_http_response(data: bytes) -> bool:
+    """
+    Check if response data contains an HTTP protocol indicator.
+
+    Validates that the response starts with "HTTP/" which indicates
+    a valid HTTP response (e.g., "HTTP/1.1 200 OK", "HTTP/1.0", etc.)
+
+    Args:
+        data: Raw bytes received from the server
+
+    Returns:
+        True if data appears to be an HTTP response, False otherwise
+    """
+    if not data:
+        return False
+
+    try:
+        # Try to decode the first line
+        lines = data.splitlines()
+        if not lines:
+            return False
+
+        first_line = lines[0].decode("utf-8", errors="ignore").strip()
+        return first_line.startswith("HTTP/")
+    except Exception as err:
+        logging.debug("Error checking HTTP response: %s", err)
+        return False
+
+
+def get_http_service(b: bytes) -> str | None:
+    """
+    Extract HTTP service banner/response from bytes.
+
+    Returns the first line of the HTTP response, which typically contains
+    the protocol version and status code (e.g., "HTTP/1.1 200 OK").
+
+    Args:
+        b: Raw bytes received from HTTP server
+
+    Returns:
+        First line of HTTP response if valid, None otherwise
+    """
+    if lines := b.splitlines():
+        try:
+            svc_txt = lines[0].decode("utf-8", errors="ignore").strip()
+            if svc_txt.startswith("HTTP/"):
+                return svc_txt
+        except Exception:
+            pass
+
+    return None

findssh-2.1.0/src/findssh/tests/conftest.py

@@ -0,0 +1,84 @@
+import pytest
+import pytest_asyncio
+import asyncio
+import socket
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import threading
+
+
+@pytest.fixture
+def http_server_port():
+    """Get an available port for test server."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture
+def mock_http_server(http_server_port):
+    """Start a simple HTTP server for testing."""
+
+    class SimpleHTTPHandler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            self.send_response(200)
+            self.send_header("Content-Length", "13")
+            self.end_headers()
+            self.wfile.write(b"Test response")
+
+        def log_message(self, format, *args):
+            pass  # Suppress logging
+
+    server = HTTPServer(("127.0.0.1", http_server_port), SimpleHTTPHandler)
+    thread = threading.Thread(target=server.serve_forever)
+    thread.daemon = True
+    thread.start()
+
+    yield http_server_port
+
+    server.shutdown()
+
+
+@pytest_asyncio.fixture
+async def mock_http_server_async(http_server_port):
+    """Async mock HTTP server using asyncio (alternative implementation)."""
+
+    async def handle_http(reader, writer):
+        """Handle HTTP connection by sending a response."""
+        # Read the request (we don't need to parse it, just consume it)
+        try:
+            await reader.readuntil(b"\r\n\r\n")
+        except asyncio.IncompleteReadError:
+            pass
+        except Exception:
+            pass
+
+        # Send HTTP response
+        response = b"HTTP/1.1 200 OK\r\nContent-Length: 13\r\n\r\nTest response"
+        writer.write(response)
+        await writer.drain()
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+    server = await asyncio.start_server(handle_http, "127.0.0.1", http_server_port)
+
+    async def serve():
+        async with server:
+            await server.serve_forever()
+
+    task = asyncio.create_task(serve())
+
+    yield http_server_port
+
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+    server.close()
+    try:
+        await server.wait_closed()
+    except Exception:
+        pass

findssh-2.1.0/src/findssh/tests/test_discovery.py

@@ -0,0 +1,134 @@
+import pytest
+import ipaddress
+import asyncio
+import findssh
+import findssh.coro
+
+TIMEOUT = 0.5
+
+
+@pytest.mark.asyncio
+async def test_discover_services_validation():
+    """Test discover_services parameter validation."""
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+
+    # Test max_concurrent validation
+    with pytest.raises(ValueError):
+        await findssh.coro.discover_services(
+            net, {"ssh": 22}, TIMEOUT, max_concurrent=0
+        )
+
+    # Test invalid port type
+    with pytest.raises(TypeError):
+        await findssh.coro.discover_services(
+            net,
+            {"ssh": "invalid"},
+            TIMEOUT,  # type: ignore
+        )
+
+
+@pytest.mark.asyncio
+async def test_discover_services_port_list():
+    """Test discover_services with port as list."""
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+
+    # Test with list of ports
+    results = await findssh.coro.discover_services(
+        net, {"http": [80, 443]}, TIMEOUT, max_concurrent=10
+    )
+
+    assert isinstance(results, dict)
+    assert "http" in results
+    assert isinstance(results["http"], list)
+
+
+@pytest.mark.asyncio
+async def test_discover_services_http_detection(mock_http_server):
+    """Test HTTP service detection with working mock HTTP server."""
+    port = mock_http_server
+
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+    results = await findssh.coro.discover_services(
+        net, {"http": port}, timeout=1.0, max_concurrent=10
+    )
+
+    assert isinstance(results, dict)
+    assert "http" in results
+    assert isinstance(results["http"], list)
+
+    # With the fixed HTTP detection (sending GET request), we should find the server
+    assert len(results["http"]) > 0, "HTTP server should be detected"
+
+    # Verify the response format
+    host, banner = results["http"][0]
+    assert isinstance(host, ipaddress.IPv4Address)
+    assert isinstance(banner, str)
+    assert "HTTP" in banner
+    assert "200" in banner
+
+
+@pytest.mark.asyncio
+async def test_discover_services_http_detection_async(mock_http_server_async):
+    """Test HTTP service detection with async mock HTTP server."""
+    port = mock_http_server_async
+
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+    results = await findssh.coro.discover_services(
+        net, {"http": port}, timeout=1.0, max_concurrent=10
+    )
+
+    assert isinstance(results, dict)
+    assert "http" in results
+    assert isinstance(results["http"], list)
+
+    # Should detect the async HTTP server
+    assert len(results["http"]) > 0, "Async HTTP server should be detected"
+
+    host, banner = results["http"][0]
+    assert isinstance(host, ipaddress.IPv4Address)
+    assert "HTTP" in banner
+
+
+def test_discover_services_multiple_services():
+    """Test discover_services returns dict structure for multiple services."""
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+
+    results = asyncio.run(
+        findssh.coro.discover_services(
+            net, {"ssh": 22, "http": 80}, TIMEOUT, max_concurrent=10
+        )
+    )
+
+    # Verify structure
+    assert isinstance(results, dict)
+    assert set(results.keys()) == {"ssh", "http"}
+    assert isinstance(results["ssh"], list)
+    assert isinstance(results["http"], list)
+
+    # Verify each result in lists has correct structure
+    for service_name, hosts in results.items():
+        for host, banner in hosts:
+            assert isinstance(host, ipaddress.IPv4Address)
+            assert isinstance(banner, str)
+
+
+def test_discover_services_structure():
+    """Test that discover_services returns correct structure for empty results."""
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+
+    # Test multiple services on ports that likely have nothing
+    results = asyncio.run(
+        findssh.coro.discover_services(
+            net,
+            {"service1": 9999, "service2": 9998, "service3": 9997},
+            timeout=0.1,
+            max_concurrent=10,
+        )
+    )
+
+    # Verify structure even with empty results
+    assert isinstance(results, dict)
+    assert "service1" in results
+    assert "service2" in results
+    assert "service3" in results
+    assert all(isinstance(v, list) for v in results.values())

findssh-2.0.1/src/findssh/tests/test_coro.py → findssh-2.1.0/src/findssh/tests/test_ssh_coroutine.py

@@ -1,5 +1,6 @@
 import ipaddress
 import asyncio
+import pytest
 
 import findssh
 import findssh.coro
@@ -15,3 +16,9 @@ def test_coroutine():
         assert isinstance(host, ipaddress.IPv4Address)
         assert isinstance(svc, str)
         break
+
+
+def test_coroutine_max_concurrent_validation():
+    net = ipaddress.ip_network("127.0.0.1/32", strict=False)
+    with pytest.raises(ValueError):
+        asyncio.run(findssh.coro.get_hosts(net, PORT, TIMEOUT, max_concurrent=0))

findssh-2.0.1/src/findssh/tests/test_threadpool.py → findssh-2.1.0/src/findssh/tests/test_ssh_threadpool.py

@@ -1,6 +1,7 @@
 """
 normally we use coroutines, but for demo purposes we have threadpool too.
 """
+
 import ipaddress
 
 import findssh.threadpool

{findssh-2.0.1 → findssh-2.1.0}/src/findssh/threadpool.py

@@ -4,12 +4,12 @@ significantly slower and uses more resources
 than the recommended asyncio coroutines in coro.py
 """
 
-from __future__ import annotations
 import concurrent.futures
+import logging
 import ipaddress as ip
-import typing as T
+from collections.abc import Iterable
 
-from .base import is_port_open
+from .base import HostResult, is_port_open
 
 __all__ = ["get_hosts"]
 
@@ -19,7 +19,7 @@ def get_hosts(
     port: int,
     timeout: float,
     service: str | None = None,
-) -> T.Iterable[tuple[ip.IPv4Address, str]]:
+) -> Iterable[HostResult]:
     """
     loops over hosts in network, one thread per address.
     This is MUCH slower than asyncio coroutines in coro.py
@@ -37,5 +37,7 @@ def get_hosts(
                 if res := future.result():
                     yield res
         except KeyboardInterrupt:
-            print("KeyboardInterrupt")
+            logging.info("KeyboardInterrupt")
+            # the shutdown() is necessary to immediately halt threads, otherwise the
+            # futures are still waited on
             exc.shutdown(wait=True, cancel_futures=True)

{findssh-2.0.1 → findssh-2.1.0/src/findssh.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: findssh
-Version: 2.0.1
+Version: 2.1.0
 Summary: find open servers on IPv4 subnet such as SSH
 Keywords: port-scan,ssh
 Classifier: Development Status :: 5 - Production/Stable
@@ -18,29 +18,28 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Security
 Classifier: Topic :: System :: Networking
 Classifier: Topic :: Utilities
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
-Provides-Extra: lint
-Requires-Dist: flake8; extra == "lint"
-Requires-Dist: flake8-bugbear; extra == "lint"
-Requires-Dist: flake8-builtins; extra == "lint"
-Requires-Dist: flake8-blind-except; extra == "lint"
-Requires-Dist: mypy; extra == "lint"
+Requires-Dist: pytest-asyncio; extra == "tests"
+Requires-Dist: mypy; extra == "tests"
+Dynamic: license-file
 
 # Find SSH servers (without NMAP)
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3336467.svg)](https://doi.org/10.5281/zenodo.3336467)
-![ci](https://github.com/scivision/findssh/workflows/ci/badge.svg)
-[![PyPI Download stats](http://pepy.tech/badge/findssh)](http://pepy.tech/project/findssh)
+[![ci](https://github.com/scivision/findssh/actions/workflows/ci.yml/badge.svg)](https://github.com/scivision/findssh/actions/workflows/ci.yml)
+[![PyPI Download stats](https://pepy.tech/badge/findssh)](https://pepy.tech/project/findssh)
 
 Platform-independently find SSH servers (or other services with open ports) on an IPv4 subnet in pure Python WITHOUT NMAP.
 Scan entire IPv4 subnet in less than 1 second using Python standard library `asyncio`  coroutines and a single thread.
 
-The default
-[asyncio coroutine](https://docs.python.org/3/library/asyncio.html)
+The findssh
+[asyncio](https://docs.python.org/3/library/asyncio.html)
+coroutine
+[TaskGroup](https://docs.python.org/3/library/asyncio-task.html#task-groups)
 uses a single thread and is more than 10x faster than
 [concurrent.futures.ThreadPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html).
 
@@ -55,7 +54,7 @@ or from this repo:
 ```sh
 git clone https://github.com/scivision/findssh
 
-pip install -e findssh
+pip install -e ./findssh
 ```
 
 ## Usage
@@ -76,6 +75,12 @@ or use project script e.g. from [pipx](https://github.com/pypa/pipx):
 findssh
 ```
 
+For example, to scan your local subnet for SSH servers:
+
+```sh
+findssh -p 22 192.168.1.0
+```
+
 * `-s`  check the string from the server to attempt to verify the correct service has been found
 * `-t` timeout per server (seconds)  useful for high latency connection
 * `-b` baseip (check other subnet besides your own)

{findssh-2.0.1 → findssh-2.1.0}/src/findssh.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/findssh/__init__.py
 src/findssh/__main__.py
 src/findssh/base.py
 src/findssh/coro.py
+src/findssh/http.py
 src/findssh/threadpool.py
 src/findssh.egg-info/PKG-INFO
 src/findssh.egg-info/SOURCES.txt
@@ -13,5 +14,7 @@ src/findssh.egg-info/entry_points.txt
 src/findssh.egg-info/requires.txt
 src/findssh.egg-info/top_level.txt
 src/findssh/tests/__init__.py
-src/findssh/tests/test_coro.py
-src/findssh/tests/test_threadpool.py
+src/findssh/tests/conftest.py
+src/findssh/tests/test_discovery.py
+src/findssh/tests/test_ssh_coroutine.py
+src/findssh/tests/test_ssh_threadpool.py

findssh-2.1.0/src/findssh.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[tests]
+pytest
+pytest-asyncio
+mypy

findssh-2.0.1/src/findssh/__init__.py

@@ -1,34 +0,0 @@
-from __future__ import annotations
-import socket
-import ipaddress
-
-from .coro import get_hosts
-
-__all__ = ["get_hosts", "address2net", "get_lan_ip"]
-
-__version__ = "2.0.1"
-
-
-def get_lan_ip() -> ipaddress.IPv4Address | ipaddress.IPv6Address:
-    """
-    get IP address of currently used LAN interface
-    ref: http://stackoverflow.com/a/23822431
-    """
-
-    name = socket.gethostname()
-    host = socket.gethostbyname(name)
-    return ipaddress.ip_address(host)
-
-
-def address2net(
-    addr: ipaddress.IPv4Address, mask: str = "24"
-) -> ipaddress.IPv4Network | ipaddress.IPv6Network:
-
-    if isinstance(addr, ipaddress.IPv4Address):
-        net = ipaddress.ip_network(addr.exploded.rsplit(".", 1)[0] + f".0/{mask}")
-    elif isinstance(addr, ipaddress.IPv6Address):
-        net = ipaddress.ip_network(addr.exploded.rsplit(":", 1)[0] + f":0/{mask}")
-    else:
-        raise TypeError(addr)
-
-    return net

findssh-2.0.1/src/findssh/__main__.py

@@ -1,73 +0,0 @@
-#!/usr/bin/env python3
-"""
-scans IPv4 subnet for SSH servers on Port 22 or other server ports.
-Useful for machines that don't/can't have NMAP installed (e.g. Windows),
-  and device does not have Avahi server.
-I wanted to make it as cross-platform as possible,
-  where the user would have only basic Python installed (Windows)
-
-Note:
-timeout value bare minimum is 0.15 seconds for LAN,
-suggest using higher values say 0.25 or 0.35 to allow for network / CPU delays
-Wifi timeout should be 1 second or more
-"""
-
-import asyncio
-import logging
-import ipaddress as ip
-from argparse import ArgumentParser
-
-from . import get_lan_ip, address2net
-from . import coro
-from . import threadpool
-
-PORT = 22
-TIMEOUT = 1.0
-
-
-def main():
-    p = ArgumentParser("scan for hosts with open port, without NMAP")
-    p.add_argument("-p", "--port", help="single port to try", default=PORT, type=int)
-    p.add_argument(
-        "-s", "--service", default="", help="string to match to qualify detections"
-    )
-    p.add_argument(
-        "-t",
-        "--timeout",
-        help="timeout to wait for server. Must be finite or will hang.",
-        type=float,
-        default=TIMEOUT,
-    )
-    p.add_argument("-b", "--baseip", help="set a specific subnet to scan")
-    p.add_argument("-v", "--verbose", action="store_true")
-    p.add_argument(
-        "-threadpool", help="use threadpool instead of asyncio", action="store_true"
-    )
-    P = p.parse_args()
-
-    if P.verbose:
-        logging.basicConfig(level=logging.DEBUG)
-
-    if not P.baseip:
-        ownip = get_lan_ip()
-        print("own address", ownip)
-    else:
-        ownip = ip.ip_address(P.baseip)
-
-    net = address2net(ownip)
-    print("searching", net)
-
-    if P.threadpool:
-        for host in threadpool.get_hosts(
-            net,
-            P.port,
-            P.timeout,
-            P.service,
-        ):
-            print(host)
-    else:
-        asyncio.run(coro.get_hosts(net, P.port, P.timeout, P.service))
-
-
-if __name__ == "__main__":
-    main()

findssh-2.0.1/src/findssh/coro.py

@@ -1,67 +0,0 @@
-"""
-this method uses Python asyncio coroutines and is significantly faster and leaner,
-here using only ONE thread total, instead of the slower one-thread-per-address
-threadpool.py method
-"""
-
-from __future__ import annotations
-import logging
-import ipaddress as ip
-import asyncio
-
-from .base import get_service
-
-__all__ = ["get_hosts"]
-
-
-async def get_hosts(
-    net: ip.IPv4Network,
-    port: int,
-    timeout: float,
-    service: str | None = None,
-) -> list[tuple[ip.IPv4Address, str]]:
-    """
-    Timeout must be finite otherwise non-existant hosts are waited for forever
-    """
-
-    hosts = []
-    futures = [waiter(host, port, service, timeout) for host in net.hosts()]
-    for h in asyncio.as_completed(futures):
-        if host := await h:
-            print(host)
-            hosts.append(host)
-
-    return hosts
-
-
-async def waiter(
-    host: ip.IPv4Address, port: int, service: str, timeout: float
-) -> tuple[ip.IPv4Address, str]:
-    try:
-        res = await asyncio.wait_for(is_port_open(host, port, service), timeout=timeout)
-    except asyncio.TimeoutError:
-        res = None
-
-    return res
-
-
-async def is_port_open(
-    host: ip.IPv4Address, port: int, service: str
-) -> tuple[ip.IPv4Address, str]:
-    """
-    https://docs.python.org/3/library/asyncio-stream.html#asyncio.open_connection
-    """
-    host_str = host.exploded
-
-    try:
-        reader, _ = await asyncio.open_connection(host_str, port)
-        if not (b := await reader.read(32)):
-            return None
-    except OSError as err:  # to avoid flake8 error OSError has ConnectionError
-        logging.debug(err)
-        return None
-
-    if svc_txt := get_service(b, service):
-        return host, svc_txt
-
-    return None

findssh-2.0.1/src/findssh.egg-info/requires.txt

@@ -1,10 +0,0 @@
-
-[lint]
-flake8
-flake8-bugbear
-flake8-builtins
-flake8-blind-except
-mypy
-
-[tests]
-pytest