scapy.contrib.isotp package

class scapy.contrib.isotp.ISOTP(_pkt, /, *, data=b'')

Bases: Packet

Packet class for ISOTP messages. This class contains additional slots for source address (tx_id), destination address (rx_id), extended source address (ext_address) and extended destination address (rx_ext_address) information. This information gets filled from ISOTPSockets or the ISOTPMessageBuilder, if it is available. Address information is not used for Packet comparison.

Parameters:

• args – Arguments for Packet init, for example bytes string

• kwargs – Keyword arguments for Packet init.

aliastypes

comment: bytes | None

default_fields: Dict[str, Any]

static defragment(can_frames: List[Packet], use_extended_addressing: bool | None = None) → ISOTP | None

Helper function to defragment a list of CAN frames to one ISOTP message

Parameters:

• can_frames – A list of CAN frames

• use_extended_addressing – Specify if extended ISO-TP addressing is used in the packets for defragmentation.

Returns:

An ISOTP message containing the data of the CAN frames or None

direction: int | None

explicit

ext_address: int | None

fields: Dict[str, Any]

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|              DATA             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                            Fig. ISOTP                            

ISOTP fields

data

StrField

b''

fieldtype: Dict[str, AnyField]

fragment(*args: Any, **kargs: Any) → List[Packet]

Helper function to fragment an ISOTP message into multiple CAN frames.

Returns:

A list of CAN frames

name

original

overload_fields: Dict[Type[Packet], Dict[str, Any]]

overloaded_fields: Dict[str, Any]

packetfields: List[AnyField]

parent

payload: Packet

post_transforms

raw_packet_cache: bytes | None

raw_packet_cache_fields: Dict[str, Any] | None

rx_ext_address: int | None

rx_id: int | None

sent_time: EDecimal | float | None

sniffed_on: _GlobInterfaceType | None

time: EDecimal | float

tx_id: int | None

underlayer

validate_fields() → None

Helper function to validate information in tx_id, rx_id, ext_address and rx_ext_address slots

wirelen: int | None

class scapy.contrib.isotp.ISOTPHeader(_pkt, /, *, flags=<Flag 0 ()>, identifier=0, length=None, reserved=0)

Bases: CAN

aliastypes

extract_padding(p: bytes) → Tuple[bytes, bytes | None]

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|FLAGS|                        IDENTIFIER                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     LENGTH    |                    RESERVED                   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               |
+-+-+-+-+-+-+-+-+

                         Fig. ISOTPHeader                         

ISOTPHeader fields

flags	FlagsField	<Flag 0 ()>
identifier	XBitField (29 bits)	0
length	ByteField	None
reserved	ThreeBytesField	0

guess_payload_class(payload: bytes) → Type[Packet]

ISO-TP encodes the frame type in the first nibble of a frame. This is used to determine the payload_class

Parameters:

payload – payload bytes string

Returns:

Type of payload class

post_build(pkt: bytes, pay: bytes) → bytes

This will set the ByteField ‘length’ to the correct value.

class scapy.contrib.isotp.ISOTPHeaderEA(_pkt, /, *, flags=<Flag 0 ()>, identifier=0, length=None, reserved=0, extended_address=0)

Bases: ISOTPHeader

aliastypes

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|FLAGS|                        IDENTIFIER                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     LENGTH    |                    RESERVED                   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               |EXTENDED ADDRES|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                        Fig. ISOTPHeaderEA                        

ISOTPHeaderEA fields

flags	FlagsField	<Flag 0 ()>
identifier	XBitField (29 bits)	0
length	ByteField	None
reserved	ThreeBytesField	0
extended_address	XByteField	0

post_build(p: bytes, pay: bytes) → bytes

This will set the ByteField ‘length’ to the correct value. ‘chb(len(pay) + 1)’ is required, because the field ‘extended_address’ is counted as payload on the CAN layer

class scapy.contrib.isotp.ISOTPMessageBuilder(use_ext_address: bool | None = None, rx_id: int | ~typing.List[int] | ~typing.Iterable[int] | None = None, basecls: ~typing.Type[~scapy.contrib.isotp.isotp_packet.ISOTP] = <class 'scapy.contrib.isotp.isotp_packet.ISOTP'>)

Bases: object

Initialize a ISOTPMessageBuilder object

Utility class to build ISOTP messages out of CAN frames, used by both ISOTP.defragment() and ISOTPSession.

This class attempts to interpret some CAN frames as ISOTP frames, both with and without extended addressing at the same time. For example, if an extended address of 07 is being used, all frames will also be interpreted as ISOTP single-frame messages.

CAN frames are fed to an ISOTPMessageBuilder object with the feed() method and the resulting ISOTP frames can be extracted using the pop() method.

Parameters:

• use_ext_address – True for only attempting to defragment with extended addressing, False for only attempting to defragment without extended addressing, or None for both

• rx_id – Destination Identifier

• basecls – The class of packets that will be returned, defaults to ISOTP

class Bucket(total_len: int, first_piece: bytes, ts: EDecimal | float)

