Initial commit

Author: Sunanditha B S

.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Build native CRC-15 component
+        run: bash canary/native/build.sh
+      - name: Set up vcan0 for SocketCAN tests
+        run: |
+          sudo modprobe vcan
+          sudo ip link add dev vcan0 type vcan
+          sudo ip link set up vcan0
+      - name: Run tests
+        run: PYTHONPATH=. python -m pytest tests/ -v

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.so
+venv/
+.venv/
+*.egg-info/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sunanditha B S
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,132 @@
+# CANARY
+
+Real-time observability and intrusion detection for CAN bus networks.
+
+CAN, plus "canary in the coal mine." An early-warning system for the network that runs almost every car, tractor, and industrial machine on the planet.
+
+---
+
+## Problem
+
+Modern vehicles run 50-100+ ECUs (engine, brakes, steering, infotainment, and more), all talking over a shared CAN bus. CAN was designed in the 1980s for a closed, trusted network. It has no authentication and no encryption. Any node on the bus can send a frame claiming to be any other node.
+
+That assumption stopped being safe once cars got Bluetooth, cellular modems, and USB ports. An attacker who reaches the bus, whether through an infotainment exploit, an OBD-II dongle, or a compromised telematics unit, can inject frames that look completely legitimate to every other ECU on the network.
+
+## Why CAN Attacks Matter
+
+Miller and Valasek's 2015 Jeep Cherokee remote takeover showed that CAN injection can control steering, braking, and acceleration. The attack surface has only grown since, as vehicles add more connectivity, while the CAN network itself still has essentially no built-in defense against a node that's lying about who it is.
+
+Catching this means watching behavior, not just checking protocol correctness. A malicious frame is often a perfectly well-formed CAN frame. That's the actual engineering problem CANARY is built around.
+
+## Architecture
+
+```
+                 ┌──────────────────────────────┐
+                 │           ECU Nodes           │
+                 │  (Engine, Brake, Door, or an  │
+                 │   attacker injecting frames)  │
+                 └───────────────┬────────────────┘
+                                 │ CANFrame
+                                 ▼
+                 ┌──────────────────────────────┐
+                 │        BusInterface           │
+                 │   SimulatedBus (today)        │
+                 │   SocketCANBus (future)       │
+                 └───────────────┬────────────────┘
+                        ┌────────┼────────┐
+                        ▼        ▼         ▼
+                 ┌─────────┐ ┌────────┐ ┌───────┐
+                 │  Logger  │ │Detector│ │ Stats │
+                 │ (CSV +   │ │(rules) │ │Engine │
+                 │  replay) │ │        │ │       │
+                 └─────────┘ └───┬────┘ └───┬───┘
+                                 │ Alerts    │ Telemetry
+                                 ▼           ▼
+                        ┌──────────────────────────┐
+                        │      Dashboard (TUI)       │
+                        └──────────────────────────┘
+```
+
+Everything downstream of the bus talks to it only through `BusInterface.subscribe()` and `.offer()`. The logger, detector, and stats engine don't know or care whether frames come from a simulation or a real `vcan0` interface.
+
+## Features
+
+- Multi-ECU simulation with realistic timing, jitter, and priority-based arbitration
+- CSV traffic logging plus timing-accurate replay from log files
+- Rule-based anomaly detection: ID spoofing, malformed frames, impossible message frequency, flooding/DoS, replay attacks
+- Severity-tagged alerts, LOW through CRITICAL
+- Live terminal dashboard showing bus utilization, arbitration latency, top talkers, and recent alerts
+- A native C component (CRC-15 checksum) bridged via `ctypes`, matching how real CAN controllers compute frame integrity at the bit level
+- `SocketCANBus`: real Linux SocketCAN support via a raw `AF_CAN` socket, no external library. Works against a real interface (`vcan0` or physical hardware) with zero changes to the detector, logger, or dashboard
+- 45 unit and integration tests (2 SocketCAN tests skip automatically outside a CAN-capable kernel, verified passing in CI against `vcan0`)
+- Pre-generated sample datasets: clean traffic and a mixed multi-attack scenario
+
+## Demo
+
+```bash
+pip install -r requirements.txt
+bash canary/native/build.sh          # build the C CRC-15 component
+PYTHONPATH=. python -m canary.simulator.generate_samples
+```
+
+This regenerates `data/sample_logs/normal_traffic.csv` (0 alerts) and `data/attack_scenarios/mixed_attacks.csv` (spoofing, malformed frame, flooding, and replay all caught), printing each alert as it fires.
+
+To run the live dashboard against a running simulation:
+```python
+from canary.simulator import Simulator
+from canary.dashboard import run_dashboard
+
+sim = Simulator("live_demo.csv")
+# in practice: run sim.step() on a timer thread, then:
+run_dashboard(sim.stats, sim.detector)
+```
+
+## How It Works
+
+1. ECUs send frames on a schedule with realistic jitter (`canary/ecu/`).
+2. SimulatedBus resolves priority via a min-heap on arbitration ID, lower ID wins, the same way real CAN arbitration works (`canary/bus/`).
+3. Logger, Detector, and StatsEngine each subscribe independently. None of them know the others exist.
+4. Detector tracks per-ID baselines (expected source, size, period) and runs six independent rules against every frame, producing severity-tagged alerts.
+5. StatsEngine aggregates telemetry, rates, latency, top talkers, purely from what it observes. It never touches bus internals.
+6. Dashboard renders both and owns nothing else.
+
+## Design Decisions
+
+Arbitration is modeled as priority scheduling, not bit-level contention. This captures the real effect, latency under load and deterministic priority, without simulating electrical signaling that nothing downstream needs.
+
+C shows up exactly once, for the CRC-15 checksum, because that's genuinely bit-level, hardware-adjacent work. It's not there for its own sake.
+
+A number of protocol features are left out on purpose: bit-stuffing, ACK slots, error frames, remote frames, overload frames, the bus-off state machine, exact bit-level arbitration. None of them change what the detector can observe, so implementing them would just be chasing CAN-spec completeness instead of building detection tooling.
+
+`BusInterface` got extracted after Module 4, not designed upfront, and it required zero changes to the detector, logger, or ECU code. That's what you get from subscriber-pattern decoupling from day one.
+
+Two real bugs only showed up at integration time, in Module 7: ECU frames defaulted to wall-clock timestamps instead of simulated time, and the stats engine mixed wall-clock latency against simulated-time frames. Both got fixed with explicit, documented clock-passing rather than patched over. See `Simulator.__init__` and `StatsEngine.observe()`.
+
+## Future Work
+
+- CAN-FD support (larger payloads, flexible data rate)
+- UDS (Unified Diagnostic Services) simulation
+- J1939 (heavy-vehicle protocol layer)
+- ISO-TP (multi-frame transport protocol)
+- ML-based anomaly detection, as a stretch goal
+
+## Running Tests
+
+```bash
+PYTHONPATH=. python -m pytest tests/ -v
+```
+
+45 tests cover frame validation, bus arbitration, ECU scheduling, logging/replay round-trips, the native CRC-15 (checked against a pure-Python reference implementation), all six detection rules, the stats engine, dashboard rendering, full simulator integration across every attack scenario, and SocketCAN frame encode/decode.
+
+Two of those tests exercise a live `vcan0` interface and skip automatically if the kernel has no CAN support. To run them locally on Linux:
+```bash
+sudo modprobe vcan
+sudo ip link add dev vcan0 type vcan
+sudo ip link set up vcan0
+PYTHONPATH=. python -m pytest tests/test_socketcan.py -v
+```
+CI runs these for real against `vcan0` on every push.
+
+## License
+
+MIT. See LICENSE.

