# bcap API 手册 开发者参考文档。快速接入说明见 [`../README.md`](../README.md)。 ## 1. 主包职责 主包负责： - 统一的报文事实层 - 统一的 flow 表达 - 统一的轻量 hint 层 - 以 TCP 为重点的轻状态跟踪 主包不负责： - 报告生成 - 业务规则判断 - 用户侧展示文案 - 动作编排 - 深度流重组 - 应用层协议解析框架 核心对象： - `Decoder` - 单包事实解码 - `Tracker` - flow 状态与轻量提示 - `Analyzer` - `Decoder + Tracker` 组合入口 ## 2. 公开入口 ### 2.1 `Decoder` 构造： ```go decoder := bcap.NewDecoder() ``` 主要方法： ```go Decode(packet gopacket.Packet) (Packet, error) DecodeWithOptions(packet gopacket.Packet, opts DecodeOptions) (Packet, error) ``` 使用时机： - 只想获得单包事实 - 自己维护状态机 - 想把 `bcap` 当作标准化事实提取层 ### 2.2 `Tracker` 构造： ```go tracker := bcap.NewTracker() tracker := bcap.NewTrackerWithConfig(cfg) ``` 主要方法： ```go Observe(packet Packet) (Observation, error) CleanupExpiredFlows() int ActiveFlowCount() int Stop() ``` 使用时机： - 已经在别处完成解码 - 只想复用 `bcap` 的 flow / hint 跟踪能力 ### 2.3 `Analyzer` 构造： ```go analyzer := bcap.NewAnalyzer() analyzer := bcap.NewAnalyzerWithConfig(cfg) ``` 主要方法： ```go ObservePacket(packet gopacket.Packet) (Observation, error) ObservePacketWithOptions(packet gopacket.Packet, opts DecodeOptions) (Observation, error) Decoder() *Decoder Tracker() *Tracker Stop() ``` 使用时机： - 在线抓包 - 离线遍历 - 绝大多数直接接入型工具 ## 3. `DecodeOptions` `DecodeOptions` 目前包含两个字段： ```go type DecodeOptions struct { BaseTime time.Time SrcMACOverride net.HardwareAddr } ``` 字段： - `BaseTime` - 用于计算 `Packet.Meta.RelativeTime` - `Analyzer.ObservePacket(...)` 未显式传入时，会自动以首包时间作为基准 - `SrcMACOverride` - 用于覆盖源 MAC ## 4. 数据模型 ### 4.1 `Packet` `Packet` 表示单包事实。 ```go type Packet struct { Meta Meta Link LinkFacts Network NetworkFacts Transport TransportFacts Raw RawFacts } ``` 不包含跨包推断结果。 ### 4.2 `Meta` ```go type Meta struct { Timestamp time.Time TimestampMicros int64 RelativeTime time.Duration CaptureLength int Length int } ``` 字段： - `Timestamp` / `TimestampMicros` - 捕获时间 - `RelativeTime` - 相对 `BaseTime` 的时间差 - `CaptureLength` - 实际捕获长度 - `Length` - 原始报文长度 ### 4.3 `LinkFacts` ```go type LinkFacts struct { Kind LinkKind SrcMAC net.HardwareAddr DstMAC net.HardwareAddr } ``` 当前支持的链路类型： - `LinkKindEthernet` - `LinkKindLinuxSLL` - `LinkKindLinuxSLL2` - `LinkKindUnknown` ### 4.4 `NetworkFacts` ```go type NetworkFacts struct { Family NetworkFamily SrcIP string DstIP string TTL uint8 HopLimit uint8 ProtocolNumber uint16 ARP *ARPFacts } ``` 当前支持的网络族： - `NetworkFamilyIPv4` - `NetworkFamilyIPv6` - `NetworkFamilyARP` - `NetworkFamilyUnknown` 备注： - IPv4 报文主要填 `TTL` - IPv6 报文主要填 `HopLimit` - ARP 报文会同时填充 `ARP` ### 4.5 `TransportFacts` ```go type TransportFacts struct { Kind ProtocolKind Payload int TCP *TCPFacts UDP *UDPFacts ICMP *ICMPFacts Unknown *UnknownTransportFacts } ``` 当前支持协议： - `ProtocolTCP` - `ProtocolUDP` - `ProtocolICMPv4` - `ProtocolICMPv6` - `ProtocolARP` - `ProtocolUnknown` ### 4.6 协议事实结构 #### `TCPFacts` ```go type TCPFacts struct { SrcPort string DstPort string Seq uint32 Ack uint32 Window uint16 SYN bool ACK bool FIN bool RST bool ECE bool CWR bool PSH bool Checksum uint16 Payload int } ``` #### `UDPFacts` ```go type UDPFacts struct { SrcPort string DstPort string Length uint16 Payload int } ``` #### `ICMPFacts` ```go type ICMPFacts struct { Version int Type uint8 Code uint8 Checksum uint16 ID uint16 Seq uint16 Payload int } ``` #### `ARPFacts` ```go type ARPFacts struct { Operation uint16 SenderMAC net.HardwareAddr TargetMAC net.HardwareAddr SenderIP string TargetIP string } ``` ### 4.7 `FlowKey` / `FlowRef` 推荐使用结构化 flow，不把字符串 key 当成唯一公共接口。 ```go type Endpoint struct { IP string Port string } type FlowKey struct { Family NetworkFamily Protocol ProtocolKind Src Endpoint Dst Endpoint } type FlowRef struct { Forward FlowKey Reverse FlowKey Stable string } ``` 方法： ```go func (f FlowKey) StableString() string ``` 字段： - `Forward` - 当前方向 - `Reverse` - 反向方向 - `Stable` - 稳定字符串表达，可用于日志和 map key ### 4.8 `Observation` ```go type Observation struct { Packet Packet Flow FlowRef Hints HintSet } ``` - `Packet` - 报文事实 - `Flow` - 流引用 - `Hints` - 推断结果 ## 5. Hint 模型 ### 5.1 `HintSet` ```go type HintSet struct { Summary SummaryHint Tags []Tag TCP *TCPHint UDP *UDPHint ICMP *ICMPHint ARP *ARPHint } ``` - `Summary` - 摘要代码 - `Tags` - 标签集合 - 协议专属 hint - 放在对应子结构中 ### 5.2 TCP hints ```go type TCPHint struct { Phase TCPPhase Event TCPEvent LegacyState uint8 Seq uint32 Ack uint32 Window uint16 Payload int Retransmission bool Keepalive bool KeepaliveResponse bool RST bool ECE bool CWR bool } ``` Phase： - `TCPPhaseHandshake` - `TCPPhaseEstablished` - `TCPPhaseTeardown` - `TCPPhaseSpecial` - `TCPPhaseUnknown` Event： - `TCPEventSYN` - `TCPEventSYNACK` - `TCPEventHandshakeACK` - `TCPEventACK` - `TCPEventRetransmission` - `TCPEventKeepalive` - `TCPEventKeepaliveResp` - `TCPEventFIN` - `TCPEventFINACK` - `TCPEventTeardownACK` - `TCPEventRST` - `TCPEventECE` - `TCPEventCWR` - `TCPEventUnknown` 常见 Tag： - `TagTCPHandshakeSYN` - `TagTCPHandshakeSYNACK` - `TagTCPHandshakeACK` - `TagTCPTeardownFIN` - `TagTCPTeardownFINACK` - `TagTCPTeardownACK` - `TagTCPPacket` - `TagTCPRetransmit` - `TagTCPKeepalive` - `TagTCPKeepaliveResp` - `TagTCPRst` - `TagTCPEce` - `TagTCPCwr` ### 5.3 UDP / ICMP / ARP hints #### `UDPHint` ```go type UDPHint struct { Payload int } ``` 对应 Tag： - `TagUDPPacket` #### `ICMPHint` ```go type ICMPHint struct { Version int Type uint8 Code uint8 IsEcho bool IsEchoReply bool IsUnreachable bool IsTimeExceeded bool } ``` 对应 Tag： - `TagICMPPacket` - `TagICMPEchoRequest` - `TagICMPEchoReply` - `TagICMPUnreachable` - `TagICMPTimeExceeded` #### `ARPHint` ```go type ARPHint struct { Operation uint16 Request bool Reply bool } ``` 对应 Tag： - `TagARPRequest` - `TagARPReply` ## 6. TCP 跟踪边界 `Tracker` 对 TCP 只做轻量跟踪，不做完整 TCP 栈模拟。 当前覆盖： - 握手识别 - 挥手识别 - 普通 ACK 识别 - 重传识别 - keepalive 识别 - keepalive response 识别 - RST / ECE / CWR 识别 实现说明： - 基于 flow 跟踪 - 使用有限 segment 记忆辅助判断重传 - keepalive 使用启发式判断 - 支持超时清理 不覆盖： - 严格 TCP 协议验证 - 深度重组 - 业务级根因结论 ## 7. 配置 ### 7.1 `PacketsConfig` ```go type PacketsConfig struct { ConnectionTimeout time.Duration CleanupInterval time.Duration } ``` 字段： - `ConnectionTimeout` - flow 状态保留时长 - `CleanupInterval` - 自动清理周期 默认值： ```go const ( DefaultConnectionTimeout = 5 * time.Minute DefaultCleanupInterval = 1 * time.Minute ) ``` 默认配置： ```go cfg := bcap.DefaultConfig() ``` ### 7.2 生命周期方法 `Tracker`： - `CleanupExpiredFlows() int` - `ActiveFlowCount() int` - `Stop()` `Analyzer`： - `Decoder() *Decoder` - `Tracker() *Tracker` - `Stop()` 备注： - 长生命周期进程退出前调用 `Stop()` - 如需自行控制清理节奏，可将 `CleanupInterval` 设为 `0`，再手动调用 `CleanupExpiredFlows()` ## 8. 错误模型 `bcap` 使用 `*ParseError` 表达解析问题： ```go type ParseError struct { Type ParseErrorType Layer string Message string Err error } ``` 错误类型： - `ErrTypeLinkLayer` - `ErrTypeNetwork` - `ErrTypeTransport` - `ErrTypeUnsupported` 常见触发条件： - 没有有效网络层 - 协议层对象类型不匹配 - 跟踪阶段缺少必须的协议事实 ## 9. 子包 ### 9.1 `libpcap` `libpcap` 子包负责在线抓包输入。 入口： - `FindAllDevs()` - `NewCatch(host, filter)` - `NewCatchEth(eth, filter)` - `SetRecall(func(gopacket.Packet))` - `Run()` - `Stop()` 常见组合： - 子包接收 `gopacket.Packet` - 主包 `Analyzer` 做解析和提示 - 上层工具做展示和统计 ### 9.2 `nfq` `nfq` 子包负责 NFQUEUE 输入适配。 入口： - `NewNfQueue(ctx, queid, maxqueue)` - `SetRecall(func(id uint32, q *nfqueue.Nfqueue, p Packet))` - `Run()` - `Stop()` 备注： - `nfq.Packet` 只是 NFQUEUE 输入包装 - 它不是主包的 `bcap.Packet` - 一般仍然从其中取 `gopacket.Packet`，再交给 `Analyzer` 或 `Decoder` ## 10. 示例 ### 10.1 直接用 `Analyzer` ```go analyzer := bcap.NewAnalyzer() defer analyzer.Stop() obs, err := analyzer.ObservePacket(packet) if err != nil { return err } fmt.Println(obs.Flow.Stable) fmt.Println(obs.Packet.Transport.Kind) fmt.Println(obs.Hints.Summary.Code) ``` ### 10.2 自己管理解码和跟踪 ```go decoder := bcap.NewDecoder() tracker := bcap.NewTracker() defer tracker.Stop() decoded, err := decoder.DecodeWithOptions(packet, bcap.DecodeOptions{ BaseTime: firstPacketTS, }) if err != nil { return err } obs, err := tracker.Observe(decoded) if err != nil { return err } ``` ### 10.3 典型离线遍历 ```go f, err := os.Open("sample.pcap") if err != nil { return err } defer f.Close() reader, err := pcapgo.NewReader(f) if err != nil { return err } source := gopacket.NewPacketSource(reader, reader.LinkType()) analyzer := bcap.NewAnalyzer() defer analyzer.Stop() for packet := range source.Packets() { obs, err := analyzer.ObservePacket(packet) if err != nil { continue } fmt.Println(obs.Packet.Network.SrcIP, obs.Hints.Summary.Code) } ``` ## 11. 辅助函数 主包还提供两个轻量格式化函数： - `FormatDuration(time.Duration) string` - `FormatBytes(uint64) string` 用于轻量日志与终端展示。 ## 12. 迁移说明 主包旧接口已经被清理，删除项包括： - `Packets` - `PacketInfo` - `ParsePacket` - `NewPackets` - `NewPacketsWithConfig` - `LegacyPacketInfoFromObservation` - `GetStateDescription` - `PrintStats` - `ExportConnectionsToJSON` 迁移方向： - 旧的单包解析入口迁到 `Decoder` - 旧的“包 + 状态”混合对象迁到 `Observation` - 旧的连接跟踪职责迁到 `Tracker` - 大部分调用场景直接迁到 `Analyzer` 旧代码如果大量依赖字符串 key： - 新代码优先改为使用 `FlowRef.Forward` / `FlowRef.Reverse` - 如果只是为了日志或 map key，可以继续使用 `FlowRef.Stable` ## 13. 相关文档 - 快速入口见 [`../README.md`](../README.md) - 设计备忘见 [`dev.md`](./dev.md)