otcat 1.0.0__py3-none-any.whl

otcat/__init__.py

@@ -0,0 +1,56 @@
+"""otcat: Python bindings for the otcat Go core.
+
+A thin, typed wrapper around the real otcat/otc binary -- every read
+and write in this package is executed by the same tested, fuzzed Go
+Modbus TCP client the accompanying paper describes, not a Python
+reimplementation of the protocol. See client.py's module docstring for
+why that's a subprocess boundary rather than a cgo/ctypes one.
+
+Quick start::
+
+    from otcat import Client
+
+    c = Client("127.0.0.1:502")
+    v = c.read("holding:40001")
+    print(v.value, v.quality)
+
+    for v in c.watch("holding:40001", interval="500ms", count=10):
+        print(v.ts, v.value)
+
+    c.write("holding:40001", 100)  # confirm=True by default in the library
+
+Optional extras (install with e.g. ``pip install otcat[pandas]``):
+
+- ``otcat.pandas_ext`` -- DataFrame conversion, a rolling-window buffer
+- ``otcat.alerting`` -- threshold rules with debounce, for automations
+- ``otcat.audit`` -- read-only OT asset discovery / fingerprinting
+- ``otcat.aio`` -- asyncio client for FastAPI and friends
+"""
+from .client import Client
+from .exceptions import (
+    ConnectionError,
+    IOFailureError,
+    OtcatBinaryNotFoundError,
+    OtcatError,
+    ProtocolError,
+    Timeout,
+    UsageError,
+    WriteAbortedError,
+)
+from .models import Value, WritePlan
+
+__all__ = [
+    "Client",
+    "Value",
+    "WritePlan",
+    "OtcatError",
+    "OtcatBinaryNotFoundError",
+    "UsageError",
+    "ConnectionError",
+    "ProtocolError",
+    "WriteAbortedError",
+    "IOFailureError",
+    "Timeout",
+]
+
+__version__ = "1.0.0"

otcat/_binary.py

