Yash-Patil-1/PacketWatch
GitHub: Yash-Patil-1/PacketWatch
PacketWatch 是一款 Python 编写的 PCAP 网络流量分析与异常检测 CLI 工具，通过五个检测模块识别端口扫描、DNS 隧道、C2 beacon、暴力破解和数据泄露等可疑网络活动。
Stars: 1 | Forks: 0
📡 PacketWatch
Network Traffic Analyzer & Anomaly Detector
SOC-grade CLI tool for PCAP analysis — detect port scans, DNS tunnels, C2 beacons, brute force attacks, and data exfiltration.
## 📋 概述
PacketWatch 读取 PCAP 文件，重构网络流，并应用五个检测模块来识别可疑的网络活动。专为需要实用网络流量分析能力的 SOC 分析师、威胁猎手和安全专业的学生而构建。
**为什么做这个项目？** 网络流量分析是一项核心的 SOC 技能。PacketWatch 展示了解析原始数据包（使用 Scapy、pyshark 或内置的原始解析器）、重构双向流以及在网络层应用检测逻辑的实用能力。
## ✨ 功能
| 功能 | 描述 |
|---------|-------------|
| **多后端 PCAP 读取器** | Scapy（主要）、pyshark/TShark（备选）、原始二进制解析器（零依赖） |
| **5 个检测模块** | 端口扫描、DNS 隧道、C2 beacon、暴力破解、数据泄露 |
| **流量重构** | 具备时间、字节计数和协议分析的双向流构建器 |
| **HTML 报告** | 采用 matplotlib 图表（饼图、柱状图、时间线）的专业暗色主题报告 |
| **JSON 导出** | 用于 SIEM 摄取和程序化处理的结构化输出 |
| **终端输出** | 带有严重性标记和 ASCII 图表的彩色控制台报告 |
| **MITRE ATT&CK** | 每个异常都映射到 MITRE 技术 ID |
| **检测器注册表** | 自动发现检测模块 — 易于扩展 |
| **示例 PCAP** | 内置包含 6 种攻击场景的 PCAP 供测试使用 |
## 🚀 快速开始
### 安装
```
# 克隆 repository
git clone https://github.com/Yash-Patil-1/PacketWatch.git
cd PacketWatch
# 创建 virtual environment（推荐）
python3 -m venv .venv
source .venv/bin/activate
# 安装 PacketWatch
pip install -e .
# 验证安装
packetwatch --version
```
### 基本用法
```
# 使用所有 detectors 分析 PCAP 文件
packetwatch analyze sample_traffic.pcap
# 使用 verbose 输出和 per-detector breakdown 进行分析
packetwatch analyze sample_traffic.pcap --verbose
# 仅运行特定的 detectors
packetwatch analyze sample_traffic.pcap --detectors port_scan,dns_tunnel
# 生成 HTML/JSON/terminal 报告
packetwatch analyze sample_traffic.pcap --output ./reports
# 列出所有可用的 detection modules
packetwatch list-detectors
# 显示 PCAP 文件信息（packets, protocols, duration）
packetwatch info sample_traffic.pcap
# 显示详细的版本和 backend 信息
packetwatch version
```
### 示例输出
```
$ packetwatch analyze sample_traffic.pcap --verbose
[+] Loaded 184 packets from sample_traffic.pcap
[+] Built 126 flows
[+] Running 5 detectors...
────────────────────────────────────────────────────────────
🚨 HIGH | beacon | Regular packet intervals to 203.0.113.200:443 — mean: 1.0s, jitter: 0.0%
🚨 HIGH | dns_tunnel | 192.168.1.100 made 43 DNS queries (129/min) — possible tunneling
⚠️ MEDIUM | exfil | 10.0.0.10 sent 2.0 MB to 203.0.113.200:443 (50 packets)
⚠️ MEDIUM | exfil | 10.0.0.10 sent 2.0 MB but received only 0 B (ratio: inf:1)
⚠️ MEDIUM | port_scan | 10.0.0.99 performed a FIN scan on 192.168.1.1 (7 ports)
⚠️ MEDIUM | brute_force | 192.168.1.200 attempted 20 SSH connections to 1 targets (126/min)
🟢 LOW | port_scan | 10.0.0.5 has 16 short connections to 1 targets
🟢 LOW | port_scan | 192.168.1.200 has 20 short connections to 1 targets
────────────────────────────────────────────────────────────
Results: 9 anomalies detected
PCAP Stats:
Duration: 587.00s
Protocols: TCP, UDP
Reader: scapy
Anomaly Breakdown by Detector:
port_scan: 3
exfil: 2
brute_force: 2
beacon: 1
dns_tunnel: 1
```
## 🔍 检测模块
| 检测器 | 异常 | 方法 | MITRE |
|----------|---------|--------|-------|
| **端口扫描** | SYN、FIN、Xmas、NULL 扫描 | TCP 标志分析，唯一目标端口，连接速率 | T1046 |
| **DNS 隧道** | 基于 DNS 的数据泄露 | 域名的香农熵，TXT 记录大小，查询量 | T1572 |
| **C2 Beacon** | 命令与控制通信 | 时间间隔规律性，变异系数（抖动）分析 | T1571 |
| **暴力破解** | SSH/RDP 密码猜测 | 针对认证端口（22/3389/21/23）的 SYN 爆发，连接速率 | T1110 |
| **数据泄露** | 大量出站传输 | 每流字节计数，源到目的地的比率，持续时间 Z-score 异常值 | T1048 |
## 📁 项目结构
```
PacketWatch/
├── pyproject.toml # Package configuration
├── requirements.txt # Python dependencies
├── README.md # This file
├── PRD.md # Product requirements document
├── sample_traffic.pcap # Bundled sample PCAP (6 attack scenarios)
│
├── src/
│ └── packetwatch/
│ ├── __init__.py # Package init (version: 1.0.0)
│ ├── models.py # Packet, Flow, Anomaly, AnalysisResult dataclasses
│ ├── reader.py # PCAP reader (Scapy/pyshark/raw backends)
│ ├── analyzer.py # Analysis orchestrator + FlowBuilder
│ ├── reporter.py # Reporter (HTML, JSON, Terminal)
│ ├── main.py # CLI entry point (5 subcommands)
│ │
│ ├── detectors/
│ │ ├── __init__.py # BaseDetector ABC + registry + auto-discovery
│ │ ├── port_scan.py # SYN, FIN, Xmas, NULL scan detection
│ │ ├── dns_tunnel.py # High-entropy domains, TXT records, query volume
│ │ ├── beacon.py # C2 beacon timing jitter analysis
│ │ ├── brute_force.py # SSH/RDP brute force detection
│ │ └── exfil.py # Data exfiltration volume/ratio/duration analysis
│ │
│ └── templates/
│ └── report.html # Jinja2 HTML report template
│
├── scripts/
│ └── generate_sample_pcap.py # PCAP generator with attack scenarios
│
├── tests/
│ ├── test_reader.py # 20 tests — PCAP parsing
│ ├── test_detectors.py # 31 tests — detection logic
│ ├── test_reporter.py # 34 tests — report generation
│ └── test_main.py # 23 tests — CLI integration
│
├── docs/ # Documentation
│ ├── getting_started.md
│ ├── usage.md
│ ├── architecture.md
│ ├── development.md
│ ├── reporting.md
│ └── rules.md
│
└── reports/ # Generated report output
```
## 🧪 运行测试
```
# 安装 dev dependencies
pip install -e ".[dev]"
# 运行所有测试
python3 -m pytest tests/ -v
# 运行 coverage
python3 -m pytest tests/ --cov=src --cov-report=term
# 运行特定的测试文件
python3 -m pytest tests/test_detectors.py -v
```
**当前测试结果：104/104 通过**
## 🛠️ CLI 参考
```
usage: packetwatch [-h] [--version] {info,analyze,list-detectors,version,report} ...
Network Traffic Analyzer & Anomaly Detector
Commands:
info Show PCAP file info (packets, protocols, duration)
analyze Analyze PCAP for anomalies
list-detectors List available detection modules
version Show detailed version and system information
report Generate reports from cached JSON analysis
```
### analyze
```
packetwatch analyze
[--output DIR] [--format {html,json,terminal,all}]
[--detectors LIST] [--verbose]
```
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `pcap` | PCAP 文件的路径 | 必填 |
| `--output, -o` | 报告的输出目录 | 禁用 |
| `--format, -f` | 报告格式：html、json、terminal、all | all |
| `--detectors` | 以逗号分隔的检测器名称 | 所有检测器 |
| `--verbose, -v` | 每个检测器的详细分类 | False |
### report
```
packetwatch report [--output DIR] [--format {html,json,terminal,all}]
```
从先前缓存的 JSON 分析（例如，来自 `packetwatch analyze --format json`）重新生成报告。
## 📊 示例报告预览
HTML 报告包含：
- **受 GitHub 启发的暗色主题**（#0d1117 背景）
- **摘要卡片** — 总数据包、流、异常、持续时间
- **严重性迷你卡片** — 严重/高/中/低计数
- **严重性饼图** — 异常分布
- **检测器分类柱状图** — 按检测模块划分的异常
- **异常时间线散点图** — 按时间顺序排列的攻击序列
- **热门源/目标 IP** — 根据异常涉及情况进行排名
- **异常表** — 严重性标记、检测器标签、评分条、MITRE ID
- **响应式设计**，适用于桌面和移动端
## 📝 许可证
本项目基于 MIT License 授权。
## 👨💻 作者
**Yash Patil** — 网络安全分析师 | SOC 运营与事件响应
- 📧 yashpatil7714@gmail.com
- 🔗 [LinkedIn](https://www.linkedin.com/in/yash-patil-997357330)
- 🐙 [GitHub](https://github.com/Yash-Patil-1)
## 🔗 相关项目
- [**LogSentinel**](https://github.com/Yash-Patil-1/LogSentinel) — 日志分析与威胁检测引擎
- [**Incident Responder**](https://github.com/Yash-Patil-1/IncidentResponder) — 自动化事件响应框架
使用 Python、Scapy、matplotlib、Jinja2 构建，以及对网络安全的热情打造。
标签：IP 地址批量处理, PB级数据处理, PCAP解析, Python, 安全运维, 插件系统, 无后门, 红队行动, 网络安全, 逆向工具, 隐私保护