pcapng

Documentation

Overview

Package pcapng decodes the PCAPng (next-generation packet capture, draft-tuexen-opsawg-pcapng) file format. PCAPng has been Wireshark's default capture format since 2018 and the emitted format of most modern tcpdump builds; operators increasingly get .pcapng files instead of classic .pcap. Sits alongside `internal/pcap.Inspect` (classic libpcap) for the complete packet-capture container coverage.

Wrap-vs-native judgement

Native. The PCAPng spec is fully public; every block has
a tight 4-byte Block Type + 4-byte Block Total Length +
body + 4-byte Block Total Length (repeated for backward
navigation through the file). The first block is always a
Section Header Block (SHB) whose Byte-Order Magic
(0x1A2B3C4D) dispatches endianness for the entire section.
No crypto, no compression — operators paste the full file
hex and get a structured per-block summary.

What this package covers

• **Block framing** — outer 8-byte header (Type + Length), padded body, and trailing repeated 4-byte Block Total Length validating the back-pointer. Type field is 32-bit so the first SHB's bytes drive endianness detection for the rest of the section.

• **9-entry block type table** (per the IANA pcapng-block- types registry): 0x0A0D0D0A Section Header Block (palindrome — also serves as endianness-detection token), 0x00000001 Interface Description Block (IDB), 0x00000003 Simple Packet Block (SPB; obsolete — surfaced verbatim as length+caplen+data), 0x00000004 Name Resolution Block (NRB), 0x00000005 Interface Statistics Block (ISB), 0x00000006 Enhanced Packet Block (EPB; the canonical packet record), 0x00000007 IRIG Timestamp Block (rare), 0x00000009 Decryption Secrets Block (DSB; TLS / SSH key log materials), 0x0BAD0001 Custom Block.

• **Section Header Block (SHB) body**:

• 4-byte Byte-Order Magic (0x1A2B3C4D in section endianness; mismatch implies the wrong endianness was guessed).

• 2-byte Major Version (expected 1).

• 2-byte Minor Version (expected 0).

• 8-byte Section Length (int64; -1 = not specified).

• Options (variable; walked).

• **Interface Description Block (IDB) body**:

• 2-byte LinkType (uses the same LINKTYPE_* values as libpcap; resolved via the existing internal/pcap LinkTypeName).

• 2-byte Reserved.

• 4-byte SnapLen (max captured bytes per packet).

• Options (if_name / if_description / if_IPv4addr / if_MACaddr / if_speed / if_tsresol / if_os / etc.).

• **Enhanced Packet Block (EPB) body** — the canonical packet record:

• 4-byte Interface ID (index into the section's IDB list).

• 4-byte Timestamp High + 4-byte Timestamp Low (joined to a 64-bit count; resolution depends on the referenced IDB's if_tsresol option, default 10⁻⁶ s).

• 4-byte Captured Packet Length.

• 4-byte Original Packet Length.

• Packet Data (caplen bytes, padded to 4-byte boundary).

• Options (epb_flags / epb_hash / epb_dropcount).

• **Interface Statistics Block (ISB)** — 4-byte Interface ID + 8-byte Timestamp + options (per-interface counters).

• **Options walker** — (Code uint16, Length uint16, Value padded to 4-byte boundary). Generic Options 1 = comment, 2 = custom string (registered per-block-type code 2-N). Block-specific common options surfaced as decoded UTF-8 when the value is plausibly text (SHB hardware/os/ userappl; IDB if_name/if_description/if_os).

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

• Classic libpcap (.pcap) — that's `internal/pcap.Inspect` and the `pcap_decode` Spec; this package handles only the next-gen PCAPng container.

• Per-record protocol dissection — the operator pulls individual frames out of the EPB hex preview and feeds them into the existing 80+ protocol-specific decoders.

• PCAPng capture (this is a *file* reader, not a live- capture interface).

• Decryption Secrets Block payload parsing — the wireshark-flavoured key log file format inside DSB deserves its own dissector (Type 0x544C534B = TLSK is surfaced as raw hex).

Index

• Constants
• type EnhancedPacket
• type InspectOpts
  • func DefaultInspectOpts() InspectOpts
• type Interface
• type Option
• type Section
• type Summary
  • func Inspect(b []byte, opts InspectOpts) (*Summary, error)

Constants

const (
	BlockSHB    uint32 = 0x0A0D0D0A
	BlockIDB    uint32 = 0x00000001
	BlockSPB    uint32 = 0x00000003
	BlockNRB    uint32 = 0x00000004
	BlockISB    uint32 = 0x00000005
	BlockEPB    uint32 = 0x00000006
	BlockIRIG   uint32 = 0x00000007
	BlockDSB    uint32 = 0x00000009
	BlockCustom uint32 = 0x0BAD0001
)

Block types from the IANA pcapng registry.

Types

type EnhancedPacket

type EnhancedPacket struct {
	Index             int    `json:"index"`
	InterfaceID       uint32 `json:"interface_id"`
	TimestampHigh     uint32 `json:"timestamp_high"`
	TimestampLow      uint32 `json:"timestamp_low"`
	Timestamp64       uint64 `json:"timestamp_64"`
	CapturedLength    uint32 `json:"captured_length"`
	OriginalLength    uint32 `json:"original_length"`
	PayloadHex        string `json:"payload_hex,omitempty"`
	PayloadBytesShown int    `json:"payload_bytes_shown,omitempty"`
}

EnhancedPacket is one EPB record summary.

type InspectOpts

type InspectOpts struct {
	// MaxRecords caps the number of EPB summaries returned
	// per section. The block counters and BlockSummary map
	// still reflect the full file walk.
	MaxRecords int
	// MaxPayloadBytes caps the per-EPB payload hex preview.
	MaxPayloadBytes int
}

InspectOpts tunes the walker for output size.

func DefaultInspectOpts

func DefaultInspectOpts() InspectOpts

DefaultInspectOpts returns sensible caps: first 50 EPBs per section, 32-byte hex preview per record.

type Interface

type Interface struct {
	Index        int      `json:"index"`
	LinkType     int      `json:"link_type"`
	LinkTypeName string   `json:"link_type_name"`
	SnapLen      uint32   `json:"snap_length"`
	Options      []Option `json:"options,omitempty"`
}

Interface is one IDB (per-section interface descriptor).

type Option

type Option struct {
	Code      int    `json:"code"`
	Length    int    `json:"length"`
	ValueHex  string `json:"value_hex,omitempty"`
	ValueText string `json:"value_text,omitempty"`
}

Option is one (Code, Length, Value) record from a block's options list.

type Section

type Section struct {
	MajorVersion  int              `json:"major_version"`
	MinorVersion  int              `json:"minor_version"`
	SectionLength int64            `json:"section_length"`
	Options       []Option         `json:"options,omitempty"`
	Interfaces    []Interface      `json:"interfaces,omitempty"`
	BlockSummary  map[string]int   `json:"block_summary"`
	Records       []EnhancedPacket `json:"records,omitempty"`
}

Section is one PCAPng section (delimited by an SHB).

type Summary

type Summary struct {
	Endianness string    `json:"endianness"`
	Sections   []Section `json:"sections"`
	BlockCount int       `json:"block_count"`
	TotalBytes int       `json:"total_bytes"`
	Notes      []string  `json:"notes,omitempty"`
}

Summary is the top-level structured view of a PCAPng file.

func Inspect

func Inspect(b []byte, opts InspectOpts) (*Summary, error)

Inspect walks a PCAPng file from its raw bytes and returns a Summary. Returns an error only for unrecoverable framing issues; per-block decoding errors are flagged via Notes.