@@ -0,0 +1,83 @@
+"""Locates the otcat binary this package wraps.
+
+Resolution order, first match wins:
+
+1. ``OTCAT_BINARY`` environment variable, if set (an explicit escape
+   hatch -- useful for pointing at a locally built binary during otcat
+   Go-side development, or a version other than the one bundled here).
+2. A binary bundled inside this wheel, under ``otcat/_bin/``, matching
+   the current OS and CPU architecture. Platform-specific wheels (see
+   ``docs/packaging.md`` in the Python package) ship exactly one such
+   binary; this source checkout ships only ``otcat-linux-amd64``,
+   enough to develop and test on the platform this project's own CI
+   runs on.
+3. ``otcat`` or ``otc`` on ``$PATH`` -- covers the case where the Go
+   binary was installed separately (``go install``, a system package
+   from Cloudsmith, a manual download).
+
+If none of these resolve, :class:`OtcatBinaryNotFoundError` explains
+exactly what was tried, so a confusing "file not found" from deep
+inside subprocess machinery never reaches the caller.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import stat
+from pathlib import Path
+
+from .exceptions import OtcatBinaryNotFoundError
+
+_BIN_DIR = Path(__file__).parent / "_bin"
+
+
+def _platform_tag() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    os_name = {"darwin": "darwin", "linux": "linux", "windows": "windows"}.get(system, system)
+    arch = {
+        "x86_64": "amd64", "amd64": "amd64",
+        "aarch64": "arm64", "arm64": "arm64",
+    }.get(machine, machine)
+    return f"{os_name}-{arch}"
+
+
+def _bundled_path() -> Path | None:
+    tag = _platform_tag()
+    suffix = ".exe" if tag.startswith("windows") else ""
+    candidate = _BIN_DIR / f"otcat-{tag}{suffix}"
+    return candidate if candidate.is_file() else None
+
+
+def find_binary() -> str:
+    """Return a path to a working otcat binary, or raise
+    :class:`OtcatBinaryNotFoundError` with a clear explanation."""
+    tried: list[str] = []
+
+    env = os.environ.get("OTCAT_BINARY")
+    if env:
+        tried.append(f"$OTCAT_BINARY={env}")
+        if os.path.isfile(env) and os.access(env, os.X_OK):
+            return env
+
+    bundled = _bundled_path()
+    if bundled:
+        tried.append(f"bundled binary at {bundled}")
+        if not os.access(bundled, os.X_OK):
+            # Wheel installers don't always preserve the executable
+            # bit; fix it rather than fail on something this
+            # trivially fixable.
+            bundled.chmod(bundled.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        return str(bundled)
+    else:
+        tried.append(f"bundled binary for platform '{_platform_tag()}' (none shipped in this install)")
+
+    for name in ("otcat", "otc"):
+        found = shutil.which(name)
+        tried.append(f"'{name}' on $PATH")
+        if found:
+            return found
+
+    raise OtcatBinaryNotFoundError(tried)

otcat/aio.py

@@ -0,0 +1,134 @@
+"""Async twin of :class:`otcat.client.Client`, built on
+``asyncio.create_subprocess_exec`` instead of the synchronous
+``subprocess`` module, so it doesn't block an event loop -- the
+relevant case being a FastAPI endpoint that reads or watches a
+register without stalling every other request being served by the
+same process. Same flags, same JSON parsing, same exception mapping;
+see client.py's module docstring for the design rationale, which
+applies here unchanged.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+from . import _binary
+from .exceptions import Timeout, error_for_exit_code
+from .models import Value, WritePlan
+
+_DEFAULT_TIMEOUT = 5.0
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        binary: str | None = None,
+        unit: int = 1,
+        type: str = "uint16",  # noqa: A002
+        byte_order: str = "big",
+        word_order: str = "high",
+        raw_address: bool = False,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.endpoint = endpoint
+        self.binary = binary or _binary.find_binary()
+        self.unit = unit
+        self.type = type
+        self.byte_order = byte_order
+        self.word_order = word_order
+        self.raw_address = raw_address
+        self.timeout = timeout
+
+    def _base_flags(self) -> list[str]:
+        flags = [
+            "--modbus", self.endpoint,
+            "--unit", str(self.unit),
+            "--type", self.type,
+            "--byte-order", self.byte_order,
+            "--word-order", self.word_order,
+            "--timeout", f"{self.timeout}s",
+            "--json",
+        ]
+        if self.raw_address:
+            flags.append("--raw-address")
+        return flags
+
+    async def _run(self, args: list[str]) -> tuple[int, str, str]:
+        proc = await asyncio.create_subprocess_exec(
+            self.binary, *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=self.timeout + 5
+            )
+        except asyncio.TimeoutError as e:
+            proc.kill()
+            await proc.wait()
+            raise Timeout(
+                f"otcat process did not exit within {self.timeout + 5}s"
+            ) from e
+        assert proc.returncode is not None  # guaranteed once communicate() has returned
+        return proc.returncode, stdout.decode(), stderr.decode()
+
+    async def read(self, spec: str) -> Value:
+        code, out, err = await self._run([*self._base_flags(), "--read", spec])
+        if code != 0:
+            raise error_for_exit_code(code, err)
+        return Value.from_json(json.loads(out.strip().splitlines()[-1]))
+
+    async def write(self, spec: str, value: Any, *, confirm: bool = True) -> None:
+        args = [*self._base_flags(), "--write", spec, "--value", str(value)]
+        if confirm:
+            args.append("--confirm")
+        code, _out, err = await self._run(args)
+        if code != 0:
+            raise error_for_exit_code(code, err)
+
+    async def dry_run(self, spec: str, value: Any) -> WritePlan:
+        args = [*self._base_flags(), "--write", spec, "--value", str(value), "--dry-run"]
+        code, out, err = await self._run(args)
+        if code != 0:
+            raise error_for_exit_code(code, err)
+        return WritePlan.from_json(json.loads(out.strip().splitlines()[-1]))
+
+    async def watch(
+        self, spec: str, *, interval: str = "1s", count: int = 0
+    ) -> AsyncIterator[Value]:
+        """Async generator streaming readings -- `async for v in
+        client.watch(...)`. Ideal for a FastAPI WebSocket endpoint
+        forwarding live register values to a browser."""
+        args = [
+            *self._base_flags(),
+            "--watch", spec,
+            "--interval", interval,
+            "--count", str(count),
+        ]
+        proc = await asyncio.create_subprocess_exec(
+            self.binary, *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            assert proc.stdout is not None
+            async for raw_line in proc.stdout:
+                line = raw_line.decode().strip()
+                if not line:
+                    continue
+                yield Value.from_json(json.loads(line))
+        finally:
+            if proc.returncode is None:
+                proc.terminate()
+                try:
+                    await asyncio.wait_for(proc.wait(), timeout=3)
+                except asyncio.TimeoutError:
+                    proc.kill()
+                    await proc.wait()
+
+    def __repr__(self) -> str:
+        return f"AsyncClient(endpoint={self.endpoint!r}, unit={self.unit}, type={self.type!r})"

otcat/alerting.py

@@ -0,0 +1,174 @@
+"""A small rule-based alerting engine for turning a watch() stream into
+callbacks -- the building block for "page someone when the tank gets
+above 90%" or "trigger a downstream automation when a coil flips."
+
+Deliberately minimal: no rule DSL, no persistence, no distributed
+state. A Rule is a predicate and two callbacks (on_trigger, on_clear);
+the engine's only real logic is debouncing so a value oscillating
+right at a threshold doesn't fire on every single sample.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import Client
+from .models import Value
+
+logger = logging.getLogger("otcat.alerting")
+
+
+@dataclass
+class Rule:
+    """spec: address to watch. predicate: called with the decoded
+    value; return True when the alert condition is met. on_trigger is
+    called once when the rule transitions False->True (after
+    `debounce` consecutive breaching samples, not on the first one --
+    see AlertEngine's docstring for why). on_clear, if given, is
+    called once on the True->False transition."""
+
+    spec: str
+    predicate: Callable[[Any], bool]
+    on_trigger: Callable[[Value], None]
+    on_clear: Callable[[Value], None] | None = None
+    debounce: int = 1
+    name: str = ""
+
+    # internal state
+    _consecutive: int = field(default=0, repr=False, compare=False)
+    _active: bool = field(default=False, repr=False, compare=False)
+
+    def __post_init__(self):
+        self.name = self.name or self.spec
+
+
+@dataclass
+class Threshold:
+    """A Rule built from a plain numeric threshold, for the common
+    case that doesn't need a custom predicate.
+
+    >>> Threshold(spec="holding:0", above=9000).as_rule(on_trigger=page_oncall)
+    """
+
+    spec: str
+    above: float | None = None
+    below: float | None = None
+    debounce: int = 3
+    name: str = ""
+
+    def as_rule(
+        self,
+        on_trigger: Callable[[Value], None],
+        on_clear: Callable[[Value], None] | None = None,
+    ) -> Rule:
+        above, below = self.above, self.below
+
+        def predicate(value: Any) -> bool:
+            v = float(value)
+            if above is not None and v > above:
+                return True
+            if below is not None and v < below:
+                return True
+            return False
+
+        return Rule(
+            spec=self.spec,
+            predicate=predicate,
+            on_trigger=on_trigger,
+            on_clear=on_clear,
+            debounce=self.debounce,
+            name=self.name or self.spec,
+        )
+
+
+class AlertEngine:
+    """Polls a set of Rules, one otcat --watch subprocess per unique
+    spec, and dispatches on_trigger/on_clear callbacks with debounce.
+
+    Debounce exists because a raw threshold on a live signal will
+    otherwise fire, clear, and re-fire every time noise crosses the
+    line -- exactly the alert-fatigue failure mode any real automation
+    or paging system needs to avoid. `debounce=N` requires N
+    consecutive breaching samples before on_trigger fires, and (by the
+    same logic, for the same reason) N consecutive non-breaching
+    samples before on_clear fires.
+
+    This runs rules sequentially in one thread by design: it is meant
+    for a handful of rules on a slow-moving industrial process (seconds
+    between readings, not microseconds), not a high-frequency
+    multiplexed data feed. For dozens of independent high-frequency
+    watches, run separate AlertEngine instances (or Client.watch()
+    loops) in separate threads/processes instead of adding concurrency
+    complexity to this class.
+    """
+
+    def __init__(self, client: Client):
+        self.client = client
+        self._rules: list[Rule] = []
+
+    def add_rule(self, rule: Rule) -> "AlertEngine":
+        self._rules.append(rule)
+        return self
+
+    def threshold(
+        self,
+        spec: str,
+        *,
+        above: float | None = None,
+        below: float | None = None,
+        on_trigger: Callable[[Value], None],
+        on_clear: Callable[[Value], None] | None = None,
+        debounce: int = 3,
+        name: str = "",
+    ) -> "AlertEngine":
+        """Convenience: build and add a Threshold rule in one call."""
+        rule = Threshold(spec=spec, above=above, below=below, debounce=debounce, name=name).as_rule(
+            on_trigger=on_trigger, on_clear=on_clear
+        )
+        return self.add_rule(rule)
+
+    def poll_once(self) -> None:
+        """Read every rule's spec once and evaluate it. Useful for
+        testing a rule set, or for driving the engine from your own
+        scheduler instead of run()'s built-in loop."""
+        for rule in self._rules:
+            try:
+                value = self.client.read(rule.spec)
+            except Exception:
+                logger.exception("otcat alerting: read failed for rule %r", rule.name)
+                continue
+            self._evaluate(rule, value)
+
+    def _evaluate(self, rule: Rule, value: Value) -> None:
+        breached = False
+        try:
+            breached = rule.predicate(value.value)
+        except Exception:
+            logger.exception("otcat alerting: predicate failed for rule %r", rule.name)
+            return
+
+        if breached:
+            rule._consecutive += 1
+            if not rule._active and rule._consecutive >= rule.debounce:
+                rule._active = True
+                rule.on_trigger(value)
+        else:
+            rule._consecutive = 0
+            if rule._active:
+                rule._active = False
+                if rule.on_clear:
+                    rule.on_clear(value)
+
+    def run(self, *, interval_seconds: float = 1.0, iterations: int | None = None) -> None:
+        """Blocking loop: poll_once() every interval_seconds. Run this
+        in a background thread for a long-lived service; iterations
+        (mainly for tests) bounds the loop instead of running forever."""
+        i = 0
+        while iterations is None or i < iterations:
+            self.poll_once()
+            i += 1
+            if iterations is None or i < iterations:
+                time.sleep(interval_seconds)

otcat/audit.py

@@ -0,0 +1,156 @@
+"""Read-only auditing helpers for OT asset discovery and exposure
+assessment -- the Python-side equivalent of the Go core's own
+safety-first ethos (see the accompanying paper, "Safety Is a Default,
+Not a Feature"): every function in this module only ever issues reads.
+There is no scan-and-write mode, no fuzzer, no credential attack (moot
+anyway -- Modbus has no authentication to attack), and no function that
+sends more than one request at a time to a single device. That is a
+deliberate, permanent design boundary for this module, not a version-1
+limitation to be lifted later.
+
+Intended use: legitimate asset inventory, exposure mapping, and
+red-team reconnaissance *you are authorized to perform* against
+equipment you are authorized to test. Running any scanner, including
+this one, against equipment you do not have explicit authorization to
+test may be illegal in your jurisdiction and can disrupt a live
+physical process regardless of intent -- see the Go core's own
+Limitations section for why Modbus's total absence of authentication
+means "I can reach it" has never implied "I am allowed to."
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from .client import Client
+from .exceptions import ConnectionError as OtcatConnectionError
+from .exceptions import ProtocolError
+
+
+@dataclass
+class ScanResult:
+    table: str
+    address: int
+    responsive: bool
+    exception_code: str | None = None
+    latency_ms: float | None = None
+
+
+@dataclass
+class ScanReport:
+    endpoint: str
+    table: str
+    start: int
+    count: int
+    results: list[ScanResult] = field(default_factory=list)
+
+    @property
+    def responsive_addresses(self) -> list[int]:
+        return [r.address for r in self.results if r.responsive]
+
+    @property
+    def response_rate(self) -> float:
+        return len(self.responsive_addresses) / len(self.results) if self.results else 0.0
+
+    def summary(self) -> str:
+        lat = [r.latency_ms for r in self.results if r.latency_ms is not None]
+        avg_lat = sum(lat) / len(lat) if lat else float("nan")
+        return (
+            f"{self.endpoint} {self.table}:{self.start}..{self.start + self.count - 1}: "
+            f"{len(self.responsive_addresses)}/{len(self.results)} addresses responsive "
+            f"({self.response_rate:.0%}), avg latency {avg_lat:.1f}ms"
+        )
+
+
+def scan_range(
+    client: Client,
+    table: str,
+    start: int,
+    count: int,
+    *,
+    delay_seconds: float = 0.0,
+) -> ScanReport:
+    """Sweep [start, start+count) with individual single-value reads,
+    recording which addresses respond, which raise a protocol
+    exception (and which one), and per-address latency. Read-only,
+    always -- see the module docstring.
+
+    delay_seconds paces requests between addresses; the default (0)
+    sends as fast as the client allows, which is fine for otcat's own
+    mock server and most modern devices, but consider a small delay
+    (e.g. 0.05) against older or resource-constrained field hardware,
+    the same courtesy the paper's own write-safety design extends
+    throughout: a scanner should not become a denial-of-service tool
+    by accident.
+    """
+    report = ScanReport(endpoint=client.endpoint, table=table, start=start, count=count)
+    for offset in range(count):
+        addr = start + offset
+        t0 = time.perf_counter()
+        try:
+            client.read(f"{table}:{addr}")
+            latency_ms = (time.perf_counter() - t0) * 1000
+            report.results.append(ScanResult(table, addr, responsive=True, latency_ms=latency_ms))
+        except ProtocolError as e:
+            latency_ms = (time.perf_counter() - t0) * 1000
+            report.results.append(
+                ScanResult(table, addr, responsive=False, exception_code=e.exception_code, latency_ms=latency_ms)
+            )
+        except OtcatConnectionError:
+            report.results.append(ScanResult(table, addr, responsive=False))
+        if delay_seconds:
+            time.sleep(delay_seconds)
+    return report
+
+
+@dataclass
+class DeviceFingerprint:
+    endpoint: str
+    reachable: bool
+    tables_responsive: dict[str, bool] = field(default_factory=dict)
+    latency_ms_p50: float | None = None
+    latency_ms_p99: float | None = None
+    samples: int = 0
+
+
+def fingerprint(client: Client, *, samples: int = 20, probe_address: int = 0) -> DeviceFingerprint:
+    """A lightweight, read-only device fingerprint: which of the four
+    Modbus data tables respond at all at probe_address, and the
+    round-trip latency distribution over `samples` reads of one
+    holding register -- useful groundwork for both an asset inventory
+    entry and a latency budget for how aggressively you can safely
+    poll this specific device (see the paper's own methodology for why
+    latency percentiles, not just a mean, are the right thing to record
+    here).
+    """
+    fp = DeviceFingerprint(endpoint=client.endpoint, reachable=False)
+
+    for table in ("holding", "input", "coil", "discrete"):
+        try:
+            client.read(f"{table}:{probe_address}")
+            fp.tables_responsive[table] = True
+            fp.reachable = True
+        except ProtocolError:
+            # Reached the device; this table/address combination just
+            # isn't valid there. Still evidence of reachability.
+            fp.tables_responsive[table] = False
+            fp.reachable = True
+        except OtcatConnectionError:
+            fp.tables_responsive[table] = False
+
+    if fp.reachable:
+        latencies: list[float] = []
+        for _ in range(samples):
+            t0 = time.perf_counter()
+            try:
+                client.read(f"holding:{probe_address}")
+                latencies.append((time.perf_counter() - t0) * 1000)
+            except (ProtocolError, OtcatConnectionError):
+                pass
+        if latencies:
+            latencies.sort()
+            fp.samples = len(latencies)
+            fp.latency_ms_p50 = latencies[len(latencies) // 2]
+            fp.latency_ms_p99 = latencies[min(len(latencies) - 1, int(len(latencies) * 0.99))]
+
+    return fp

otcat/client.py

@@ -0,0 +1,188 @@
+"""The synchronous otcat client.
+
+This is deliberately a subprocess wrapper around the real, compiled Go
+binary -- not a reimplementation of the Modbus protocol in Python.
+Every byte that crosses a real socket is still produced and parsed by
+the same Go core the paper describes and the Go test suite exercises;
+this package's only job is turning that binary's ndjson stdout into
+typed Python objects, and Python calls into the right CLI flags.
+
+Why subprocess and not a cgo shared library / ctypes binding: it is
+the integration surface otcat was already designed around (stdin,
+stdout, one ndjson object per line), it costs nothing extra to keep
+correct as the Go core evolves, and it works on every platform the Go
+binary itself supports with zero additional build tooling on the
+Python side. The cost is one process-spawn per read/write and a few
+milliseconds of overhead -- immaterial next to a Modbus round trip
+(see the paper's own latency figures) and irrelevant for --watch,
+which spawns once and streams.
+
+Write safety: exactly one behavior carries over from the CLI without
+a Python-side opinion layered on top -- Client.write() defaults to
+confirm=True, deliberately the *opposite* default of the CLI's own
+--confirm flag. The CLI defaults to refusing because a human might be
+about to fat-finger a command; a library call is already the result of
+a programmer deciding, in code, to write a specific value -- there is
+no keystroke left to protect against. If you want the CLI's stricter
+default in your own code, pass confirm=False and handle
+WriteAbortedError.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Iterator
+from typing import Any
+
+from . import _binary
+from .exceptions import Timeout, error_for_exit_code
+from .models import Value, WritePlan
+
+_DEFAULT_TIMEOUT = 5.0
+
+
+class Client:
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        binary: str | None = None,
+        unit: int = 1,
+        type: str = "uint16",  # noqa: A002 - matches the CLI's --type name
+        byte_order: str = "big",
+        word_order: str = "high",
+        raw_address: bool = False,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        """endpoint: "host:port" of a Modbus TCP device or otcat-mockplc."""
+        self.endpoint = endpoint
+        self.binary = binary or _binary.find_binary()
+        self.unit = unit
+        self.type = type
+        self.byte_order = byte_order
+        self.word_order = word_order
+        self.raw_address = raw_address
+        self.timeout = timeout
+
+    # -- shared flag building -------------------------------------------------
+
+    def _base_flags(self) -> list[str]:
+        flags = [
+            "--modbus", self.endpoint,
+            "--unit", str(self.unit),
+            "--type", self.type,
+            "--byte-order", self.byte_order,
+            "--word-order", self.word_order,
+            "--timeout", f"{self.timeout}s",
+            "--json",
+        ]
+        if self.raw_address:
+            flags.append("--raw-address")
+        return flags
+
+    def _run(self, args: list[str], input_text: str | None = None) -> subprocess.CompletedProcess:
+        try:
+            return subprocess.run(
+                [self.binary, *args],
+                input=input_text,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout + 5,  # generous margin over otcat's own --timeout
+            )
+        except subprocess.TimeoutExpired as e:
+            raise Timeout(
+                f"otcat process did not exit within {self.timeout + 5}s "
+                f"(otcat's own --timeout is {self.timeout}s; this is the "
+                f"Python-side watchdog on top of it)"
+            ) from e
+
+    # -- public API -------------------------------------------------------------
+
+    def read(self, spec: str) -> Value:
+        """Read one address once. spec: e.g. "holding:40001" or
+        "holding:200:2" for a 2-register array."""
+        proc = self._run([*self._base_flags(), "--read", spec])
+        if proc.returncode != 0:
+            raise error_for_exit_code(proc.returncode, proc.stderr)
+        return Value.from_json(json.loads(proc.stdout.strip().splitlines()[-1]))
+
+    def read_many(self, specs: list[str]) -> list[Value]:
+        """Convenience: read() each spec in sequence (N processes, N
+        round trips -- not a single batched Modbus request, since
+        otcat's own protocol layer doesn't batch either; see the
+        paper's discussion of why the client stays single-request)."""
+        return [self.read(spec) for spec in specs]
+
+    def write(
+        self,
+        spec: str,
+        value: Any,
+        *,
+        confirm: bool = True,
+    ) -> None:
+        """Write value to spec. See the module docstring for why
+        confirm defaults to True here, opposite the CLI's own default."""
+        args = [*self._base_flags(), "--write", spec, "--value", str(value)]
+        if confirm:
+            args.append("--confirm")
+        proc = self._run(args)
+        if proc.returncode != 0:
+            raise error_for_exit_code(proc.returncode, proc.stderr)
+
+    def dry_run(self, spec: str, value: Any) -> WritePlan:
+        """Compute exactly what write(spec, value) would send, with
+        zero network I/O -- see internal/cliapp's --dry-run in the Go
+        core; this calls the identical code path."""
+        args = [*self._base_flags(), "--write", spec, "--value", str(value), "--dry-run"]
+        proc = self._run(args)
+        if proc.returncode != 0:
+            raise error_for_exit_code(proc.returncode, proc.stderr)
+        return WritePlan.from_json(json.loads(proc.stdout.strip().splitlines()[-1]))
+
+    def watch(
+        self,
+        spec: str,
+        *,
+        interval: str = "1s",
+        count: int = 0,
+    ) -> Iterator[Value]:
+        """Stream readings as they arrive. A generator wrapping one
+        long-lived `otcat --watch` subprocess -- values are yielded the
+        instant otcat's own stdout flushes them (line-buffered, exactly
+        as documented in the Go codec package), not batched.
+
+        count=0 (the default) streams until the caller stops iterating
+        (breaking out of a `for` loop terminates the subprocess
+        cleanly) or the process is otherwise interrupted.
+        """
+        args = [
+            *self._base_flags(),
+            "--watch", spec,
+            "--interval", interval,
+            "--count", str(count),
+        ]
+        proc = subprocess.Popen(
+            [self.binary, *args],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+        try:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                line = line.strip()
+                if not line:
+                    continue
+                yield Value.from_json(json.loads(line))
+        finally:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+
+    def __repr__(self) -> str:
+        return f"Client(endpoint={self.endpoint!r}, unit={self.unit}, type={self.type!r})"

otcat/exceptions.py

@@ -0,0 +1,84 @@
+"""otcat's Python exceptions mirror the Go CLI's exit-code contract
+(see the main project's README, "Exit codes" table) one-for-one, so
+catching a specific class tells you exactly what class of failure
+happened without parsing error text.
+"""
+from __future__ import annotations
+
+
+class OtcatError(Exception):
+    """Base class for every error this package raises."""
+
+
+class OtcatBinaryNotFoundError(OtcatError):
+    """No otcat/otc binary could be located."""
+
+    def __init__(self, tried: list[str]):
+        self.tried = tried
+        msg = (
+            "could not find an otcat binary. Tried, in order:\n  - "
+            + "\n  - ".join(tried)
+            + "\n\nFix: install the Go binary (see "
+            "https://github.com/QuitOperation/otcat#install--build) and "
+            "ensure it's on $PATH, or set OTCAT_BINARY to its exact path."
+        )
+        super().__init__(msg)
+
+
+class UsageError(OtcatError):
+    """Exit code 1: bad arguments, malformed address spec, bad literal.
+    Almost always a bug in the calling code, not a transient condition."""
+
+
+class ConnectionError(OtcatError):  # noqa: A001 - deliberately shadows builtin, mirrors Go's naming
+    """Exit code 2: dial failure, timeout, connection refused."""
+
+
+class ProtocolError(OtcatError):
+    """Exit code 3: the device returned a real Modbus exception
+    (illegal address, illegal value, etc). See .exception_code."""
+
+    def __init__(self, message: str, exception_code: str | None = None):
+        super().__init__(message)
+        self.exception_code = exception_code
+
+
+class WriteAbortedError(OtcatError):
+    """Exit code 4: a write was refused because it was not confirmed.
+    This is otcat's safety gate working as designed, not a bug --
+    catching this and silently retrying with confirm=True defeats the
+    entire point of the gate. See client.py's module docstring."""
+
+
+class IOFailureError(OtcatError):
+    """Exit code 5: e.g. a broken output pipe, or an otherwise
+    unclassified failure."""
+
+
+class Timeout(OtcatError):
+    """Raised by watch()/read() when a client-side Python timeout
+    (distinct from otcat's own --timeout) elapses -- e.g. a watch
+    generator that produced no value for longer than expected."""
+
+
+_EXIT_CODE_MAP = {
+    1: UsageError,
+    2: ConnectionError,
+    3: ProtocolError,
+    4: WriteAbortedError,
+    5: IOFailureError,
+}
+
+
+def error_for_exit_code(code: int, stderr: str) -> OtcatError:
+    cls = _EXIT_CODE_MAP.get(code, OtcatError)
+    message = stderr.strip() or f"otcat exited with code {code}"
+    if cls is ProtocolError:
+        # otcat's protocol-error stderr looks like:
+        #   otcat: read holding:0: modbus: unit 1 function 0x03: illegal data address (0x02)
+        exc_code = None
+        if "(0x" in message:
+            exc_code = message.rsplit("(0x", 1)[-1].rstrip(")")
+            exc_code = "0x" + exc_code
+        return ProtocolError(message, exception_code=exc_code)
+    return cls(message)

otcat/models.py

@@ -0,0 +1,75 @@
+"""Typed models mirroring the JSON otcat's Go core actually emits
+(``internal/protocol.Value`` and ``internal/protocol.WritePlan``).
+Nothing here is reimplemented protocol logic -- it's just a typed
+Python view of exactly the bytes the Go binary printed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Value:
+    """One reading. Field-for-field the same shape as the ndjson
+    otcat --json prints, so ``Value(**json.loads(line))`` (after
+    renaming ``ts``) is a valid way to think about this type even
+    though the real parsing goes through :func:`from_json`."""
+
+    address: str
+    type: str
+    value: Any
+    quality: str
+    ts: datetime
+    raw: list[int] | None = None
+
+    @property
+    def good(self) -> bool:
+        return self.quality == "good"
+
+    @classmethod
+    def from_json(cls, obj: dict) -> "Value":
+        ts_raw = obj["ts"]
+        # Go's RFC3339Nano sometimes omits the fractional seconds
+        # entirely (whole-second timestamps); Python's fromisoformat
+        # (3.11+) handles the 'Z' suffix natively, but we support 3.9+
+        # so normalize it ourselves.
+        ts_norm = ts_raw.replace("Z", "+00:00")
+        try:
+            ts = datetime.fromisoformat(ts_norm)
+        except ValueError:
+            ts = datetime.now(timezone.utc)
+        return cls(
+            address=obj["address"],
+            type=obj["type"],
+            value=obj["value"],
+            quality=obj["quality"],
+            ts=ts,
+            raw=obj.get("raw"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class WritePlan:
+    """The output of Client.dry_run(): exactly what a write would
+    send, computed with zero network I/O (mirrors
+    internal/protocol.WritePlan)."""
+
+    driver: str
+    address: str
+    literal: str
+    type: str | None = None
+    registers: list[int] = field(default_factory=list)
+    coils: list[bool] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, obj: dict) -> "WritePlan":
+        return cls(
+            driver=obj["driver"],
+            address=obj["address"],
+            literal=obj["literal"],
+            type=obj.get("type"),
+            registers=obj.get("registers", []) or [],
+            coils=obj.get("coils", []) or [],
+        )

otcat/pandas_ext.py

@@ -0,0 +1,103 @@
+"""pandas integration. Kept as a separate, optional-import module
+(pandas is not a hard dependency of otcat's core client -- see
+pyproject.toml's [project.optional-dependencies]) so anything that
+only needs Client/AsyncClient never has to install pandas at all.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from .client import Client
+from .models import Value
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+_MISSING_PANDAS = (
+    "pandas is required for otcat.pandas_ext but is not installed. "
+    "Install it with: pip install otcat[pandas]"
+)
+
+
+def _require_pandas():
+    try:
+        import pandas as pd
+    except ImportError as e:  # pragma: no cover - exercised only without pandas installed
+        raise ImportError(_MISSING_PANDAS) from e
+    return pd
+
+
+def values_to_dataframe(values: Iterable[Value]) -> "pd.DataFrame":
+    """Convert any iterable of Value (e.g. Client.read_many's return,
+    or a fully-consumed Client.watch() generator) into a DataFrame with
+    columns [address, type, value, quality, ts] and ts as the index --
+    ready for `.resample()`, `.rolling()`, or a straight `.plot()`."""
+    pd = _require_pandas()
+    rows = [
+        {
+            "ts": v.ts,
+            "address": v.address,
+            "type": v.type,
+            "value": v.value,
+            "quality": v.quality,
+        }
+        for v in values
+    ]
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df = df.set_index("ts")
+    return df
+
+
+def read_many_df(client: Client, specs: list[str]) -> "pd.DataFrame":
+    """client.read_many(specs), as a DataFrame. One row per spec."""
+    return values_to_dataframe(client.read_many(specs))
+
+
+def watch_df(
+    client: Client,
+    spec: str,
+    *,
+    count: int,
+    interval: str = "1s",
+) -> "pd.DataFrame":
+    """Block until `count` samples are collected via client.watch(),
+    then return them as one DataFrame. For an unbounded live stream
+    instead, iterate client.watch() directly and accumulate/append
+    however your application (a dashboard, a rolling buffer) wants --
+    a single ever-growing DataFrame is usually the wrong shape for a
+    truly unbounded stream, which is why this helper requires a finite
+    count rather than offering an unbounded DataFrame-producing mode."""
+    values = list(client.watch(spec, interval=interval, count=count))
+    return values_to_dataframe(values)
+
+
+class RollingBuffer:
+    """A fixed-size rolling window over a live watch() stream,
+    materialized as a DataFrame on demand -- the shape a live
+    dashboard or a streaming feature-engineering step usually wants:
+    bounded memory, always-current, no unbounded accumulation.
+
+    >>> client = Client("127.0.0.1:502")
+    >>> buf = RollingBuffer(maxlen=500)
+    >>> for v in client.watch("holding:0", interval="200ms"):
+    ...     buf.push(v)
+    ...     if len(buf) >= 10:
+    ...         df = buf.to_dataframe()
+    ...         # df.value.rolling(5).mean(), df.plot(), feed a model, etc.
+    """
+
+    def __init__(self, maxlen: int = 1000):
+        from collections import deque
+        self.maxlen = maxlen
+        self._buf: deque[Value] = deque(maxlen=maxlen)
+
+    def push(self, value: Value) -> None:
+        self._buf.append(value)
+
+    def __len__(self) -> int:
+        return len(self._buf)
+
+    def to_dataframe(self) -> "pd.DataFrame":
+        return values_to_dataframe(list(self._buf))

otcat-1.0.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: otcat
+Version: 1.0.0
+Summary: Python bindings for otcat, the netcat for industrial I/O -- reads and writes Modbus TCP through the real Go core.
+Project-URL: Homepage, https://github.com/QuitOperation/otcat
+Project-URL: Go core, https://github.com/QuitOperation/otcat
+Project-URL: Documentation, https://github.com/QuitOperation/otcat/tree/main/python
+Project-URL: Issues, https://github.com/QuitOperation/otcat/issues
+Author-email: Moustafa Mahmoud Atta <MoustafaAt1a@outlook.com>
+License: MIT
+Keywords: automation,ics,industrial,modbus,ot,plc,scada
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: pandas>=1.5; extra == 'all'
+Requires-Dist: streamlit>=1.28; extra == 'all'
+Requires-Dist: uvicorn>=0.23; extra == 'all'
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.28; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.23; extra == 'fastapi'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# otcat (Python)
+
+Python bindings for [otcat](https://github.com/QuitOperation/otcat),
+the netcat for industrial I/O. This package wraps the real, compiled
+Go binary — every Modbus read and write is still executed by the same
+tested, fuzzed Go core the main project's paper describes, not a
+Python reimplementation of the protocol.
+
+```python
+from otcat import Client
+
+c = Client("127.0.0.1:502")
+v = c.read("holding:40001")
+print(v.value, v.quality, v.ts)
+
+for v in c.watch("holding:40001", interval="500ms", count=10):
+    print(v.ts, v.value)
+
+c.write("holding:40001", 100)  # confirm=True by default -- see "Write safety" below
+```
+
+## Install
+
+```sh
+pip install otcat                 # core client only, zero extra dependencies
+pip install otcat[pandas]         # + DataFrame helpers
+pip install otcat[fastapi]        # + the async client's natural home
+pip install otcat[dashboard]      # + Streamlit
+pip install otcat[all]            # everything
+```
+
+The Go binary itself ships bundled inside platform-specific wheels; if
+none is available for your platform, install it separately (`go
+install github.com/QuitOperation/otcat/cmd/otcat@latest`, or one of the
+[Cloudsmith packages](../docs/releasing.md)) and either put it on
+`$PATH` or point `OTCAT_BINARY` at it directly. See
+[`docs/packaging.md`](docs/packaging.md) for exactly how the bundled
+binary is resolved.
+
+## Write safety: one deliberate difference from the CLI
+
+The Go CLI refuses every write by default unless `--confirm` is passed
+or an interactive operator answers a y/N prompt — the right default
+for a human typing a command who might have a typo. `Client.write()`
+defaults to `confirm=True` instead, because a library call is already
+the result of a programmer's code deciding, deliberately, to write a
+specific value; there is no keystroke left to protect against. Pass
+`confirm=False` if you want the stricter behavior and are prepared to
+catch `WriteAbortedError`.
+
+## Modules
+
+| Module | What it's for |
+|---|---|
+| `otcat.Client` | Synchronous read/write/watch/dry_run — the core |
+| `otcat.aio.AsyncClient` | Same API, `asyncio`-native — FastAPI, WebSockets |
+| `otcat.pandas_ext` | `Value` lists ↔ `DataFrame`, plus a bounded `RollingBuffer` for live dashboards |
+| `otcat.alerting` | Threshold rules with debounce → callbacks, for automations and paging |
+| `otcat.audit` | Read-only OT asset discovery / device fingerprinting (never writes — see its module docstring) |
+
+## Examples
+
+See [`examples/`](examples/): a pandas time-series pull, a FastAPI
+service with a live WebSocket, a Streamlit dashboard, a threshold
+alerting script, and a read-only network audit script.
+
+## Exit codes → exceptions
+
+| Go CLI exit code | Python exception |
+|---|---|
+| 1 | `otcat.UsageError` |
+| 2 | `otcat.ConnectionError` |
+| 3 | `otcat.ProtocolError` (`.exception_code` holds the Modbus exception, e.g. `"0x02"`) |
+| 4 | `otcat.WriteAbortedError` |
+| 5 | `otcat.IOFailureError` |
+| (n/a) | `otcat.Timeout` — a Python-side watchdog, distinct from otcat's own `--timeout` |
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Every test is an integration test against a freshly spawned
+`otcat-mockplc` — see `tests/conftest.py`. Building `otcat-mockplc`
+requires a Go 1.22+ toolchain on `$PATH` at test time (the shipped
+wheel itself needs no Go toolchain to *use*, only this repo's test
+suite needs one to build its own test fixture).
+
+## License
+
+MIT — same as the Go core.

otcat-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+otcat/__init__.py,sha256=E-b9-DPbwOLQBBsnW4SydBefRRj6OOgLH4V6ff7dqPQ,1547
+otcat/_binary.py,sha256=N4001fu-m7XyxunqMyCdPCAXy2TGqQi6ub6q7fP85jc,2928
+otcat/aio.py,sha256=1NoWGvy-lWNRvZcZw41Y2-M_eLZyuAgG5azCjr01Xqw,4855
+otcat/alerting.py,sha256=iL0xjQr4bu6B3_LUCwZy4__y7LDVouTxmJCasp9qFxg,6138
+otcat/audit.py,sha256=m_dc-hSfftNBhx0bubRDAtHXEqmIolojEuENihGJda4,6095
+otcat/client.py,sha256=EvCwzx6dddyN1OwG_2v-eoI-m8XaaQx6IhJC1H0y7dk,7341
+otcat/exceptions.py,sha256=8xoy4skJV6qq2XBzDNUhBjp9dfLrsDYA69fGd6YO860,2958
+otcat/models.py,sha256=7lGwkEUI8RM32IjXJt_5eHr_zwPASAv_I2JWkDkfAjs,2366
+otcat/pandas_ext.py,sha256=ns0PdgWk90QTuqK2Qayb3BZkbhTBqqEr3-Xb_4I1QC4,3435
+otcat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+otcat/_bin/otcat-linux-amd64,sha256=0q49tIHzby_EmTIBBA4pWKtBjIT-WgBZM3H81SM52Mk,2363652
+otcat-1.0.0.dist-info/METADATA,sha256=fTo2idXb1mIHSVQngNlACP8d0AOlFpuSEVbh7e7CfCM,5462
+otcat-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+otcat-1.0.0.dist-info/RECORD,,

otcat-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any