219 lines
4.1 KiB
Markdown
219 lines
4.1 KiB
Markdown
# 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. 快速开始
|
||
|
||
安装：
|
||
|
||
```bash
|
||
go get b612.me/bcap
|
||
```
|
||
|
||
最常见的接入方式是直接使用 `Analyzer`：
|
||
|
||
```go
|
||
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
|
||
}
|
||
```
|
||
|
||
如果你需要自行控制“解码”和“跟踪”两个阶段，也可以拆开使用：
|
||
|
||
```go
|
||
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/api.md)
|
||
|
||
如果你要看当前架构思路和设计边界，请看：
|
||
|
||
- [`doc/dev.md`](./doc/dev.md)
|
||
|
||
## 8. 迁移提示
|
||
|
||
`bcap` 主包已经移除了旧的胖接口，旧的以下模型不再推荐使用，并且主体已经删除：
|
||
|
||
- `Packets`
|
||
- `PacketInfo`
|
||
- `ParsePacket`
|
||
- `NewPackets`
|
||
- `NewPacketsWithConfig`
|
||
- `LegacyPacketInfoFromObservation`
|
||
- `GetStateDescription`
|
||
- `PrintStats`
|
||
- `ExportConnectionsToJSON`
|
||
|
||
新的迁移方向是：
|
||
|
||
- 单包事实解析改用 `Decoder`
|
||
- 报文观察结果改用 `Observation`
|
||
- TCP 轻量状态识别改用 `Tracker`
|
||
- 大多数场景直接改用 `Analyzer`
|
||
|
||
## 9. 测试
|
||
|
||
开发或改动后，至少建议执行：
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
## 10. License
|
||
|
||
本项目采用 Apache License 2.0。
|
||
|
||
完整协议文本见：
|
||
|
||
- [`LICENSE`](./LICENSE)
|