sylo-plc-comms 0.1.0

package/scripts/_download_allowlist.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Shared download-allowlist loader / membership gate.
+
+The canonical allowlist lives at packages/sylo-logicforge/assets/download-allowlist.json
+and is operator-managed via the LogicForge Settings tab. The agent never edits
+it — the download script reads it and refuses any IP not present and enabled.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def allowlist_path() -> Path:
+    """Allowlist JSON path (env override for project-local testing)."""
+    env = os.environ.get("LOGICFORGE_DOWNLOAD_ALLOWLIST", "").strip()
+    if env:
+        return Path(env).expanduser().resolve()
+    # Canonical file lives with sylo-logicforge (the LogicForge Settings tab
+    # reads/writes it there); resolve across the monorepo so every package
+    # enforces the same operator list.
+    sibling = (
+        Path(__file__).resolve().parents[2]
+        / "sylo-logicforge"
+        / "assets"
+        / "download-allowlist.json"
+    )
+    if sibling.is_file():
+        return sibling
+    return package_root() / "assets" / "download-allowlist.json"
+
+
+def default_allowlist() -> dict[str, Any]:
+    return {
+        "allow_downloads": False,
+        "post_download_mode": "program",
+        "ips": [],
+        "updated_at": None,
+        "notes": "Operator-managed via LogicForge Settings tab.",
+    }
+
+
+def load_allowlist() -> dict[str, Any]:
+    path = allowlist_path()
+    if not path.is_file():
+        return default_allowlist()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return default_allowlist()
+    if not isinstance(data, dict):
+        return default_allowlist()
+    # Normalize / fill missing keys
+    base = default_allowlist()
+    base.update(data)
+    if not isinstance(base.get("ips"), list):
+        base["ips"] = []
+    if base.get("post_download_mode") not in ("program", "run"):
+        base["post_download_mode"] = "program"
+    return base
+
+
+def save_allowlist(data: dict[str, Any]) -> dict[str, Any]:
+    path = allowlist_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = dict(data)
+    data["updated_at"] = datetime.now(timezone.utc).isoformat()
+    if data.get("post_download_mode") not in ("program", "run"):
+        data["post_download_mode"] = "program"
+    if not isinstance(data.get("ips"), list):
+        data["ips"] = []
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return data
+
+
+def _ip_from_comm_path(comm_path: str) -> str | None:
+    """Extract a bare IPv4 from a Rockwell comm path, else None."""
+    import re
+
+    raw = comm_path.strip()
+    # Look for an IPv4 anywhere in the path
+    m = re.search(r"\b\d{1,3}(?:\.\d{1,3}){3}\b", raw)
+    return m.group(0) if m else None
+
+
+def check_ip_allowed(ip_or_comm: str, allowlist: dict[str, Any] | None = None) -> tuple[bool, str]:
+    """Return (allowed, reason). Resolves bare IP from a comm path if needed."""
+    al = allowlist if allowlist is not None else load_allowlist()
+    if not al.get("allow_downloads", False):
+        return False, "Downloads are disabled in the allowlist (allow_downloads=false)."
+
+    ip = ip_or_comm.strip()
+    if "\\" in ip or "/" in ip:
+        ip = _ip_from_comm_path(ip) or ip
+
+    for entry in al.get("ips", []):
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("ip") == ip:
+            if entry.get("enabled", True):
+                return True, ip
+            return False, f"IP {ip} is in the allowlist but disabled."
+    return False, f"IP {ip} is not in the download allowlist. The agent cannot download to it."

package/scripts/_json_out.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Shared JSON stdout helpers for sylo-plc-comms scripts."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def emit(payload: dict[str, Any]) -> None:
+    """Print JSON to stdout and exit with code 0 or 1."""
+    print(json.dumps(payload, indent=2))
+    if payload.get("ok") is False:
+        sys.exit(1)
+
+
+def emit_error(message: str, **extra: Any) -> None:
+    emit({"ok": False, "error": message, **extra})

