ipdecode

package
v0.666.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

Documentation

Overview

Package ipdecode parses raw IP packets (IPv4 + IPv6) plus the most-deployed next-layer headers (TCP, UDP, ICMP, ICMPv6). This is the foundational network-decode primitive every other application-layer Spec sits on top of — operators routinely paste raw pcap bytes that include the IP + transport headers, and pulling those out manually is tedious.

Wrap-vs-native judgement

Native. IPv4 (RFC 791), IPv6 (RFC 8200), TCP (RFC 9293), UDP (RFC 768), ICMP (RFC 792), and ICMPv6 (RFC 4443) are all fully published with fixed-format headers. TCP options (RFC 9293 §3.2.5 + RFC 2018 / 7323) are a TLV list with a small dispatch table. Pasting a hex blob from Wireshark / tshark / tcpdump-raw / a network forensics dump is enough — no live capture, no kernel, no networking.

What this package covers

  • **IPv4/IPv6 auto-detection** by the first nibble (4 or 6). Anything else is rejected.
  • **IPv4 header** (RFC 791): version, IHL (header length in 32-bit words), DSCP (Differentiated Services Code Point) + ECN (Explicit Congestion Notification) broken out of the ToS byte, total length, identification, flags (DF / MF), fragment offset, TTL, protocol (named per IANA registry: 1 ICMP / 2 IGMP / 6 TCP / 17 UDP / 41 IPv6 / 47 GRE / 50 ESP / 51 AH / 89 OSPF / 132 SCTP / 137 MPLS-in-IP), header checksum, source and destination IPv4 addresses. Options field surfaced as raw hex when IHL > 5.
  • **IPv6 header** (RFC 8200): version, traffic class (DSCP + ECN broken out), flow label, payload length, next header (named the same as IPv4 protocol field), hop limit, source + destination IPv6 addresses. Walks extension headers (Hop-by-Hop 0, Routing 43, Fragment 44, ESP 50, AH 51, Destination 60) and surfaces them as a count + list with raw hex; the final inner-next-header is what dispatches to the transport-layer decoder.
  • **TCP header** (RFC 9293): source port, destination port, sequence number, acknowledgment number, data offset, full 9-bit flag field broken out as named bools (NS / CWR / ECE / URG / ACK / PSH / RST / SYN / FIN), window size, checksum, urgent pointer, and options walked as a TLV list with named decode for:
  • 0 End of Option List (EOL)
  • 1 No-Operation (NOP)
  • 2 Maximum Segment Size (MSS)
  • 3 Window Scale
  • 4 SACK Permitted
  • 5 SACK (block list)
  • 8 Timestamps
  • 34 TCP Fast Open Cookie For SYN packets a **JA4T fingerprint** (FoxIO) is also computed — window_size_option-kinds_MSS_window-scale, the passive OS / TCP-stack fingerprint (the modern p0f analogue). Verified byte-for-byte against a FoxIO snapshot.
  • **UDP header** (RFC 768): source port, destination port, length, checksum.
  • **ICMP** (RFC 792): type + code with name lookup for 0 Echo Reply, 3 Destination Unreachable (with 16 sub- codes including Network/Host/Protocol/Port Unreachable / Fragmentation Needed / Network/Host Unreachable for ToS), 4 Source Quench, 5 Redirect, 8 Echo Request, 9 Router Advertisement, 10 Router Solicitation, 11 Time Exceeded (with sub-codes), 12 Parameter Problem, 13 Timestamp Request, 14 Timestamp Reply. For Echo Request/Reply (type 0/8): identifier + sequence number broken out + payload hex.
  • **ICMPv6** (RFC 4443): type + code with name lookup for the error types (1 Destination Unreachable with sub-codes / 2 Packet Too Big / 3 Time Exceeded / 4 Parameter Problem), the informational types (128 Echo Request / 129 Echo Reply with identifier + sequence), and the NDP types (133 Router Solicitation / 134 Router Advertisement / 135 Neighbor Solicitation / 136 Neighbor Advertisement / 137 Redirect).

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

  • Checksum validation — operators routinely paste hex blobs from broken-checksum environments (offload, NAT, mid-stream re-injection), and a "checksum invalid" warning is more noise than signal. The captured checksum is surfaced for operators who want to verify independently.
  • IPv4 fragment reassembly — the offset / MF flag / identification are surfaced so callers can do their own reassembly across packets.
  • Ethernet / VLAN / MPLS framing — operators feed the IP packet (the first byte must be a version nibble); stripping L2 is the caller's job.
  • GRE / IPSec ESP / AH inner-payload decode — the protocol-name is surfaced but the encrypted / encapsulated body is left as raw hex.
  • Deep IPv6 extension header decode — Hop-by-Hop, Routing, Destination Options have their own TLV option lists (RFC 8200 §4.3 / 4.4 / 4.6) that warrant a separate iteration; for now the next-header chain is walked but the option lists are surfaced as raw hex.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ICMP 

type ICMP struct {
	Type       int    `json:"type"`
	TypeName   string `json:"type_name"`
	Code       int    `json:"code"`
	CodeName   string `json:"code_name,omitempty"`
	Checksum   string `json:"checksum"`
	Identifier int    `json:"identifier,omitempty"`
	Sequence   int    `json:"sequence,omitempty"`
	BodyHex    string `json:"body_hex,omitempty"`
}

ICMP is the decoded ICMP header (RFC 792).

type ICMPv6 

type ICMPv6 struct {
	Type       int    `json:"type"`
	TypeName   string `json:"type_name"`
	Code       int    `json:"code"`
	CodeName   string `json:"code_name,omitempty"`
	Checksum   string `json:"checksum"`
	Identifier int    `json:"identifier,omitempty"`
	Sequence   int    `json:"sequence,omitempty"`
	BodyHex    string `json:"body_hex,omitempty"`
}

