# PySentinel

**Repository Path**: southwind957/py-sentinel

## Basic Information

- **Project Name**: PySentinel
- **Description**: 一款基于 PyQt6 + uv 管理的桌面端攻防一体工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2025-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ⚔️ PySentinel

一款基于 PyQt6 + uv 管理的桌面端安全分析与网络辅助工具。

## 🚀 项目概述

PySentinel 是一款可视化的安全分析与网络辅助工具，提供以下核心功能：

- **握手检测** - 实时监听并提示外部发起的 TCP 握手请求
- **网段扫描** - 扫描指定 IP 段内的存活主机和开放端口
- **快速链接** - 快速访问常用安全文档与工具链接
- **文件监控** - 监控文件系统变化，检测潜在的 Webshell
- **系统信息** - 查看系统资源使用情况和网络接口信息

本项目采用 uv 管理与运行，无需复杂依赖配置，快速安装、运行、调试。

## 🧩 功能清单

### 1. 握手检测模块
- ✅ 监听特定端口上的 TCP SYN 握手请求
- ✅ 实时显示来源 IP、目标端口、时间戳
- ✅ 支持多端口同时监控
- ✅ 启动/停止/暂停/恢复控制
- ✅ 数据包统计和监控状态显示
- ⚠️ 需要管理员/root 权限

### 2. 网段扫描模块
- ✅ 支持多种 IP 输入格式（CIDR、范围、单IP）
- ✅ 并发扫描提升速度（可配置并发数）
- ✅ Ping 存活检测
- ✅ 端口扫描功能（可选）
- ✅ 实时进度显示和结果更新
- ✅ 结果导出（JSON / CSV）
- ✅ 扫描取消功能

### 3. 快速链接模块
- ✅ 预设常用安全资源链接
- ✅ 分类管理和树形显示
- ✅ 添加/编辑/删除自定义链接
- ✅ 搜索和过滤功能
- ✅ 在系统默认浏览器中打开
- ✅ JSON 持久化存储

### 4. 文件监控模块
- ✅ 实时监控文件系统变化
- ✅ Webshell 关键字检测
- ✅ 可配置监控目录和文件类型
- ✅ 忽略特定文件夹（如 node_modules）
- ✅ 文件大小限制配置

### 5. 系统信息模块
- ✅ CPU、内存、磁盘使用率监控
- ✅ 网络接口信息查看
- ✅ 实时资源使用情况更新

## 🧱 项目结构

```
PySentinel/
├── pyproject.toml              # uv 管理配置
├── README.md                   # 项目说明
├── QUICKSTART.md               # 快速开始指南
├── PROJECT_SUMMARY.md          # 项目实现总结
├── app.py                      # 程序入口
├── config.json                 # 运行时配置（自动生成）
├── config.example.json         # 配置示例文件
├── links.json                  # 快速链接配置
├── install.bat / install.sh    # 安装脚本
├── run.bat / run.sh           # 启动脚本
│
├── core/                       # 核心业务逻辑层
│   ├── __init__.py
│   ├── handshake_detector.py  # 握手检测
│   ├── network_scanner.py     # 网络扫描
│   ├── quick_links.py         # 快速链接管理
│   ├── file_monitor.py        # 文件监控
│   └── system_info.py         # 系统信息
│
├── ui/                         # 用户界面层
│   ├── __init__.py
│   ├── main_window.py         # 主窗口
│   ├── styles.py              # 样式定义
│   ├── components/            # UI 通用组件
│   ├── themes/                # 主题配置
│   └── widgets/               # 功能组件
│       ├── __init__.py
│       ├── handshake_widget.py    # 握手检测UI
│       ├── scanner_widget.py      # 网络扫描UI
│       ├── links_widget.py        # 快速链接UI
│       ├── file_monitor_widget.py # 文件监控UI
│       ├── system_info_widget.py  # 系统信息UI
│       └── settings_widget.py     # 设置UI
│
├── utils/                      # 工具模块
│   ├── __init__.py
│   ├── ip_utils.py            # IP 地址工具
│   ├── logger.py              # 日志系统
│   ├── config.py              # 配置管理
│   ├── config_models.py       # 配置数据模型
│   └── validation.py          # 数据验证
│
├── logs/                       # 日志文件目录
└── backups/                    # 配置备份目录
```

