iotsploit-protocols 0.0.9__py3-none-any.whl

iotsploit_protocols/canbus/definitions.py

@@ -0,0 +1,252 @@
+"""What a target says about one CAN frame, frozen and free of storage detail.
+
+A target holds CAN frames in two places for historical reasons: ARXML frames
+and transmitter-less DBC frames sit under ``bus.properties.messages``, while
+transmitter-attributed DBC frames sit under ``component.facets.can.messages``.
+Those are different JSON shapes describing the same wire, and every consumer
+that reads them directly grows its own opinion about which fields exist.
+
+These types are the single shape everything downstream works in. The catalogue
+converts both storage forms into them once; the codec, the composer plugin, the
+live capture, and the UI all read them and never touch the raw target again.
+
+Nothing here validates a bit layout. That is the codec's job, because the
+authority on whether a signal fits is ``cantools``, and duplicating its rules
+here would produce a second answer to the same question.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple
+
+#: Frame ids wider than these cannot be put on a wire. Standard CAN carries an
+#: 11-bit identifier and extended CAN a 29-bit one.
+MAX_STANDARD_FRAME_ID = 0x7FF
+MAX_EXTENDED_FRAME_ID = 0x1FFFFFFF
+
+
+@dataclass(frozen=True)
+class SignalDefinition:
+    """One field packed into a frame's payload.
+
+    Carries everything needed to rebuild a ``cantools`` signal and nothing that
+    only describes where it was stored. ``factor`` and ``offset`` convert raw
+    to physical: ``physical = raw * factor + offset``.
+    """
+
+    name: str
+    start_bit: int
+    length: int
+    #: ``"little"`` (Intel, DBC ``@1``) or ``"big"`` (Motorola, DBC ``@0``).
+    byte_order: str = "little"
+    signed: bool = False
+    factor: float = 1.0
+    offset: float = 0.0
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    unit: str = ""
+    #: ``"M"`` for the switch, ``"m3"`` or ``"m3,m4"`` for a branch signal.
+    multiplexer: Optional[str] = None
+    #: Which switch selects this branch signal. Only load-bearing when a frame
+    #: has more than one multiplexer, but stored always so it never has to be
+    #: inferred from position.
+    multiplexer_signal: Optional[str] = None
+    choices: Optional[Mapping[int, str]] = None
+    is_float: bool = False
+
+    @property
+    def is_multiplexer(self) -> bool:
+        """Whether this signal selects which branch signals are present."""
+        return self.multiplexer == "M"
+
+    @property
+    def multiplexer_ids(self) -> Tuple[int, ...]:
+        """The switch values this signal is present for.
+
+        Empty for ordinary signals and for the switch itself. ARXML joins
+        several with commas because one signal can belong to more than one
+        branch; DBC only ever writes a single value.
+        """
+        if not self.multiplexer or self.multiplexer == "M":
+            return ()
+        ids = []
+        for token in self.multiplexer.split(","):
+            token = token.strip()
+            if token.startswith("m") and token[1:].lstrip("-").isdigit():
+                ids.append(int(token[1:]))
+        return tuple(ids)
+
+
+@dataclass(frozen=True)
+class FrameDefinition:
+    """One frame on one bus, with where it came from attached.
+
+    ``(bus_id, frame_id, is_extended)`` is the identity. A name is not: the
+    same name legitimately appears on two buses, and 0x123 standard and 0x123
+    extended are different frames sharing a wire.
+
+    ``unsupported_reason`` is set rather than raised so that a frame the
+    composer cannot encode is still listable. The UI shows it as a disabled row
+    explaining itself, which is more useful than omitting it and leaving the
+    operator to wonder where it went.
+    """
+
+    bus_id: str
+    frame_id: int
+    is_extended: bool
+    name: str
+    dlc: int
+    signals: Tuple[SignalDefinition, ...] = ()
+    is_fd: bool = False
+    senders: Tuple[str, ...] = ()
+    cycle_time_ms: Optional[int] = None
+    #: ``"bus"`` or ``"component"`` -- which storage location this came from.
+    owner_kind: str = "bus"
+    component_id: Optional[str] = None
+    component_name: Optional[str] = None
+    #: Index in the list it was read from, so a diagnostic can point at the row.
+    source_index: int = 0
+    #: AUTOSAR container payloads, kept only to detect and refuse one.
+    contained_messages: Tuple[Mapping[str, Any], ...] = ()
+    unsupported_reason: Optional[str] = None
+
+    @property
+    def is_supported(self) -> bool:
+        return self.unsupported_reason is None
+
+    @property
+    def frame_id_hex(self) -> str:
+        return f"0x{self.frame_id:X}"
+
+    @property
+    def multiplexer_signal_name(self) -> Optional[str]:
+        """The name of this frame's switch signal, if it has one."""
+        for signal in self.signals:
+            if signal.is_multiplexer:
+                return signal.name
+        return None
+
+    def signal(self, name: str) -> Optional[SignalDefinition]:
+        for signal in self.signals:
+            if signal.name == name:
+                return signal
+        return None
+
+    def encoding_key(self) -> Tuple[Any, ...]:
+        """Everything that changes the bytes on the wire, and nothing else.
+
+        Two rows describing one frame are duplicates when this matches. Where
+        they came from, who sends them, and how often deliberately do not
+        appear: two components declaring the same frame identically is
+        ordinary, and treating that as a conflict would make half the DBCs in
+        the world unusable.
+        """
+        return (
+            self.frame_id,
+            self.is_extended,
+            self.is_fd,
+            self.name,
+            self.dlc,
+            tuple(
+                (
+                    s.name,
+                    s.start_bit,
+                    s.length,
+                    s.byte_order,
+                    s.signed,
+                    s.factor,
+                    s.offset,
+                    s.unit,
+                    s.multiplexer,
+                    s.multiplexer_signal,
+                    s.is_float,
+                    tuple(sorted((s.choices or {}).items())),
+                )
+                for s in self.signals
+            ),
+            bool(self.contained_messages),
+        )
+
+
+@dataclass(frozen=True)
+class BusDefinition:
+    """A CAN bus and the frames resolved onto it."""
+
+    bus_id: str
+    name: str
+    frames: Tuple[FrameDefinition, ...] = ()
+    #: Identities that resolved to more than one incompatible definition.
+    #: Listed separately because they are findings about the target, not
+    #: frames anyone can use.
+    conflicts: Tuple[str, ...] = ()
+
+    def frame(self, frame_id: int, is_extended: bool) -> Optional[FrameDefinition]:
+        for candidate in self.frames:
+            if candidate.frame_id == frame_id and candidate.is_extended == is_extended:
+                return candidate
+        return None
+
+
+@dataclass(frozen=True)
+class EncodedFrame:
+    """The bytes a frame encodes to, with the flags needed to put them on a wire."""
+
+    frame_id: int
+    is_extended: bool
+    is_fd: bool
+    dlc: int
+    data: bytes
+    name: str
+    #: Values after normalization: choice labels resolved, numeric text parsed,
+    #: nothing echoed back as the operator typed it.
+    signals: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def data_hex(self) -> str:
+        return self.data.hex().upper()
+
+
+@dataclass(frozen=True)
+class DecodedFrame:
+    """The result of reading bytes against a definition.
+
+    Never raised, always returned, because the bytes come off a wire and a
+    capture that dies on one malformed frame is not a capture. ``ok`` says
+    which half of this object is meaningful.
+    """
+
+    ok: bool
+    name: str
+    signals: Dict[str, Any] = field(default_factory=dict)
+    #: Raw integers behind any named choice, so a code missing from the value
+    #: table is reported as the number it was rather than lost.
+    raw_values: Dict[str, int] = field(default_factory=dict)
+    reason: Optional[str] = None
+
+    @classmethod
+    def failed(cls, name: str, reason: str) -> "DecodedFrame":
+        return cls(ok=False, name=name, reason=reason)
+
+
+def canonical_frame_id(frame_id: int, is_extended: bool = False) -> str:
+    """The string form of a frame id, matching the CAN facet's own function.
+
+    Duplicated from ``iotsploit_django.tools.can_facet`` on purpose: this
+    package must not import Django, and an observation's ``subject_id`` has to
+    join across both. Uppercase hex, no ``0x``, zero-padded to the width of the
+    id space -- three digits standard, eight extended -- so a standard 0x123
+    and an extended 0x123 stay distinct keys.
+    """
+    return f"{frame_id:0{8 if is_extended else 3}X}"
+
+
+def frame_id_is_valid(frame_id: int, is_extended: bool) -> bool:
+    """Whether a frame id fits the identifier width it claims."""
+    if not isinstance(frame_id, int) or isinstance(frame_id, bool) or frame_id < 0:
+        return False
+    return frame_id <= (MAX_EXTENDED_FRAME_ID if is_extended else MAX_STANDARD_FRAME_ID)
+
+
+def signals_by_name(signals: Sequence[SignalDefinition]) -> Dict[str, SignalDefinition]:
+    return {signal.name: signal for signal in signals}

