iotsploit-priv 0.0.9__py3-none-any.whl

iotsploit_priv/__init__.py

@@ -0,0 +1,19 @@
+from iotsploit_priv.client import (
+    INSTALL_HINT,
+    VERB_TABLE_HASH,
+    PrivilegedHelperError,
+    PrivilegedHelperProtocolError,
+    PrivilegedHelperUnavailable,
+    PrivilegedResult,
+    call,
+)
+
+__all__ = [
+    "INSTALL_HINT",
+    "VERB_TABLE_HASH",
+    "PrivilegedHelperError",
+    "PrivilegedHelperProtocolError",
+    "PrivilegedHelperUnavailable",
+    "PrivilegedResult",
+    "call",
+]

iotsploit_priv/client.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SOCKET_PATH = Path("/run/iotsploit/priv.sock")
+MAX_REQUEST_BYTES = 4_096
+MAX_RESPONSE_BYTES = 24_576
+# A VLAN edit can run four commands, each capped at 10 seconds, so a shorter
+# patience here reports a working helper as missing.
+DEFAULT_TIMEOUT_SECONDS = 45.0
+INSTALL_HINT = "Install the IoTSploit privileged helper with `priv install`."
+
+VERB_SCHEMAS = {
+    "can-fd-up": {
+        "iface": "can",
+        "bitrate": "integer",
+        "sample_point": "ratio",
+        "dbitrate": "integer",
+        "dsample_point": "ratio",
+    },
+    "can-link-state": {"iface": "can", "state": ["up", "down"]},
+    "can-up": {"iface": "can", "bitrate": "integer-or-null"},
+    "doip-config": {"iface": "network"},
+    "route-via": {"action": ["add", "delete"], "cidr": "ipv4-/16", "gateway": "ipv4"},
+    "vlan-add": {
+        "parent": "network",
+        "vlan_id": "1-4094",
+        "address": "ipv4-interface",
+        "local_mac": "mac-or-null",
+        "peer_ip": "ipv4-or-null",
+        "peer_mac": "mac-or-null",
+    },
+    "vlan-edit": {
+        "parent": "network",
+        "vlan_id": "1-4094",
+        "address": "ipv4-interface",
+        "local_mac": "mac-or-null",
+        "peer_ip": "ipv4-or-null",
+        "peer_mac": "mac-or-null",
+    },
+    "vlan-delete": {"parent": "network", "vlan_id": "1-4094"},
+}
+VERB_TABLE_HASH = hashlib.sha256(
+    json.dumps(VERB_SCHEMAS, sort_keys=True, separators=(",", ":")).encode()
+).hexdigest()
+
+
+class PrivilegedHelperError(RuntimeError):
+    pass
+
+
+class PrivilegedHelperUnavailable(PrivilegedHelperError):
+    pass
+
+
+class PrivilegedHelperProtocolError(PrivilegedHelperError):
+    pass
+
+
+@dataclass(frozen=True)
+class PrivilegedResult:
+    ok: bool
+    exit: int
+    stdout: str
+    stderr: str
+    output_truncated: bool = False
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise PrivilegedHelperProtocolError(f"duplicate response key: {key}")
+        result[key] = value
+    return result
+
+
+def _decode_response(data: bytes) -> PrivilegedResult:
+    if len(data) > MAX_RESPONSE_BYTES:
+        raise PrivilegedHelperProtocolError("privileged helper response exceeds 24 KiB")
+    if not data.endswith(b"\n") or data.count(b"\n") != 1:
+        raise PrivilegedHelperProtocolError("privileged helper returned an incomplete or trailing response")
+    try:
+        payload = json.loads(data, object_pairs_hook=_unique_object)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise PrivilegedHelperProtocolError("privileged helper returned invalid JSON") from exc
+    if not isinstance(payload, dict):
+        raise PrivilegedHelperProtocolError("privileged helper response must be an object")
+
+    required = {"ok", "exit", "stdout", "stderr"}
+    allowed = required | {"output_truncated"}
+    if set(payload) - allowed or not required.issubset(payload):
+        raise PrivilegedHelperProtocolError("privileged helper returned an unexpected response schema")
+    if type(payload["ok"]) is not bool or type(payload["exit"]) is not int:
+        raise PrivilegedHelperProtocolError("privileged helper returned invalid status fields")
+    if not isinstance(payload["stdout"], str) or not isinstance(payload["stderr"], str):
+        raise PrivilegedHelperProtocolError("privileged helper returned non-string output")
+    truncated = payload.get("output_truncated", False)
+    if type(truncated) is not bool:
+        raise PrivilegedHelperProtocolError("privileged helper returned an invalid truncation flag")
+    return PrivilegedResult(
+        ok=payload["ok"],
+        exit=payload["exit"],
+        stdout=payload["stdout"],
+        stderr=payload["stderr"],
+        output_truncated=truncated,
+    )
+
+
+def call(
+    verb: str,
+    args: dict[str, Any],
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    *,
+    socket_path: str | os.PathLike[str] = DEFAULT_SOCKET_PATH,
+) -> PrivilegedResult:
+    if not isinstance(verb, str) or not verb:
+        raise ValueError("verb must be a non-empty string")
+    if not isinstance(args, dict):
+        raise ValueError("args must be an object")
+    request = json.dumps({"verb": verb, "args": args}, separators=(",", ":"), ensure_ascii=False).encode() + b"\n"
+    if len(request) > MAX_REQUEST_BYTES:
+        raise ValueError("privileged helper request exceeds 4 KiB")
+    if not hasattr(socket, "AF_UNIX"):
+        raise PrivilegedHelperUnavailable("Privileged helper is Linux-only.")
+
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.settimeout(float(timeout))
+    try:
+        client.connect(os.fspath(socket_path))
+        client.sendall(request)
+        client.shutdown(socket.SHUT_WR)
+        response = bytearray()
+        while True:
+            chunk = client.recv(4_096)
+            if not chunk:
+                break
+            response.extend(chunk)
+            if len(response) > MAX_RESPONSE_BYTES:
+                raise PrivilegedHelperProtocolError("privileged helper response exceeds 24 KiB")
+    except PrivilegedHelperProtocolError:
+        raise
+    except (OSError, TimeoutError) as exc:
+        raise PrivilegedHelperUnavailable(f"Privileged helper unavailable. {INSTALL_HINT}") from exc
+    finally:
+        client.close()
+    return _decode_response(bytes(response))