## ⚙️ 快速开始

### 1. 安装 uv

```bash
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. 安装系统依赖

**Windows**: 安装 Npcap（握手检测功能必需）
- 下载: https://npcap.com/
- 安装时勾选 "WinPcap API-compatible Mode"

**Linux**: 安装 libpcap
```bash
# Ubuntu/Debian
sudo apt-get install libpcap-dev

# CentOS/RHEL
sudo yum install libpcap-devel
```

**macOS**: 通常已预装，如有问题：
```bash
brew install libpcap
```

### 3. 安装项目依赖

```bash
# Windows
install.bat

# Linux/macOS
chmod +x install.sh
./install.sh
```

### 4. 运行程序

```bash
# Windows（以管理员身份运行）
run.bat

# Linux/macOS（需要 root 权限）
sudo ./run.sh
```

详细使用说明请参考 [QUICKSTART.md](QUICKSTART.md)

### 5. 开发与调试

```bash
# 安装开发依赖
uv add --dev pytest black mypy

# 运行测试
uv run pytest

# 代码格式化
uv run black .

# 类型检查
uv run mypy .
```

## 📚 相关文档

- [快速开始指南](QUICKSTART.md) - 详细的安装和使用说明
- [项目实现总结](PROJECT_SUMMARY.md) - 完整的功能清单和技术细节
- [配置示例](config.example.json) - 配置文件参考

## 📋 依赖说明

- **PyQt6** >= 6.5.0 - 现代化桌面 UI 框架
- **scapy** >= 2.5.0 - 网络数据包捕获与分析
- **requests** >= 2.31.0 - HTTP 请求库
- **rich** >= 13.0.0 - 终端美化输出
- **psutil** >= 5.9.0 - 系统和进程监控

## ⚠️ 重要提示

### 权限要求

**握手检测功能**需要管理员/root 权限才能捕获网络数据包：

**Windows**: 
- 右键点击 `run.bat`，选择"以管理员身份运行"
- 或在管理员权限的终端中运行

**Linux/macOS**: 
```bash
sudo ./run.sh
```

**其他功能**（网段扫描、快速链接、文件监控、系统信息）不需要特殊权限。

### 安全提示

- ⚠️ 仅在授权的网络环境中使用
- ⚠️ 遵守当地法律法规
- ⚠️ 不要用于非法目的
- ⚠️ 扫描前获得网络管理员许可

## 🎯 架构设计

### 设计原则
- **分层架构**: UI、Core、Utils 三层分离
- **低耦合**: UI 与逻辑完全分离，逻辑层不依赖 UI
- **高内聚**: 每个模块职责明确，功能独立
- **可扩展**: 易于添加新功能模块
- **可测试**: 每个模块独立可测试

### 技术特点
- **类型提示**: 使用 Python 类型注解提高代码质量
- **文档字符串**: 完整的函数和类文档
- **错误处理**: 全面的异常捕获和处理
- **日志记录**: 详细的运行日志和调试信息
- **配置管理**: 灵活的配置系统，支持版本迁移

## 🪄 未来扩展方向

- 🔒 网络防御（实时阻断恶意握手）
- 📊 扫描结果可视化（图表统计）
- 🤖 自动化安全策略联动（Webhook / AI 判断）
- 🔍 流量分析与异常检测
- 🛡️ 漏洞扫描集成
- 📱 远程监控和通知
- 🔌 插件系统支持

## 📝 配置文件

### config.json
应用程序运行时配置文件，首次运行时自动生成。包含以下配置项：

```json
{
  "_meta": {
    "version": "1.2.0",
    "created": "2024-11-14T10:00:00.000000",
    "last_modified": "2025-11-14T11:53:12.860905"
  },
  "monitoring": {
    "default_interface": "auto",
    "monitored_ports": [22, 80, 443, 3389, 8080],
    "notification_enabled": true,
    "log_level": "INFO",
    "auto_start": false
  },
  "scanning": {
    "default_ip_range": "192.168.1.0/24",
    "default_ports": [22, 80, 443, 8080],
    "max_concurrent_scans": 50,
    "default_timeout": 1.0,
    "ping_timeout": 1.0,
    "retry_count": 1
  },
  "ui": {
    "theme": "dark",
    "window_geometry": null,
    "auto_save_results": true,
    "show_notifications": true,
    "minimize_to_tray": true
  },
  "file_monitor": {
    "ignored_folders": [".git", ".svn", "node_modules", "__pycache__", "vendor", "cache"],
    "webshell_keywords": ["shell", "backdoor", "webshell", "hack", "exploit", "cmd", "eval", "system", "exec", "base64_decode", "assert", "passthru"],
    "scan_extensions": [".php", ".jsp", ".asp", ".aspx", ".py", ".sh"],
    "max_file_size_mb": 10
  },
  "export": {
    "default_format": "json",
    "default_directory": "exports",
    "include_timestamp": true
  },
  "security": {
    "require_admin": true,
    "log_all_packets": false,
    "max_log_size_mb": 100
  }
}
```

**配置说明**：
- `_meta`: 配置文件元数据（版本、创建时间、修改时间）
- `monitoring`: 握手检测相关配置
- `scanning`: 网络扫描相关配置
- `ui`: 用户界面相关配置
- `file_monitor`: 文件监控相关配置
- `export`: 导出功能相关配置
- `security`: 安全相关配置

### config.example.json
配置示例文件，用于参考和版本控制。不会被程序直接使用。

### links.json
快速链接配置文件，包含预设的安全资源链接。可通过 UI 界面管理。

### 配置文件位置
- 所有配置文件位于项目根目录
- 配置备份保存在 `backups/` 目录
- 日志文件保存在 `logs/` 目录

## 🐛 故障排除

### 问题：无法启动握手监控
**解决方案**：
- ✅ 确保以管理员/root 权限运行
- ✅ 检查 Scapy 是否正确安装：`uv run python -c "import scapy; print(scapy.__version__)"`
- ✅ Windows: 确认 Npcap 已安装
- ✅ Linux/Mac: 确认 libpcap 已安装
- ✅ 检查防火墙设置
- ✅ 确认网络接口可用

### 问题：扫描速度慢
**解决方案**：
- ✅ 调整 `config.json` 中的 `max_concurrent_scans` 参数（默认50，可增至100-200）
- ✅ 减小扫描范围
- ✅ 检查网络连接质量
- ✅ 调整 `default_timeout` 参数（默认1.0秒）

### 问题：UI 显示异常
**解决方案**：
- ✅ 确保 PyQt6 版本 >= 6.5.0：`uv run python -c "from PyQt6.QtCore import PYQT_VERSION_STR; print(PYQT_VERSION_STR)"`
- ✅ 更新 PyQt6：`uv add --upgrade pyqt6`
- ✅ 尝试更新显卡驱动
- ✅ 检查系统 DPI 设置
- ✅ 切换主题（设置 -> UI -> 主题）

### 问题：依赖安装失败
**解决方案**：
- ✅ 确保 uv 正确安装：`uv --version`
- ✅ 手动同步依赖：`uv sync`
- ✅ 清理缓存：`uv cache clean`
- ✅ 检查网络连接
- ✅ 使用国内镜像（如需要）

### 问题：配置文件损坏
**解决方案**：
- ✅ 检查 `backups/` 目录中的备份文件
- ✅ 删除 `config.json`，程序会自动重新生成
- ✅ 参考 `config.example.json` 手动修复

### 查看日志
所有运行日志保存在 `logs/` 目录，文件名格式：`pysentinel_YYYYMMDD.log`

如需帮助，请提交 Issue 并附上日志文件。

## 📄 许可证

MIT License

## 👥 贡献

欢迎提交 Issue 和 Pull Request！

## ✅ 项目状态

**当前版本**: v0.1.0 (MVP 完成)

### 完成度
- ✅ 核心功能: 100%
- ✅ UI 界面: 100%
- ✅ 配置系统: 100%
- ✅ 日志系统: 100%
- ✅ 文档: 100%

### 特性
- ✅ 使用 uv 管理项目依赖，极简快速
- ✅ 采用 PyQt6 打造现代化 UI
- ✅ 代码结构清晰，逻辑与界面分层
- ✅ 五大核心功能完整实现
- ✅ 完善的配置管理和版本迁移
- ✅ 详细的日志记录和错误处理
- ✅ 跨平台支持（Windows/Linux/macOS）

**项目可投入使用** 🎉