modscanner 0.1.0__tar.gz

modscanner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davis Onyeoguzoro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modscanner-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: modscanner
+Version: 0.1.0
+Summary: A safety-first Modbus discovery and register inspection toolkit.
+Author: Davis Onyeoguzoro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/davisonyeas/modscanner
+Project-URL: Documentation, https://davisonyeas.github.io/modscanner/
+Project-URL: Repository, https://github.com/davisonyeas/modscanner
+Project-URL: Issues, https://github.com/davisonyeas/modscanner/issues
+Project-URL: Changelog, https://github.com/davisonyeas/modscanner/blob/master/CHANGELOG.md
+Keywords: modbus,modbus-tcp,modbus-rtu,industrial-automation,plc,scada
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymodbus<3.15,>=3.14
+Requires-Dist: rich<15,>=13
+Requires-Dist: typer<1,>=0.12
+Dynamic: license-file
+
+# ModScanner
+
+A safety-first Modbus scanning toolkit for Python.
+
+ModScanner helps engineers inspect Modbus devices without immediately falling back to slow, one-register-at-a-time scanning. It reads registers in blocks and adaptively splits rejected blocks to identify valid and invalid addresses.
+
+> **Project status:** 
+Early development. Version 0.1.0 supports only 
+> **Modbus TCP holding register scanning. 
+
+## Features 
+
+- Read-only Modbus TCP scanning
+- Holding register reads using function code 03
+- Configurable device ID, port, timeout, range, and block size
+- Adaptive block splitting when a device rejects a register range
+- Seperation of protocol errors, transport errors, and invalid responses
+- Terminal output using Rich
+- Typed Python data module
+- Transport abstraction that is built untop of PyModbus
+- Unit tested scanning behavior
+
+## Installation
+
+Install ModScanner from PyPI using either of two(2) methods the below:
+
+1. Install ModScanner from PyPI:
+
+```bash
+pip install modscanner
+```
+
+2. Using uv:
+
+```bash
+uv add modscanner
+```
+
+Verify the installation using:
+```bash
+modscanner --help
+or
+modscanner --h
+or 
+modscanner version
+```
+
+> **The above help shows the commands available, while the version shows the current version you have installd on your machine**
+
+## Quick start
+
+There are different ways to use the library;
+
+1. Scan holding registers `0` through `19` on a Modbus TCP device using the below:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --device-id 1 --start 0 --count 20
+```
+
+> **The above expects you to use the IP Address of the Modbus device, so replace the 192.168.1.10 with your Modbus device**
+
+2. Specify the TCP port, timeout, and request block size using:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --port 502 --device-id 1 --start 0 --count 100 --block-size 50 --timeout 2
+```
+
+Run:
+```bash
+modscanner scan-tcp --help
+```
+
+to see all available options.
+
+## Addressing
+
+ModScanner uses zero-based Modbus protocol addresses.
+
+For example, a vendor document may label the first holding register as `40001`, while its protocol address is commonly `0`.
+
+Always confirm how the device manufacturer represents register addresses before scanning.
+
+## Adaptive scanning
+
+Some Modbus devices reject an entire request when only one address is within the requested block is invalid.
+
+ModScanner handles this by:
+1. Reading a block of registers.
+2. Accepting the block when the response is valid.
+3. Splitting a block when the device return a protocol-level error.
+4. Continuing until individual valid and invalid addresses are identified.
+5. Avoiding recursive requests after transport failure such as timeouts.
+
+This reduces unnecessary requests while stil supporting sparse register maps.
+
+## Safety
+
+ModScanner 0.1.0 is read-only.
+
+It does not write coils or registers. Future write-validation functionality will require explicit register allowlists, value limits, confirmation, readback, and audit logging.
+
+Read-only registers should also be used carefully on production systems. Confirm the target IP address, port, device ID, and permitted register range before scanning industrial equipments.
+
+## Current limitation
+
+Version 0.1.0 does not yet support:
+
+- Modbus RTU
+- Coils
+- Discrete inputs
+- Input registers
+- Automatic device ID discovery
+- JSON, CSV, or YAML exports
+- Data type decoding
+- Byte-order or word-order conversion
+- Device profiles
+- Register monitoring
+- Register writes
+- Writable-register validation
+
+> **All the above are planned for future releasesa**
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## Security
+
+Do not use ModScanner to perform unauthorized scanning or testing.
+
+## Author
+Developed by [Davis Onyeoguzoro](https://github.com/davisonyeas)

modscanner-0.1.0/README.md

@@ -0,0 +1,130 @@
+# ModScanner
+
+A safety-first Modbus scanning toolkit for Python.
+
+ModScanner helps engineers inspect Modbus devices without immediately falling back to slow, one-register-at-a-time scanning. It reads registers in blocks and adaptively splits rejected blocks to identify valid and invalid addresses.
+
+> **Project status:** 
+Early development. Version 0.1.0 supports only 
+> **Modbus TCP holding register scanning. 
+
+## Features 
+
+- Read-only Modbus TCP scanning
+- Holding register reads using function code 03
+- Configurable device ID, port, timeout, range, and block size
+- Adaptive block splitting when a device rejects a register range
+- Seperation of protocol errors, transport errors, and invalid responses
+- Terminal output using Rich
+- Typed Python data module
+- Transport abstraction that is built untop of PyModbus
+- Unit tested scanning behavior
+
+## Installation
+
+Install ModScanner from PyPI using either of two(2) methods the below:
+
+1. Install ModScanner from PyPI:
+
+```bash
+pip install modscanner
+```
+
+2. Using uv:
+
+```bash
+uv add modscanner
+```
+
+Verify the installation using:
+```bash
+modscanner --help
+or
+modscanner --h
+or 
+modscanner version
+```
+
+> **The above help shows the commands available, while the version shows the current version you have installd on your machine**
+
+## Quick start
+
+There are different ways to use the library;
+
+1. Scan holding registers `0` through `19` on a Modbus TCP device using the below:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --device-id 1 --start 0 --count 20
+```
+
+> **The above expects you to use the IP Address of the Modbus device, so replace the 192.168.1.10 with your Modbus device**
+
+2. Specify the TCP port, timeout, and request block size using:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --port 502 --device-id 1 --start 0 --count 100 --block-size 50 --timeout 2
+```
+
+Run:
+```bash
+modscanner scan-tcp --help
+```
+
+to see all available options.
+
+## Addressing
+
+ModScanner uses zero-based Modbus protocol addresses.
+
+For example, a vendor document may label the first holding register as `40001`, while its protocol address is commonly `0`.
+
+Always confirm how the device manufacturer represents register addresses before scanning.
+
+## Adaptive scanning
+
+Some Modbus devices reject an entire request when only one address is within the requested block is invalid.
+
+ModScanner handles this by:
+1. Reading a block of registers.
+2. Accepting the block when the response is valid.
+3. Splitting a block when the device return a protocol-level error.
+4. Continuing until individual valid and invalid addresses are identified.
+5. Avoiding recursive requests after transport failure such as timeouts.
+
+This reduces unnecessary requests while stil supporting sparse register maps.
+
+## Safety
+
+ModScanner 0.1.0 is read-only.
+
+It does not write coils or registers. Future write-validation functionality will require explicit register allowlists, value limits, confirmation, readback, and audit logging.
+
+Read-only registers should also be used carefully on production systems. Confirm the target IP address, port, device ID, and permitted register range before scanning industrial equipments.
+
+## Current limitation
+
+Version 0.1.0 does not yet support:
+
+- Modbus RTU
+- Coils
+- Discrete inputs
+- Input registers
+- Automatic device ID discovery
+- JSON, CSV, or YAML exports
+- Data type decoding
+- Byte-order or word-order conversion
+- Device profiles
+- Register monitoring
+- Register writes
+- Writable-register validation
+
+> **All the above are planned for future releasesa**
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## Security
+
+Do not use ModScanner to perform unauthorized scanning or testing.
+
+## Author
+Developed by [Davis Onyeoguzoro](https://github.com/davisonyeas)

modscanner-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "modscanner"
+version = "0.1.0"
+description = "A safety-first Modbus discovery and register inspection toolkit."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+
+authors = [
+    { name = "Davis Onyeoguzoro" },
+]
+
+keywords = [
+    "modbus",
+    "modbus-tcp",
+    "modbus-rtu",
+    "industrial-automation",
+    "plc",
+    "scada",
+]
+
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Manufacturing",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "pymodbus>=3.14,<3.15",
+    "rich>=13,<15",
+    "typer>=0.12,<1",
+]
+
+
+[project.scripts]
+modscanner = "modscanner.cli:app"
+
+
+[project.urls]
+Homepage = "https://github.com/davisonyeas/modscanner"
+Documentation = "https://davisonyeas.github.io/modscanner/"
+Repository = "https://github.com/davisonyeas/modscanner"
+Issues = "https://github.com/davisonyeas/modscanner/issues"
+Changelog = "https://github.com/davisonyeas/modscanner/blob/master/CHANGELOG.md"
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+[tool.setuptools.package-data]
+modscanner = ["py.typed"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.22",
+    "twine>=6.2.0",
+]

modscanner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

modscanner-0.1.0/src/modscanner/__init__.py

@@ -0,0 +1,30 @@
+"""modScanner public package interface"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+
+from modscanner.models import (
+    RegisterArea,
+    RegisterResult,
+    ResultStatus,
+    ScanPlan,
+    ScanReport,
+    TcpTarget,
+)
+from modscanner.scanner import Scanner
+
+try:
+    __version__ = version("modscanner")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "RegisterArea",
+    "RegisterResult",
+    "ResultStatus",
+    "ScanPlan",
+    "ScanReport",
+    "Scanner",
+    "TcpTarget",
+    "__version__",
+]

modscanner-0.1.0/src/modscanner/cli.py

@@ -0,0 +1,118 @@
+"""command-line interface for ModScanner"""
+
+import typer
+from rich.console import Console
+from modscanner.exceptions import ModScannerConnectionError
+from modscanner.models import ScanPlan, TcpTarget
+from modscanner.reporters.console import render_report
+from modscanner.scanner import Scanner
+from modscanner.transports.pymodbus_transport import (
+    PymodbusTcpTransport,
+)
+
+app = typer.Typer(
+    name="modscanner",
+    help="safely discover and inspect Modbus devices via RTU and TCP.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["--help", "--h", "-help", "--h"]},
+)
+
+console = Console()
+
+
+@app.command("scan-tcp")
+def scan_tcp(
+    host: str = typer.Argument(
+        ...,
+        help="hostname or IP address of the Modbus TCP device.",
+    ),
+    start: int = typer.Option(
+        0,
+        "--start",
+        "-s",
+        min=0,
+        max=65_535,
+        help="zero-based starting register address.",
+    ),
+    count: int = typer.Option(
+        10,
+        "--count",
+        "-c",
+        min=1,
+        max=65_536,
+        help="number of registers to scan.",
+    ),
+    device_id: int = typer.Option(
+        1,
+        "--device-id",
+        "-d",
+        min=1,
+        max=247,
+        help="Modbus device identifier.",
+    ),
+    port: int = typer.Option(
+        502,
+        "--port",
+        "-p",
+        min=1,
+        max=65_535,
+        help="Modbus TCP port.",
+    ),
+    timeout: float = typer.Option(
+        3.0,
+        "--timeout",
+        min=0.1,
+        help="Request timeout in seconds.",
+    ),
+    block_size: int = typer.Option(
+        125,
+        "--block-size",
+        min=1,
+        max=125,
+        help="maximum registers requested per block.",
+    ),
+) -> None:
+    """scan a range of Modbus TCP holding registers."""
+
+    try:
+        target = TcpTarget(
+            host=host,
+            port=port,
+            device_id=device_id,
+            timeout=timeout,
+        )
+
+        plan = ScanPlan(
+            start=start,
+            count=count,
+            block_size=block_size,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    transport = PymodbusTcpTransport(target)
+    scanner = Scanner(transport, target)
+
+    try:
+        transport.connect()
+        report = scanner.scan_holding_registers(plan)
+    except ModScannerConnectionError as exc:
+        console.print(f"Connection failed: {exc}")
+        raise typer.Exit(code=2) from exc
+    finally:
+        transport.close()
+
+    render_report(report, console)
+
+
+@app.command()
+def version() -> None:
+    """display the installed ModScanner version"""
+
+    from modscanner import __version__
+
+    console.print(f"modscanner {__version__}")
+
+
+if __name__ == "__main__":
+    app()

modscanner-0.1.0/src/modscanner/exceptions.py

@@ -0,0 +1,9 @@
+"""exceptions raised by modscanne"""
+
+
+class ModScannerError(Exception):
+    """base exception fpr all modscanner errors"""
+
+
+class ModScannerConnectionError(Exception):
+    """raised when a Modbus connection cannot be establised"""

modscanner-0.1.0/src/modscanner/models.py

@@ -0,0 +1,100 @@
+"""core data models used by modscanner"""
+
+from enum import StrEnum
+from dataclasses import dataclass
+
+
+class RegisterArea(StrEnum):
+    """supported modbus data areas"""
+
+    COIL = "coil"
+    DISCRETE_INPUT = "discrete_input"
+    INPUT_REGISTER = "input_register"
+    HOLDING_REGISTER = "holding_register"
+
+
+class ResultStatus(StrEnum):
+    """outcome  of reading individual modbus addresss"""
+
+    OK = "ok"
+    PROTOCOL_ERROR = "protocol_error"
+    TRANSPORT_ERROR = "transport_error"
+    INVALID_RESPONSE = "invalid_response"
+
+
+@dataclass(frozen=True, slots=True)
+class TcpTarget:
+    """commection information for a modbus tcp device"""
+
+    host: str
+    port: int = 502
+    device_id: int = 1
+    timeout: float = 3.0
+
+    def post_init__(self) -> None:
+        if not self.host.strip():
+            raise ValueError("host cannot be empty")
+
+        if not 1 <= self.port <= 65_535:
+            raise ValueError("port must be between 1 and 65535")
+
+        if not 1 <= self.device_id <= 247:
+            raise ValueError("device_id must be between 1 and 247")
+
+        if self.timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+
+@dataclass(frozen=True, slots=True)
+class ScanPlan:
+    """description og contiguous holding register scan"""
+
+    start: int
+    count: int
+    block_size: int = 125
+    area: RegisterArea = RegisterArea.HOLDING_REGISTER
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.start <= 65_535:
+            raise ValueError("start must be between 0 and 65535")
+
+        if self.count < 1:
+            raise ValueError("count must be atleast 1")
+
+        if self.start + self.count > 65_536:
+            raise ValueError("the requested address range exceeeds 65535")
+
+        if not 1 <= self.block_size <= 125:
+            raise ValueError("block size must be between 1 and 125")
+
+
+@dataclass(frozen=True, slots=True)
+class RegisterResult:
+    """result for one scanned Modbus register"""
+
+    address: int
+    area: RegisterArea
+    status: ResultStatus
+    value: int | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScanReport:
+    """complete result of a Modbus register scan"""
+
+    target: TcpTarget
+    plan: ScanPlan
+    results: tuple[RegisterResult, ...]
+
+    @property
+    def successful_count(self) -> int:
+        """return the number of successfully read registers"""
+
+        return sum(result.status is ResultStatus.OK for result in self.results)
+
+    @property
+    def failed_count(self) -> int:
+        """return the number of registers that could not be read"""
+
+        return len(self.results) - self.successful_count

modscanner-0.1.0/src/modscanner/reporters/console.py

@@ -0,0 +1,40 @@
+"""rich terminal output for ModScanner reports"""
+
+from rich.console import Console
+from rich.table import Table
+from modscanner.models import ScanReport
+
+
+def render_report(
+    report: ScanReport,
+    console: Console | None = None,
+) -> None:
+    """render a scan report as a terminal table"""
+
+    output = console or Console()
+
+    table = Table(
+        title=(
+            f"Holding registers: "
+            f"{report.target.host}:{report.target.port} "
+            f"(device {report.target.device_id})"
+        )
+    )
+
+    table.add_column("Address", justify="right")
+    table.add_column("Value", justify="right")
+    table.add_column("Status")
+    table.add_column("Error")
+
+    for result in report.results:
+        table.add_row(
+            str(result.address),
+            "" if result.value is None else str(result.value),
+            result.status.value,
+            result.error or "",
+        )
+
+    output.print(table)
+    output.print(
+        f"Successful: {report.successful_count} | Failed: {report.failed_count}"
+    )

modscanner-0.1.0/src/modscanner/scanner.py

@@ -0,0 +1,151 @@
+"""read-only Modbus register scanning logic"""
+
+from modscanner.models import (
+    RegisterArea,
+    RegisterResult,
+    ResultStatus,
+    ScanPlan,
+    ScanReport,
+    TcpTarget,
+)
+from modscanner.transports.base import (
+    ModbusTransport,
+    ReadErrorKind,
+)
+
+
+class Scanner:
+    """read-only Modbus scanner"""
+
+    def __init__(
+        self,
+        transport: ModbusTransport,
+        target: TcpTarget,
+    ) -> None:
+        self._transport = transport
+        self._target = target
+
+    def scan_holding_registers(self, plan: ScanPlan) -> ScanReport:
+        """scan holding registers using adaptive block splitting"""
+
+        results: list[RegisterResult] = []
+
+        range_end = plan.start + plan.count
+        current_address = plan.start
+
+        while current_address < range_end:
+            block_count = min(
+                plan.block_size,
+                range_end - current_address,
+            )
+
+            self._scan_block(
+                address=current_address,
+                count=block_count,
+                results=results,
+            )
+
+            current_address += block_count
+
+        results.sort(key=lambda result: result.address)
+
+        return ScanReport(
+            target=self._target,
+            plan=plan,
+            results=tuple(results),
+        )
+
+    def _scan_block(
+        self,
+        address: int,
+        count: int,
+        results: list[RegisterResult],
+    ) -> None:
+        block = self._transport.read_holding_registers(
+            address=address,
+            count=count,
+            device_id=self._target.device_id,
+        )
+
+        if block.ok:
+            values = block.values
+
+            if values is None or len(values) != count:
+                self._append_failures(
+                    address=address,
+                    count=count,
+                    status=ResultStatus.INVALID_RESPONSE,
+                    error="transport returned an invalid successful result",
+                    results=results,
+                )
+                return
+
+            for offset, value in enumerate(values):
+                results.append(
+                    RegisterResult(
+                        address=address + offset,
+                        area=RegisterArea.HOLDING_REGISTER,
+                        status=ResultStatus.OK,
+                        value=value,
+                    )
+                )
+
+            return
+
+        if block.error_kind is ReadErrorKind.PROTOCOL and count > 1:
+            left_count = count // 2
+            right_count = count - left_count
+
+            self._scan_block(
+                address=address,
+                count=left_count,
+                results=results,
+            )
+
+            self._scan_block(
+                address=address + left_count,
+                count=right_count,
+                results=results,
+            )
+
+            return
+
+        status = self._status_from_error_kind(block.error_kind)
+
+        self._append_failures(
+            address=address,
+            count=count,
+            status=status,
+            error=block.error or "unknown Modbus error",
+            results=results,
+        )
+
+    @staticmethod
+    def _status_from_error_kind(
+        error_kind: ReadErrorKind | None,
+    ) -> ResultStatus:
+        if error_kind is ReadErrorKind.PROTOCOL:
+            return ResultStatus.PROTOCOL_ERROR
+
+        if error_kind is ReadErrorKind.TRANSPORT:
+            return ResultStatus.TRANSPORT_ERROR
+
+        return ResultStatus.INVALID_RESPONSE
+
+    @staticmethod
+    def _append_failures(
+        address: int,
+        count: int,
+        status: ResultStatus,
+        error: str,
+        results: list[RegisterResult],
+    ) -> None:
+        for offset in range(count):
+            results.append(
+                RegisterResult(
+                    address=address + offset,
+                    area=RegisterArea.HOLDING_REGISTER,
+                    status=status,
+                    error=error,
+                )
+            )

modscanner-0.1.0/src/modscanner/transports/base.py

@@ -0,0 +1,62 @@
+"""transport abstraction used by the ModScanner core"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+
+class ReadErrorKind(StrEnum):
+    """categories of errors returned by a transport"""
+
+    PROTOCOL = "protocol"
+    TRANSPORT = "transport"
+    INVALID_RESPONSE = "invalid_response"
+
+
+@dataclass(frozen=True, slots=True)
+class BlockRead:
+    """result of reading one contiguous block of rgisters"""
+
+    values: tuple[int, ...] | None = None
+    error_kind: ReadErrorKind | None = None
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        """return whether the operation wass a success"""
+
+        return self.error_kind is None
+
+    @classmethod
+    def success(cls, values: tuple[int, ...]) -> "BlockRead":
+        """create a successful block result"""
+
+        return cls(values=values)
+
+    @classmethod
+    def failure(
+        cls,
+        kind: ReadErrorKind,
+        error: str,
+    ) -> "BlockRead":
+        """create a failed block result"""
+
+        return cls(error_kind=kind, error=error)
+
+
+class ModbusTransport(Protocol):
+    """interface implemented by concret Modbus transports"""
+
+    def connect(self) -> None:
+        """connect to the Modbus device"""
+
+    def close(self) -> None:
+        """close the connection"""
+
+    def read_holding_registers(
+        self,
+        address: int,
+        count: int,
+        device_id: int,
+    ) -> BlockRead:
+        """read a contiguoous block of holding registers"""

modscanner-0.1.0/src/modscanner/transports/pymodbus_transport.py

@@ -0,0 +1,89 @@
+"""PyModbus-backed Modbus TCP transport"""
+
+from pymodbus.client import ModbusTcpClient
+from pymodbus.exceptions import ModbusException
+from modscanner.exceptions import ModScannerConnectionError
+from modscanner.models import TcpTarget
+from modscanner.transports.base import BlockRead, ReadErrorKind
+
+
+class PymodbusTcpTransport:
+    """synchronous Modbus TCP transport using PyModbus"""
+
+    def __init__(self, target: TcpTarget) -> None:
+        self._target = target
+        self._client = ModbusTcpClient(
+            host=target.host,
+            port=target.port,
+            timeout=target.timeout,
+        )
+
+    def connect(self) -> None:
+        """connect to the configured Modbus TCP device"""
+
+        try:
+            connected = self._client.connect()
+        except (ModbusException, OSError, TimeoutError) as exc:
+            raise ModScannerConnectionError(
+                f"could not connect to {self._target.host}:{self._target.port}: {exc}"
+            ) from exc
+
+        if not connected:
+            raise ModScannerConnectionError(
+                f"could not connect to {self._target.host}:{self._target.port}"
+            )
+
+    def close(self) -> None:
+        """close the PyModbus TCP connection"""
+
+        self._client.close()
+
+    def read_holding_registers(
+        self,
+        address: int,
+        count: int,
+        device_id: int,
+    ) -> BlockRead:
+        """read holding registers using function code 03"""
+
+        try:
+            response = self._client.read_holding_registers(
+                address,
+                count=count,
+                device_id=device_id,
+            )
+        except (ModbusException, OSError, TimeoutError) as exc:
+            return BlockRead.failure(
+                ReadErrorKind.TRANSPORT,
+                str(exc),
+            )
+
+        if response is None:
+            return BlockRead.failure(
+                ReadErrorKind.INVALID_RESPONSE,
+                "the device returned no response object",
+            )
+
+        if response.isError():
+            return BlockRead.failure(
+                ReadErrorKind.PROTOCOL,
+                str(response),
+            )
+
+        registers = getattr(response, "registers", None)
+
+        if registers is None:
+            return BlockRead.failure(
+                ReadErrorKind.INVALID_RESPONSE,
+                "the response did not contain registers",
+            )
+
+        values = tuple(int(value) for value in registers)
+
+        if len(values) != count:
+            return BlockRead.failure(
+                ReadErrorKind.INVALID_RESPONSE,
+                f"expected {count} registers but received {len(values)}",
+            )
+
+        return BlockRead.success(values)

modscanner-0.1.0/src/modscanner.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: modscanner
+Version: 0.1.0
+Summary: A safety-first Modbus discovery and register inspection toolkit.
+Author: Davis Onyeoguzoro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/davisonyeas/modscanner
+Project-URL: Documentation, https://davisonyeas.github.io/modscanner/
+Project-URL: Repository, https://github.com/davisonyeas/modscanner
+Project-URL: Issues, https://github.com/davisonyeas/modscanner/issues
+Project-URL: Changelog, https://github.com/davisonyeas/modscanner/blob/master/CHANGELOG.md
+Keywords: modbus,modbus-tcp,modbus-rtu,industrial-automation,plc,scada
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymodbus<3.15,>=3.14
+Requires-Dist: rich<15,>=13
+Requires-Dist: typer<1,>=0.12
+Dynamic: license-file
+
+# ModScanner
+
+A safety-first Modbus scanning toolkit for Python.
+
+ModScanner helps engineers inspect Modbus devices without immediately falling back to slow, one-register-at-a-time scanning. It reads registers in blocks and adaptively splits rejected blocks to identify valid and invalid addresses.
+
+> **Project status:** 
+Early development. Version 0.1.0 supports only 
+> **Modbus TCP holding register scanning. 
+
+## Features 
+
+- Read-only Modbus TCP scanning
+- Holding register reads using function code 03
+- Configurable device ID, port, timeout, range, and block size
+- Adaptive block splitting when a device rejects a register range
+- Seperation of protocol errors, transport errors, and invalid responses
+- Terminal output using Rich
+- Typed Python data module
+- Transport abstraction that is built untop of PyModbus
+- Unit tested scanning behavior
+
+## Installation
+
+Install ModScanner from PyPI using either of two(2) methods the below:
+
+1. Install ModScanner from PyPI:
+
+```bash
+pip install modscanner
+```
+
+2. Using uv:
+
+```bash
+uv add modscanner
+```
+
+Verify the installation using:
+```bash
+modscanner --help
+or
+modscanner --h
+or 
+modscanner version
+```
+
+> **The above help shows the commands available, while the version shows the current version you have installd on your machine**
+
+## Quick start
+
+There are different ways to use the library;
+
+1. Scan holding registers `0` through `19` on a Modbus TCP device using the below:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --device-id 1 --start 0 --count 20
+```
+
+> **The above expects you to use the IP Address of the Modbus device, so replace the 192.168.1.10 with your Modbus device**
+
+2. Specify the TCP port, timeout, and request block size using:
+
+```bash
+modscanner scan-tcp 192.168.1.10 --port 502 --device-id 1 --start 0 --count 100 --block-size 50 --timeout 2
+```
+
+Run:
+```bash
+modscanner scan-tcp --help
+```
+
+to see all available options.
+
+## Addressing
+
+ModScanner uses zero-based Modbus protocol addresses.
+
+For example, a vendor document may label the first holding register as `40001`, while its protocol address is commonly `0`.
+
+Always confirm how the device manufacturer represents register addresses before scanning.
+
+## Adaptive scanning
+
+Some Modbus devices reject an entire request when only one address is within the requested block is invalid.
+
+ModScanner handles this by:
+1. Reading a block of registers.
+2. Accepting the block when the response is valid.
+3. Splitting a block when the device return a protocol-level error.
+4. Continuing until individual valid and invalid addresses are identified.
+5. Avoiding recursive requests after transport failure such as timeouts.
+
+This reduces unnecessary requests while stil supporting sparse register maps.
+
+## Safety
+
+ModScanner 0.1.0 is read-only.
+
+It does not write coils or registers. Future write-validation functionality will require explicit register allowlists, value limits, confirmation, readback, and audit logging.
+
+Read-only registers should also be used carefully on production systems. Confirm the target IP address, port, device ID, and permitted register range before scanning industrial equipments.
+
+## Current limitation
+
+Version 0.1.0 does not yet support:
+
+- Modbus RTU
+- Coils
+- Discrete inputs
+- Input registers
+- Automatic device ID discovery
+- JSON, CSV, or YAML exports
+- Data type decoding
+- Byte-order or word-order conversion
+- Device profiles
+- Register monitoring
+- Register writes
+- Writable-register validation
+
+> **All the above are planned for future releasesa**
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## Security
+
+Do not use ModScanner to perform unauthorized scanning or testing.
+
+## Author
+Developed by [Davis Onyeoguzoro](https://github.com/davisonyeas)

modscanner-0.1.0/src/modscanner.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/modscanner/__init__.py
+src/modscanner/cli.py
+src/modscanner/exceptions.py
+src/modscanner/models.py
+src/modscanner/py.typed
+src/modscanner/scanner.py
+src/modscanner.egg-info/PKG-INFO
+src/modscanner.egg-info/SOURCES.txt
+src/modscanner.egg-info/dependency_links.txt
+src/modscanner.egg-info/entry_points.txt
+src/modscanner.egg-info/requires.txt
+src/modscanner.egg-info/top_level.txt
+src/modscanner/reporters/__init__.py
+src/modscanner/reporters/console.py
+src/modscanner/transports/__init__.py
+src/modscanner/transports/base.py
+src/modscanner/transports/pymodbus_transport.py

modscanner-0.1.0/src/modscanner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

modscanner-0.1.0/src/modscanner.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modscanner = modscanner.cli:app

modscanner-0.1.0/src/modscanner.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pymodbus<3.15,>=3.14
+rich<15,>=13
+typer<1,>=0.12

modscanner-0.1.0/src/modscanner.egg-info/top_level.txt

@@ -0,0 +1 @@
+modscanner