canary/__init__.py

@@ -0,0 +1,9 @@
+from .frame import CANFrame
+from .bus import BusInterface, SimulatedBus
+from .socketcan_bus import SocketCANBus
+
+# Backward-compat alias: existing tests/modules reference CANBus directly.
+# New code should prefer SimulatedBus / BusInterface.
+CANBus = SimulatedBus
+
+__all__ = ["CANFrame", "BusInterface", "SimulatedBus", "SocketCANBus", "CANBus"]

canary/bus/__init__.py

@@ -0,0 +1,80 @@
+"""
+CAN bus core.
+
+Arbitration is modeled as strict priority ordering (lower ID wins).
+Tracks bus utilization against a configured bit rate.
+"""
+
+import heapq
+import itertools
+from typing import Callable, List
+
+from .frame import CANFrame
+
+# Rough overhead per classic CAN frame in bits (SOF + arbitration + control +
+# CRC + ACK + EOF + stuffing headroom), used for utilization estimates.
+FRAME_OVERHEAD_BITS = 47
+
+
+class BusInterface:
+    """Contract every bus implementation must satisfy. Callers should
+    depend on this, not on SimulatedBus directly."""
+
+    def subscribe(self, callback) -> None:
+        raise NotImplementedError
+
+    def offer(self, frame) -> None:
+        raise NotImplementedError
+
+
+class SimulatedBus(BusInterface):
+    def __init__(self, bitrate_bps: int = 500_000):
+        self.bitrate_bps = bitrate_bps
+        self._pending: List[tuple] = []   # heap of (arbitration_id, seq, frame)
+        self._seq_counter = itertools.count()
+        self._subscribers: List[Callable[[CANFrame], None]] = []
+        self._bits_transmitted = 0
+        self._window_start = None
+        self.frames_transmitted = 0
+        self.frames_dropped = 0
+
+    def subscribe(self, callback: Callable[[CANFrame], None]) -> None:
+        """Register a listener (logger, detector, dashboard) for every
+        frame that wins arbitration and is transmitted."""
+        self._subscribers.append(callback)
+
+    def offer(self, frame: CANFrame) -> None:
+        """An ECU offers a frame to the bus. It queues for arbitration
+        rather than transmitting immediately, so simultaneous offers
+        resolve by priority (lowest arbitration_id first)."""
+        heapq.heappush(self._pending, (frame.arbitration_id, next(self._seq_counter), frame))
+
+    def tick(self) -> None:
+        """Resolve one round of arbitration: the highest-priority pending
+        frame transmits, all others remain queued for the next tick."""
+        if not self._pending:
+            return
+        _, _, frame = heapq.heappop(self._pending)
+        self._transmit(frame)
+
+    def _transmit(self, frame: CANFrame) -> None:
+        frame_bits = FRAME_OVERHEAD_BITS + frame.dlc * 8
+        self._bits_transmitted += frame_bits
+        self.frames_transmitted += 1
+        for callback in self._subscribers:
+            callback(frame)
+
+    def utilization(self, elapsed_seconds: float) -> float:
+        """Bus utilization as a fraction of capacity over the elapsed window.
+        Caller tracks elapsed_seconds; the bus only tracks bits transmitted."""
+        if elapsed_seconds <= 0:
+            return 0.0
+        capacity_bits = self.bitrate_bps * elapsed_seconds
+        return min(self._bits_transmitted / capacity_bits, 1.0)
+
+    def reset_utilization_counter(self) -> None:
+        self._bits_transmitted = 0
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)

