TrixY-OppA/PortSi

# PortSi - 专业漏洞评估工具 PortSi 是一款使用 Python 开发的高性能、经生产强化的网络安全审计工具。它结合了多层 socket 扫描能力与实时的国家漏洞数据库 (NVD) API 智能，以生成全面的基础边界防御评估报告。 该漏洞扫描器展示了清晰的架构、全面的安全分析以及执行级别的报告能力。 ## 核心功能 * **自适应扫描延迟：** 内置速率限制（0.1秒至0.2秒的连接步调控制），以确保快速的 socket 扫描不会触发网络防火墙，或对在线的企业资产模拟拒绝服务 攻击行为。 * **弹性威胁情报：** 与 NVD API 深度集成，包含结构化的 try-except 块、对 HTTP 424/429 速率限制的优雅处理、指数退避机制，并以清晰的警告替代程序崩溃。 * **自动化报告生成：** 使用 ReportLab 模板，即时将扫描结果编译为专业的、可用于生产环境的 PDF 漏洞日志，并带有自动化的 HTML/XML 转义机制，以安全处理原始的 API 响应。 ## 架构与技术栈 * **核心语言：** Python 3.12+（全面类型化并使用严格的 Type Hints） * **网络审计：** `nmap` 二进制文件与 `python-nmap` 集成 * **报告引擎：** 带有定制 flowables 和防御性样式的 `reportlab` * **API 集成：** 带有动态查询管理的 `requests` 库 ## 架构概述 ``` ┌─────────────────────────────────────────────────────────────┐ │ main.py (Orchestration) │ │ ├── Argument parsing (argparse) │ │ └── Pipeline coordination │ └─────────────────────────────────────────────────────────────┘ │ ↓ ┌────────────────────────────────────────────────────────────┐ │ scanner.py (Reconnaissance) │ │ ├── Target validation (socket, ipaddress, DNS) │ │ ├── Fast socket scan (multi-threaded) │ │ └── Nmap service fingerprinting (-sV -O -T4) │ └────────────────────────────────────────────────────────────┘ │ ↓ ┌────────────────────────────────────────────────────────────┐ │ vnum_checker.py (Vulnerability Analysis) │ │ ├── NIST NVD API v2 queries │ │ ├── Exponential backoff retry (rate limiting) │ │ └── Fallback to local vulnerability database │ └────────────────────────────────────────────────────────────┘ │ ↓ ┌────────────────────────────────────────────────────────────┐ │ reporter.py (Report Generation) │ │ ├── ReportLab PDF generation │ │ ├── Executive summary metrics │ │ ├── Detailed findings table │ │ └── CVE details with CVSS scores │ └────────────────────────────────────────────────────────────┘ │ ↓ ✓ scan_report_*.pdf ``` ## 模块详情 ### scanner.py (信息侦察) - **validate_target(target: str) → str** - 验证 IPv4/IPv6 地址和主机名 - 拒绝环回地址 (127.0.0.0/8, ::1) - 通过输入净化防止命令注入 - 为主机名执行 DNS 解析 - **fast_socket_scan(target: str, ports: List[int]) → List[int]** - 使用 ThreadPoolExecutor 进行多线程 TCP 连接扫描 - 默认：前 20 个最常见端口 - 超时：每个端口 2 秒 - 返回按数字排序的开放端口列表 - **run_nmap_scan(target: str, open_ports: List[int]) → Dict[int, Dict[str, Any]]** - 使用 Nmap 进行深度服务指纹识别 - 参数：`-sV` (服务版本)、`-O` (操作系统检测)、`-T4` (速度) - 返回：{port: {service, version, cpe, state}} ### vnum_checker.py (漏洞分析) - **fetch_cves_for_service(cpe_string: str, keyword: str) → List[Dict]** - 查询 NIST NVD API v2 端点 - 针对 HTTP 429（速率限制）的指数退避：1秒、2秒、4秒 - 在 API 持续失败时回退至本地数据库 - 返回：[{cve_id, cvss_score, severity, description}, ...] - **FallbackVulnerabilityDB()** - 包含已知严重漏洞的本地 JSON 数据库 - 覆盖：Apache、OpenSSL、MySQL、SSH、nginx - 在 NVD API 不可用时激活 ### reporter.py (报告生成) - **VulnerabilityReport.generate_pdf() → str** - 基于 ReportLab 的 PDF 生成 - 自定义调色板（深石板灰，深红色） - 部分： - 页眉：目标，时间戳 - 执行摘要：指标表 - 详细发现：端口、服务、CVE、CVSS 评分 - CVE 详情：完整漏洞列表 - 输出：`scan_report_[target]_[timestamp].pdf` ### main.py (编排调度) - **VulnerabilityScanner.execute()** - 协调完整的 pipeline - 阶段：验证 → socket 扫描 → nmap → CVE 分析 → 报告 - 优雅的错误处理 - 带有时间戳的详细日志记录 ### 虚拟环境设置与依赖安装 #### MacOS 设置 ``` # 激活现有虚拟环境 source env/bin/activate # 验证 Python 版本 python --version # Should be 3.12.4 # 安装 Dependencies pip install --upgrade pip pip install nmap requests pillow reportlab # 验证 Nmap 安装 which nmap nmap --version # Should show 7.x or later ``` #### Windows 设置 ``` # 激活现有虚拟环境 call env\Scripts\activate # 验证 Python 版本 python --version # 安装 Dependencies python -m pip install --upgrade pip pip install nmap requests pillow reportlab # 验证 Nmap 安装 where nmap nmap --version ``` #### Linux 设置 ``` # 激活现有虚拟环境 source env/bin/activate # 验证 Python 版本 python3 --version # 安装 Dependencies pip install --upgrade pip pip install nmap requests pillow reportlab # 验证 Nmap 安装 which nmap nmap --version ``` ## 用法 ### 基础扫描 ``` python main.py --target 192.168.1.1 ``` ### 自定义端口扫描 ``` python main.py --target example.com --ports 22,80,443,3306,5432 ``` ### 详细日志 ``` python main.py --target 10.0.0.5 --verbose ``` ### 主机名扫描 ``` python main.py --target example.com ``` ## 输出 ### 日志文件 - `vuln_scanner.log` - 带有时间戳的完整执行日志 ### PDF 报告 - `scan_report_[target]_[timestamp].pdf` - 示例：`scan_report_192.168.1.1_20260621_143022.pdf` ### 报告内容 ``` ┌─────────────────────────────────────┐ │ VULNERABILITY SCAN REPORT │ ├─────────────────────────────────────┤ │ Target: 192.168.1.1 │ │ Date: 2026-06-21 14:30:22 │ ├─────────────────────────────────────┤ │ EXECUTIVE SUMMARY │ │ ├─ Total Open Ports: 5 │ │ ├─ Total CVEs Found: 12 │ │ ├─ Critical: 2 │ │ ├─ High: 4 │ │ ├─ Medium: 5 │ │ └─ Low: 1 │ ├─────────────────────────────────────┤ │ DETAILED FINDINGS │ │ Port │ Service │ Version │ CVSS │ │─────────────────────────────────────│ │ 22 │ SSH │ 7.4 │ 7.5/H │ │ 80 │ HTTP │ 1.1 │ 9.8/C │ │ 443 │ HTTPS │ TLS 1.2 │ 5.3/M │ │ │ ... │ ... │ ... │ ├─────────────────────────────────────┤ │ CVE DETAILS │ │ CVE-2021-44228 │ 10.0 │CRITICAL│ │ CVE-2021-3129 │ 9.8 │CRITICAL│ │ ... │ ... │ ... │ └─────────────────────────────────────┘ ``` ## 安全特性 1. **输入验证** - 字符白名单（字母、数字、点、连字符、冒号） - 长度限制（最多 255 个字符） - IPv4/IPv6/主机名验证 - 环回地址拒绝 2. **防止命令注入** - 无原始 shell 执行 - 通过 python-nmap 库安全地向 Nmap 传递参数 - 在任何系统调用之前进行输入净化 3. **网络安全** - Socket 连接超时（2 秒） - 使用 context manager 进行资源清理 - 对 NVD API 查询使用 HTTPS - 为 API 请求提供 User-Agent 头 4. **数据完整性** - 结构化异常处理 - 在查找 CVE 之前验证服务版本 - 通过回退机制实现优雅降级 5. **日志与审计跟踪** - 全面的日志输出到文件和控制台 - 所有操作均带有时间戳 - 日志中不包含敏感数据 - 提供 DEBUG 和 INFO 级别以供诊断 ## 错误处理 ### 优雅降级 - 如果 Nmap 失败：仅报告 socket 扫描结果 - 如果 NVD API 失败：回退至本地漏洞数据库 - 如果服务版本未知：跳过 CVE 查找（避免误报） - 键盘中断 (Ctrl+C)：干净退出并以零状态码退出 ### 异常处理层级 1. **ValueError** - 输入验证失败（被捕获并清晰报告） 2. **socket.gaierror** - DNS 解析失败 3. **nmap.PortScannerError** - Nmap 执行错误 4. **requests.RequestException** - 网络/API 错误 5. **KeyboardInterrupt** - 用户终止 ## 性能特征 - **Socket 扫描**：约 2-5 秒（10 个并发线程 × 2 秒超时） - **Nmap 扫描**：30-120 秒（取决于端口数量和时序模板） - **CVE 查找**：每个服务 5-15 秒（API 查询 + 重试） - **报告生成**：1-2 秒 - **总扫描时间**：5-15 分钟（典型网络，因系统数量而异） ## 日志格式 ``` 2026-06-21 14:30:22,123 - scanner - INFO - Validating target: 192.168.1.1 2026-06-21 14:30:22,456 - scanner - INFO - Valid IP address: 192.168.1.1 2026-06-21 14:30:22,789 - scanner - INFO - Starting fast socket scan on 192.168.1.1 for 20 ports 2026-06-21 14:30:25,012 - scanner - INFO - Fast socket scan completed. Open ports: [22, 80, 443] 2026-06-21 14:30:25,345 - scanner - INFO - Starting Nmap scan on 192.168.1.1 for ports: 22,80,443 ``` ## 故障排除 ### "Nmap: command not found" ``` brew install nmap # 验证 which nmap nmap --version ``` ### Socket 扫描时提示 "Permission denied" ``` # 某些端口需要提升权限 sudo python main.py --target 192.168.1.1 ``` ### NVD API 速率限制 (429 错误) - 自动指数退避：1秒、2秒、4秒延迟 - 重试后回退至本地数据库 - 检查日志以获取详细信息：`grep -i "rate limit" vuln_scanner.log` ### 执行 Nmap 时提示 "Connection refused" - 验证是否已安装 nmap：`which nmap` - 验证 nmap 是否可执行：`ls -la /usr/local/bin/nmap` - 如有需要请重新安装：`brew reinstall nmap` ## 代码质量标准 ✓ **Type Hints**：所有函数均已完全类型化（Python 3.12+） ✓ **日志记录**：使用专业的日志记录而非 print 语句 ✓ **错误处理**：带有上下文信息的全面异常处理 ✓ **安全性**：输入验证、注入防护、安全的 API 调用 ✓ **模块化**：在 4 个模块中实现了清晰的关注点分离 ✓ **文档**：包含 Docstrings、内联注释和全面的 README ✓ **资源管理**：全面使用 context manager (with 语句) ✓ **退出代码**：规范的退出代码（0=成功，1=失败） ## 作品集亮点 1. **企业级架构**：模块化设计，清晰的关注点分离 2. **安全工程**：输入验证、注入防护、安全的默认设置 3. **API 集成**：支持速率限制和回退机制的 NVD API v2 4. **并发编程**：多线程 socket 扫描 5. **专业报告**：使用 ReportLab 样式生成 PDF 6. **容错性**：指数退避，优雅降级 7. **日志与可观测性**：全面的审计跟踪 8. **Python 最佳实践**：Type hints、context manager、推导式 ## 参考 - [NVD API v2 文档](https://nvd.nist.gov/developers/vulnerabilities) - [python-nmap 文档](https://xael.org/pages/python-nmap-en.html) - [ReportLab 文档](https://www.reportlab.com/docs/reportlab-userguide.pdf) - [CVSS v3.1 规范](https://www.first.org/cvss/v3.1/specification-document) ## 许可证 本项目按“原样”提供，用于作品集展示目的。 ## 作者 VulnScanner 1.0 - 网络安全工程师作品集项目

标签：CTI, Python, 威胁情报, 字符串匹配, 实时处理, 开发者工具, 插件系统, 数据统计, 无后门, 端口扫描, 网络安全, 逆向工具, 隐私保护