PeleaRaul/PortScanner
GitHub: PeleaRaul/PortScanner
一款支持异步 TCP 与原始数据包扫描的多功能端口扫描器，提供 GUI/CLI 双模式、服务识别及多种格式的报告导出功能。
Stars: 0 | Forks: 0
# ⚡ CyberScan Suite v3.1
**带有 GUI 和 CLI 的专业网络端口扫描器**
CyberScan Suite 是一款多线程端口扫描器，具备用于高性能全端口扫描的异步 TCP 连接、原始数据包扫描类型（SYN/ACK/FIN/NULL/XMAS）、主机发现、服务识别、TLS 证书抓取以及带有样式的 HTML 报告生成功能。它采用与 [ProxyScraper](https://github.com/) 美学相匹配的深绿色赛博控制台主题。
## 目录
- [功能](#features)
- [安装说明](#installation)
- [快速开始](#quick-start)
- [CLI 参考](#cli-reference)
- [GUI 指南](#gui-guide)
- [扫描类型](#scan-types)
- [架构](#architecture)
- [配置](#configuration)
- [数据库](#database)
- [测试](#testing)
- [贡献](#contributing)
- [免责声明](#disclaimer)
- [许可证](#license)
## 功能
### 扫描
| 功能 | 描述 |
|---|---|
| **异步 TCP Connect** | 基于 `asyncio` 的扫描器，具有 512 个并发连接 — 可在几秒内扫描所有 65535 个端口 |
| **原始数据包扫描** | 通过 Scapy 进行 SYN, ACK, FIN, NULL, XMAS 隐秘扫描（需要 root/管理员权限） |
| **UDP 扫描** | 特定协议探测：DNS (53), SNMP (161), NTP (123)，以及通用回退 |
| **主机发现** | ICMP ping (Scapy)，TCP ping 回退 (80/443/22/445)，用于本地子网的 ARP 扫描 |
| **速率限制** | 可调节的 0-500ms 探测延迟，以避免网络拥塞 |
### 服务智能
| 功能 | 描述 |
|---|---|
| **端口数据库** | 150+ 个知名端口到服务的映射（SSH, HTTP, MySQL, Redis, MongoDB, Kafka 等） |
| **Banner 抓取** | 协议感知探测：Web 端口使用 HTTP `HEAD /`，SSH/FTP/SMTP 使用被动读取 |
| **版本解析** | 基于 Regex 从 banner 中提取（SSH 版本、HTTP Server 头、Redis 版本等） |
| **TLS 证书** | 为 HTTPS 端口（443, 8443, 9443）抓取 CN, Organization 和 Issuer |
| **OS 提示** | 基于 TTL 的 OS 检测：~64 = Linux，~128 = Windows，~255 = 网络设备 |
### 报告与持久化
| 功能 | 描述 |
|---|---|
| **SQLite 数据库** | 完整的扫描历史、按主机跟踪、批量结果持久化 |
| **CSV 导出** | 包含所有字段，可直接用于电子表格 |
| **JSON 导出** | 机器可读，适用于 API |
| **纯文本** | Nmap 风格的开放端口摘要 |
| **HTML 报告** | 带有摘要卡片、颜色编码结果表和元数据的样式化报告 |
| **扫描差异对比** | 将当前扫描与前一次扫描进行对比 — 找出新增/关闭/变更的端口 |
### 界面
| 功能 | 描述 |
|---|---|
| **GUI 模式** | 采用 CustomTkinter 深绿色主题，带有可排序的结果表、实时搜索和 KPI 卡片 |
| **CLI 模式** | 完全的无人值守操作，包含 `scan`, `history`, `export`, `stats` 子命令 |
| **统计信息** | 实时的按状态计数、热门服务、按开放端口数排名的主机 |
| **进度** | 进度条、预计剩余时间 (ETA)、吞吐量 (jobs/sec)、已用时间 |
| **设置** | 上次使用的配置在多次运行之间持久化保存 |
## 安装说明
### 从源码安装（推荐）
```
git clone https://github.com/yourusername/cyberscan-suite.git
cd cyberscan-suite
# 创建虚拟环境
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate
# 安装核心依赖
pip install -r requirements.txt
# 可选：raw packet 扫描 (SYN, ACK, FIN, NULL, XMAS)
pip install scapy
```
### 作为包安装
```
pip install .
```
### 依赖要求
| 依赖 | 是否必需 | 用途 |
|---|---|---|
| `customtkinter` | 是 (GUI) | 现代化主题 GUI |
| `CTkMessagebox` | 是 (GUI) | 对话框 |
| `scapy` | 可选 | 原始数据包扫描 (SYN, ACK, FIN, NULL, XMAS) |
## 快速开始
### GUI 模式
```
python main.py
```
直接运行而不带参数将启动 GUI。输入目标，选择端口预设，选择扫描类型，然后点击开始。
### CLI 模式
```
# 快速扫描 localhost
python main.py scan --targets 127.0.0.1 --ports quick
# 使用 async TCP connect 进行全端口扫描
python main.py scan --targets 192.168.1.10 --ports full --type tcp-connect
# 通过 host discovery 扫描子网
python main.py scan --targets 192.168.1.0/24 --ports common --export html
# 查看扫描历史
python main.py history
# 导出之前的扫描
python main.py export --scan-id 1 --format csv
# Database 统计信息
python main.py stats
```
## CLI 参考
### `scan`
运行端口扫描。
```
python main.py scan --targets [options]
```
| 选项 | 默认值 | 描述 |
|---|---|---|
| `--targets` | *(必填)* | 目标：以逗号/换行符分隔，支持 CIDR (`192.168.1.0/24`) |
| `--ports` | `quick` | 预设名称或自定义规范 (`22,80,1-100`) |
| `--type` | `tcp-connect` | 扫描类型：`tcp-connect`, `syn`, `ack`, `fin`, `null`, `xmas`, `udp` |
| `--threads` | `64` | 线程数（用于非异步扫描） |
| `--timeout` | `1.0` | 探测超时时间（秒） |
| `--no-discovery` | *(关闭)* | 跳过主机发现阶段 |
| `--rate-limit` | `0` | 探测之间的延迟（毫秒） |
| `--export` | *(无)* | 导出格式：`plain`, `json`, `csv`, `html`, `all` |
### `history`
显示数据库中最近的扫描记录。
```
python main.py history [--limit 20]
```
### `export`
导出先前扫描的结果。
```
python main.py export --scan-id --format
```
### `stats`
显示数据库统计信息。
```
python main.py stats
```
## GUI 指南
### 布局
```
┌──────────────────────────────────────────────────────┐
│ ⚡ CyberScan Suite [History] [Stats] [Export] │
├──────────┬───────────────────────────────┬───────────┤
│ CONTROLS │ RESULTS TABLE │ PROGRESS │
│ │ ┌─────────────────────────┐ │ ┌───────┐ │
│ Targets │ │ Search │ State Filter │ │ │ Stats │ │
│ Preset │ ├─────────────────────────┤ │ │ │ │
│ Ports │ │ KPI Cards (5) │ │ ├───────┤ │
│ Types │ ├─────────────────────────┤ │ │Terminal│ │
│ Threads │ │ Host Port Type State │ │ │ │ │
│ Timeout │ │ ...sortable results... │ │ │ │ │
│ Rate │ │ │ │ │ │ │
│ Start │ │ │ │ │ │ │
│ Stop │ └─────────────────────────┘ │ └───────┘ │
└──────────┴───────────────────────────────┴───────────┘
```
### 端口预设
| 预设 | 端口 | 用例 |
|---|---|---|
| Quick | 15 | 快速检查最常见的端口 |
| Common | 100+ | 标准网络审计 |
| Web | 19 | Web 服务器枚举 |
| Windows | 24 | Windows/LAN 服务发现 |
| Database | 15 | 数据库端口枚举 |
| IOT | 10 | IoT 设备发现 |
| Full | 1-65535 | 完整端口枚举 |
| Custom | 用户自定义 | 任意组合（例如 `22,80,1-100`） |
## 扫描类型
| 类型 | 方法 | 需要 Scapy | 权限 |
|---|---|---|---|
| TCP Connect | `socket.connect_ex()` | 否 | 无 |
| TCP SYN | Scapy `sr1()` | 是 | Root/管理员 |
| ACK | 带 ACK flag 的 Scapy `sr1()` | 是 | Root/管理员 |
| FIN | 带 FIN flag 的 Scapy `sr1()` | 是 | Root/管理员 |
| NULL | 无 flag 的 Scapy `sr1()` | 是 | Root/管理员 |
| XMAS | 带 FIN+URG+PSH 的 Scapy `sr1()` | 是 | Root/管理员 |
| UDP | `socket.sendto()` + `recvfrom()` | 否 | 无 |
## 架构
```
cyberscan-suite/
├── main.py # Entry point (GUI if no args, CLI if args)
├── pyproject.toml # Package configuration
├── requirements.txt # Core dependencies
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
├── README.md
├── cyberscan/
│ ├── __init__.py # Package metadata
│ ├── config.py # Theme colors, scan types, presets, port DB, paths
│ ├── models.py # ScanResult, HostInfo, ScanStats dataclasses
│ ├── database.py # SQLite: scan history, batch results, scan diffing
│ ├── scanner.py # ScannerEngine: async TCP + threaded raw scans
│ ├── discovery.py # ICMP/TCP/ARP host discovery, TTL OS hints
│ ├── services.py # Service lookup, banners, version parsing, TLS certs
│ ├── exporter.py # CSV/JSON/plain/HTML export
│ ├── cli.py # argparse CLI (scan, history, export, stats)
│ ├── gui.py # CustomTkinter GUI (thread-safe queue-based updates)
│ └── utils.py # Target expansion, port parsing, settings
└── tests/
├── test_ports.py # Port parsing tests
├── test_targets.py # CIDR expansion tests
├── test_services.py # Service lookup + version parsing tests
└── test_presets.py # Port preset resolution tests
```
### 关键设计决策
- **异步 TCP Connect**：使用带有 512 个连接信号量的 `asyncio` 进行全端口扫描，避免了线程池开销。
- **线程安全的 GUI**：工作线程通过 `queue.Queue` 与主线程通信 — 不会从后台线程调用 Tkinter。
- **优雅的 Scapy 降级**：在没有 Scapy 的情况下，TCP Connect 和 UDP 扫描也能正常工作。原始数据包扫描会报告“不支持”而不会崩溃。
- **批量 SQLite 插入**：为了提高性能，单次扫描的所有结果都在单个事务中插入。
## 配置
设置保存在 `cyberscan_config/settings.json` 中：
```
{
"threads": 64,
"timeout": 1.0,
"preset": "Common",
"host_discovery": true,
"rate_limit_ms": 0
}
```
### 主题
深绿色主题与 ProxyScraper v3 共享：
| 颜色 | Hex | 用途 |
|---|---|---|
| 背景 | `#070b07` | 应用背景 |
| 面板 | `#0d1410` | 侧边栏、卡片 |
| 绿色 | `#39ff88` | 标题、开放端口、激活状态 |
| 静音色 | `#7cb895` | 标签、关闭的端口 |
| 红色 | `#ff4458` | 错误、停止按钮 |
| 黄色 | `#ffc944` | 被过滤的端口、警告 |
| 蓝色 | `#44aaff` | 端口号、主机计数 |
| 紫色 | `#aa66ff` | OS 提示 |
## 数据库
SQLite 数据库存储在 `cyberscan_config/cyberscan_database.db`。
### Schema
**`scan_history`** — 每次扫描执行对应一行记录
| 列 | 类型 | 描述 |
|---|---|---|
| `id` | INTEGER PK | 自动递增的扫描 ID |
| `scan_time` | REAL | Unix 时间戳 |
| `targets` | TEXT | 原始目标规范 |
| `ports` | TEXT | 使用的端口规范 |
| `scan_types` | TEXT | 包含扫描类型的 JSON 数组 |
| `total_jobs` | INTEGER | 发送的总探测数 |
| `open_count` | INTEGER | 发现的开放端口数 |
| `closed_count` | INTEGER | 关闭的端口数 |
| `filtered_count` | INTEGER | 被过滤的端口数 |
| `error_count` | INTEGER | 错误数 |
| `duration_sec` | REAL | 扫描持续时间 |
| `throughput` | REAL | 每秒任务数 |
**`results`** — 单个扫描结果
| 列 | 类型 | 描述 |
|---|---|---|
| `scan_id` | INTEGER FK | 对 `scan_history.id` 的引用 |
| `host` | TEXT | 目标 IP |
| `port` | INTEGER | 端口号 |
| `scan_type` | TEXT | 使用的扫描方法 |
| `state` | TEXT | open, closed, filtered, error |
| `reason` | TEXT | 确定该状态的原因 |
| `rtt_ms` | REAL | 往返时间 |
| `banner` | TEXT | 服务 banner |
| `service` | TEXT | 识别出的服务 |
| `version` | TEXT | 解析出的版本字符串 |
| `os_hint` | TEXT | 基于 TTL 的 OS 猜测 |
| `mac` | TEXT | MAC 地址（如果发现） |
| `vendor` | TEXT | 供应商（如果已知） |
| `tls_cert` | TEXT | TLS 证书信息 |
| `timestamp` | REAL | 结果时间戳 |
**`hosts`** — 发现的主机清单
| 列 | 类型 | 描述 |
|---|---|---|
| `ip` | TEXT PK | IP 地址 |
| `hostname` | TEXT | 解析出的主机名 |
| `os_hint` | TEXT | OS 猜测 |
| `mac` | TEXT | MAC 地址 |
| `vendor` | TEXT | 供应商 |
| `first_seen` | REAL | 首次发现时间 |
| `last_seen` | REAL | 最后发现时间 |
## 测试
```
# 运行所有测试
pytest
# 运行 coverage
pytest --cov=cyberscan
# 运行特定测试文件
pytest tests/test_ports.py
```
### 测试覆盖率
| 测试文件 | 测试数 | 覆盖范围 |
|---|---|---|
| `test_ports.py` | 13 | 端口解析：单个、逗号、范围、混合、去重、验证 |
| `test_targets.py` | 9 | CIDR 展开、逗号/换行符解析、去重 |
| `test_services.py` | 12 | 端口→服务查找、从 banner 解析版本 |
| `test_presets.py` | 6 | 预设解析、自定义端口、全范围 |
## 免责声明
**仅在你拥有或获得明确授权评估的系统和网络上使用 CyberScan Suite。** 原始数据包扫描需要提升的权限，结果可能因 OS、防火墙和网络路径而异。未经授权的端口扫描在你所在的司法管辖区可能是非法的。
## 许可证
MIT可证 — 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
版权所有 (c) 2026 Pelea Raul-Daniel
标签：Python, 异步编程, 插件系统, 数据泄露防护, 数据统计, 无后门, 端口扫描, 网络安全, 网络探测, 计算机取证, 逆向工具, 隐私保护