Rohit30Confluence/mini-scanner

# Mini 扫描器 [](https://img.shields.io/badge/Python-3.10%2B-blue) [](https://img.shields.io/badge/License-MIT-green) [](https://img.shields.io/badge/Status-Active-success) ## 概述 Mini Scanner 是一个开源的 TCP 端口扫描器，旨在展示现代 Python 开发实践，同时提供清晰、模块化且可扩展的代码库。 与庞大的安全框架不同，Mini Scanner 专注于可读性、可维护性和教育意义。它专为希望了解网络扫描器内部工作原理的开发者、学生和安全爱好者设计。 该项目提供了一个坚实的基础，可以在未来的版本中通过高级网络功能进行扩展。 ## 功能特性 - TCP Connect 端口扫描 - 使用 ThreadPoolExecutor 进行并发扫描 - Banner Grabbing - 主机名解析 - 可配置超时时间 - 易读的终端输出 - JSON 输出 - Web 界面（本地 Flask 控制台 + 静态演示） - 模块化架构 - 日志支持 - 单元测试 - 易于扩展 ## 为什么选择 Mini Scanner？ 创建 Mini Scanner 是为了在实现一个实用的网络工具的同时，展示专业的软件工程实践。 该项目强调： - 整洁的架构 - 关注点分离 - 可读的代码 - 类型提示 - 测试 - 文档 - 可扩展性 Mini Scanner 的目标不是成为 Nmap 的另一个复制品，而是致力于成为一个教育性的网络框架，让开发者能够轻松理解和扩展。 # 安装说明 克隆仓库： ``` git clone https://github.com/Rohit30Confluence/mini-scanner.git cd mini-scanner ``` 创建虚拟环境： ``` python -m venv .venv ``` Linux/macOS ``` source .venv/bin/activate ``` Windows ``` .venv\Scripts\activate ``` 安装依赖 ``` pip install -e . ``` # 快速开始 扫描 localhost ``` mini-scanner scan localhost ``` 扫描 IP 地址 ``` mini-scanner scan 192.168.1.10 ``` 扫描主机名 ``` mini-scanner scan scanme.nmap.org ``` 扫描自定义端口范围 ``` mini-scanner scan localhost --ports 1-1000 ``` 增加超时时间 ``` mini-scanner scan localhost --timeout 2 ``` 输出为 JSON ``` mini-scanner scan localhost --json ``` 更喜欢使用浏览器？请查看下方的 [Web 界面](#web-interface)。 # 输出示例 ``` Target: scanme.nmap.org PORT STATUS SERVICE 22 OPEN ssh 80 OPEN http 443 OPEN https 9929 OPEN nping-echo ``` JSON 输出 ``` { "host": "scanme.nmap.org", "ports": [ { "port": 22, "status": "open", "banner": "OpenSSH" }, { "port": 80, "status": "open", "banner": "nginx" } ] } ``` # Web 界面 Mini Scanner 提供了两种在浏览器中使用的方式，以替代 CLI。它们共享相同的视觉设计——一个配线架（patch-panel）显示界面，其中每个被扫描的端口会亮起绿色（开放）、红色（关闭）或琥珀色（被过滤）——但它们在按钮背后的实际运行机制有所不同。 ## 1. 实时扫描器 (`webapp/`，本地运行) 这是一个 Flask 应用，它使用与 CLI 相同的 TCP 连接 / 并发线程 / Banner Grabbing 逻辑来执行真实的扫描。安装后，它会直接调用 `mini_scanner` 包，因此扫描结果与 CLI 完全一致。 ``` pip install -r requirements-web.txt cd webapp python app.py ``` 然后打开 **http://localhost:5000**。要与他人分享，请将 `webapp/` 部署到运行 Python 的主机上（例如 Render 或 Railway）——GitHub Pages 无法运行此部分，因为它仅提供静态文件服务。完整的部署步骤请参见 `webapp/README_WEBUI.md`。 内置安全限制：扫描需要您确认拥有测试目标的授权，端口数量上限为 1024 个，每个端口的超时时间为 5 秒，并且按 IP 进行速率限制（6 次扫描/分钟），以防止公共部署被用于恶意的批量扫描。 ## 2. 静态演示 (`docs/`，托管在 GitHub Pages 上) 这是相同 UI 的纯 HTML/CSS/JS 版本，可通过本仓库的 **Settings → Pages** 免费直接托管。由于 Pages 仅提供静态文件服务，此版本在客户端**模拟**结果（根据您的输入进行确定性地模拟），而不是执行真实的网络扫描——它的存在是为了在没有服务器的情况下演示界面和输出格式。这一点在 UI 界面中已有明确标注。 在线地址：`https://rohit30confluence.github.io/mini-scanner/`（如果尚未激活，请在仓库的 **Settings → Pages** → Source: Deploy from a branch → `main` / `docs` 中开启）。 | | 实时扫描器 (`webapp/`) | 静态演示 (`docs/`) | |---|---|---| | 真实网络扫描 | ✅ 是 | ❌ 模拟 | | 托管方式 | 本地，或 Render/Railway 等 | GitHub Pages（免费，内置） | | 需要服务器 | 是 | 否 | | 适用场景 | 实际扫描已授权目标 | 展示 UI，无需配置 | # 项目架构 ``` CLI Browser │ │ ▼ ▼ Argument Parser Web UI (Flask / static) │ │ ▼ ▼ Target Resolver ────────▶ Scanner Engine │ ▼ Result Objects │ ▼ Output Formatter ``` 每个模块都具有单一的职责，使得项目易于理解、测试和扩展。Web UI 直接复用与 CLI 相同的扫描引擎 / 结果对象，而不是重复编写扫描逻辑。 # 项目结构 ``` mini-scanner/ ├── mini_scanner/ │ ├── __init__.py │ ├── __main__.py │ ├── main.py │ ├── scanner.py │ ├── parser.py │ ├── config.py │ ├── target.py │ ├── result.py │ ├── output.py │ ├── logger.py │ └── exceptions.py │ ├── webapp/ # Live Flask web console (real scans) │ ├── app.py │ ├── scan_engine.py │ ├── templates/ │ └── static/ │ ├── docs/ # Static GitHub Pages demo (simulated scans) │ ├── index.html │ ├── style.css │ └── app.js │ ├── tests/ │ ├── examples/ │ ├── pyproject.toml ├── requirements-web.txt ├── README.md ├── LICENSE └── CHANGELOG.md ``` # 工作原理 1. 解析命令行参数（或在 Web UI 中解析浏览器表单）。 2. 验证目标和端口。 3. 将主机名解析为 IP 地址。 4. 创建工作线程。 5. 尝试 TCP 连接。 6. 记录开放的端口。 7. 在可用时抓取服务 Banner。 8. 格式化结果。 9. 在终端中显示、在 Web 配线架上渲染，或导出为 JSON。 # 开发指南 安装开发依赖 ``` pip install -r requirements-dev.txt ``` 运行测试 ``` pytest ``` 运行 lint 检查 ``` ruff check . ``` 格式化代码 ``` black . ``` 排序导入 ``` isort . ``` 类型检查 ``` mypy . ``` 覆盖率测试 ``` coverage run -m pytest coverage report ``` # 测试 该项目包含以下内容的自动化测试： - 解析器 - 扫描器 - 输出格式化器 - 配置 - 结果对象 未来的版本将扩大以下方面的测试覆盖率： - IPv6 - Banner Grabbing - CLI - Web UI（Flask 路由 + 扫描引擎） - 日志记录 - 超时处理 - 并发扫描 # 路线图 ## 版本 1.0 - TCP Connect 扫描 - Banner Grabbing - JSON 输出 - 日志记录 - 单元测试 ## 版本 1.1 - IPv6 支持 - CSV 导出 - 多目标扫描 - 更好的错误处理 ## 版本 1.2 - 异步扫描器 - CIDR 支持 - 进度条 - 服务检测 ## 版本 2.0 - UDP 扫描器 - SYN 扫描（在支持的系统上） - 插件系统 - REST API - Docker 镜像 - ~~Web 仪表盘~~ — 已发布：请参阅 [Web 界面](#web-interface) # 安全 Mini Scanner 仅用于已授权的安全测试。 在扫描您不拥有或未管理的网络或系统之前，请务必获得许可。这适用于 Web 界面以及 CLI——实时扫描器在运行任何扫描之前，都需要明确确认授权。 作者不对滥用本软件的行为负责。 请负责任地报告安全问题。 详情请参阅 **SECURITY.md**。 # 贡献 欢迎贡献。 您可以通过以下方式做出贡献： - 报告 bug - 提议新功能 - 改进文档 - 编写测试 - 重构代码 - 提升性能 - 改进 Web UI（`webapp/` 和 `docs/`） 在提交 Pull Request 之前，请阅读 **CONTRIBUTING.md**。 # 许可证 该项目基于 MIT 许可证授权。 有关更多信息，请参阅 **LICENSE** 文件。 # 致谢 Mini Scanner 的灵感来源于网络基础知识、Python 的标准 socket 库，以及开源社区对可读、可维护软件的重视。 ## 免责声明 本项目仅出于教育、研究和授权的安全评估目的提供。 用户需自行确保遵守适用的法律、法规和组织政策。未经授权扫描系统或网络可能是违法行为。 请负责任地使用本软件。

标签：Python, 安全规则引擎, 并发编程, 插件系统, 教学项目, 数据统计, 无后门, 服务器安全, 端口扫描, 网络工具, 逆向工具