Bases: object

Helper class to store not finished ISOTP messages while building.

push(piece: bytes) → None

property count: int

Returns the number of ready ISOTP messages built from the provided can frames

Returns:

Number of ready ISOTP messages

feed(can: Iterable[Packet] | Packet) → None

Attempt to feed an incoming CAN frame into the state machine

pop(identifier: int | None = None, ext_addr: int | None = None) → ISOTP | None

Returns a built ISOTP message

Parameters:

• identifier – if not None, only return isotp messages with this destination

• ext_addr – if identifier is not None, only return isotp messages with this extended address for destination

Returns:

an ISOTP packet, or None if no message is ready

class scapy.contrib.isotp.ISOTPNativeSocket(iface: str | ~scapy.supersocket.SuperSocket | None = None, tx_id: int = 0, rx_id: int = 0, ext_address: int | None = None, rx_ext_address: int | None = None, bs: int = 0, stmin: int = 0, padding: bool = False, listen_only: bool = False, frame_txtime: int = 0, fd: bool = False, basecls: ~typing.Type[~scapy.packet.Packet] = <class 'scapy.contrib.isotp.isotp_packet.ISOTP'>)

Bases: SuperSocket

ISOTPSocket using the can-isotp kernel module

Parameters:

• iface – a CANSocket instance or an interface name

• tx_id – the CAN identifier of the sent CAN frames

• rx_id – the CAN identifier of the received CAN frames

• ext_address – the extended address of the sent ISOTP frames

• rx_ext_address – the extended address of the received ISOTP frames

• bs – block size sent in Flow Control ISOTP frames

• stmin – minimum desired separation time sent in Flow Control ISOTP frames

• padding – If True, pads sending packets with 0x00 which not count to the payload. Does not affect receiving packets.

• listen_only – Does not send Flow Control frames if a First Frame is received

• frame_txtime – Separation time between two CAN frames during send

• basecls – base class of the packets emitted by this socket

auxdata_available: bool = True

can_isotp_fc_options_fmt = '@3B'

can_isotp_ll_options_fmt = '@3B'

can_isotp_options_fmt = '@2I4B'

desc = 'read/write packets at a given CAN interface using CAN_ISOTP socket '

recv(x: int = 65535) → Packet | None

recv_raw(x: int = 65535) → Tuple[Type[Packet] | None, bytes | None, float | None]

Receives a packet, then returns a tuple containing (cls, pkt_data, time)

sockaddr_can_fmt = '@H3I'

class scapy.contrib.isotp.ISOTPSession(*args: Any, **kwargs: Any)

Bases: DefaultSession

Defragment ISOTP packets ‘on-the-flow’.

Usage:

>>> sniff(session=ISOTPSession)

on_packet_received(pkt: Packet | None) → None

scapy.contrib.isotp.ISOTPSocket

alias of ISOTPSoftSocket

class scapy.contrib.isotp.ISOTPSoftSocket(can_socket: Optional["CANSocket"] = None, tx_id: int = 0, rx_id: int = 0, ext_address: Optional[int] = None, rx_ext_address: Optional[int] = None, bs: int = 0, stmin: int = 0, padding: bool = False, listen_only: bool = False, basecls: Type[Packet] = <class 'scapy.contrib.isotp.isotp_packet.ISOTP'>)

Bases: SuperSocket

This class is a wrapper around the ISOTPSocketImplementation, for the reasons described below.

The ISOTPSoftSocket aims to be fully compatible with the Linux ISOTP sockets provided by the can-isotp kernel module, while being usable on any operating system. Therefore, this socket needs to be able to respond to an incoming FF frame with a FC frame even before the recv() method is called. A thread is needed for receiving CAN frames in the background, and since the lower layer CAN implementation is not guaranteed to have a functioning POSIX select(), each ISOTP socket needs its own CAN receiver thread. SuperSocket automatically calls the close() method when the GC destroys an ISOTPSoftSocket. However, note that if any thread holds a reference to an ISOTPSoftSocket object, it will not be collected by the GC.

The implementation of the ISOTP protocol, along with the necessary thread, are stored in the ISOTPSocketImplementation class, and therefore:

• There no reference from ISOTPSocketImplementation to ISOTPSoftSocket

• ISOTPSoftSocket can be normally garbage collected

• Upon destruction, ISOTPSoftSocket.close() will be called

• ISOTPSoftSocket.close() will call ISOTPSocketImplementation.close()

• RX background thread can be stopped by the garbage collector

Initialize an ISOTPSoftSocket using the provided underlying can socket.

Example (with NativeCANSocket underneath):

>>> conf.contribs['ISOTP'] = {'use-can-isotp-kernel-module': False}
>>> load_contrib('isotp')
>>> with ISOTPSocket("can0", tx_id=0x641, rx_id=0x241) as sock:
>>>     sock.send(...)

Example (with PythonCANSocket underneath):

