isramabrouk1/port_scanner

# 🔐 带 CVE 关联引擎的端口扫描器    ## 📋 目录 - [概述](#-overview) - [功能](#-features) - [架构](#-architecture) - [安装说明](#-installation) - [快速开始](#-quick-start) - [使用示例](#-usage-examples) - [项目结构](#-project-structure) - [技术深入解析](#-technical-deep-dive) - [安全与道德规范](#-security--ethics) - [故障排除](#-troubleshooting) - [贡献](#-contributing) - [许可证](#-license) ## 🎯 概述 该工具通过以下方式自动化网络安全审计的侦查阶段： 1. **扫描**：使用并发连接尝试扫描目标主机的开放 TCP 端口 2. **识别**：通过 banner grabbing 和端口到服务的映射识别服务 3. **关联**：将检测到的服务与精心挑选的本地 CVE 数据库及 NVD API 后备方案中的已知漏洞进行关联 4. **评分**：使用 CVSS v3.1 阈值（严重/高/中/低）对风险进行评分 5. **生成**：生成带有可视化的专业 HTML 审计报告 **专为**：需要快速进行漏洞分类而不依赖黑盒工具的安全工程师、SOC 分析师、渗透测试人员和 DevSecOps 团队设计。 ## ✨ 功能 ### 🔍 扫描引擎 - **并发 TCP 连接扫描**：基于 ThreadPoolExecutor 的并行扫描（约 2 秒内扫描 100 个端口，而顺序扫描需要 147 秒） - **智能超时处理**：在 socket 层面区分 `closed`（收到 RST）和 `filtered`（丢弃 SYN）端口 - **Banner Grabbing**：通过特定协议的探测（SSH、HTTP、FTP 等）进行服务指纹识别 - **可配置的 CLI**：`--host`、`--ports`、`--threads`、`--timeout`、`--verbose`、`--report` ### 🛡️ 漏洞关联 - **本地 SQLite 数据库**：包含 50 多个精选的真实世界 CVE，涵盖常见服务（OpenSSH、Apache、vsftpd、MySQL 等） - **NVD API 后备**：当本地数据库没有匹配项时，自动查询 NIST 国家漏洞数据库 - **智能缓存**：基于文件的 JSON 缓存可防止冗余的 API 调用，并妥善处理速率限制 - **CVSS v3.1 评分**：一致地应用官方严重性阈值： 严重：9.0–10.0 | 高：7.0–8.9 | 中：4.0–6.9 | 低：0.1–3.9 ### 📊 报告 - **专业 HTML 报告**：结合 Chart.js 可视化的 Jinja2 模板 - **五个必备部分**：目标信息、扫描摘要、端口/服务表、漏洞详情、风险评估 + 建议 - **可操作的修复方案**：根据检测到的风险提供针对特定服务的安全指导 ### 🔧 工程质量 - **模块化架构**：跨 6 个专注的 Python 模块实现关注点分离 - **容错性**：妥善处理 DNS 故障、API 超时和网络错误 - **除标准库外无外部依赖**：API/报告功能仅使用 `requests`、`python-dotenv`、`jinja2` ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────┐ │ scanner.py │ │ • CLI entry point (argparse) │ │ • TCP scanning + banner grabbing (socket) │ │ • Threading orchestration (ThreadPoolExecutor) │ │ • Calls correlator → reporter pipeline │ └────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ correlator.py │ │ • Maps port → service keyword (COMMON_SERVICES) │ │ • Queries local DB first, then NVD API │ │ • Calculates risk level from highest CVSS score │ │ • Attaches per-service recommendations │ └────────────┬────────────────────────────────────┘ │ ┌───────┴───────┐ ▼ ▼ ┌─────────┐ ┌─────────────┐ │cve_db.py│ │ nvd_api.py │ │• SQLite │ │• REST API │ │• 50 CVEs│ │• Caching │ │• Query │ │• Rate limit│ └─────────┘ └─────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ reporter.py │ │ • Jinja2 HTML templating │ │ • Chart.js risk distribution visualization │ │ • Outputs professional audit report │ └─────────────────────────────────────────────────┘ ``` ## ⚙️ 安装说明 ### 前置条件 - Python 3.8+ - pip 包管理器 ### 设置 ``` # Clone 仓库 git clone https://github.com/yourusername/port-scanner-cve.git cd port-scanner-cve # 安装 dependencies pip install -r requirements.txt # 配置环境变量（可选但推荐） cp .env.example .env # 编辑 .env 并添加你的 NVD API key: # NVD_API_KEY=your_key_here # 在此获取免费 key: https://nvd.nist.gov/developers/request-an-api-key # 初始化 CVE 数据库（在首次扫描时自动运行，但可以预填充） python cve_db.py ``` ### 依赖项 (`requirements.txt`) ``` requests>=2.28.0 python-dotenv>=0.19.0 jinja2>=3.1.0 ``` ## 🚀 快速开始 ### 基础扫描 ``` python scanner.py --host scanme.nmap.org --start-port 1 --end-port 100 ``` ### 带报告的全面审计 ``` python scanner.py \ --host target.example.com \ --start-port 1 \ --end-port 1000 \ --threads 50 \ --timeout 2.0 \ --report audit_report.html ``` ### 详细模式（显示所有端口状态） ``` python scanner.py --host scanme.nmap.org --ports 20-85 --verbose ``` ## 📖 使用示例 ### 示例 1：扫描单个主机，默认端口 ``` $ python scanner.py --host scanme.nmap.org [INFO] Target : scanme.nmap.org (45.33.32.156) [INFO] Ports : 1 - 100 [INFO] Threads : 100 [INFO] Started : 2026-05-15 22:21:23 PORT SERVICE STATUS BANNER ------------------------------------------------------------ 22 SSH open SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2. Risk : Critical (CVSS 9.8) CVEs : 6 found CVE-2023-38408 9.8 Remote code execution via ssh-agent... CVE-2020-15778 7.8 Command injection in scp recursive... Recommend: Disable root login, enforce key-based auth... 80 HTTP open HTTP/1.1 200 OK... Risk : Critical (CVSS 9.8) CVEs : 7 found ... [SUMMARY] Scanned : 100 ports [SUMMARY] Open : 2 [SUMMARY] Filtered : 98 ``` ### 示例 2：生成 HTML 报告 ``` $ python scanner.py --host scanme.nmap.org --report report.html [REPORT] Report saved to: report.html ``` → 在任何浏览器中打开 `report.html`，即可获得包含以下内容的专业审计文档： - 执行摘要仪表板 - 风险分布饼图 (Chart.js) - 包含 CVE ID、分数、描述的详细漏洞表 - 颜色编码的严重性徽章 - 可操作的修复建议 ### 示例 3：针对慢速网络进行调整 ``` python scanner.py --host target.com --threads 10 --timeout 5.0 ``` → 降低线程数并增加超时时间，以避免触发速率限制或 IDS 警报。 ## 📁 项目结构 ``` port-scanner-cve/ ├── scanner.py # Main CLI: scanning, threading, orchestration ├── cve_db.py # SQLite database: init, seed, query functions ├── nvd_api.py # NVD REST API: fetch, parse, cache, rate-limit handling ├── correlator.py # Core logic: service→keyword mapping, risk scoring, recommendations ├── reporter.py # HTML report generation via Jinja2 + Chart.js ├── templates/ │ └── report_template.html # Jinja2 template for audit reports ├── data/ │ ├── vulns.db # SQLite database (auto-created) │ └── cache/ # JSON cache for NVD API responses ├── .env # Environment variables (NVD_API_KEY) ├── .env.example # Template for .env ├── requirements.txt # Python dependencies ├── README.md # This file └── LICENSE # MIT License ``` ## 🔬 技术深入解析 ### 如何确定端口状态 | 状态 | 网络行为 | Python 异常 | 含义 | |-------|-----------------|------------------|---------| | `open` | SYN → 收到 SYN+ACK | 无 | 服务正在监听 | | `closed` | SYN → 收到 RST+ACK | `ConnectionRefusedError` | 端口可达，无程序监听 | | `filtered` | SYN → 静默丢弃 | `socket.timeout` | 防火墙/IDS 拦截 | ### CVE 关联逻辑 ``` # 1. 检测到 Port 22 → COMMON_SERVICES[22] = "SSH" # 2. "SSH" → SERVICE_TO_KEYWORD["SSH"] = "openssh" # 3. 查询本地 DB: SELECT * FROM cves WHERE service = 'openssh' # 4. 如果为空 → fetch_cves_from_api("openssh") # 5. 取最高 CVSS 分数 → 通过官方阈值映射到严重程度 # 6. 从 RECOMMENDATIONS dict 附加建议 ``` ### 为什么使用本地数据库 + API 后备？ | 方法 | 优点 | 缺点 | |----------|------|------| | **仅限本地数据库** | 快速，离线，确定性 | 覆盖范围有限（50 个 CVE） | | **仅限 API** | 完整的 NVD 覆盖范围（25 万+ CVE） | 速度慢，有速率限制，依赖网络 | | **混合（本工具）** | ✅ 针对常见服务速度快 ✅ 边缘情况的后备方案 ✅ 缓存减少 API 调用 | 逻辑稍复杂 | ### CVSS 评分实现 我们使用 NVD 的**基础分数**（权威）并应用**官方严重性阈值**： ``` def _get_risk_level(score): if score >= 9.0: return "Critical" elif score >= 7.0: return "High" elif score >= 4.0: return "Medium" elif score > 0.0: return "Low" else: return "Informational" ``` *注意：环境/时间指标需要黑盒扫描中无法提供的目标上下文——这是文档中已知的限制。* ## ⚠️ 安全与道德规范 ### 仅限授权使用 此工具专为以下用途设计： - ✅ 对您拥有或获得明确书面测试许可的系统进行安全审计 - ✅ 在受控实验室环境中进行教育目的的使用 - ✅ 符合组织政策的内部漏洞评估 ### 禁止用于： - ❌ 未经授权扫描第三方系统 - ❌ 恶意侦查或准备攻击 - ❌ 任何违反当地计算机犯罪法的活动 ### 操作注意事项 - **速率限制**：高线程数可能会触发 IDS/IPS 警报。使用 `--threads 10-20` 进行更隐蔽的扫描。 - **API 密钥**：切勿将 `.env` 提交到版本控制。在生产环境中使用环境变量。 - **数据敏感性**：报告可能包含漏洞细节——请安全地存储和共享。 ## 🛠️ 故障排除 | 问题 | 解决方案 | |-------|----------| | `Cannot resolve hostname` | 验证 DNS 或直接使用 IP 地址 | | `All ports filtered` | 目标可能位于严格的防火墙之后；减少 `--threads`，增加 `--timeout` | | `NVD API timeout` | 检查互联网连接；在 `nvd_api.py` 中增加超时时间；验证 API 密钥 | | `Database not found` | 运行 `python cve_db.py` 进行初始化，或确保 `data/vulns.db` 存在 | | `Report not generating` | 验证 `templates/report_template.html` 是否存在；检查 Jinja2 是否安装 | ## 📜 许可证 基于 MIT 许可证分发。详情请参阅 `LICENSE`。 ## 🙏 致谢 - [NIST 国家漏洞数据库](https://nvd.nist.gov) 提供 CVE 数据和 API - [PortSwigger Web 安全学院](https://portswigger.net/web-security) 提供 Web 安全培训 - [Scanme.Nmap.Org](https://scanme.nmap.org) 提供合法测试目标 - 开源 Python 社区提供的 `socket`、`concurrent.futures`、`sqlite3` 和 `jinja2` *本项目作为学术网络安全课程的一部分进行开发。所有漏洞数据均来源于公开的权威数据库。*

标签：CVE关联, DevSecOps, Python, 上游代理, 实时处理, 插件系统, 数据统计, 无后门, 端口扫描, 逆向工具