findssh 2.0.0__tar.gz → 2.1.0__tar.gz

{findssh-2.0.0/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.0
+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,23 +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
-Provides-Extra: tests
-Provides-Extra: lint
 License-File: LICENSE.txt
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+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).
 
@@ -49,7 +54,7 @@ or from this repo:
 ```sh
 git clone https://github.com/scivision/findssh
 
-pip install -e findssh
+pip install -e ./findssh
 ```
 
 ## Usage
@@ -64,6 +69,18 @@ from command line:
 python -m findssh
 ```
 
+or use project script e.g. from [pipx](https://github.com/pypa/pipx):
+
+```sh
+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)
@@ -88,3 +105,11 @@ Thread pool (100 thread max, slow, heavy):
 
 1.39 s ± 213 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
 ```
+
+Trying to open too many threads via ThreadPoolExecutor can cause a system error like
+
+```
+OSError: [Errno 24] Too many open files
+```
+
+Thus in practical terms, using coroutines can be significantly faster than threads while using less system resources.

{findssh-2.0.0 → 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
@@ -38,6 +40,18 @@ from command line:
 python -m findssh
 ```
 
+or use project script e.g. from [pipx](https://github.com/pypa/pipx):
+
+```sh
+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)
@@ -62,3 +76,11 @@ Thread pool (100 thread max, slow, heavy):
 
 1.39 s ± 213 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
 ```
+
+Trying to open too many threads via ThreadPoolExecutor can cause a system error like
+
+```
+OSError: [Errno 24] Too many open files
+```
+
+Thus in practical terms, using coroutines can be significantly faster than threads while using less system resources.

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

@@ -4,7 +4,6 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "findssh"
-version = "2.0.0"
 description = "find open servers on IPv4 subnet such as SSH"
 keywords = ["port-scan", "ssh"]
 classifiers = [
@@ -24,22 +23,23 @@ classifiers = [
   "Topic :: System :: Networking",
   "Topic :: Utilities"
 ]
-dynamic = ["readme"]
-requires-python = ">=3.9"
+dynamic = ["readme", "version"]
+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"}
+version = {attr = "findssh.__version__"}
 
 [tool.black]
 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.0 → 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():