way2nafea/PortScanner-Pro

# PortScanner Pro 一个使用 Flask 构建的专业、全栈 TCP 端口扫描仪表盘。PortScanner Pro 结合了多线程 Python 扫描引擎、REST API、持久化扫描历史以及现代化的 Web 仪表盘 —— 此外还提供了一个用于终端操作的独立 CLI。 ## 📋 概述 PortScanner Pro 允许您扫描 IP 地址或主机名的自定义端口范围（或包含常用端口的精选“快速扫描”列表），并在仪表盘中查看实时结果：开放/关闭/过滤状态、可获取的 banner/服务信息，以及您可以重新访问、搜索和导出的历史扫描记录。 该项目遵循清晰的分层架构： ``` Flask Route (routes/) → Service Layer (services/) → Scanner Engine (core/scanner.py) ``` 路由仅负责转换 HTTP 与服务调用之间的对应关系，服务层负责统筹和历史记录的持久化，而扫描引擎是一个纯粹的、可复用的模块，不依赖于 Flask —— 因此它在 Web 应用和 CLI 中的工作方式完全一致。 ## ✨ 功能 - **多线程 TCP 扫描**，支持可配置的 worker pool 和单端口超时设置 - 支持**自定义端口范围**或包含常用端口（SSH、HTTP/S、数据库、RDP 等）的精选**快速扫描列表** - 对扫描目标提供**可选的 reverse DNS 查询** - **持久化扫描历史**（查看、搜索和清除过往扫描记录） - 用于编程化扫描和访问历史记录的 **REST API** - **交互式 CLI**，用于基于终端的扫描，与 Web 应用共享相同的扫描引擎 - **现代化仪表盘 UI**，具备明亮/深色主题、实时扫描进度可视化、可排序/搜索的结果表格以及 CSV/JSON/TXT 导出功能 - **集中式配置**（超时时间、线程限制、端口范围上限），以确保扫描在安全的范围内进行 - 具备自动日志轮转的**结构化日志** - **一致的 JSON 响应结构**和专用的 404/500 错误页面 ## 📸 截图 _将仪表盘、扫描结果和历史记录面板的截图添加到 `screenshots/` 文件夹中并在此处引用，例如：_ ```   ``` ## 📁 文件夹结构 ``` PortScanner-Pro/ │ ├── app.py # Flask application entrypoint ├── cli.py # Command-line interface ├── config.py # Centralized configuration ├── requirements.txt ├── README.md ├── LICENSE ├── .gitignore │ ├── core/ │ └── scanner.py # Scanning engine (sockets, threading, validation) │ ├── routes/ │ ├── api.py # REST API blueprint (/api/scan, /api/history) │ └── web.py # HTML dashboard route │ ├── services/ │ ├── scan_service.py # Orchestrates scans, wraps the engine │ └── history_service.py # Reads/writes persistent scan history │ ├── utils/ │ ├── logger.py # Logging setup (rotating file handler) │ ├── validators.py # Request payload validation │ └── response.py # Consistent success/error JSON schema │ ├── templates/ │ ├── base.html │ ├── index.html │ ├── 404.html │ └── 500.html │ ├── static/ │ ├── css/ │ │ ├── style.css │ │ └── dashboard.css │ ├── js/ │ │ ├── app.js │ │ ├── scanner.js │ │ ├── history.js │ │ └── ui.js │ └── images/ │ ├── data/ # Persisted scan history (history.json), git-ignored ├── logs/ # Rotating application logs, git-ignored ├── exports/ # Exported scan results (CSV/JSON/TXT), git-ignored ├── screenshots/ # README screenshots └── tests/ # Test suite (add your tests here) ``` ## 🚀 安装 **环境要求：** Python 3.10+ ``` # 1. Clone the repository git clone https://github.com//PortScanner-Pro.git cd PortScanner-Pro # 2. 创建并激活 virtual environment python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 3. 安装依赖 pip install -r requirements.txt ``` ## ▶️ 用法 ### Web 仪表盘 ``` python app.py ``` 默认情况下，应用运行在 `http://0.0.0.0:5000`。在浏览器中打开该地址即可访问仪表盘。 环境变量（可选）： | 变量 | 默认值 | 描述 | |---------------------|-----------|----------------------------------| | `PORTSCANNER_DEBUG` | `true` | 启用/禁用 Flask 调试模式 | | `PORTSCANNER_HOST` | `0.0.0.0` | Flask 服务器绑定的主机 | | `PORTSCANNER_PORT` | `5000` | Flask 服务器绑定的端口 | ### CLI ``` python cli.py ``` CLI 会引导您完成目标选择、端口范围（或默认值）、超时时间和线程数的设置，然后在发现端口时实时打印结果 —— 复用与 Web 应用完全相同的扫描引擎。 ## 🛠️ 使用的技术 - **后端：** Python 3, Flask - **扫描：** Python `socket` 模块, `concurrent.futures.ThreadPoolExecutor` - **前端：** HTML5, CSS3（自定义设计系统），原生 JavaScript（无框架） - **持久化：** 基于 JSON 的扫描历史 (`data/history.json`) - **日志：** 带有轮转文件处理程序的 Python `logging` ## 🔌 API 端点 所有 API 响应均遵循统一结构：`{"success": bool, "message": str, "data": ...}`。 | 方法 | 端点 | 描述 | |----------|-----------------|-----------------------------------------------| | `POST` | `/api/scan` | 针对目标运行端口扫描 | | `GET` | `/api/history` | 获取所有过往扫描摘要 | | `DELETE` | `/api/history` | 清除所有扫描历史 | **`POST /api/scan`** 请求体： ``` { "target": "127.0.0.1", "start_port": 1, "end_port": 100, "ports": [21, 22, 80], "timeout": 1.0, "max_workers": 100, "use_reverse_dns": false } ``` - `target` 为必填项；所有其他字段均为可选，若未提供则使用 `config.py` 中的默认值。 - 如果提供了 `ports`（显式列表），其优先级高于 `start_port`/`end_port`。 - 超出配置上限（最大端口范围、最大线程数、最大超时时间）的请求将被拒绝，并返回 `400` 响应。 ## 💻 CLI 用法 运行 `python cli.py` 将启动交互式提示： 1. 输入目标 IP 地址或主机名（自动解析）。 2. 输入起始/结束端口范围，或接受默认值。 3. 输入超时时间和线程数，或接受默认值。 4. 随着每个端口的扫描完成，结果将实时打印，随后是扫描摘要（已扫描端口、发现的开放端口、总耗时）。 ## 🔭 未来改进 - 通过 WebSockets/Server-Sent Events 实现实时扫描进度（目前在请求发送期间于客户端模拟） - 针对开放端口的 Service/banner 指纹识别 - 定时/周期性扫描 - 用户身份验证及多用户扫描历史 - UDP 端口扫描支持 - Docker 化部署 ## ⚠️ 安全免责声明 本工具**仅限于教育目的和授权的安全测试**。请仅扫描您拥有或获得明确书面授权进行测试的系统和网络。未经授权的端口扫描可能会违反您所在司法管辖区的计算机滥用相关法律。作者和贡献者对任何滥用本软件的行为不承担任何责任。 ## 📄 许可证 基于 [MIT License](LICENSE) 发布。

标签：Flask, REST API, Web仪表盘, 插件系统, 数据可视化, 数据统计, 端口扫描, 网络测绘, 逆向工具