`can`

CAN bus and automotive security - list interfaces, open/close, send/receive frames, OBD-II PID helpers, DBC file parsing, bit-level signal decoding, frame fuzzing, log replay, and UDS diagnostic session control.

Load with: use can

What this module does

can gives ilusm programs access to the CAN (Controller Area Network) bus found in vehicles, industrial controllers, and embedded systems. You can open a physical or virtual interface (vcan0, can0, etc.), send and receive frames, and query engine sensors via the standard OBD-II PID set.

For security research: fuzz a range of CAN IDs with fixed or random payloads, replay a captured log, parse DBC database files to get message names, and decode individual bit-level signals from raw frame data. UDS helpers let you open a diagnostic session and read/write ECU memory by identifier.

Quick example

use can

# List available interfaces
ifaces = canin()

# Open can0
h = canop("can0")

# Send a raw frame
canse(h, 0x100, "\x01\x02\x03\x04")

# Receive a frame (1 second timeout)
f = canre(h, 1000)
prn(f)

# Query vehicle speed via OBD-II
pid = canob2()  # vehicle speed PID
rsp = canob7(h, pid)

# Fuzz all IDs from 0x000 to 0x7FF with a fixed payload
results = canfu(h, 0x000, 0x7FF, "\x00\x00\x00\x00")

cancl(h)

Functions

Interface management

canin()

Returns available CAN interfaces via host native __can_interfaces.

canop(iface)

Opens a CAN interface by name. Returns a handle for subsequent operations.

cancl(handle)

Closes an open CAN interface.

Frames

canse(handle, can_id, data)

Sends a CAN frame with the given 11/29-bit ID and payload string.

canre(handle, timeout_ms)

Receives the next CAN frame. Blocks up to timeout_ms milliseconds. Returns a frame object or nil on timeout.

canfr(id, data, extended)

Constructs a frame object with {id, data, ext, dlc}. dlc is set to len(data).

canst(id, data)

Constructs a standard (11-bit) frame.

canex(id, data)

Constructs an extended (29-bit) frame.

canid(id)

Converts an integer CAN ID to a hex string.

canid1(hex_str)

Converts a hex string CAN ID to an integer.

OBD-II PIDs

canob()

Engine coolant temperature PID frame (0x01 0x05).

canob1()

Engine RPM PID frame (0x01 0x0C).

canob2()

Vehicle speed PID frame (0x01 0x0D).

canob3()

Throttle position PID frame (0x01 0x11).

canob4()

Fuel level PID frame (0x01 0x2F).

canob5()

MIL status / DTC count PID frame (0x01 0x01).

canob6()

Clear DTCs (diagnostic trouble codes) frame (0x04).

canob7(handle, pid)

Sends an OBD-II PID frame and waits 1 second for the response. Returns the response frame.

DBC parsing

candb(path)

Parses a DBC (CAN database) file. Returns an object mapping message names to {id, signals}. Only parses message definitions (BO_ lines) - signal parsing is not yet implemented.

Signal decoding

cansi(frame, start_bit, length, factor, offset)

Extracts a numeric signal from a CAN frame's data bytes. Reads length bits starting at start_bit (LSB-first), then applies raw * factor + offset to produce the physical value.

Fuzzing

canfu(handle, start_id, end_id, data)

Sends data to every CAN ID from start_id to end_id inclusive. Records errors. Returns a list of {id, error} objects for IDs that failed.

canfu1(handle, can_id, iterations)

Random-payload fuzzer. Sends iterations frames to can_id, each with a fresh 8-byte random payload via cry.cryrn(8). Returns the iteration count.

Replay

canre1(handle, log_file)

Reads a CAN log file (space-separated hex_id hex_data per line) and replays each frame. Returns the count of successfully replayed frames.

UDS diagnostics

canud(handle)

Opens a UDS extended diagnostic session on ECU address 0x7E0 (service 0x10 0x03). Returns the response frame.

canud1(handle, addr, data)

Writes data to an ECU memory identifier using UDS service 0x2E. Returns the response.

canud2(handle, level)

Requests a security access seed for the given access level (UDS service 0x27). Returns the seed bytes, or nil.

canud3(handle, level, key)

Sends the security access key response for the given level. Returns the response frame.

Notes

This module is intended for authorised automotive diagnostics and security research only.
All interface operations delegate to __can_* host natives - a CAN hardware or SocketCAN binding must be available.
Requires trl, txt, and bin.