0x1f6/dashcap

# dashcap 网络数据包行车记录仪 —— 持续进行全包捕获，并支持按需持久化。 dashcap 将所有网络流量持续捕获到预分配的 pcapng 分段环形缓冲区中。当被触发时（通过 REST API、信号或 CLI），它会保存相关的捕获窗口（包括触发时刻*之前*的流量），以供后续分析。可以把它当作你网络的行车记录仪：一直在录制，仅在发生情况时保存。 ## 工作原理 ``` Network Interface → Capture Engine → Segment Writer → Ring Buffer (fixed size, overwrites oldest) ↓ on trigger Saved Captures (pcapng + metadata.json) ``` - 数据包通过 libpcap (Linux/macOS) 或 Npcap (Windows) 捕获，并写入固定大小的 pcapng 分段文件 - 分段以环形方式循环 —— 当缓冲区满时，最旧的分段会被覆盖 - 所有磁盘空间在启动时预分配；占用空间恒定为 `segment_count * segment_size` - 触发操作会将相关时间窗口合并为单个 `capture.pcapng` 文件，保存在 `saved/` 目录中并附带元数据 ## 状态 **第一阶段 (MVP) 已完成。** 核心的磁盘捕获管道及 REST API 触发功能已在 Linux 上运行。完整路线图请参阅 [DESIGN.md](DESIGN.md)。 已实现的功能： - `gopacket/pcap` 捕获后端（跨平台） - 带有精确字节追踪的 pcapng 分段写入器 - 带有预分配分段和循环功能的环形缓冲区 - 包含 `/trigger`, `/status`, `/health`, `/ring`, `/triggers` 端点的 REST API - Bearer-token API 认证（默认启用，自动生成 token） - API 服务器的 TLS 支持 (`--tls-cert` / `--tls-key`) - 触发保存功能将分段合并为单个 `capture.pcapng` 文件 - 接口锁定（每个接口仅允许一个实例） - 磁盘安全检查（基于绝对值和百分比的可用空间阈值） - 平台感知路径 ## 系统要求 | 平台 | 需求 | |----------|-------------| | Linux | `libpcap-dev` (`apt install libpcap-dev` 或 `dnf install libpcap-devel`) | | Windows | 已安装 [Npcap](https://npcap.com/) (与 Wireshark 相同) | | macOS | libpcap (随 Xcode Command Line Tools 提供) | | 所有 | 启用 CGO 的 Go 1.25+ | ## 构建 ``` make build # → bin/dashcap ``` 二进制文件需要 `CGO_ENABLED=1`，因为 gopacket 需要链接 libpcap。这由 Makefile 自动处理。 对于交叉编译（需要特定平台的 libpcap/Npcap SDK）： ``` make cross # → dist/dashcap-linux-amd64, dist/dashcap-windows-amd64.exe, dist/dashcap-darwin-arm64 ``` ## 快速开始 本示例使用环回接口 (`lo`)，因此除了 `CAP_NET_RAW` 外，你无需任何特殊硬件或权限即可试用。 ### 1. 构建并启动 dashcap ``` make build # 从一个小型环形缓冲区开始（总共 10 MB，1 MB 分段 = 10 个分段） sudo bin/dashcap -i lo --buffer-size 10MB --segment-size 1MB --api-port 9800 ``` 你应该会看到： ``` API token: dashcap vdev starting on interface lo ring buffer: 10 segments x 1MB = 10MB total ring pre-allocated at /var/lib/dashcap/lo WARNING: API auth enabled without TLS — tokens sent in cleartext REST API listening on :9800 ``` 从输出中复制 API token —— 所有 API 请求（除了 `/health`）都需要它。要使用可预测的 token，请传递 `--api-token ` 或设置 `DASHCAP_API_TOKEN=`。 ### 2. 生成一些流量 在第二个终端中： ``` ping -c 100 127.0.0.1 # 或 curl http://127.0.0.1:9800/api/v1/health ``` ### 3. 检查状态 ``` curl -s -H "Authorization: Bearer " http://127.0.0.1:9800/api/v1/status | python3 -m json.tool ``` ``` { "interface": "lo", "uptime": "42s", "segment_count": 10, "total_packets": 200, "total_bytes": 19600 } ``` ### 4. 触发保存 ``` curl -s -X POST -H "Authorization: Bearer " http://127.0.0.1:9800/api/v1/trigger | python3 -m json.tool ``` ``` { "id": "1740960600000000000-1", "timestamp": "2026-03-02T22:30:00Z", "source": "api", "status": "pending" } ``` ### 5. 检查已保存的捕获 ``` ls /var/lib/dashcap/lo/saved/ # → 2026-03-02T22-30-00_api/ cat /var/lib/dashcap/lo/saved/2026-03-02T22-30-00_api/metadata.json # → trigger metadata with capture path # 在 Wireshark 中打开（所有分段合并为一个文件）： wireshark /var/lib/dashcap/lo/saved/2026-03-02T22-30-00_api/capture.pcapng ``` ### 6. 查看环形缓冲区状态 ``` curl -s -H "Authorization: Bearer " http://127.0.0.1:9800/api/v1/ring | python3 -m json.tool ``` ### 7. 停止 dashcap 按 `Ctrl+C` 或发送 `SIGTERM` —— dashcap 会刷新活动分段并干净地退出。 ## CLI 参考 | 标志 | 默认值 | 描述 | |------|---------|-------------| | `-i`, `--interface` | *(必填)* | 要进行捕获的网络接口 | | `--buffer-size` | `2GB` | 环形缓冲区总大小 (例如 `2GB`, `500MB`) | | `--segment-size` | `100MB` | 每个环形分段的大小 (例如 `100MB`, `1MB`) | | `--data-dir` | `/var/lib/dashcap/` | 环形缓冲区和已保存捕获的数据目录 | | `--api-port` | `9800` | REST API 的 TCP 端口 (`0` = 禁用) | | `--api-token` | *(自动生成)* | API 认证的 Bearer token | | `--no-auth` | `false` | 完全禁用 API 认证 | | `--tls-cert` | | TLS 证书文件路径 (需要 `--tls-key`) | | `--tls-key` | | TLS 私钥文件路径 (需要 `--tls-cert`) | | `--pre-duration` | `5m` | 触发前向前保存的时长 | | `--promiscuous` | `true` | 在接口上启用混杂模式 | | `--snaplen` | `0` | 快照长度 (`0` = 完整数据包) | 环境变量： | 变量 | 描述 | |----------|-------------| | `DASHCAP_API_TOKEN` | API token (会被 `--api-token` 标志覆盖) | 子命令： ``` dashcap version # Print version, commit, and build time ``` ## REST API 所有端点均返回 JSON。API 监听 `--api-port` 指定的端口。 **认证：** 除 `/health` 外的所有端点都需要 bearer token。每次请求都需包含 `Authorization: Bearer ` 标头。Token 会在启动时打印到 stderr。使用 `--no-auth` 禁用认证。 **TLS：** 传递 `--tls-cert` 和 `--tls-key` 以启用 HTTPS。若无 TLS，token 将以明文传输（会记录警告日志）。 | 方法 | 端点 | 认证 | 描述 | |--------|----------|------|-------------| | `GET` | `/api/v1/health` | 否 | 存活检查 —— 返回 `{"status": "ok"}` | | `GET` | `/api/v1/status` | 是 | 实例状态：接口、运行时间、包/字节计数 | | `POST` | `/api/v1/trigger` | 是 | 触发保存触发前窗口的数据 | | `GET` | `/api/v1/triggers` | 是 | 列出所有触发记录（最新的在前） | | `GET` | `/api/v1/ring` | 是 | 每个分段的元数据：索引、路径、时间戳、包/字节计数 | ## 配置 dashcap 通过 CLI 标志进行配置。YAML 配置文件支持计划在第二阶段推出。 提供了示例配置文件 [`configs/dashcap.example.yaml`](configs/dashcap.example.yaml) 供参考。 ## 项目结构 ``` dashcap/ ├── cmd/dashcap/ # CLI entry point (Cobra) ├── internal/ │ ├── api/ # REST API server (net/http) │ ├── buffer/ # Ring manager + pcapng segment writer │ ├── capture/ # Packet capture abstraction (gopacket/pcap) │ ├── config/ # Runtime configuration + validation │ ├── persist/ # Save triggered captures to disk │ ├── storage/ # Platform-specific disk ops (prealloc, flock, free space) │ └── trigger/ # Trigger dispatcher (multiplexes API/signal/CLI sources) ├── configs/ # Example configuration ├── DESIGN.md # Full architecture and design document ├── Makefile # Build, test, lint, cross-compile targets └── go.mod ``` ## 开发 ``` make test # Run tests with race detector make lint # Run golangci-lint make fmt # Format code (gofmt + goimports) make cover # Generate coverage report (coverage.html) ```

标签：EVTX分析, EVTX分析, Go语言, HTTP 参数枚举, pcapng, REST API, 全包捕获, 抓包工具, 持续监控, 故障排查, 日志审计, 服务管理, 流量录制, 环形缓冲区, 程序破解, 网络安全, 网络流量分析, 行车记录仪, 防御绕过, 隐私保护