iotsploit-protocols 0.0.9__py3-none-any.whl

iotsploit_protocols/canbus/socketcan.py

@@ -0,0 +1,385 @@
+"""One-shot SocketCAN I/O: open, do exactly one thing, close.
+
+This is deliberately not a driver. ``iotsploit_drivers.socketcan`` owns
+discovery, link lifecycle, and a long-lived streaming socket, and it stays that
+way -- borrowing it here would either drag privileged link mutation into a send
+path or add a second mutable "current device" to race against. SocketCAN allows
+several sockets on one interface, so a client here and the driver's monitor
+coexist without contending for the bus.
+
+Two prohibitions are absolute, and they are why this module is small:
+
+*It never changes host networking.* No ``sudo``, no ``ip link``, no bitrate, no
+listen-only, no bringing an interface up. A link is configured outside
+IoTSploit; this opens one that is already up or fails saying so. A tool that
+quietly reconfigures an interface to make its own call succeed has changed the
+vehicle's bus to suit itself.
+
+*It never retries.* One request puts at most one frame on the wire. A retry
+loop around a send that may have already reached an ECU is how one confirmed
+action becomes several unconfirmed ones.
+
+``python-can`` is imported inside the functions that need it, not at module
+scope. It opens platform sockets and reads host configuration on import, and a
+preview must work on a host with no CAN interface at all.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Iterator, Optional
+
+from iotsploit_protocols.canbus.definitions import EncodedFrame
+from iotsploit_protocols.errors import NotConfigured, ProtocolError
+
+#: Linux caps an interface name at IFNAMSIZ-1 and forbids whitespace and '/'.
+#: Checked before opening because python-can reports a bad name as a generic
+#: OSError, which reads as "the bus is down" rather than "that is not a name".
+#: ``\Z`` rather than ``$``: ``$`` also matches just before a trailing
+#: newline, so "can0\n" would pass as a valid name.
+_CHANNEL_RE = re.compile(r"\A[A-Za-z0-9_.:-]{1,15}\Z")
+
+#: What builds the underlying bus. Injected in tests so the deterministic suite
+#: never opens can0, vcan0, or a socket of any kind.
+BusFactory = Callable[..., Any]
+
+
+class CanTransportError(ProtocolError):
+    """The local socket refused the frame.
+
+    Never means an ECU did or did not receive anything. It means this host's
+    CAN stack would not accept the message for transmission, which is a
+    different claim entirely and is the only one a sender can honestly make.
+    """
+
+
+@dataclass(frozen=True)
+class SocketCanConfig:
+    """Where to send, and how long to wait for the socket to take it.
+
+    ``channel`` is the kernel interface name (``can0``), never the device
+    driver's own id (``can_001``). They look similar in a UI and only one of
+    them can be opened.
+    """
+
+    channel: str
+    timeout: float = 1.0
+    #: Whether to open the socket in FD mode. Set from the frame, not guessed:
+    #: a classic socket rejects a 16-byte payload.
+    fd: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.channel, str) or not _CHANNEL_RE.match(self.channel):
+            raise NotConfigured(
+                f"{self.channel!r} is not a usable SocketCAN interface name; "
+                "expected something like 'can0' or 'vcan0'"
+            )
+        if self.timeout is None or self.timeout <= 0:
+            raise NotConfigured(f"send timeout must be positive, not {self.timeout!r}")
+
+
+def _default_bus_factory(**kwargs: Any) -> Any:
+    import can  # imported here: see the module docstring
+
+    return can.Bus(**kwargs)
+
+
+def _build_message(frame: EncodedFrame) -> Any:
+    import can
+
+    return can.Message(
+        arbitration_id=frame.frame_id,
+        is_extended_id=frame.is_extended,
+        is_fd=frame.is_fd,
+        data=frame.data,
+        # check=True makes python-can validate the id against the flag and the
+        # payload length against the frame type before anything reaches the
+        # kernel, so a mismatch is a stated error rather than a silent
+        # truncation on the wire.
+        check=True,
+    )
+
+
+class SocketCanClient:
+    """A socket that exists for the duration of one send.
+
+    Used as a context manager so the socket closes on every path, including the
+    one where the send raised. A leaked SocketCAN socket keeps receiving into a
+    kernel buffer nobody drains.
+    """
+
+    def __init__(
+        self,
+        config: SocketCanConfig,
+        *,
+        bus_factory: Optional[BusFactory] = None,
+    ) -> None:
+        self.config = config
+        self._bus_factory = bus_factory or _default_bus_factory
+        self._bus: Any = None
+
+    def __enter__(self) -> "SocketCanClient":
+        self.open()
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def open(self) -> None:
+        if self._bus is not None:
+            return
+        try:
+            self._bus = self._bus_factory(
+                interface="socketcan",
+                channel=self.config.channel,
+                fd=self.config.fd,
+                # The host's can.conf must not be able to redirect this to
+                # another interface or quietly supply a bitrate.
+                ignore_config=True,
+            )
+        except Exception as error:
+            raise CanTransportError(
+                f"cannot open SocketCAN interface {self.config.channel!r}: {error}. "
+                "The interface has to exist and be up before sending; "
+                "IoTSploit does not configure it."
+            ) from error
+
+    def close(self) -> None:
+        bus, self._bus = self._bus, None
+        if bus is None:
+            return
+        try:
+            bus.shutdown()
+        except Exception:  # noqa: BLE001 - a failed close must not mask the result
+            pass
+
+    def send(self, frame: EncodedFrame) -> None:
+        """Put exactly one frame on the wire.
+
+        Returning normally means the local socket accepted the frame. It does
+        not mean an ECU received it, acted on it, or even that anything was
+        listening -- and no caller may report otherwise.
+        """
+        if self._bus is None:
+            self.open()
+
+        try:
+            message = _build_message(frame)
+        except (ValueError, TypeError) as error:
+            # check=True validates the id against the extended flag and the
+            # payload length against the frame type. It raises from the
+            # constructor rather than from send(), so catching only around the
+            # send would let this escape as a bare ValueError.
+            raise CanTransportError(
+                f"frame 0x{frame.frame_id:X} cannot be represented on a CAN bus: {error}"
+            ) from error
+
+        try:
+            self._bus.send(message, timeout=self.config.timeout)
+        except Exception as error:
+            raise CanTransportError(
+                f"SocketCAN refused frame 0x{frame.frame_id:X} on "
+                f"{self.config.channel!r}: {error}"
+            ) from error
+
+
+@dataclass(frozen=True)
+class CaptureBudget:
+    """When a capture stops, stated two ways because either can run out first.
+
+    A capture with no budget is a leak: it runs inside a worker, and an
+    observation scope needs a run that ends in order to mean anything. The
+    frame budget is the one that saves you on a busy bus, where thirty seconds
+    is millions of frames; the duration is the one that saves you on a silent
+    bus, where the frame budget would never be reached.
+    """
+
+    duration_s: float = 30.0
+    max_frames: int = 200_000
+
+    def __post_init__(self) -> None:
+        if self.duration_s <= 0:
+            raise NotConfigured(f"capture duration must be positive, not {self.duration_s!r}")
+        if self.max_frames <= 0:
+            raise NotConfigured(f"frame budget must be positive, not {self.max_frames!r}")
+
+
+class SocketCanReceiver:
+    """A read-only socket that yields frames until its budget runs out.
+
+    There is no send path here, not even a disabled one. What this cannot do is
+    part of what it is.
+
+    It opens its own socket rather than borrowing the streaming driver's. That
+    is not duplication for its own sake: SocketCAN permits several sockets on
+    one interface, so a capture neither disturbs nor depends on the driver's
+    monitor, and neither one's lifetime is tied to the other's.
+
+    Note for anyone reading this next to the hardware: a CAN controller in
+    normal mode **acknowledges frames it receives, in silicon**. Attaching an
+    interface to a live bus is therefore not electrically inert, whatever this
+    software does or does not send. Listen-only is host link configuration
+    (``ip link set can0 type can listen-only on``) and this class must not set
+    it, for the same reason the sender must not set a bitrate.
+    """
+
+    def __init__(
+        self,
+        config: SocketCanConfig,
+        *,
+        bus_factory: Optional[BusFactory] = None,
+        clock: Optional[Callable[[], float]] = None,
+    ) -> None:
+        self.config = config
+        self._bus_factory = bus_factory or _default_bus_factory
+        self._clock = clock or time.monotonic
+        self._bus: Any = None
+        self._stop = False
+
+    def __enter__(self) -> "SocketCanReceiver":
+        self.open()
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def open(self) -> None:
+        if self._bus is not None:
+            return
+        try:
+            self._bus = self._bus_factory(
+                interface="socketcan",
+                channel=self.config.channel,
+                fd=self.config.fd,
+                ignore_config=True,
+            )
+        except Exception as error:
+            raise CanTransportError(
+                f"cannot open SocketCAN interface {self.config.channel!r} for capture: "
+                f"{error}. The interface has to exist and be up; IoTSploit does not "
+                "configure it."
+            ) from error
+
+    def close(self) -> None:
+        bus, self._bus = self._bus, None
+        if bus is None:
+            return
+        try:
+            bus.shutdown()
+        except Exception:  # noqa: BLE001 - a failed close must not mask the capture
+            pass
+
+    def stop(self) -> None:
+        """Ask the loop to finish at its next opportunity."""
+        self._stop = True
+
+    def frames(
+        self,
+        budget: CaptureBudget,
+        *,
+        check_cancelled: Optional[Callable[[], None]] = None,
+    ) -> Iterator[Any]:
+        """Yield received messages until the budget is spent.
+
+        The socket is closed on every exit path -- normal end, exception, and
+        the consumer abandoning the generator -- because a leaked SocketCAN
+        socket keeps filling a kernel buffer that nobody drains.
+        """
+        if self._bus is None:
+            self.open()
+
+        started = self._clock()
+        deadline = started + budget.duration_s
+        delivered = 0
+        try:
+            while not self._stop and delivered < budget.max_frames:
+                remaining = deadline - self._clock()
+                if remaining <= 0:
+                    break
+                # Bounded by whichever is sooner, so a silent bus still wakes up
+                # to notice its own deadline instead of blocking past it.
+                try:
+                    message = self._bus.recv(timeout=min(remaining, 0.25))
+                except Exception as error:
+                    # SocketCAN binds to an interface that is down and only says
+                    # so at the first read, so a capture that opened cleanly
+                    # still fails here. python-can spells that CanOperationError,
+                    # which is not an OSError: unwrapped it escapes every
+                    # caller's except clause and reaches the operator as a crash.
+                    raise CanTransportError(
+                        f"capture on {self.config.channel!r} failed: {error}. The "
+                        "interface has to stay up for the whole sample; IoTSploit "
+                        "does not configure it."
+                    ) from error
+                if check_cancelled is not None:
+                    check_cancelled()
+                if message is None:
+                    continue
+                delivered += 1
+                yield message
+        finally:
+            self.close()
+
+
+#: ``ARPHRD_CAN`` from ``linux/if_arp.h``. What marks a net device as a CAN
+#: interface rather than an Ethernet one.
+ARPHRD_CAN = 280
+
+
+@dataclass(frozen=True)
+class CanInterface:
+    """A CAN interface this host has, as sysfs describes it."""
+
+    name: str
+    is_up: bool
+    #: ``vcan``/``vxcan`` devices carry no transceiver, so nothing an operator
+    #: does on one can reach a vehicle. Worth saying out loud before a capture.
+    is_virtual: bool
+
+    @property
+    def label(self) -> str:
+        state = "up" if self.is_up else "down"
+        kind = "virtual" if self.is_virtual else "hardware"
+        return f"{self.name} ({kind}, {state})"
+
+
+def list_can_interfaces(sysfs_root: str = "/sys/class/net") -> "list[CanInterface]":
+    """Every CAN interface on this host, newest kernel truth, read-only.
+
+    Reads sysfs rather than shelling out to ``ip`` or asking the device driver.
+    That keeps it unprivileged, keeps it free of the driver's lifecycle -- the
+    plugins must not initialize or connect a device merely to list one -- and
+    means it works when the driver has never been touched.
+
+    An interface that is *down* is still listed. Hiding it would leave an
+    operator wondering why the interface they can see in ``ip link`` is absent
+    here; saying "down" tells them what to fix.
+    """
+    root = Path(sysfs_root)
+    found: list[CanInterface] = []
+    try:
+        entries = sorted(root.iterdir())
+    except OSError:
+        return found
+
+    for entry in entries:
+        try:
+            if int((entry / "type").read_text().strip()) != ARPHRD_CAN:
+                continue
+            operstate = (entry / "operstate").read_text().strip()
+        except (OSError, ValueError):
+            continue
+        found.append(
+            CanInterface(
+                name=entry.name,
+                # vcan reports "unknown" rather than "up"; treat anything that
+                # is not explicitly "down" as usable and let the open fail
+                # honestly if it is not.
+                is_up=operstate != "down",
+                is_virtual=entry.name.startswith(("vcan", "vxcan")),
+            )
+        )
+    return found

iotsploit_protocols/doip/__init__.py

@@ -0,0 +1,22 @@
+"""DoIP transport and UDS diagnostics."""
+
+from __future__ import annotations
+
+__all__ = [
+    "FACET_KEY",
+    "DoipClient",
+    "DoipConfig",
+    "DoipFacet",
+    "DoipUdsClient",
+    "RoutingActivationFailed",
+    "UdsClient",
+    "UdsResponse",
+]
+
+from iotsploit_protocols.doip.client import (
+    DoipClient,
+    DoipConfig,
+    RoutingActivationFailed,
+)
+from iotsploit_protocols.doip.facet import FACET_KEY, DoipFacet
+from iotsploit_protocols.doip.uds import DoipUdsClient, UdsClient, UdsResponse

iotsploit_protocols/doip/client.py

@@ -0,0 +1,267 @@
+"""A DoIP connection: routing activation, framing, one diagnostic exchange.
+
+Replaces the transport half of the old ``DoIP_Mgr``. The differences that
+matter, each of them a defect in what came before:
+
+**Framing follows the length field.** The old code read exactly 13 bytes, slept
+half a second, then read 2048 more. TCP guarantees neither that one ``recv`` is
+one message nor that an acknowledgement arrives alone, so a coalesced or split
+segment silently desynchronized the stream and every subsequent response was
+attributed to the wrong request. Here the 8-byte header is read, its length
+field is believed, and exactly that many bytes follow.
+
+**One client is one connection to one ECU.** The old module exported a
+process-wide singleton, so two ECUs could not be addressed at once and a
+half-open socket poisoned every later caller.
+
+**Nothing here knows about a vehicle.** No default host, no NIC name, no sudo,
+no interactive prompt. A caller supplies a config; an unconfigured target fails
+loudly rather than probing whatever used to live at a hardcoded address.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+from dataclasses import dataclass
+from typing import Optional
+
+from iotsploit_protocols.errors import NotConfigured, ProtocolError
+
+logger = logging.getLogger(__name__)
+
+#: protocol_version, inverse_version, payload_type, payload_length.
+HEADER_LEN = 8
+
+#: ISO 13400-2 version 0x02, followed by its bitwise inverse. The pair is how a
+#: receiver rejects a stream that is not DoIP at all.
+PROTOCOL_VERSION = b"\x02\xfd"
+
+#: The payload types this client uses. ISO 13400-2.
+PT_GENERIC_NACK = 0x0000
+PT_ROUTING_ACTIVATION_REQUEST = 0x0005
+PT_ROUTING_ACTIVATION_RESPONSE = 0x0006
+PT_ALIVE_CHECK_REQUEST = 0x0007
+PT_ALIVE_CHECK_RESPONSE = 0x0008
+PT_DIAGNOSTIC_MESSAGE = 0x8001
+PT_DIAGNOSTIC_ACK = 0x8002
+PT_DIAGNOSTIC_NACK = 0x8003
+
+#: Routing activation response codes worth naming. 0x10 is the only success.
+ROUTING_ACTIVATION_OK = 0x10
+ROUTING_ACTIVATION_CODES = {
+    0x00: "unknown source address",
+    0x01: "all sockets registered and active",
+    0x02: "source address does not match",
+    0x03: "source address already registered",
+    0x04: "missing authentication",
+    0x05: "rejected confirmation",
+    0x06: "unsupported activation type",
+    0x10: "success",
+}
+
+
+class RoutingActivationFailed(ProtocolError):
+    """The gateway refused to route for us. Nothing else can work until it does."""
+
+    def __init__(self, code: int) -> None:
+        self.code = code
+        name = ROUTING_ACTIVATION_CODES.get(code, "unknown")
+        super().__init__(f"routing activation refused: 0x{code:02X} ({name})")
+
+
+@dataclass(frozen=True)
+class DoipConfig:
+    """Where to connect, and which ECU to address.
+
+    ``host`` has no default on purpose. The address it replaces was a function
+    default naming one vehicle's gateway, so an unconfigured bench quietly
+    probed that address and reported its silence as a result.
+    """
+
+    host: str
+    logical_address: int
+    port: int = 13400
+    tester_address: int = 0x0E80
+    activation_type: int = 0x00
+    timeout: float = 5.0
+
+    def __post_init__(self) -> None:
+        if not self.host:
+            raise NotConfigured("DoIP host is required; there is no default")
+        if not 0 < self.port < 65536:
+            raise NotConfigured(f"DoIP port {self.port!r} is out of range")
+        for name in ("logical_address", "tester_address"):
+            value = getattr(self, name)
+            if not 0 <= value <= 0xFFFF:
+                raise NotConfigured(f"DoIP {name} 0x{value:X} is not a 16-bit address")
+
+
+class DoipClient:
+    """One TCP connection to one DoIP entity.
+
+    Use as a context manager: routing activation happens on entry and the socket
+    is closed on exit even when a request raises.
+    """
+
+    def __init__(self, config: DoipConfig) -> None:
+        self.config = config
+        self._sock: Optional[socket.socket] = None
+
+    # ── lifecycle ─────────────────────────────────────────────────────────
+
+    def __enter__(self) -> "DoipClient":
+        self.connect()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def connect(self) -> None:
+        """Open the socket and activate routing.
+
+        Routing activation is not optional politeness: until the gateway accepts
+        it, diagnostic messages are discarded, and the old code's habit of
+        pressing on regardless is why a refused activation looked like a silent
+        ECU.
+        """
+        if self._sock is not None:
+            return
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(self.config.timeout)
+        sock.connect((self.config.host, self.config.port))
+        self._sock = sock
+        logger.debug("DoIP connected to %s:%d", self.config.host, self.config.port)
+        try:
+            self._activate_routing()
+        except Exception:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        if self._sock is None:
+            return
+        try:
+            self._sock.close()
+        except OSError:
+            logger.debug("DoIP socket close failed", exc_info=True)
+        finally:
+            self._sock = None
+
+    @property
+    def connected(self) -> bool:
+        return self._sock is not None
+
+    # ── exchanges ─────────────────────────────────────────────────────────
+
+    def request(self, payload: bytes) -> bytes:
+        """Send one UDS payload to the configured ECU and return the response.
+
+        The positive/negative acknowledgement DoIP interposes (0x8002 / 0x8003)
+        is consumed here rather than handed upward: it says the *gateway* took
+        the message, which is not an answer to the diagnostic request and was
+        the source of the old code's magic offsets.
+        """
+        self._send(PT_DIAGNOSTIC_MESSAGE, self._addresses() + payload)
+        return self.read()
+
+    def read(self) -> bytes:
+        """The next diagnostic response, sending nothing.
+
+        Used by the UDS layer after a responsePending: the ECU will send the
+        real answer by itself, and re-sending the request would perform it
+        twice.
+        """
+        while True:
+            payload_type, body = self._read_message()
+
+            if payload_type == PT_DIAGNOSTIC_ACK:
+                logger.debug("DoIP ack")
+                continue
+            if payload_type == PT_DIAGNOSTIC_NACK:
+                code = body[4] if len(body) > 4 else -1
+                raise ProtocolError(f"DoIP refused the diagnostic message: 0x{code:02X}")
+            if payload_type == PT_ALIVE_CHECK_REQUEST:
+                # Answering keeps the socket registered. Ignoring it, as the old
+                # code did, gets the connection dropped mid-session.
+                self._send(PT_ALIVE_CHECK_RESPONSE, self._addresses()[:2])
+                continue
+            if payload_type == PT_GENERIC_NACK:
+                code = body[0] if body else -1
+                raise ProtocolError(f"DoIP header negative acknowledge: 0x{code:02X}")
+            if payload_type == PT_DIAGNOSTIC_MESSAGE:
+                # source(2) + target(2) then the UDS payload.
+                return body[4:]
+
+            logger.debug("DoIP ignoring payload type 0x%04X", payload_type)
+
+    # ── internals ─────────────────────────────────────────────────────────
+
+    def _addresses(self) -> bytes:
+        return self.config.tester_address.to_bytes(2, "big") + self.config.logical_address.to_bytes(
+            2, "big"
+        )
+
+    def _activate_routing(self) -> None:
+        request = (
+            self.config.tester_address.to_bytes(2, "big")
+            + bytes([self.config.activation_type])
+            + b"\x00\x00\x00\x00"
+        )
+        self._send(PT_ROUTING_ACTIVATION_REQUEST, request)
+
+        payload_type, body = self._read_message()
+        if payload_type != PT_ROUTING_ACTIVATION_RESPONSE:
+            raise ProtocolError(
+                f"expected routing activation response, got payload type 0x{payload_type:04X}"
+            )
+        if len(body) < 5:
+            raise ProtocolError(f"routing activation response truncated: {len(body)} bytes")
+        code = body[4]
+        if code != ROUTING_ACTIVATION_OK:
+            raise RoutingActivationFailed(code)
+        logger.debug("DoIP routing activated for tester 0x%04X", self.config.tester_address)
+
+    def _require_socket(self) -> socket.socket:
+        if self._sock is None:
+            raise ProtocolError("DoIP client is not connected; use it as a context manager")
+        return self._sock
+
+    def _send(self, payload_type: int, body: bytes) -> None:
+        """Header plus body.
+
+        Built by hand rather than through scapy's ``DoIP`` layer, which declares
+        source_address/target_address as *conditional* fields for some payload
+        types: handing it a body that already contains those addresses encodes
+        them twice, once zeroed. The header is four fields and the parser here
+        already reads it directly, so building it directly keeps one definition
+        of the format instead of two that must agree.
+        """
+        header = (
+            PROTOCOL_VERSION
+            + payload_type.to_bytes(2, "big")
+            + len(body).to_bytes(4, "big")
+        )
+        self._require_socket().sendall(header + body)
+
+    def _read_message(self) -> tuple[int, bytes]:
+        """One whole DoIP message: header, then exactly what it declares."""
+        header = self._read_exactly(HEADER_LEN)
+        payload_type = int.from_bytes(header[2:4], "big")
+        declared = int.from_bytes(header[4:HEADER_LEN], "big")
+        if declared > 0xFFFF:
+            # A length this large is a desynchronized stream, not a real message.
+            raise ProtocolError(f"implausible DoIP payload length {declared}")
+        return payload_type, self._read_exactly(declared) if declared else b""
+
+    def _read_exactly(self, count: int) -> bytes:
+        sock = self._require_socket()
+        chunks = []
+        remaining = count
+        while remaining > 0:
+            chunk = sock.recv(remaining)
+            if not chunk:
+                raise ProtocolError(f"DoIP peer closed after {count - remaining} of {count} bytes")
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        return b"".join(chunks)