Module codec 

Pure CDP frame codec — 802.3 + LLC/SNAP framing, the CDP header, and the TLV body.

Nothing in this file touches a socket, a capture handle, the LLM or AppState. Every function here is a pure transformation between bytes and structured values, which is the whole point: the raw-Ethernet transport in super needs packet-capture privilege and cannot run in the test environment, so the part of CDP that can actually be wrong — the wire format — is isolated where it can be tested exhaustively against literal specification bytes and against real captures. See src/server/cdp/CLAUDE.md for what is proven and what is not.

Frame layout

destination MAC (6)  01:00:0C:CC:CC:CC
source MAC      (6)
802.3 length    (2)  = 8 + len(CDP payload)   -- a LENGTH, not an EtherType
LLC  DSAP       (1)  0xAA
LLC  SSAP       (1)  0xAA
LLC  control    (1)  0x03  (unnumbered information)
SNAP OUI        (3)  00:00:0C  (Cisco)
SNAP protocol   (2)  0x2000    (CDP)
CDP  version    (1)  1 or 2
CDP  TTL        (1)  seconds the neighbour should keep the entry
CDP  checksum   (2)
CDP  TLVs       (n)  type(2) length(2) value(length-4)

Note the TLV length includes its own 4-byte header, which is the single most common mistake when hand-writing CDP: a Device ID of "myswitch" (8 bytes) is 00 01 00 0C, not 00 01 00 08.

Structs

CdpAddress

One entry of an Addresses or Management Address TLV.

CdpAdvertisement

A CDP advertisement, in the terms the LLM reasons about.

DecodedCdp

What decode_payload found, including the checksum verdict.

FrameHeader

The addressing of a received frame.

OtherTlv

A TLV this codec recognises the existence of but does not model.

Enums

Duplex

Interface duplex, as advertised in the Duplex TLV.

Constants

CAPABILITY_FLAGS

Device capability bits, as advertised in the Capabilities TLV.

CDP_HEADER_LEN

version + ttl + checksum.

CDP_MULTICAST_MAC

The CDP multicast destination. Every CDP advertisement goes here; there is no unicast CDP.

CDP_PAYLOAD_OFFSET

Offset of the CDP payload inside a complete frame.

ETHERNET_HEADER_LEN

Ethernet header length: destination + source + length field.

LLC_CONTROL_UI

LLC control byte: unnumbered information.

LLC_SAP_SNAP

LLC DSAP/SSAP for SNAP-encapsulated traffic.

LLC_SNAP_HEADER

The complete LLC + SNAP header that precedes every CDP payload.

LLC_SNAP_HEADER_LEN

LLC + SNAP header length.

MAX_8023_LENGTH

The largest value the 802.3 length field can carry as a length.

MAX_TEXT_TLV

Cap on any single text field the model authors.

SNAP_OUI_CISCO

SNAP OUI for Cisco.

SNAP_PROTOCOL_CDP

SNAP protocol id for CDP.

TLV_ADDRESSES

TLV_CAPABILITIES

TLV_DEVICE_ID

TLV_DUPLEX

TLV_MANAGEMENT_ADDRESS

TLV_NATIVE_VLAN

TLV_PLATFORM

TLV_PORT_ID

TLV_SOFTWARE_VERSION

Functions

capability_bits

Encode capability names into a bitmask, rejecting anything unrecognised.

capability_names

Decode a capability bitmask into the names this codec knows.

checksum

The CDP checksum: a 16-bit one’s-complement sum (RFC 1071) over the CDP payload with the checksum field zeroed — with Cisco’s non-standard treatment of an odd-length payload.

decode_frame

Split a complete Ethernet frame into its header and the CDP payload.

decode_payload

Parse a CDP payload into an advertisement plus the checksum verdict.

encode_frame

Wrap a CDP payload in the 802.3 + LLC/SNAP header addressed to the CDP multicast group.

encode_payload

Serialise an advertisement to a CDP payload, checksum included.

mac_to_string

Render a MAC as the canonical lowercase colon form.

parse_mac

Parse aa:bb:cc:dd:ee:ff or aa-bb-cc-dd-ee-ff into six bytes.

payload_checksum

The checksum a CDP payload should carry: checksum over the payload with bytes 2..4 forced to zero.