canary/bus/bus.py

@@ -0,0 +1,42 @@
+"""
+CAN frame data model.
+
+Represents a single CAN 2.0 frame as it would appear on the bus.
+Extended (29-bit) IDs are supported via `extended=True`; standard
+frames use 11-bit IDs.
+"""
+
+from dataclasses import dataclass, field
+import time
+
+STANDARD_ID_MAX = 0x7FF        # 11-bit
+EXTENDED_ID_MAX = 0x1FFFFFFF   # 29-bit
+MAX_DLC = 8
+
+
+@dataclass(frozen=True)
+class CANFrame:
+    arbitration_id: int
+    data: bytes
+    extended: bool = False
+    timestamp: float = field(default_factory=time.monotonic)
+    source_ecu: str = "unknown"
+
+    def __post_init__(self):
+        max_id = EXTENDED_ID_MAX if self.extended else STANDARD_ID_MAX
+        if not (0 <= self.arbitration_id <= max_id):
+            raise ValueError(
+                f"arbitration_id {self.arbitration_id:#x} out of range "
+                f"for {'extended' if self.extended else 'standard'} frame"
+            )
+        if len(self.data) > MAX_DLC:
+            raise ValueError(f"payload length {len(self.data)} exceeds max DLC of {MAX_DLC}")
+
+    @property
+    def dlc(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        hex_data = self.data.hex(" ")
+        id_fmt = f"{self.arbitration_id:08X}" if self.extended else f"{self.arbitration_id:03X}"
+        return f"<CANFrame id=0x{id_fmt} dlc={self.dlc} data=[{hex_data}] src={self.source_ecu}>"