iotsploit_protocols/canbus/errorframes.py

@@ -0,0 +1,154 @@
+"""Telling a bus fault apart from a frame, before anything reads an address.
+
+A SocketCAN socket delivers bus faults as *error frames*, and python-can turns
+them on by default (``CAN_RAW_ERR_FILTER``). They are not messages. The
+``CAN_ERR_FLAG`` lives in the CAN ID, and python-can masks it off before it
+exposes ``arbitration_id``, so what is left there is an error *class*, not an
+address: ``CAN_ERR_CRTL`` arrives looking exactly like a frame with id ``0x004``
+whose ``data[1]`` happens to be the controller status.
+
+Anything that keys on ``(arbitration_id, is_extended)`` without testing
+``is_error_frame`` first therefore invents a frame ``0x004`` no ECU ever sent
+and counts bus faults as traffic. For a capture that writes observations the
+consequence is worse than a wrong number on a screen: it records that phantom
+frame as a documented-versus-observed finding against the target.
+
+Why this exists twice
+---------------------
+``iotsploit_drivers.socketcan.can_errors`` holds the same constants, and the
+duplication is deliberate rather than an oversight. ``iotsploit-drivers``
+depends on ``iotsploit-core`` alone, and the dependency direction both CAN plans
+fix is ``exploits -> protocols -> core``; importing the driver package from here
+would add an edge neither plan sanctions, to reach nine integers out of
+``linux/can/error.h`` that have not changed since 2007. The precedent is
+``canonical_frame_id``, duplicated for the same reason.
+
+The two are not redundant in what they produce. The driver formats a
+``candump -e`` style description for a live stream; a capture needs a per-class
+tally it can total over a window. They share the vocabulary, not the output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Mapping, Tuple
+
+# Error class, carried in the masked arbitration id. linux/can/error.h.
+CAN_ERR_TX_TIMEOUT = 0x001
+CAN_ERR_LOSTARB = 0x002
+CAN_ERR_CRTL = 0x004
+CAN_ERR_PROT = 0x008
+CAN_ERR_TRX = 0x010
+CAN_ERR_ACK = 0x020
+CAN_ERR_BUSOFF = 0x040
+CAN_ERR_BUSERROR = 0x080
+CAN_ERR_RESTARTED = 0x100
+
+ERROR_CLASSES: Dict[int, str] = {
+    CAN_ERR_TX_TIMEOUT: "tx-timeout",
+    CAN_ERR_LOSTARB: "lost-arbitration",
+    CAN_ERR_CRTL: "controller-problem",
+    CAN_ERR_PROT: "protocol-violation",
+    CAN_ERR_TRX: "transceiver-status",
+    CAN_ERR_ACK: "no-acknowledgement-on-tx",
+    CAN_ERR_BUSOFF: "bus-off",
+    CAN_ERR_BUSERROR: "bus-error",
+    CAN_ERR_RESTARTED: "controller-restarted",
+}
+
+#: Controller status, ``data[1]``. These are the ones worth surfacing to an
+#: operator: a bus sitting at error-passive is saying the bitrate is wrong, the
+#: FD configuration is wrong, or the wiring is wrong -- which is the actual
+#: explanation for a capture that "sees nothing".
+CONTROLLER_STATUS: Dict[int, str] = {
+    0x01: "rx-overflow",
+    0x02: "tx-overflow",
+    0x04: "rx-error-warning",
+    0x08: "tx-error-warning",
+    0x10: "rx-error-passive",
+    0x20: "tx-error-passive",
+    0x40: "back-to-error-active",
+}
+
+#: Statuses that mean the link is degraded rather than merely noisy. A capture
+#: whose data-frame count is low and whose faults are these must say so instead
+#: of reporting an empty bus.
+DEGRADED_STATUSES = frozenset(
+    {"rx-error-passive", "tx-error-passive", "rx-error-warning", "tx-error-warning"}
+)
+
+
+@dataclass(frozen=True)
+class ErrorFrame:
+    """One classified fault, reduced to what a tally needs."""
+
+    classes: Tuple[str, ...]
+    controller_status: Tuple[str, ...] = ()
+
+    @property
+    def labels(self) -> Tuple[str, ...]:
+        """Every name this fault should be counted under."""
+        return self.classes + self.controller_status
+
+    @property
+    def is_degraded(self) -> bool:
+        return "bus-off" in self.classes or any(
+            status in DEGRADED_STATUSES for status in self.controller_status
+        )
+
+
+def _flag_names(mapping: Mapping[int, str], value: int) -> List[str]:
+    return [name for bit, name in sorted(mapping.items()) if value & bit]
+
+
+def classify_error_frame(arbitration_id: int, data: Any = None) -> ErrorFrame:
+    """Read an error frame's class, and the controller status when it has one.
+
+    ``arbitration_id`` is what python-can exposes after masking off
+    ``CAN_ERR_FLAG``: a bitmask of error classes, never an address.
+
+    Never raises. A live capture is a long-running loop, so a message-shaped
+    object carrying something other than an ``int`` and ``bytes`` degrades to
+    ``unknown-error-class`` rather than ending the capture.
+    """
+    try:
+        flags = int(arbitration_id or 0)
+    except (TypeError, ValueError):
+        flags = 0
+
+    classes = tuple(_flag_names(ERROR_CLASSES, flags))
+    if not classes:
+        classes = ("unknown-error-class",)
+
+    status: Tuple[str, ...] = ()
+    if flags & CAN_ERR_CRTL:
+        # An int is excluded rather than coerced: bytes(n) would allocate n
+        # zero bytes, which is both a wrong reading and a way to exhaust a
+        # long-running capture's memory from one malformed message.
+        try:
+            payload = b"" if isinstance(data, int) else bytes(data or b"")
+        except (TypeError, ValueError):
+            payload = b""
+        if len(payload) > 1:
+            status = tuple(_flag_names(CONTROLLER_STATUS, payload[1]))
+
+    return ErrorFrame(classes=classes, controller_status=status)
+
+
+def is_error_frame(message: Any) -> bool:
+    """Whether this is a fault rather than traffic.
+
+    Read before identity, always. A message object that does not carry the
+    attribute is treated as traffic, which is the safe default for a scripted
+    frame source in a test.
+    """
+    return bool(getattr(message, "is_error_frame", False))
+
+
+def is_remote_frame(message: Any) -> bool:
+    """Whether this is a remote request rather than a data frame.
+
+    Its own category: a remote frame carries no payload, and counting it as a
+    zero-length data frame would report a frame whose signals are all zero.
+    """
+    return bool(getattr(message, "is_remote_frame", False))

iotsploit_protocols/canbus/errors.py

@@ -0,0 +1,47 @@
+"""Errors the CAN catalogue and codec raise.
+
+Two types, split the way :mod:`iotsploit_protocols.errors` splits its three:
+by what the caller can do about it.
+
+``CanDefinitionError``  the target is wrong -- fix the ARXML, DBC, or facet.
+``CanValueError``       the operator's input is wrong -- fix the value.
+
+The difference is not cosmetic. A definition error means no value would have
+worked and the form should say so once, at the top; a value error belongs
+against the signal row that caused it, which is why it carries a field map.
+
+Transport failures are deliberately absent. The house rule in
+:mod:`iotsploit_protocols.errors` is that a connection failure stays
+``OSError`` rather than being re-spelled. ``python-can`` does not follow it: a
+SocketCAN interface that is down surfaces as ``can.CanOperationError``, which
+is not an ``OSError``, so :mod:`iotsploit_protocols.canbus.socketcan` wraps it
+in ``CanTransportError`` rather than let a caller's ``except OSError`` miss it.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from iotsploit_protocols.errors import ProtocolError
+
+
+class CanDefinitionError(ProtocolError):
+    """The target cannot describe the requested frame.
+
+    Covers absent, ambiguous, conflicting, and unsupported definitions. The
+    caller cannot fix any of them by changing a signal value, which is what
+    separates this from :class:`CanValueError`.
+    """
+
+
+class CanValueError(ProtocolError):
+    """A supplied signal value is missing, unknown, or out of range.
+
+    ``field_errors`` maps a dotted path (``signals.VehicleSpeed``) to a message
+    about that one field, so an editor can put the text next to the input that
+    caused it instead of showing one opaque failure for the whole frame.
+    """
+
+    def __init__(self, message: str, field_errors: Optional[Dict[str, str]] = None) -> None:
+        self.field_errors: Dict[str, str] = dict(field_errors or {})
+        super().__init__(message)