ICMPv6 is the decoded ICMPv6 header (RFC 4443).

type IPv4 

type IPv4 struct {
	IHL               int    `json:"ihl_words"`
	HeaderLengthB     int    `json:"header_length_bytes"`
	DSCP              int    `json:"dscp"`
	ECN               int    `json:"ecn"`
	ECNName           string `json:"ecn_name"`
	TotalLength       int    `json:"total_length"`
	Identification    int    `json:"identification"`
	FlagDontFragment  bool   `json:"flag_dont_fragment"`
	FlagMoreFragments bool   `json:"flag_more_fragments"`
	FragmentOffset    int    `json:"fragment_offset"`
	TTL               int    `json:"ttl"`
	HeaderChecksum    string `json:"header_checksum"`
	SourceIP          string `json:"source_ip"`
	DestinationIP     string `json:"destination_ip"`
	OptionsHex        string `json:"options_hex,omitempty"`
}

IPv4 is the decoded IPv4 header.

type IPv6 

type IPv6 struct {
	TrafficClass   int              `json:"traffic_class"`
	DSCP           int              `json:"dscp"`
	ECN            int              `json:"ecn"`
	ECNName        string           `json:"ecn_name"`
	FlowLabel      int              `json:"flow_label"`
	PayloadLength  int              `json:"payload_length"`
	NextHeader     int              `json:"next_header"`
	NextHeaderName string           `json:"next_header_name"`
	HopLimit       int              `json:"hop_limit"`
	SourceIP       string           `json:"source_ip"`
	DestinationIP  string           `json:"destination_ip"`
	Extensions     []*IPv6Extension `json:"extensions,omitempty"`
}

IPv6 is the decoded IPv6 header.

type IPv6Extension 

type IPv6Extension struct {
	Number     int    `json:"number"`
	Name       string `json:"name"`
	LengthB    int    `json:"length_bytes"`
	NextHeader int    `json:"next_header"`
	DataHex    string `json:"data_hex,omitempty"`
}

IPv6Extension is one parsed IPv6 extension header.

type Packet 

type Packet struct {
	HexInput string `json:"hex_input"`
	Version  int    `json:"version"`
	IPv4     *IPv4  `json:"ipv4,omitempty"`
	IPv6     *IPv6  `json:"ipv6,omitempty"`

	// Transport / next-layer dispatch.
	ProtocolNumber int     `json:"protocol_number"`
	ProtocolName   string  `json:"protocol_name"`
	TCP            *TCP    `json:"tcp,omitempty"`
	UDP            *UDP    `json:"udp,omitempty"`
	ICMP           *ICMP   `json:"icmp,omitempty"`
	ICMPv6         *ICMPv6 `json:"icmpv6,omitempty"`
	PayloadHex     string  `json:"payload_hex,omitempty"`
}

Packet is the decoded view of one IP packet.

func Decode 

func Decode(hexBlob string) (*Packet, error)

Decode parses a hex-encoded IP packet.

func DecodeBytes 

func DecodeBytes(b []byte) (*Packet, error)

DecodeBytes parses a raw IP packet.

type TCP 

type TCP struct {
	SourcePort      int          `json:"source_port"`
	DestinationPort int          `json:"destination_port"`
	SequenceNumber  uint32       `json:"sequence_number"`
	AckNumber       uint32       `json:"ack_number"`
	DataOffset      int          `json:"data_offset_words"`
	HeaderLengthB   int          `json:"header_length_bytes"`
	FlagNS          bool         `json:"flag_ns"`
	FlagCWR         bool         `json:"flag_cwr"`
	FlagECE         bool         `json:"flag_ece"`
	FlagURG         bool         `json:"flag_urg"`
	FlagACK         bool         `json:"flag_ack"`
	FlagPSH         bool         `json:"flag_psh"`
	FlagRST         bool         `json:"flag_rst"`
	FlagSYN         bool         `json:"flag_syn"`
	FlagFIN         bool         `json:"flag_fin"`
	FlagsString     string       `json:"flags_string"`
	WindowSize      int          `json:"window_size"`
	Checksum        string       `json:"checksum"`
	UrgentPointer   int          `json:"urgent_pointer"`
	Options         []*TCPOption `json:"options,omitempty"`
	PayloadHex      string       `json:"payload_hex,omitempty"`
	JA4T            string       `json:"ja4t,omitempty"`
}

TCP is the decoded TCP header.

type TCPOption 

type TCPOption struct {
	Kind        int            `json:"kind"`
	Name        string         `json:"name"`
	Length      int            `json:"length"`
	DataHex     string         `json:"data_hex,omitempty"`
	MSS         int            `json:"mss,omitempty"`
	WindowScale int            `json:"window_scale,omitempty"`
	Timestamps  *TCPTimestamps `json:"timestamps,omitempty"`
	SACKBlocks  [][2]uint32    `json:"sack_blocks,omitempty"`
}

TCPOption is one TCP option in the options list.

type TCPTimestamps 

type TCPTimestamps struct {
	TSval uint32 `json:"tsval"`
	TSecr uint32 `json:"tsecr"`
}

TCPTimestamps is the option-8 TSval+TSecr pair.

type UDP 

type UDP struct {
	SourcePort      int    `json:"source_port"`
	DestinationPort int    `json:"destination_port"`
	Length          int    `json:"length"`
	Checksum        string `json:"checksum"`
	PayloadHex      string `json:"payload_hex,omitempty"`
}

UDP is the decoded UDP header.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.