goscapy — Go Network Packet Crafting, Dissecting, Sending, Receiving, and Sniffing Library

Features

Everything you need for packet engineering — from crafting to sniffing with a clean, idiomatic Go API.

🔨 Builder API

Fluent method chaining for type-safe, explicit packet construction with compile-time guarantees.

⚡ Shortcut Functions

One-liners for common protocol stacks with sensible defaults. Build packets in a single function call.

🔬 Dissect & Introspect

Parse raw bytes into structured packets with automatic protocol detection, layer extraction, and Show() / Summary() multi-format display.

📡 Send & Receive

Send and receive packets via raw sockets at both L2 (Ethernet) and L3 (IP) levels, with batch I/O, zero-copy, and io_uring async support.

👃 Sniffing

Capture live traffic with callback or channel-based APIs, plus BPF filter support and Linux PacketMMAP (TPACKET_V3) high-performance capture.

✅ Auto Checksums

IP, TCP, UDP, ICMP, ICMPv6, and IPv6 checksums are computed automatically during serialization.

🔗 Layer Binding

Automatic field inference between adjacent layers — IP over Ethernet sets EtherType automatically.

🧩 On-Demand Modules

Contrib module system for lean builds — import only the protocols you need and load with contrib.Load().

🔍 p0f Fingerprinting

Passive OS fingerprinting via TCP SYN analysis (window size, TTL, option layout), with built-in signature database.

💾 PCAP Read/Write

Pure-Go PCAP/pcapng file reading and writing — no libpcap dependency for offline analysis and storage.

🔄 TCP Stream Reassembly

Track TCP sessions, reassemble segments in sequence order, handle overlaps and retransmissions for application-layer analysis.

💻 Cross-Platform

Works on macOS (Darwin) and Linux with platform-specific raw socket implementations. Zero CGO dependencies.

Ping in 3 Libraries — Compare the Simplicity

The same task — build an ICMP Echo Request, send it, receive the reply — written in Python Scapy, goscapy, and raw Go standard library. See how goscapy brings Scapy's elegance to Go.

🐍 Python Scapy ~3 lines

                                    python
                                

                                    from scapy.all import *

# Build + send + receive in one line
ans = sr1(IP(dst="8.8.8.8") /
          ICMP(), timeout=3)
ans.show()
                                

🦎 goscapy (this project) ~3 lines

                                    go
                                

                                    // Build + send + receive first reply
pkt := goscapy.NewIP().
    DstIP("8.8.8.8").
    Over(goscapy.NewICMP().
        Type(8).Code(0)).
    Packet()

_, resp, _ := sendrecv.SendRecv1(
    pkt, "en0", 3*time.Second)
fmt.Println(resp.Summary())
                                

🔵 Go net (stdlib) ~40+ lines

                                    go
                                

                                    // Manual ICMP header construction
type icmpMsg struct {
    Type uint8
    Code uint8
    Chksum uint16
    ID   uint16
    Seq  uint16
}

// Marshal binary by hand...
// Compute checksum manually...
// Open raw socket with net.ListenPacket...
// Handle platform differences...
// Parse response binary by hand...
// ~30 lines of boilerplate
// No layer dissection
// No auto checksums
// No cross-platform abstraction
                                

Feature	🐍 Scapy	🦎 goscapy	🔵 Go stdlib
Build ICMP packet	1 line	1 chain	Manual struct + marshal
Checksum	Auto ✅	Auto ✅	Manual ❌
Send + receive	`sr1()`	`SendRecv1()`	Socket + read loop
Dissect response	Auto ✅	Auto ✅	Manual parsing ❌
Performance	Interpreted 🐢	Compiled ⚡	Compiled ⚡
Type safety	Dynamic	Compile-time ✅	Manual

Library Comparison

How does goscapy compare to other standard or popular network libraries in the Go ecosystem? Here is a breakdown of their features and recommended use cases.

Core Capability Matrix