package/scripts/_opcua_client.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Shared asyncua (OPC UA client) helpers for sylo-plc-comms scripts.
+
+asyncua is async, so each script wraps a coroutine in asyncio.run(). This
+helper centralizes endpoint connect, namespace resolution, node-id parsing,
+and JSON coercion of OPC UA variant values.
+
+Rockwell Logix OPC UA server conventions:
+  - Default endpoint: opc.tcp://<ip>:4840
+  - The user tags live in the namespace named "Tags" (namespace index 2 on
+    most 5380/5580 controllers). Tags are String NodeIds whose identifier is
+    the full tag path, e.g. ns=2;s=MyTag  or  ns=2;s=Program:MainProgram.MyTag
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from _json_out import emit_error
+
+
+def ensure_asyncua() -> str:
+    """pip-install asyncua if not importable. Returns a status string."""
+    try:
+        import asyncua  # noqa: F401
+
+        return "already_importable"
+    except ImportError:
+        pass
+
+    import subprocess
+    import sys
+
+    subprocess.check_call(
+        [sys.executable, "-m", "pip", "install", "asyncua", "--quiet"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return "installed"
+
+
+def default_endpoint(ip: str, port: int = 4840, path: str = "") -> str:
+    base = f"opc.tcp://{ip}:{port}"
+    return f"{base}{path}" if path else base
+
+
+async def connect(endpoint: str, timeout: float = 10.0):
+    """Open an asyncua Client and return it. Caller must `await client.close()`
+    (prefer `async with`). On failure, emit_error + exit."""
+    from asyncua import Client
+
+    client = Client(url=endpoint, timeout=timeout)
+    try:
+        await client.connect()
+    except Exception as exc:
+        msg = str(exc).strip() or type(exc).__name__
+        emit_error(f"OPC UA connect failed to {endpoint}: {msg}")
+    return client
+
+
+async def namespaces(client) -> list[dict[str, Any]]:
+    """Return [{index, uri}] for the server."""
+    try:
+        uris = await client.get_namespace_array()
+    except Exception as exc:
+        emit_error(f"get_namespace_array failed: {exc}")
+        return []
+    return [{"index": i, "uri": u} for i, u in enumerate(uris)]
+
+
+async def tags_namespace_index(client) -> int | None:
+    """Find the namespace index whose URI ends with 'Tags' (Rockwell convention).
+    Falls back to index 2 if no match."""
+    ns = await namespaces(client)
+    for entry in ns:
+        uri = str(entry["uri"])
+        if uri.rstrip("/").endswith("Tags"):
+            return entry["index"]
+    return 2 if len(ns) > 2 else None
+
+
+def parse_node_id(spec: str, default_ns: int = 2):
+    """Parse a node id spec into an asyncua ua.NodeId.
+
+    Accepted forms:
+      "ns=2;s=MyTag"          -> NodeId("MyTag", 2, StringNodeId)
+      "MyTag"                 -> NodeId("MyTag", default_ns)
+      "ns=3;i=1001"           -> NodeId(1001, 3, NumericNodeId)
+    """
+    from asyncua import ua
+
+    spec = spec.strip()
+    ns = default_ns
+    if "ns=" in spec:
+        parts = {p.split("=", 1)[0]: p.split("=", 1)[1] for p in spec.split(";") if "=" in p}
+        ns = int(parts.get("ns", default_ns))
+        if "s" in parts:
+            return ua.NodeId(parts["s"], ns)
+        if "i" in parts:
+            return ua.NodeId(int(parts["i"]), ns, ua.NodeIdType.Numeric)
+        if "b" in parts:
+            return ua.NodeId(bytes.fromhex(parts["b"]), ns, ua.NodeIdType.ByteString)
+        if "g" in parts:
+            return ua.NodeId(parts["g"], ns, ua.NodeIdType.Guid)
+    # Bare identifier -> string node id in default namespace
+    if spec.isdigit():
+        return ua.NodeId(int(spec), ns, ua.NodeIdType.Numeric)
+    return ua.NodeId(spec, ns)
+
+
+def jsonable(v: Any) -> Any:
+    """Coerce OPC UA variant values to JSON-friendly Python types."""
+    if v is None:
+        return None
+    if isinstance(v, (str, int, float, bool)):
+        return v
+    if isinstance(v, bytes):
+        try:
+            return v.decode("utf-8", errors="replace")
+        except Exception:
+            return v.hex()
+    if isinstance(v, (list, tuple)):
+        return [jsonable(x) for x in v]
+    if isinstance(v, dict):
+        return {str(k): jsonable(val) for k, val in v.items()}
+    # Extension objects / datetimes / enums -> string
+    try:
+        import datetime
+        if isinstance(v, datetime.datetime):
+            return v.isoformat()
+    except Exception:
+        pass
+    return str(v)
+
+
+# Map common OPC UA browse names / NodeId types to a short type label
+def variant_type_label(vt) -> str:
+    try:
+        return str(vt.name if hasattr(vt, "name") else vt)
+    except Exception:
+        return str(vt)

package/scripts/cip_plc_info.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Full PLC controller attributes via ciplogix (read-only CIP Identity + attrs).
+
+Richer than plc_status.py (which is the pre-download keyswitch check). This is
+the agent-facing "tell me about this controller" tool.
+
+Usage:
+  py -3.12 cip_plc_info.py --ip 10.1.200.45
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from _cip_client import ensure_ciplogix, open_driver, plc_info_dict
+from _download_allowlist import load_allowlist
+from _json_out import emit
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Full PLC controller info via ciplogix")
+    parser.add_argument("--ip", required=True, help="Controller IPv4 address")
+    args = parser.parse_args()
+
+    try:
+        ensure_ciplogix()
+    except Exception as exc:
+        from _json_out import emit_error
+        emit_error(f"ciplogix setup failed: {exc}")
+
+    plc = open_driver(args.ip, init_tags=False)
+    try:
+        info = plc_info_dict(plc)
+        info["ip"] = args.ip
+        info["reachable"] = True
+        info["error"] = None
+    except Exception as exc:
+        plc.close()
+        from _json_out import emit_error
+        emit_error(f"get_plc_info failed: {exc}")
+        return
+    finally:
+        try:
+            plc.close()
+        except Exception:
+            pass
+
+    allowlist = load_allowlist()
+    info["in_allowlist"] = any(
+        isinstance(e, dict) and e.get("ip") == args.ip and e.get("enabled", True)
+        for e in allowlist.get("ips", [])
+    )
+    emit({"ok": True, **info})
+
+
+if __name__ == "__main__":
+    main()

package/scripts/cip_tag_list.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""List controller (and program) tags from a Logix PLC via ciplogix.
+
+Read-only. init_tags=True pulls the full tag list including UDT/struct layout;
+this is the same call ciplogix makes on connect when init_tags=True, just
+exposed explicitly. Optionally filter by substring and/or include program tags.
+
+Usage:
+  py -3.12 cip_tag_list.py --ip 10.1.200.45
+  py -3.12 cip_tag_list.py --ip 10.1.200.45 --filter IA00 --include-programs
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from _cip_client import ensure_ciplogix, normalize_tag_entry, open_driver
+from _json_out import emit, emit_error
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="List Logix controller tags via ciplogix")
+    parser.add_argument("--ip", required=True, help="Controller IPv4 address")
+    parser.add_argument("--filter", default="", help="Optional case-insensitive tag-name substring filter")
+    parser.add_argument(
+        "--include-programs",
+        action="store_true",
+        help="Also list program-scoped tags (one extra round trip per program)",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=0,
+        help="Cap number of tags returned (0 = no cap). Apply after filtering.",
+    )
+    args = parser.parse_args()
+
+    try:
+        ensure_ciplogix()
+    except Exception as exc:
+        emit_error(f"ciplogix setup failed: {exc}")
+
+    plc = open_driver(args.ip, init_tags=True)
+    try:
+        flt = (args.filter or "").strip().lower()
+        try:
+            raw_tags = plc.get_tag_list()
+        except Exception as exc:
+            emit_error(f"get_tag_list failed: {exc}")
+            return
+
+        tags = [normalize_tag_entry(t) for t in raw_tags]
+
+        program_tags: list[dict] = []
+        if args.include_programs:
+            try:
+                programs = plc.get_programs()  # type: ignore[attr-defined]
+            except Exception:
+                programs = []
+            for prog in programs:
+                prog_name = prog if isinstance(prog, str) else getattr(prog, "name", str(prog))
+                try:
+                    p_raw = plc.get_tag_list(program=prog_name)
+                except Exception:
+                    p_raw = []
+                for t in p_raw:
+                    t["program"] = prog_name
+                    program_tags.append(normalize_tag_entry(t))
+
+        all_tags = tags + program_tags
+        if flt:
+            all_tags = [
+                t for t in all_tags
+                if flt in (str(t.get("tag_name") or "").lower())
+                or flt in (str(t.get("program") or "").lower())
+            ]
+        total = len(all_tags)
+        if args.limit and args.limit > 0:
+            all_tags = all_tags[: args.limit]
+
+        emit({
+            "ok": True,
+            "ip": args.ip,
+            "controller_tag_count": len(tags),
+            "program_tag_count": len(program_tags),
+            "total_matching": total,
+            "returned": len(all_tags),
+            "truncated": total > len(all_tags),
+            "tags": all_tags,
+        })
+    finally:
+        try:
+            plc.close()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/scripts/cip_tag_read.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Read one or many Logix tags from a PLC via ciplogix (read-only).
+
+Accepts a JSON list of tag names on stdin (--tags-json also accepted). Uses
+ciplogix multi-service read when more than one tag is given. Returns per-tag
+value + error. Bit/array element syntax follows pycomm3 conventions:
+  MyTag, MyTag.0, MyArray[3], MyStruct.Member, Program:MainProgram.MyTag
+
+Usage:
+  py -3.12 cip_tag_read.py --ip 10.1.200.45 --tags "MyDint,MyBool.0"
+  echo '["MyDint","MyReal"]' | py -3.12 cip_tag_read.py --ip 10.1.200.45 --stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from _cip_client import ensure_ciplogix, open_driver
+from _json_out import emit, emit_error
+
+
+def _coerce_value(v):
+    """Make ciplogix tag values JSON-serializable (bytes, structs, datetimes)."""
+    if v is None:
+        return None
+    if isinstance(v, (str, int, float, bool)):
+        return v
+    if isinstance(v, bytes):
+        try:
+            return v.decode("utf-8", errors="replace")
+        except Exception:
+            return list(v)
+    if isinstance(v, (list, tuple)):
+        return [_coerce_value(x) for x in v]
+    if isinstance(v, dict):
+        return {str(k): _coerce_value(val) for k, val in v.items()}
+    # pycomm3 struct Tag objects / datetime / enum -> string-ish
+    return str(v)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Read Logix tags via ciplogix")
+    parser.add_argument("--ip", required=True, help="Controller IPv4 address")
+    parser.add_argument("--tags", default="", help="Comma-separated tag names")
+    parser.add_argument("--tags-json", default="", help="JSON array of tag names")
+    parser.add_argument("--stdin", action="store_true", help="Read JSON array of tags from stdin")
+    args = parser.parse_args()
+
+    # Resolve tag list
+    names: list[str] = []
+    if args.stdin:
+        raw = sys.stdin.read().strip()
+        try:
+            parsed = json.loads(raw) if raw else []
+        except json.JSONDecodeError as exc:
+            emit_error(f"stdin is not valid JSON: {exc}")
+            return
+        if not isinstance(parsed, list):
+            emit_error("stdin JSON must be an array of tag name strings.")
+            return
+        names = [str(x).strip() for x in parsed if str(x).strip()]
+    if args.tags_json:
+        try:
+            parsed = json.loads(args.tags_json)
+        except json.JSONDecodeError as exc:
+            emit_error(f"--tags-json is not valid JSON: {exc}")
+            return
+        names.extend(str(x).strip() for x in parsed if str(x).strip())
+    if args.tags:
+        names.extend(x.strip() for x in args.tags.split(",") if x.strip())
+
+    names = [n for n in names if n]
+    if not names:
+        emit_error("No tag names supplied. Use --tags, --tags-json, or --stdin.")
+
+    try:
+        ensure_ciplogix()
+    except Exception as exc:
+        emit_error(f"ciplogix setup failed: {exc}")
+
+    plc = open_driver(args.ip, init_tags=True)
+    try:
+        results: list[dict] = []
+        try:
+            resp = plc.read(*names)
+        except Exception as exc:
+            # All-failed path — still emit one error row per tag so the caller
+            # can see which tags were attempted.
+            for n in names:
+                results.append({"tag": n, "ok": False, "value": None, "error": str(exc)})
+            emit({"ok": True, "ip": args.ip, "results": results, "all_failed": True})
+            return
+
+        # plc.read returns a single Tag when one name, or a list of Tags when many.
+        resp_list = resp if isinstance(resp, list) else [resp]
+        for name, tag in zip(names, resp_list):
+            err = None
+            try:
+                err = getattr(tag, "error", None)
+                if not err and getattr(tag, "status", None) not in (None, "", "Success"):
+                    err = str(getattr(tag, "status"))
+            except Exception:
+                pass
+            results.append({
+                "tag": name,
+                "ok": not err,
+                "value": _coerce_value(getattr(tag, "value", None)),
+                "error": err,
+                "type": getattr(tag, "tag_type", None) or getattr(tag, "data_type_name", None),
+            })
+        ok_count = sum(1 for r in results if r["ok"])
+        emit({
+            "ok": True,
+            "ip": args.ip,
+            "requested": len(names),
+            "succeeded": ok_count,
+            "failed": len(names) - ok_count,
+            "results": results,
+        })
+    finally:
+        try:
+            plc.close()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()