beast6713/PortFootprint
GitHub: beast6713/PortFootprint
PortFootprint 是一个零依赖、跨平台的生产级 TCP 端口扫描与服务指纹识别 CLI 框架，解决网络端口发现、服务识别及扫描报告导出与对比的需求。
Stars: 0 | Forks: 0
# PortFootprint
PortFootprint 是一个生产级、高度模块化、跨平台的 TCP 端口扫描与服务指纹识别命令行界面（CLI）工具，完全使用标准 Python 实现。
本代码仓库实现了设计的 **阶段 1**、**阶段 2** 和 **阶段 3**，提供了稳定的多线程扫描核心、模块化的服务发现与协议指纹识别引擎，以及专业的报告生成、统计、历史记录、比较和 CLI 增强。
## 概述
PortFootprint 完全在用户态 socket API 下运行，确保其在 Windows、macOS 和 Linux 上可靠运行，而无需 root 或管理员权限。它使用 **Clean Architecture** 和 **SOLID** 原则进行设计，分离了各个关注层，使得该框架可以轻松集成到更大的环境中。
## 已实现的功能
### 阶段 1：并发核心
- **健壮的 DNS 查询**：验证目标并处理 IPv4/IPv6 名称解析。
- **端口规范解析器**：支持范围 (`20-80`)、逗号分隔列表 (`22,80,443`)、重复项检查以及自动排序。
- **多线程扫描引擎**：通过可配置的 `ThreadPoolExecutor` 并发执行 TCP Connect 扫描。
- **Socket 超时与重试**：可为每个端口连接请求自定义参数设置。
- **动态视觉指示器**：线程安全的终端进度状态更新。
### 阶段 2：服务发现与探测
- **主动/被动 Banner Grabbing**：读取初始 socket 欢迎字符串；如果无响应，则回退到发送安全的 ASCII 探测。
- **动态 Protocol Registry**：实现了一种注册表模式，允许指纹模块自行注册映射端口匹配、优先级和 banner 关键字。
- **独立的 Protocol 模块**：HTTP、HTTPS/TLS、SSH、FTP、SMTP、DNS、IRC 以及数据库（MySQL、PostgreSQL、Redis、MongoDB）。
- **安全解码**：Unicode 异常捕获，安全地从 UTF-8 回退到 Latin-1。
### 阶段 3：报告与操作增强
- **动态导出注册表**：根据请求的报告扩展名动态分配给相应的导出器。
- **专业导出器**：
- **JSON 报告**：全面的结构化 JSON 布局，包含目标详细信息、统计数据以及详细的服务证书/header 字典。
- **CSV 报告**：扁平化的、适配电子表格的 CSV 列表。
- **HTML 报告**：响应式、交互式的单文件 HTML 报告，包含摘要卡片、快速搜索过滤、暗色模式样式，以及显示特定于 protocol 握手数据的可折叠详情。
- **性能与 Protocol 指标**：计算平均扫描速度（每秒端口数）、服务检测计数，并识别最常用的 protocol。
- **执行历史记录管理器**：将扫描指标保存到本地历史日志数据库 (`.portfootprint_history.json`) 中。
- **差分扫描比较**：允许比较两份 JSON 报告（`--compare old.json new.json`）以发现新开放的端口、已关闭的端口以及更新的服务版本变更。
- **灵活的配置文件**：使用 `config.json` 参数覆盖默认设置。
- **结构化文件日志记录**：支持线程名称、日志级别、时间戳和日志文件输出。
## 要求
- **Python 版本**：Python 3.8 或更高版本。
- **外部依赖**：零外部运行时要求（仅使用标准库）。
## 安装
克隆此代码仓库并直接使用 Python 运行扫描器：
```
# Clone 仓库
git clone https://github.com/username/PortFootprint.git
cd PortFootprint
```
要运行本地测试验证套件，请安装开发依赖：
```
# 安装开发依赖
pip install -r requirements.txt
```
## 完整 CLI 命令速查表
以下是扫描器执行命令的渐进列表，按从基础诊断到最复杂的组合排序：
### 1. 基础系统诊断
* 检查命令行选项和帮助菜单详情：
python main.py --help
* 输出当前框架的发布版本：
python main.py --version
### 2. 标准扫描
* 使用默认的 top 端口扫描目标主机名：
python main.py scanme.nmap.org
* 直接扫描原始 IP 地址目标：
python main.py 127.0.0.1
### 3. 自定义端口选择
* 扫描单个自定义端口：
python main.py localhost -p 80
* 扫描多个逗号分隔的端口：
python main.py localhost -p 22,80,443,8080
* 扫描一个包含边界的端口范围：
python main.py localhost -p 20-100
* 扫描包含单个端口和端口范围的混合列表：
python main.py localhost -p 21-25,80,443,8080-8090
### 4. 性能设置
* 使用自定义的并发线程限制进行扫描：
python main.py localhost --threads 50
* 使用自定义的连接超时阈值（以秒为单位）进行扫描：
python main.py localhost --timeout 1.5
* 使用自定义的 socket 失败连接重试次数进行扫描：
python main.py localhost --retries 2
* 在 verbose 模式下进行扫描，以打印调试时间戳和活动线程日志：
python main.py localhost --verbose
### 5. 结构化导出报告
* 生成单个 JSON 报告：
python main.py localhost --json my_scan.json
* 生成扁平化的 CSV 电子表格：
python main.py localhost --csv my_scan.csv
* 生成交互式响应暗色模式 HTML 仪表板：
python main.py localhost --html my_scan.html
* 使用快捷方式自动保存所有支持的输出文件：
python main.py localhost --all-reports
* 将执行追踪流记录到自定义文件路径：
python main.py localhost --log-file scan.log
### 6. 操作与比较控制
* 打印本地扫描历史记录索引列表：
python main.py --history
* 比较两次扫描结果以检查差异/状态变化：
python main.py --compare old_scan.json new_scan.json
### 7. 复杂且冗长的综合命令
* 对目标主机执行高速扫描，查询混合端口列表，并使用自定义超时和重试、verbose 日志，输出所有报告文件并保存调试日志：
python main.py scanme.nmap.org -p 21,22,25,80,100-200,443,3306,8080 --threads 60 --timeout 1.2 --retries 2 --verbose --json report.json --csv report.csv --html report.html --log-file activity.log
## 控制台与报告预览
为了便于快速验证，命令执行和 HTML 仪表板的快照已保存在项目中：
* **交互式 HTML 报告**：扫描器输出一个带有内置暗色模式的交互式、响应式 HTML 报告仪表板：
* **CLI 扫描输出**：在 [cli_scan_output.txt](docs/snapshots/cli_scan_output.txt) 中查看端口扫描的终端表格输出。
* **CLI 扫描历史记录**：在 [cli_history_output.txt](docs/snapshots/cli_history_output.txt) 中查看本地扫描执行日志索引。
* **CLI 比较差异**：在 [cli_compare_output.txt](docs/snapshots/cli_compare_output.txt) 中查看差异检查日志。
## 配置文件指南
可以在当前目录下放置一个可选的 `config.json` 来覆盖默认配置：
```
{
"threads": 50,
"timeout": 1.5,
"retries": 2,
"verbose": false,
"log_file": "scan.log",
"default_reports": {
"json": "report.json",
"html": "report.html"
}
}
```
## 架构设计
PortFootprint 利用解耦的层来强制实施关注点分离：
- **cli/**：解析终端指令，打印实时进度，并显示格式化的服务详细信息和比较结果。
- **core/**：管理调度器、配置加载器、统计估算器、历史日志和比较。
- **scanner/**：控制主机名查询、端口列表解析、socket 连接 (`connect_ex`) 和线程池工作线程。
- **services/**：管理被动/主动 banner grabbing、注册表候选项查找以及专门的 protocol 指纹识别器。
- **reports/**：通过 ExportRegistry 格式化并导出 JSON、CSV 和高级交互式 HTML 报告。
- **common/**：共享的验证规则、路径清理器和标准日志初始化程序。
## 当前局限性
- **仅限 TCP Connect 扫描**：在连接时执行完整的 3 次握手，这比原始 SYN 扫描更慢且更容易被检测到。
- **主机发现**：假定目标主机处于活动状态；不执行预扫描 ping 探测。
## 路线图
- **阶段 1**：核心 TCP 扫描器、CLI 验证、线程池和进度格式化。*(已完成)*
- **阶段 2**：实现深度被动/主动 banner grabbing 和服务检测映射。*(已完成)*
- **阶段 3**：专业报告、统计指标、执行历史日志、扫描比较和配置文件。*(已完成)*
- **阶段 4**：开发高级漏洞集成插件或动态插件加载器。
## 免责声明
本软件仅严格出于教育目的、安全研究和授权审计而开发。未经目标所有者明确许可，请勿对系统执行扫描。作者和维护者不对未经授权的使用或次生损害承担任何责任。
标签：Python, Scrypt密钥派生, TCP协议, 报告生成, 插件系统, 数据泄露防护, 数据统计, 无后门, 服务指纹识别, 端口扫描, 网络探测, 逆向工具