bcap/README.md

bcap

bcap 是一个轻量的 Go 报文解析库，重点提供两类能力：

• 统一提取报文事实
• 基于连续报文输出轻量协议提示

它适合作为抓包工具、离线诊断工具、CLI/TUI 浏览器的底层解析层，但并不试图替代完整协议栈、深度重组引擎或最终用户报告系统。

1. 核心定位

bcap 主包当前围绕 3 个对象展开：

• Decoder
  • 无状态，只负责单包解码，输出 Packet
• Tracker
  • 有状态，只负责基于连续报文做轻量跟踪，输出 Observation
• Analyzer
  • Decoder + Tracker 的组合入口，适合大多数直接接入场景

分工可以直接理解为：

• Decoder 负责单包事实
• Tracker 负责跨包提示
• Analyzer 负责把两者串起来

2. 适用场景

bcap 主要适合：

• 在线抓包后的统一元数据提取
• 离线 pcap 遍历分析
• TCP/UDP/ICMP/ARP 的统一识别
• TCP 关键行为提示，例如握手、挥手、重传、keepalive、RST

bcap 不直接负责：

• 诊断结论生成
• CLI/TUI 文案
• Excel / JSON / 报告拼装
• 动作编排与干预逻辑
• 工具侧业务状态缓存

3. 快速开始

安装：

go get b612.me/bcap

最常见的接入方式是直接使用 Analyzer：

package main

import (
	"fmt"

	"b612.me/bcap"
	"github.com/gopacket/gopacket"
)

func consume(packet gopacket.Packet) error {
	analyzer := bcap.NewAnalyzer()
	defer analyzer.Stop()

	obs, err := analyzer.ObservePacket(packet)
	if err != nil {
		return err
	}

	fmt.Println("flow:", obs.Flow.Stable)
	fmt.Println("protocol:", obs.Packet.Transport.Kind)
	fmt.Println("summary:", obs.Hints.Summary.Code)

	if obs.Hints.TCP != nil {
		fmt.Println("tcp event:", obs.Hints.TCP.Event)
	}
	return nil
}

如果你需要自行控制“解码”和“跟踪”两个阶段，也可以拆开使用：

decoder := bcap.NewDecoder()
tracker := bcap.NewTracker()
defer tracker.Stop()

decoded, err := decoder.Decode(packet)
if err != nil {
	return err
}

obs, err := tracker.Observe(decoded)
if err != nil {
	return err
}

4. 支持范围

当前主包支持的主要识别范围：

• 链路层
  • Ethernet
  • Linux SLL
  • Linux SLL2
• 网络层
  • IPv4
  • IPv6
  • ARP
• 传输层 / 协议层
  • TCP
  • UDP
  • ICMPv4
  • ICMPv6
  • Unknown

当前 TCP 轻量提示重点覆盖：

• 三次握手
• 四次挥手
• 普通 ACK
• 重传
• keepalive
• keepalive response
• RST
• ECE / CWR

5. 如何选接口

优先级建议：

• 大多数工具直接用 Analyzer
• 只要报文事实时用 Decoder
• 你已经有自己的输入管线，只缺轻量状态跟踪时用 Tracker

如果没有特殊理由，优先选择 Analyzer，接入成本最低。

6. 包结构

6.1 主包 b612.me/bcap

负责：

• 统一事实模型
• 统一 flow 模型
• 统一 hint 模型
• 轻量 TCP 跟踪

6.2 子包 libpcap

负责：

• 基于 pcap 的抓包输入适配

6.3 子包 nfq

负责：

• 基于 NFQUEUE 的输入适配

通常的组合方式是：

• libpcap / nfq 提供输入
• bcap.Analyzer 负责解析与提示
• 上层工具负责展示、统计、导出和策略

7. 文档导航

如果你只是要快速接入，看本 README 基本够用。

如果你要看完整 API、模型字段、配置项和迁移说明，请继续阅读：

• doc/api.md

如果你要看当前架构思路和设计边界，请看：

• doc/dev.md

8. 迁移提示

bcap 主包已经移除了旧的胖接口，旧的以下模型不再推荐使用，并且主体已经删除：

• Packets
• PacketInfo
• ParsePacket
• NewPackets
• NewPacketsWithConfig
• LegacyPacketInfoFromObservation
• GetStateDescription
• PrintStats
• ExportConnectionsToJSON

新的迁移方向是：

• 单包事实解析改用 Decoder
• 报文观察结果改用 Observation
• TCP 轻量状态识别改用 Tracker
• 大多数场景直接改用 Analyzer

9. 测试

开发或改动后，至少建议执行：

go test ./...

10. License

本项目采用 Apache License 2.0。

完整协议文本见：

• LICENSE