Capability	🦎 goscapy	📦 gopacket	🔵 golang.org/x/net
Packet Crafting (Builder API)	Fluent Builder + Shortcut functions	Requires manual `SerializeTo()`	Requires manual struct marshalling
Packet Dissecting (Dissector)	`packet.Dissect()` auto detection	Powerful DecodingLayerParser	Only ICMP/IPv4 message parsing
L2 Send/Receive (Raw Socket)	✅ Ethernet level	❌ Depends on libpcap	❌
L3 Send/Receive (Raw Socket)	✅ IP level (ip4:tcp/udp/icmp)	❌	✅ `icmp.ListenPacket` / `ipv4.RawConn`
Sniffing	✅ Channel + Callback + BPF	✅ libpcap/afpacket/pfring	❌
PCAP Read/Write	✅ Pure Go (pcap/pcapng)	✅ (requires libpcap)	❌
TCP Stream Reassembly	✅ `tcpstream` + `reassembly`	✅ tcpassembly	❌
Auto Checksum	✅ IP/TCP/UDP/ICMP	✅^* IP/TCP/UDP (Requires manual binding)	❌ Manual calculation
Layer Binding (Auto Infer)	✅ Automatically infers adjacent fields	❌	❌
BPF Filter	✅ Generate + Attach	✅ Generate + Attach	✅ `bpf.Assemble()` generation
Protocol Coverage	40+ protocols (core + contrib on-demand)	200+ protocols decoded	icmp, ipv4, bpf, etc.
Cross-Platform	✅ Darwin + Linux	✅ Multi-platform	✅ Multi-platform
Design Philosophy	Scapy-like, elegant & simple	Comprehensive decoding, academic/analysis	Lightweight standard library extension

* Note: gopacket supports checksum calculation but requires explicit serialization options and manual network layer binding (e.g. SetNetworkLayerForChecksum).

Recommended Scenarios

🚀 Custom Packet Crafting

Recommended: goscapy

Fluent builder API and one-line SendRecv functions get the job done instantly without boilerplate.

📊 PCAP Analysis

Recommended: goscapy

Pure-Go PCAP/pcapng read/write with TCP stream reassembly and p0f fingerprinting — no libpcap dependency.

⚡ Diagnostics & Scanning

Recommended: goscapy

Perfect for building ping, traceroute, scanning, or probing tools with automatic checksums.

⚡ High-Performance Sniffing

Recommended: gopacket

Supports low-level zero-copy sniffing with afpacket and pfring for high-throughput environments.

🔵 Standard ICMP Only

Recommended: x/net/icmp

The most lightweight and zero-dependency solution if you only need standard ICMP functionality.

🔬 Protocol Reverse Engineering

Recommended: gopacket

Decodes over 200+ protocols, making it suitable for deep security analysis and research.

📦 Zero CGO Dependencies

Recommended: goscapy or x/net

goscapy is written in pure Go without CGO or libpcap dependencies, unlike gopacket which requires libpcap C libraries.

Supported Protocols

Comprehensive coverage across the network stack layers. Core protocols are loaded by default; contrib protocols are loaded on demand.

Layer	Protocols
Link	Ethernet, ARP, Dot1Q (VLAN), LLDP, Dot11 (WiFi 802.11)
Network	IPv4, IPv6 (with extension headers: Hop-by-Hop/Routing/Fragment/DestOpts), ICMP, ICMPv6, NDP (RS/RA/NS/NA/Redirect), OSPF, GRE
Transport	TCP, UDP
Tunnel / Encap	VXLAN, ERSPAN
Application	DNS, DHCP, HTTP, NTP, BGP, SNMP, TLS, QUIC, RADIUS, LDAP, Kerberos
IoT / Wireless	Bluetooth/BLE, Zigbee, LoRaWAN, VoIP (RTP/RTCP/SIP)
Monitoring / Flow	Netflow/IPFIX

Get Started in Seconds

Add goscapy to your project with a single command.

bash

# Install the latest version
go get github.com/smallnest/goscapy

Build a Packet in One Line

🔨 Builder API

                            go
                            
                        

                            // Ethernet + IP + ICMP Echo Request
pkt, err := goscapy.NewEthernet().
    SrcMAC("aa:bb:cc:dd:ee:ff").
    DstMAC("ff:ff:ff:ff:ff:ff").
    Over(goscapy.NewIP().
        SrcIP("192.168.1.1").
        DstIP("8.8.8.8")).
    Over(goscapy.NewICMP().
        Type(8).Code(0)).
    Build()
                        

⚡ Shortcut

                            go
                            
                        

                            // Same packet, in one line
pkt, err := goscapy.EtherIPICMP(
    "ff:ff:ff:ff:ff:ff",
    "8.8.8.8",
    8, 0,
)
                        

🔬 Dissect Raw Bytes

                            go
                            
                            // Parse raw bytes into structured packet
raw := []byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, ...}
pkt, err := packet.Dissect(raw, packet.DissectEthernet)

// One-line summary
fmt.Println(pkt.Summary()) // "IP 192.168.1.1 > 8.8.8.8 / ICMP echo-request"

// Detailed layer-by-layer display
pkt.Show()