smallnest/goscapy

# goscapy [](https://pkg.go.dev/github.com/smallnest/goscapy) [](https://github.com/smallnest/goscapy/actions/workflows/ci.yml) [](https://go.dev/) [](LICENSE) 一个用于构建、解析、发送、接收和嗅探网络数据包的纯Go库。goscapy 提供了符合Go语言习惯的API，包含类型安全的构建器和单行快捷函数。 ## 功能 - **Builder API** — 通过流畅的方法链进行类型安全、显式的数据包构建 - **快捷函数** — 为常见协议栈提供单行函数，配备合理的默认值 - **数据包解析** — 将原始字节解析为结构化数据包，并支持协议自动检测 - **发送与接收** — 通过原始套接字（L2 和 L3）发送和接收数据包 - **数据包嗅探** — 使用基于回调或通道的API捕获实时流量，并支持 BPF 过滤器 - **自动校验和** — 在序列化过程中自动计算 IP、TCP、UDP 和 ICMP 校验和 - **层绑定** — 相邻层之间的自动字段推断（例如，IP over Ethernet → EtherType=0x0800） - **跨平台** — 支持 Darwin (macOS) 和 Linux，包含平台特定的原始套接字实现 ## 支持的协议 | 层 | 协议 | |-------|-----------| | 链路层 | Ethernet, ARP | | 网络层 | IPv4 | | 传输层 | TCP, UDP, ICMP | | 负载 | Raw | ## 安装 ``` go get github.com/smallnest/goscapy ``` ## 快速开始 ### 构建数据包（Builder API） ``` // 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() ``` ### 构建数据包（快捷方式） ``` // Same as above, in one line pkt, err := goscapy.EtherIPICMP("ff:ff:ff:ff:ff:ff", "8.8.8.8", 8, 0) ``` ### 解析数据包 ``` raw := []byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, ...} // raw bytes pkt, err := packet.Dissect(raw, packet.DissectEthernet) fmt.Println(pkt.String()) // "Ethernet / IP / ICMP" ``` ### 发送数据包 ``` pkt, _ := goscapy.EtherIPICMP("ff:ff:ff:ff:ff:ff", "8.8.8.8", 8, 0) sendrecv.Send(pkt, "eth0") // send at L3 (IP level) sendrecv.Sendp(pkt, "eth0") // send at L2 (Ethernet) ``` ### 嗅探数据包 ``` // Callback-based sniff.Sniff(sniff.SniffConfig{ Iface: "eth0", Filter: "icmp", Timeout: 10 * time.Second, }, func(pkt *packet.Packet) bool { fmt.Println(pkt) return true // continue sniffing }) // Channel-based ch, stop := sniff.SniffChan(sniff.SniffConfig{Iface: "eth0", Count: 5}) defer stop() for pkt := range ch { fmt.Println(pkt) } ``` ## 文档 完整文档请访问 [pkg.go.dev/github.com/smallnest/goscapy](https://pkg.go.dev/github.com/smallnest/goscapy)。 ### 包 | 包 | 描述 | |---------|-------------| | `pkg/goscapy` | Builder API 和快捷函数 | | `pkg/packet` | 核心数据包/层类型，构建，解析，字段绑定 | | `pkg/layers` | 协议层定义 (Ethernet, ARP, IP, TCP, UDP, ICMP, Raw) | | `pkg/sendrecv` | 原始套接字发送/接收 (Send, Sendp, Recv, SendRecv) | | `pkg/sniff` | 支持 BPF 过滤器的数据包嗅探 | | `pkg/fields` | 字段类型系统 (序列化, 反序列化) | ### 快捷函数 | 函数 | 协议栈 | |----------|---------------| | `EtherIP` | Ethernet + IPv4 + Payload | | `EtherIPICMP` | Ethernet + IPv4 + ICMP | | `EtherIPTCP` | Ethernet + IPv4 + TCP | | `EtherIPUDP` | Ethernet + IPv4 + UDP | | `EtherARP` | Ethernet + ARP | | `IPICMP` | IPv4 + ICMP (无 Ethernet) | | `IPTCP` | IPv4 + TCP (无 Ethernet) | | `IPUDP` | IPv4 + UDP (无 Ethernet) | ### 构建器 | 构建器 | 关键方法 | |---------|-------------| | `EthernetBuilder` | `SrcMAC`, `DstMAC`, `Type` | | `IPBuilder` | `SrcIP`, `DstIP`, `TTL`, `Proto`, `ID` | | `ICMPBuilder` | `Type`, `Code`, `ID`, `Seq` | | `TCPBuilder` | `SrcPort`, `DstPort`, `Flags`, `Seq`, `Ack`, `Window` | | `UDPBuilder` | `SrcPort`, `DstPort` | | `ARPBuilder` | `Op`, `SrcMAC`, `SrcIP`, `DstMAC`, `DstIP` | ## 平台支持 | 平台 | L2 收发 | L3 收发 | BPF 过滤器 | 环回接口 | |----------|:------------:|:------------:|:----------:|:--------:| | macOS (Darwin) | BPF | AF_INET | 内核 BPF | lo0 | | Linux | AF_PACKET | AF_INET | SO_ATTACH_FILTER | lo | ## 要求 - Go 1.26+ - macOS 或 Linux - 执行原始套接字操作需要 Root/管理员权限 - `tcpdump`（可选，用于通过 `sniff.CompileFilter` 编译 BPF 过滤器字符串） ## Makefile 文件 ``` make build # Build all packages make test # Run all tests make test-race # Run tests with race detector make test-cover # Run tests with coverage profile make bench # Run benchmarks make lint # Run golangci-lint make fmt # Format code make vet # Run go vet make check # Run fmt + vet + lint + test ``` ## 许可证 MIT 许可证。详情请参阅 [LICENSE](LICENSE)。

标签：ARP, BPF 过滤器, EVTX分析, Golang, Go 语言, ICMP, IPv4, Scapy 移植, TCP, UDP, 以太网, 内核驱动, 原始套接字, 安全编程, 数据包处理, 数据包构造, 数据包解析, 网络协议, 网络嗅探, 网络安全, 网络工具, 网络库, 网络编程, 自动校验和, 防御绕过, 隐私保护