TracePcap

智能 PCAP 文件分析，提供 AI 驱动的洞察与交互式网络可视化

功能特性 • 快速开始 • 使用方法 • 文档

一个完全自托管运行的综合网络数据包分析工具。上传 PCAP 文件以可视化网络流量模式，分析数据包流，生成智能过滤器，并通过 AI 驱动的分析获取洞察。非常适合网络故障排查、安全分析、协议调试或教学用途。 ## 功能特性 | 功能 | 描述 | |---------|-------------| | **PCAP 上传与管理** | 使用 MinIO 对象存储上传和管理 PCAP/CAP 文件（最大 512MB） | | **网络可视化** | 交互式 3D 网络拓扑图，展示通信模式和关系 | | **时间线分析** | 按时间顺序查看网络事件及详细数据包信息 | | **AI 过滤器生成器** | 基于自然语言查询，由 LLM 驱动生成 Wireshark/tcpdump 过滤器 | | **数据包分析** | 使用 pcap4j 进行深度包检测和协议级分析 | | **会话追踪** | 识别并分析主机间的网络会话，支持服务端过滤、排序和 CSV 导出 | | **自定义签名规则** | 基于 YAML 的检测规则，匹配 IP、CIDR、端口、JA3、主机名、应用和协议字段 | | **故事模式** | 网络活动和事件的叙事性重构 | | **导出选项** | 导出分析结果和过滤器，以便在 Wireshark 或其他工具中使用 | | **实时处理** | 异步分析并提供进度追踪 | | **多协议支持** | 支持 TCP、UDP、ICMP 及各种应用层协议 | ## 快速开始 ### 前置条件 | 软件 | 版本 | 用途 | |----------|---------|---------| | Docker | Latest | Container runtime | | Docker Compose | Latest | Multi-container orchestration | | LLM Server | Any OpenAI-compatible API | AI filter generation (e.g., LM Studio, Ollama, OpenAI) | **最低硬件配置：** - RAM: 4GB (建议 8GB+) - Storage: 10GB (用于数据库、PCAP 文件和对象存储) ### 安装说明 **1. 克隆并设置：** ``` git clone https://github.com/NotYuSheng/TracePcap.git cd TracePcap cp .env.example .env ``` **2. 配置 `.env`：** ``` # 上传 Configuration MAX_UPLOAD_SIZE_BYTES=536870912 # 512MB default # Nginx 端口 Configuration NGINX_PORT=80 # Change if port 80 is already in use # LLM Configuration (本地 LLM 服务器) LLM_API_BASE_URL=http://localhost:1234/v1 LLM_API_KEY= LLM_MODEL=Qwen2.5-14B-Coder-Instruct LLM_TEMPERATURE=0.7 LLM_MAX_TOKENS=2000 ``` **3. 启动应用：** ``` docker compose up -d ``` **4. 访问 TracePcap：** 在浏览器中打开 **http://localhost:80**。 ## 使用方法 ### 基本工作流 1. **上传** - 导航到上传页面，拖放 PCAP 文件或点击浏览 2. **分析** - 文件会被自动处理并分析网络模式 3. **可视化** - 查看展示主机和通信流的交互式 3D 网络拓扑 4. **时间线** - 按时间顺序探索数据包级别的详情 5. **会话** - 查看特定端点之间的网络会话 6. **生成过滤器** - 使用 AI 从自然语言创建 Wireshark 过滤器（例如，“show all HTTP traffic from 192.168.1.1”） 7. **导出** - 在 Wireshark 中应用生成的过滤器或保存分析结果 ### 支持的文件格式 PCAP, CAP (默认最大 512MB，可通过 `MAX_UPLOAD_SIZE_BYTES` 配置) ## 技术栈 | 组件 | 技术 | |-----------|------------| | **Backend** | Spring Boot 3.2.1, Java 21, Maven, Lombok, MapStruct | | **Architecture** | 分层架构 (Controller → Service → Repository → Database) | | **Frontend** | React 19, Vite, TypeScript, Lucide Icons, SGDS React | | **Visualization** | D3.js, reagraph (3D network graphs), Recharts | | **Reverse Proxy** | Nginx | | **Packet Parsing** | pcap4j 1.8.2 | | **Database** | PostgreSQL 15 with Flyway migrations | | **Object Storage** | MinIO (S3-compatible) | | **Containerization** | Docker, Docker Compose | | **API Documentation** | SpringDoc OpenAPI (Swagger UI) | ## 文档 [`docs/`](docs/) 目录中提供了完整的文档： | 文档 | 描述 | |----------|-------------| | **[API Endpoints](docs/API_ENDPOINTS.md)** | 完整的 REST API 文档，包含请求/响应示例 | | **[Backend Structure](docs/BACKEND_STRUCTURE.md)** | 后端架构、包组织和设计模式 | ## 常见任务 ### 查看日志 ``` # 所有服务 docker compose logs -f # 特定服务 docker compose logs -f tracepcap-backend docker compose logs -f postgres docker compose logs -f minio ``` ### 重启服务 ``` # 重启所有 docker compose restart # 仅重启 backend docker compose restart tracepcap-backend ``` ### 备份数据 ``` # 备份数据库 docker exec tracepcap-postgres pg_dump -U tracepcap_user tracepcap > backup.sql # 备份 MinIO data (PCAP 文件) docker exec tracepcap-minio mc mirror minio/tracepcap-files ./backup-pcaps/ # 备份所有 volumes sudo tar -czf tracepcap_backup.tar.gz /var/lib/docker/volumes/tracepcap_* ``` ### 访问数据库 ``` docker exec -it tracepcap-postgres psql -U tracepcap_user tracepcap ``` ### 访问 MinIO 控制台 导航至 **http://localhost:9001** 并使用以下凭据登录： - Username: `minioadmin` - Password: `minioadmin` ### 访问 Swagger API 文档 导航至 **http://localhost:80/swagger-ui.html** 以交互式探索 API。 ## 部署 TracePcap 专为自托管部署设计： - **开发环境**：使用带有暴露端口的内置配置 - **生产环境**： - 在 `docker-compose.yml` 中更改默认的 MinIO 凭据 - 更新 PostgreSQL 密码 - 配置反向代理以支持 SSL/TLS - 根据需要调整 `MAX_UPLOAD_SIZE_BYTES` - 为您的基础设施设置适当的 LLM 配置 ## 安全 - **本地处理**：PCAP 分析完全在您的服务器上运行 - **数据隐私**：网络捕获数据不会离开您的基础设施（LLM 过滤器生成除外） - **对象存储**：MinIO 提供兼容 S3 的安全文件存储 - **数据库**：PostgreSQL 默认不暴露在 Docker 网络之外 - **无身份验证**：多用户部署时需添加身份验证层 - **LLM 隐私**：使用本地 LLM 服务器（LM Studio, Ollama）以保持过滤器查询的私密性 ## 性能 - **异步处理**：文件分析异步运行以防止阻塞 - **对象存储**：MinIO 为大型 PCAP 文件提供可扩展的存储 - **数据库索引**：通过适当的索引优化查询以实现快速查找 - **连接池**：高效的数据库连接管理 - **文件大小限制**：可配置的上传限制以防止资源耗尽 ## 架构亮点 - **分层架构**：清晰的关注点分离 (API → Service → Repository → Database) - **DTO Pattern**：使用 MapStruct 在层之间进行高效的对象映射 - **Database Migrations**：使用 Flyway 进行版本控制的 Schema 管理 - **Health Checks**：为所有服务提供内置健康检查 - **API-First Design**：OpenAPI 规范与 Swagger UI ## 自定义签名规则 TracePcap 支持用户定义的检测规则，这些规则会在 nDPI 分析后与每个会话进行匹配。匹配的规则名称会以彩色徽章的形式显示在会话 (Conversations) 选项卡和概览 (Overview) 中，并附带 nDPI 的内置检测。 ### 工作原理 规则存储在 `config/signatures.yml` 中，并作为 Docker 命名卷 (`config_data`) 挂载。该文件在每次分析运行时都会重新加载——编辑后无需重启。 您可以通过两种方式编辑规则： - **在浏览器中** — 点击导航栏中的 **Custom Detection Rules** 打开 YAML 编辑器模态框 - **在主机上** — 编辑文件并将其复制到正在运行的容器中： docker cp config/signatures.yml tracepcap-backend:/app/config/signatures.yml ### 规则格式 ``` signatures: - name: rule_name_shown_in_ui # shown as a badge (use underscores, no spaces) description: Human-readable description severity: low # low | medium | high | critical match: ip: "203.0.113.42" # exact match against srcIp OR dstIp ``` 当**所有**指定的匹配字段都满足时，规则触发。所有字段均为可选——可根据需要混合搭配。 ### 匹配字段 | 字段 | 类型 | 描述 | 示例 | |-------|------|-------------|---------| | `ip` | string | 精确匹配 srcIp 或 dstIp | `"203.0.113.42"` | | `cidr` | string | CIDR 范围匹配 srcIp 或 dstIp | `"10.0.0.0/8"` | | `srcPort` | number | 精确匹配源端口 | `67` | | `dstPort` | number | 精确匹配目标端口 | `4444` | | `ja3` | string | 精确匹配 JA3S 指纹哈希 (nDPI 5.x) | `"82f0d8a75fa483d1cfe4b7085b784d7e"` | | `hostname` | string | 精确或通配符匹配 SNI 主机名 — `*.evil.com` 匹配任何深度的子域 | `"*.evil.com"` | | `app` | string | 不区分大小写的 nDPI 应用名称 | `"Telegram"`, `"TOR"`, `"SIP"`, `"RTP"` | | `protocol` | string | 不区分大小写的传输协议 | `"TCP"`, `"UDP"`, `"ICMP"` | ### 严重性颜色 | 严重性 | 颜色 | |----------|-------| | `critical` | Red | | `high` | Orange | | `medium` | Yellow | | `low` | Purple | ### 示例 ``` signatures: # Flag a known C2 IP - name: known_c2_ip description: Known command-and-control server severity: high match: ip: "203.0.113.42" # Flag all traffic to a suspicious subnet - name: flagged_subnet severity: medium match: cidr: "198.51.100.0/24" # Detect DNS over TCP (possible zone transfer or tunnelling) - name: dns_over_tcp severity: medium match: app: "DNS" protocol: TCP # Wildcard hostname match - name: blocked_domain severity: high match: hostname: "*.malware.example.com" # JA3S fingerprint from a threat-intel feed - name: suspicious_tls_fingerprint severity: critical match: ja3: "a0e9f5d64349fb13191bc781f81f42e1" ``` [`backend/config/signatures.yml`](backend/config/signatures.yml) 中提供了一整套涵盖每种匹配字段类型的 12 个演示规则。脚本 [`sample-files/gen_demo.py`](sample-files/gen_demo.py) 可生成一个同时触发所有 12 个规则的 PCAP 文件。 ## 示例文件 [`sample-files/`](sample-files/) 目录包含示例 PCAP 文件： - `atm_capture1.cap` - ATM 网络流量样本 - `free5gc.pcap` - 5G 核心网流量样本 - `demo_all_rules.pcap` - 触发所有 12 个自定义签名演示规则（由 `gen_demo.py` 生成） 这些文件可用于测试应用程序的分析能力。 ## 许可证 本项目采用 MIT 许可证授权。详情请参见 [LICENSE](LICENSE)。

标签：3D可视化, AI安全工具, DLL注入, Docker, Java 21, MinIO, PCAP分析, PostgreSQL, React, Spring Boot, Syscalls, 协议调试, 安全防御评估, 开源安全工具, 智能过滤器, 流量可视化, 流量审计, 测试用例, 网络安全, 网络拓扑图, 网络故障排查, 网络流量分析, 自动化攻击, 自托管, 请求拦截, 逆向工程平台, 防御绕过, 隐私保护