>>> conf.contribs['ISOTP'] = {'use-can-isotp-kernel-module': False}
>>> conf.contribs['CANSocket'] = {'use-python-can': True}
>>> load_contrib('isotp')
>>> with ISOTPSocket(CANSocket(bustype='socketcan', channel="can0"), tx_id=0x641, rx_id=0x241) as sock:
>>>     sock.send(...)

Parameters:

• can_socket – a CANSocket instance, preferably filtering only can frames with identifier equal to rx_id

• tx_id – the CAN identifier of the sent CAN frames

• rx_id – the CAN identifier of the received CAN frames

• ext_address – the extended address of the sent ISOTP frames

• rx_ext_address – the extended address of the received ISOTP frames

• bs – block size sent in Flow Control ISOTP frames

• stmin – minimum desired separation time sent in Flow Control ISOTP frames

• padding – If True, pads sending packets with 0x00 which not count to the payload. Does not affect receiving packets.

• listen_only – Does not send Flow Control frames if a First Frame is received

• basecls – base class of the packets emitted by this socket

close() → None

failure_analysis() → None

recv(x: int = 65535) → Packet | None

recv_raw(x: int = 65535) → Tuple[Type[Packet] | None, bytes | None, float | None]

Receive a complete ISOTP message, blocking until a message is received or the specified timeout is reached. If self.timeout is 0, then this function doesn’t block and returns the first frame in the receive buffer or None if there isn’t any.

static select(sockets: List[SuperSocket], remain: float | None = None) → List[SuperSocket]

This function is called during sendrecv() routine to wait for sockets to be ready to receive

class scapy.contrib.isotp.ISOTP_CF(_pkt, /, *, type=2, index=0, data=b'')

Bases: Packet

aliastypes

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  TYPE | INDEX |      DATA     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                          Fig. ISOTP_CF                           

ISOTP_CF fields

type	BitEnumField	2
index	BitField (4 bits)	0
data	StrField	b''

class scapy.contrib.isotp.ISOTP_FC(_pkt, /, *, type=3, fc_flag=0, block_size=0, separation_time=0)

Bases: Packet

aliastypes

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  TYPE |FC FLAG|   BLOCK SIZE  |SEPARATION TIME|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                          Fig. ISOTP_FC                           

ISOTP_FC fields

type	BitEnumField	3
fc_flag	BitEnumField	0
block_size	ByteField	0
separation_time	ByteField	0

class scapy.contrib.isotp.ISOTP_FF(_pkt, /, *, type=1, message_size=0, extended_message_size=0, data=b'')

Bases: Packet

aliastypes

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  TYPE |      MESSAGE SIZE     |     EXTENDED MESSAGE SIZE     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                               |      DATA     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                          Fig. ISOTP_FF                           

ISOTP_FF fields

type	BitEnumField	1
message_size	BitField (12 bits)	0
extended_message_size	BitField (Cond) (32 bits)	0
data	StrField	b''

class scapy.contrib.isotp.ISOTP_SF(_pkt, /, *, type=0, message_size=None, data=b'')

Bases: Packet

aliastypes

fields_desc

Display RFC-like schema

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  TYPE |MESSAGE|              DATA             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                          Fig. ISOTP_SF                           

ISOTP_SF fields

type	BitEnumField	0
message_size	BitFieldLenField (4 bits)	None
data	StrLenField	b''

scapy.contrib.isotp.isotp_scan(sock: SuperSocket, scan_range: Iterable[int] = range(0, 2048), extended_addressing: bool = False, extended_scan_range: Iterable[int] = range(0, 256), noise_listen_time: int = 2, sniff_time: float = 0.1, output_format: str | None = None, can_interface: str | None = None, extended_can_id: bool = False, verify_results: bool = True, verbose: bool = False, stop_event: Event | None = None) → str | List[SuperSocket]

Scan for ISOTP Sockets on a bus and return findings

Scan for ISOTP Sockets in the defined range and returns found sockets in a specified format. The format can be:

• text: human readable output

• code: python code for copy&paste

• json: json string

• sockets: if output format is not specified, ISOTPSockets will be created and returned in a list

Parameters:

• sock – CANSocket object to communicate with the bus under scan

• scan_range – range of CAN-Identifiers to scan. Default is 0x0 - 0x7ff

• extended_addressing – scan with ISOTP extended addressing

• extended_scan_range – range for ISOTP extended addressing values

• noise_listen_time – seconds to listen for default communication on the bus

• sniff_time – time the scan waits for isotp flow control responses after sending a first frame

• output_format – defines the format of the returned results (text, code or sockets). Provide a string e.g. “text”. Default is “socket”.

• can_interface – interface used to create the returned code/sockets

• extended_can_id – Use Extended CAN-Frames

• verify_results – Verify scan results. This will cause a second scan of all possible candidates for ISOTP Sockets

• verbose – displays information during scan

• stop_event – Event object to asynchronously stop the scan

Returns:

Submodules

• scapy.contrib.isotp.isotp_native_socket
• scapy.contrib.isotp.isotp_packet
• scapy.contrib.isotp.isotp_scanner
• scapy.contrib.isotp.isotp_soft_socket
• scapy.contrib.isotp.isotp_utils