isis

Documentation

Overview

Package isis decodes IS-IS (Intermediate System to Intermediate System) packets per ISO 10589 and RFC 1195. IS-IS runs directly over L2 (OSI CLNS) — it has no IP header. On Ethernet it uses LLC/SNAP encapsulation or is carried directly; on point-to-point links it rides HDLC or PPP. IS-IS is the backbone IGP for large ISP and enterprise networks.

IS-IS is a **high-value ISP/enterprise routing target**. Unlike IP-based routing protocols, IS-IS runs at L2, making it accessible to any device on the same segment. Default IS-IS has NO authentication — any L2-adjacent device can inject LSPs, redirect traffic through an attacker's device (MITM at ISP scale), or black-hole arbitrary prefixes.

The wire format leaks:

• **System IDs + area addresses** — the complete L2 network topology is encoded in every Hello and LSP. Area addresses reveal the IS-IS area structure; system IDs identify every router. Together they enable offline topology reconstruction.

• **Dynamic Hostname (TLV 137)** — most operators configure hostnames in IS-IS for operator convenience. These hostnames map system IDs to human-readable router names (e.g., "core-router-nyc-01"), directly disclosing network topology and naming conventions.

• **Authentication (TLV 10)** — IS-IS auth is optional and commonly absent. Cleartext password (auth_type 1) transmits the password in plain text. HMAC-MD5 (auth_type 54) is offline-crackable via hashcat. Absent TLV 10 means NO AUTHENTICATION — LSP injection is trivial.

• **IP interface addresses (TLV 132)** — every IS-IS Hello contains the IP addresses of the originating interface, directly mapping system IDs to IP addresses for targeting.

• **LSP sequence numbers + overload bit** — the sequence number reveals router uptime and convergence history. The overload bit signals a router in maintenance or under load, making it a MITM candidate.

• **IS type (L1/L2/L1L2)** — reveals the IS-IS level structure, enabling targeted attack on L1-only devices that trust L2 LSPs by default in some configurations.

Wrap-vs-native judgement:

Native. ISO 10589 is a public standard; RFC 1195 adds IP support.
The IS-IS wire format is an 8-byte common header followed by per-PDU
fixed fields and TLV chains. No crypto at the parse layer (auth data
is opaque — auth_type is decoded, not the key material).

What this package covers:

• **8-byte IS-IS common header**: irpd, length_indicator, version, id_length, pdu_type (5-bit field with 9-entry name table), version2, reserved, max_area_addresses.

• **LAN Hello (IIH) additional fields** (PDU types 15 + 16): circuit_type, source_id (6 bytes, dotted-hex), holding_time, pdu_length, priority, lan_id (7 bytes).

• **Point-to-Point Hello additional fields** (PDU type 17): circuit_type, source_id, holding_time, pdu_length, local_circuit_id.

• **LSP additional fields** (PDU types 18 + 20): pdu_length, remaining_lifetime, lsp_id (8 bytes, hex), sequence_number, checksum, overload_bit, is_type.

• **CSNP / PSNP additional fields** (PDU types 24–27): pdu_length, source_id surfaced.

• **TLV walker**: type (1 byte) + length (1 byte) + value[length]; surfaces tlv_count and tlv_types list.

• **Key TLV decoders**: TLV 1 (Area Addresses): area_addresses[] in hex. TLV 10 (Authentication): has_auth, auth_type, auth_type_name, is_cleartext_auth. TLV 132 (IP Interface Address): ip_addresses[] in dotted-quad. TLV 137 (Dynamic Hostname): hostname string.

• **Classification flags**: is_hello, is_lsp, is_csnp, is_psnp, level (1 or 2).

What this package does NOT cover (deliberately out of scope):

• TLV 6 (IS Neighbors): neighbor system ID list not decoded.
• TLV 128/130 (IP Internal/External Reachability): old-style IP routes not decoded.
• TLV 135 (Extended IP Reachability): wide-metric IP routes not decoded.
• TLV 232 (IPv6 Reachability): IPv6 routes not decoded.
• TLV 240 (Router Capability): capability sub-TLVs not decoded.
• TLV 242 (Multi-Topology): MT-ID list not decoded.
• **Checksum verification**: the IS-IS checksum is not validated.
• **Authentication verification**: auth_data bytes are never surfaced; only auth_type is decoded (privacy-preserving).
• **CSNP/PSNP LSP Entry TLVs**: LSP range and partial entry lists not decoded.
• **LLC/SNAP framing**: feed bytes after any L2 framing has been stripped.

Index

• type Result
  • func Decode(hexStr string) (*Result, error)

Types

type Result

type Result struct {
	TotalBytes int `json:"total_bytes"`

	// Common IS-IS header (8 bytes)
	IRPD             int    `json:"irpd"`
	LengthIndicator  int    `json:"length_indicator"`
	Version          int    `json:"version"`
	IDLength         int    `json:"id_length"`
	PDUType          int    `json:"pdu_type"`
	PDUTypeName      string `json:"pdu_type_name"`
	Version2         int    `json:"version2"`
	Reserved         int    `json:"reserved"`
	MaxAreaAddresses int    `json:"max_area_addresses"`

	// Classification
	IsHello bool `json:"is_hello"`
	IsLSP   bool `json:"is_lsp"`
	IsCSNP  bool `json:"is_csnp"`
	IsPSNP  bool `json:"is_psnp"`
	Level   int  `json:"level"`

	// Hello fields (LAN + P2P)
	CircuitType    int    `json:"circuit_type,omitempty"`
	SourceID       string `json:"source_id,omitempty"`
	HoldingTime    int    `json:"holding_time,omitempty"`
	PDULength      int    `json:"pdu_length,omitempty"`
	Priority       int    `json:"priority,omitempty"`
	LANID          string `json:"lan_id,omitempty"`
	LocalCircuitID int    `json:"local_circuit_id,omitempty"`

	// LSP fields
	LSPID             string `json:"lsp_id,omitempty"`
	RemainingLifetime int    `json:"remaining_lifetime,omitempty"`
	SequenceNumber    uint32 `json:"sequence_number,omitempty"`
	Checksum          string `json:"checksum,omitempty"`
	OverloadBit       bool   `json:"overload_bit,omitempty"`
	ISType            int    `json:"is_type,omitempty"`

	// TLV summary
	TLVCount int   `json:"tlv_count"`
	TLVTypes []int `json:"tlv_types"`

	// TLV 1 — Area Addresses
	AreaAddresses []string `json:"area_addresses,omitempty"`

	// TLV 10 — Authentication
	HasAuth         bool   `json:"has_auth"`
	AuthType        int    `json:"auth_type,omitempty"`
	AuthTypeName    string `json:"auth_type_name,omitempty"`
	IsCleartextAuth bool   `json:"is_cleartext_auth"`

	// TLV 132 — IP Interface Address
	IPAddresses []string `json:"ip_addresses,omitempty"`

	// TLV 137 — Dynamic Hostname
	Hostname string `json:"hostname,omitempty"`
}

Result is the structured decode of an IS-IS PDU.

func Decode

func Decode(hexStr string) (*Result, error)

Decode parses an IS-IS PDU from a hex string. The input should be the raw IS-IS PDU bytes (after any LLC/SNAP or HDLC framing has been stripped).