iotsploit_priv/native.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import getpass
+import hashlib
+import json
+import os
+import socket
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from .client import DEFAULT_SOCKET_PATH, VERB_SCHEMAS, VERB_TABLE_HASH
+
+
+SOURCE_ROOT = Path(__file__).resolve().parents[2]
+INSTALLER = SOURCE_ROOT / "install/iotsploit-priv-install"
+DAEMON_SOURCE = SOURCE_ROOT / "privd/iotsploit-privd"
+SYSTEMD_SOURCE = SOURCE_ROOT / "systemd"
+DAEMON_DESTINATION = Path("/usr/local/libexec/iotsploit-privd")
+UNIT_DESTINATIONS = (
+    Path("/etc/systemd/system/iotsploit-privd.socket"),
+    Path("/etc/systemd/system/iotsploit-privd.service"),
+)
+
+
+@dataclass(frozen=True)
+class NativeStatus:
+    code: int
+    lines: tuple[str, ...]
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65_536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def install_manifest() -> tuple[tuple[Path, Path, int], ...]:
+    return (
+        (DAEMON_SOURCE, DAEMON_DESTINATION, 0o755),
+        (SYSTEMD_SOURCE / "iotsploit-privd.socket", UNIT_DESTINATIONS[0], 0o644),
+        (SYSTEMD_SOURCE / "iotsploit-privd.service", UNIT_DESTINATIONS[1], 0o644),
+    )
+
+
+def current_user() -> str:
+    """The account this process runs as -- the one that must reach the socket."""
+    return os.environ.get("SUDO_USER") or getpass.getuser()
+
+
+def _service_identity(service_user: str) -> tuple[int, set[int]]:
+    import pwd
+
+    account = pwd.getpwnam(service_user)
+    return account.pw_uid, set(os.getgrouplist(service_user, account.pw_gid))
+
+
+def _writable_by(path: Path, uid: int, gids: set[int]) -> bool:
+    metadata = path.stat()
+    mode = stat.S_IMODE(metadata.st_mode)
+    if metadata.st_uid == uid:
+        return bool(mode & stat.S_IWUSR)
+    if metadata.st_gid in gids:
+        return bool(mode & stat.S_IWGRP)
+    return bool(mode & stat.S_IWOTH)
+
+
+def _permission_diagnosis(caller: str, helper_group: "grp.struct_group") -> str:
+    """Say which of the two permission failures this is.
+
+    Group membership is fixed when a session starts, so the install can have
+    succeeded while the shell that ran it still cannot reach the socket. That
+    reads as a failed install unless it is named.
+    """
+    if caller in helper_group.gr_mem and helper_group.gr_gid not in os.getgroups():
+        return (
+            f"{caller} is in the iotsploit group, but this session started before that "
+            f"and still carries the old group set -- log out and back in, or run: newgrp iotsploit"
+        )
+    if caller not in helper_group.gr_mem:
+        return (
+            f"{caller} is not in the iotsploit group and cannot reach the socket "
+            f"-- run: priv install --service-user {caller}"
+        )
+    return f"{caller} cannot open the helper socket: permission denied"
+
+
+def _health_probe(socket_path: Path) -> tuple[str, str] | None:
+    """Return None when the daemon answers correctly, else (kind, detail).
+
+    The probe runs as the invoking account, so a permission error here is a
+    statement about the caller's group membership, not about the daemon.
+    """
+    caller = current_user()
+    request = b'{"verb":"status","args":{}}\n'
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.settimeout(2)
+    try:
+        client.connect(os.fspath(socket_path))
+        client.sendall(request)
+        client.shutdown(socket.SHUT_WR)
+        response = client.recv(4_096)
+    except PermissionError:
+        return ("permission", f"{caller} cannot open {socket_path}: permission denied")
+    except OSError as exc:
+        return ("unreachable", f"{caller} cannot reach {socket_path}: {exc}")
+    finally:
+        client.close()
+    try:
+        payload = json.loads(response)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return ("bad-response", "daemon did not return the bounded unknown-verb response")
+    answered = (
+        isinstance(payload, dict)
+        and payload.get("ok") is False
+        and payload.get("exit") == 2
+        and "unknown verb" in payload.get("stderr", "")
+    )
+    if answered:
+        return None
+    return ("bad-response", "daemon did not return the bounded unknown-verb response")
+
+
+def native_status(
+    service_user: str | None = None,
+    *,
+    socket_path: Path = DEFAULT_SOCKET_PATH,
+) -> NativeStatus:
+    if not hasattr(socket, "AF_UNIX"):
+        return NativeStatus(1, ("privileged helper is Linux-only",))
+
+    import grp
+
+    service_user = service_user or current_user()
+    destinations = (DAEMON_DESTINATION, *UNIT_DESTINATIONS)
+    if not any(path.exists() or path.is_symlink() for path in (*destinations, socket_path)):
+        return NativeStatus(1, ("privileged helper is not installed",))
+
+    problems: list[str] = []
+    try:
+        service_uid, service_gids = _service_identity(service_user)
+        helper_group = grp.getgrnam("iotsploit")
+    except KeyError as exc:
+        return NativeStatus(2, (f"missing account or group: {exc}",))
+
+    for source, destination, expected_mode in install_manifest():
+        try:
+            metadata = destination.lstat()
+            if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
+                problems.append(f"{destination} is not a regular file")
+                continue
+            if (metadata.st_uid, metadata.st_gid) != (0, 0):
+                problems.append(f"{destination} is not root:root")
+            if stat.S_IMODE(metadata.st_mode) != expected_mode:
+                problems.append(f"{destination} mode is not {expected_mode:04o}")
+            if sha256_file(source) != sha256_file(destination):
+                problems.append(f"{destination} checksum differs from packaged source")
+            parent = destination.parent
+            while True:
+                if _writable_by(parent, service_uid, service_gids):
+                    problems.append(f"{parent} is writable by {service_user}")
+                if parent == parent.parent:
+                    break
+                parent = parent.parent
+        except (FileNotFoundError, OSError) as exc:
+            problems.append(f"{destination}: {exc}")
+
+    if helper_group.gr_gid not in service_gids:
+        problems.append(f"{service_user} is not a member of iotsploit")
+    try:
+        metadata = socket_path.lstat()
+        if not stat.S_ISSOCK(metadata.st_mode):
+            problems.append(f"{socket_path} is not a socket")
+        if metadata.st_uid != 0 or metadata.st_gid != helper_group.gr_gid:
+            problems.append(f"{socket_path} is not root:iotsploit")
+        if stat.S_IMODE(metadata.st_mode) != 0o660:
+            problems.append(f"{socket_path} mode is not 0660")
+    except OSError as exc:
+        problems.append(f"{socket_path}: {exc}")
+    if not problems:
+        probe_failure = _health_probe(socket_path)
+        if probe_failure:
+            kind, detail = probe_failure
+            problems.append(
+                _permission_diagnosis(current_user(), helper_group) if kind == "permission" else detail
+            )
+
+    if problems:
+        return NativeStatus(2, tuple(problems))
+    members = ", ".join(sorted(set(helper_group.gr_mem))) or "none"
+    return NativeStatus(
+        0,
+        (
+            "privileged helper is healthy",
+            f"iotsploit group members: {members}",
+            f"verb table sha256: {VERB_TABLE_HASH}",
+        ),
+    )
+
+
+def verb_lines() -> tuple[str, ...]:
+    return tuple(
+        f"{verb}: {json.dumps(schema, sort_keys=True, separators=(',', ':'))}"
+        for verb, schema in sorted(VERB_SCHEMAS.items())
+    )

iotsploit_priv-0.0.9.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: iotsploit-priv
+Version: 0.0.9
+Summary: Bounded privileged-operation client for IoTSploit
+License: GPL-3.0-or-later
+Author: IoTSploit Team
+Author-email: support@iotsploit.org
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15

iotsploit_priv-0.0.9.dist-info/RECORD

@@ -0,0 +1,6 @@
+iotsploit_priv/__init__.py,sha256=DxgARFDlOaGAqaKBiOIIFLPNQteKHc_IMYi7DhMuXlg,399
+iotsploit_priv/client.py,sha256=kQWrpQU2AMkinStCVllMyAT5wU5avuYoXg874kGfQ3E,5518
+iotsploit_priv/native.py,sha256=RRTnMQSKCKL5wMkuyjgsWuLUsdGMNgZAGbDTpJFyX3M,7670
+iotsploit_priv-0.0.9.dist-info/METADATA,sha256=t_ZNnlJXbkbcMpkMUURmGKxfDnr5xGcPM1nPKUKS1IU,672
+iotsploit_priv-0.0.9.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+iotsploit_priv-0.0.9.dist-info/RECORD,,

iotsploit_priv-0.0.9.dist-info/WHEEL

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