Documentation
¶
Overview ¶
Package netflow decodes NetFlow v5 export packets per Cisco's public NetFlow v5 specification (1996; the dominant flow-export format on enterprise + ISP networks for two decades, still emitted by every Cisco / Juniper / Arista router that runs classic NetFlow). NetFlow records summarise unidirectional IP flows — every (SrcIP, DstIP, SrcPort, DstPort, Proto) tuple seen by a routing-plane sampler is exported to a collector for traffic accounting, capacity planning, anomaly detection, and SIEM correlation.
Wrap-vs-native judgement
Native. NetFlow v5 is fully public; the wire format is a tight 24-byte header followed by a uniform array of 48-byte flow records. No crypto, no compression, no variable-length fields. Operators paste NetFlow bytes (UDP destination port 2055 / 9555 / 9995) from a `tcpdump -X udp port 2055` line or a Wireshark Follow- UDP-Stream view and get the documented header + per- record breakdown.
What this package covers
**24-byte header**:
bytes 0-1: **Version** (uint16 BE; must be 5).
bytes 2-3: **Count** (uint16 BE; number of flow records in this packet, 1-30; the upper bound is set by MTU — 30 × 48 + 24 = 1464 < 1500).
bytes 4-7: **SysUptime** (uint32 BE; milliseconds since the exporting device booted).
bytes 8-11: **Unix Secs** (uint32 BE; epoch seconds of the current export).
bytes 12-15: **Unix Nsecs** (uint32 BE; nanoseconds since Unix Secs).
bytes 16-19: **Flow Sequence** (uint32 BE; per-source monotonic counter of flows exported — gaps signal collector data loss).
byte 20: **Engine Type** (uint8; flow engine type — typically 0 RP, 1 LC).
byte 21: **Engine ID** (uint8; slot/engine ID for multi-engine routers).
bytes 22-23: **Sampling Interval** — top 2 bits = **sampling mode** (0 unsampled, 1 1-in-N deterministic, 2 1-in-N random); bottom 14 bits = interval N.
**48-byte flow record** (repeated `Count` times):
bytes 0-3: SrcAddr (IPv4).
bytes 4-7: DstAddr (IPv4).
bytes 8-11: NextHop (IPv4 — next-hop router for outbound forwarding).
bytes 12-13: Input (uint16 BE; SNMP ifIndex of incoming interface).
bytes 14-15: Output (uint16 BE; SNMP ifIndex of outgoing interface).
bytes 16-19: dPkts (uint32 BE; packets in this flow).
bytes 20-23: dOctets (uint32 BE; bytes in this flow).
bytes 24-27: First (uint32 BE; SysUptime when first packet was seen, in ms).
bytes 28-31: Last (uint32 BE; SysUptime when last packet was seen, in ms).
bytes 32-33: SrcPort (uint16 BE).
bytes 34-35: DstPort (uint16 BE).
byte 36: Pad1.
byte 37: **TCP Flags** — cumulative OR of all TCP flags seen during the flow (8 named bits per RFC 793
RFC 3168: FIN / SYN / RST / PSH / ACK / URG / ECE / CWR).
byte 38: **Protocol** — IP protocol number per IANA: 0 HOPOPT / 1 ICMP / 2 IGMP / 6 TCP / 17 UDP / 41 IPv6 / 47 GRE / 50 ESP / 51 AH / 89 OSPF / 103 PIM / 112 VRRP / 132 SCTP. Uncatalogued values surfaced with the raw number.
byte 39: ToS (uint8; IP type-of-service byte).
bytes 40-41: SrcAS (uint16 BE; source ASN — populated when the exporter has BGP-table awareness).
bytes 42-43: DstAS (uint16 BE; destination ASN).
byte 44: SrcMask (uint8; source prefix length).
byte 45: DstMask (uint8; destination prefix length).
bytes 46-47: Pad2.
**Per-record derived fields**: duration in milliseconds (Last - First); protocol name lookup from the 13-entry IANA-protocol table.
What this package does NOT cover (deliberately out of scope)
UDP framing — feed NetFlow bytes after the UDP header strip. NetFlow v5 ships on UDP, conventionally to ports 2055 / 9555 / 9995.
NetFlow v9 (RFC 3954) — template-based; different envelope, different walker; warrants its own Spec.
IPFIX (RFC 7011) — IETF standardisation of NetFlow v9; also warrants its own Spec.
sFlow — InMon packet-sampling protocol; different model entirely (per-packet sample, not per-flow summary).
Flow-record aggregation / windowing — that's collector- side work; this Spec just decodes the wire.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FlowRecord ¶
type FlowRecord struct {
Index int `json:"index"`
SrcAddress string `json:"src_address"`
DstAddress string `json:"dst_address"`
NextHop string `json:"next_hop"`
InputInterface int `json:"input_interface"`
OutputInterface int `json:"output_interface"`
Packets uint32 `json:"packets"`
Bytes uint32 `json:"bytes"`
FirstSysUptimeMs uint32 `json:"first_sys_uptime_ms"`
LastSysUptimeMs uint32 `json:"last_sys_uptime_ms"`
DurationMs uint32 `json:"duration_ms"`
SrcPort int `json:"src_port"`
DstPort int `json:"dst_port"`
TCPFlags int `json:"tcp_flags"`
TCPFlagsHex string `json:"tcp_flags_hex"`
TCPFlagBreakdown TCPFlagSet `json:"tcp_flag_breakdown,omitempty"`
Protocol int `json:"protocol"`
ProtocolName string `json:"protocol_name"`
TypeOfService int `json:"type_of_service"`
SrcAS int `json:"src_as"`
DstAS int `json:"dst_as"`
SrcMask int `json:"src_mask"`
DstMask int `json:"dst_mask"`
SrcPrefix string `json:"src_prefix"`
DstPrefix string `json:"dst_prefix"`
}
FlowRecord is one decoded 48-byte flow record.
type Result ¶
type Result struct {
Version int `json:"version"`
Count int `json:"count"`
SysUptimeMs uint32 `json:"sys_uptime_ms"`
UnixSeconds uint32 `json:"unix_seconds"`
UnixNanoseconds uint32 `json:"unix_nanoseconds"`
ExportTimestampISO string `json:"export_timestamp_iso"`
FlowSequence uint32 `json:"flow_sequence"`
EngineType int `json:"engine_type"`
EngineID int `json:"engine_id"`
SamplingMode int `json:"sampling_mode"`
SamplingModeName string `json:"sampling_mode_name"`
SamplingInterval int `json:"sampling_interval"`
Records []FlowRecord `json:"records"`
TotalBytes int `json:"total_bytes"`
Notes []string `json:"notes,omitempty"`
}
Result is the top-level decoded view of a NetFlow v5 packet.
type TCPFlagSet ¶
type TCPFlagSet struct {
FIN bool `json:"fin"`
SYN bool `json:"syn"`
RST bool `json:"rst"`
PSH bool `json:"psh"`
ACK bool `json:"ack"`
URG bool `json:"urg"`
ECE bool `json:"ece"`
CWR bool `json:"cwr"`
}
TCPFlagSet is the decoded 8-bit TCP flags byte from a flow record. RFC 793 + RFC 3168.
Source Files