Ayeesha02/Network-Vulnerability-Scanner
GitHub: Ayeesha02/Network-Vulnerability-Scanner
一款零依赖的 Python 网络漏洞扫描 CLI，自动化完成主机发现、端口扫描、服务指纹识别与 CVE 匹配并输出结构化报告，专为授权渗透测试而构建。
Stars: 0 | Forks: 1
# 网络漏洞扫描器 (NVS)
## 目录
1. [概述](#overview)
2. [架构](#architecture)
3. [项目结构](#project-structure)
4. [扫描流水线](#scan-pipeline)
5. [安装说明](#installation)
6. [快速开始](#quick-start)
7. [CLI 参考](#cli-reference)
8. [模块文档](#module-documentation)
9. [CVE 特征数据库](#cve-pattern-database)
10. [报告格式](#report-format)
11. [运行测试套件](#running-the-test-suite)
12. [扩展 NVS](#extending-nvs)
13. [性能调优](#performance-tuning)
14. [限制与已知问题](#limitations--known-issues)
15. [贡献指南](#contributing)
16. [许可证](#license)
## 概述
NVS 是一个零依赖的 Python CLI，它自动化了网络渗透测试的前四个阶段
——主机发现 (ICMP + TCP-ping)，
端口枚举 (TCP connect + UDP)，服务指纹识别（针对 15+ 协议的
banner 解析），以及 CVE 分诊（针对精选的 40 条漏洞数据库
进行特征匹配）——并导出带有 CVSS 加权风险评分和优先修复措施的
结构化 JSON 报告。
专为需要快速、可审计、适合物理隔离网络（air-gap）替代方案
来替代组合使用 nmap + grep + 电子表格的安全工程师而构建。
⚠️ 仅限用于授权的渗透测试。在大多数司法管辖区，未经
明确书面许可扫描系统是非法的。
```
Targets → Live hosts → Open ports → Service versions → CVE matches → JSON report
```
| 功能 | 实现方式 | 权限要求 |
|---|---|---|
| 主机发现 | ICMP Echo Request (原始套接字) | root / CAP_NET_RAW |
| 主机发现 (备用) | TCP 连接常用端口 | 无 |
| 端口枚举 | TCP 三次握手 | 无 |
| UDP 端口扫描 | 特定协议探测 | 无 |
| Banner 抓取 | recv() / TLS 封装 | 无 |
| 服务指纹识别 | 每种协议的正则解析器 | 无 |
| 操作系统检测 | python-nmap (-O) | root (针对 Nmap) |
| CVE 特征匹配 | 本地 JSON 数据库 | 无 |
| 报告生成 | 结构化 JSON | 无 |
**核心设计原则：**
- **零强制第三方依赖** — 核心流水线运行于 Python 标准库上；`python-nmap` 和 `rich` 是可选的附加组件。
- **线程池并发** — 主机发现和端口扫描均使用 `ThreadPoolExecutor`；每次扫描均可调整池大小。
- **优雅降级** — 无权限时，原始套接字 ICMP 会回退到 TCP-ping；缺少二进制文件时会静默跳过 Nmap 阶段。
- **结构化输出** — 每次扫描都会生成适合导入漏洞管理平台的机器可读 JSON。
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ CLI (cli.py) │
│ argparse → target resolution → pipeline orchestration │
└────────────────┬────────────────────────────────────────────────┘
│
┌─────────▼─────────┐
│ Phase 1 │ host_discovery.py
│ Host Discovery │ ICMP ping sweep (raw socket)
│ │ TCP-ping fallback (no root needed)
└─────────┬──────────┘
│ live_hosts[]
┌─────────▼──────────┐
│ Phase 2a │ port_scanner.py
│ Port Enumeration │ TCP connect scan (multi-threaded)
│ │ Optional UDP probes
└─────────┬──────────┘
│ open_ports[]
┌─────────▼──────────┐
│ Phase 2b │ service_detector.py
│ Service Detection │ Banner parsing per protocol
│ │ TLS handshake + cert extraction
└─────────┬──────────┘
│ (optional)
┌─────────▼──────────┐
│ Phase 3 │ nmap_scanner.py
│ Nmap Enrichment │ OS fingerprinting (-O)
│ (optional) │ Service version detection (-sV)
│ │ NSE script execution
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ Phase 4 │ cve_mapper.py
│ CVE Mapping │ Port / service / banner / version
│ │ cross-referenced against JSON DB
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ Output │ report_generator.py
│ JSON Report │ Executive summary + risk score
│ │ Per-host findings + remediation
└────────────────────┘
Shared utilities: utils.py
IP/CIDR validation · hostname resolution · port-range parsing
ANSI colours · progress bar · timestamps
```
## 项目结构
```
nvs/
│
├── scanner/ # Main Python package
│ ├── __init__.py # Public API re-exports
│ ├── cli.py # CLI entry point (argparse + orchestration)
│ ├── utils.py # Shared helpers (IPs, ports, colours, progress)
│ ├── host_discovery.py # Phase 1: ICMP + TCP-ping host sweep
│ ├── port_scanner.py # Phase 2a: TCP connect + UDP scanning
│ ├── service_detector.py # Phase 2b: Banner parsing & fingerprinting
│ ├── nmap_scanner.py # Phase 3: python-nmap wrapper (optional)
│ ├── cve_mapper.py # Phase 4: CVE pattern matching engine
│ └── report_generator.py # JSON report builder
│
├── data/
│ └── cve_patterns.json # Bundled CVE database (40 patterns, v1.0.0)
│
├── tests/
│ ├── __init__.py
│ ├── test_host_discovery.py # ICMP checksum, packet structure, sweep logic
│ ├── test_port_scanner.py # PortResult, TCP scan, UDP scan, port parsing
│ └── test_cve_mapper.py # CVE loading, matching, filtering, report gen
│
├── reports/ # Runtime output directory (git-ignored)
│ └── .gitkeep
│
├── requirements.txt # Optional dependencies
├── setup.py # Package installer & entry-point definition
├── .gitignore
└── README.md
```
## 扫描流水线
### 阶段 1 — 主机发现 (`host_discovery.py`)
**目标：** 在花费时间对死主机进行端口扫描之前，识别目标范围内哪些 IP 可达。
**ICMP 扫描（首选，需要 root）**
1. 创建原始 `AF_INET / SOCK_RAW / IPPROTO_ICMP` 套接字。
2. 构建 ICMP type-8 (Echo Request) 数据包，包含：
- Type=8, Code=0
- Identifier = `os.getpid() & 0xFFFF`
- Sequence = 1
- Payload = 时间戳字节
- Checksum = 基于 header + payload 的 RFC 1071 Internet 校验和
3. 捕获回复（type-0 Echo Reply）；计算 RTT。
**TCP-Ping 备用方案（无 root）**
当抛出 `PermissionError`（无 `CAP_NET_RAW`）时，会尝试 TCP 连接一系列常用端口（80, 443, 22, 445…）。任何成功的 `connect_ex() == 0` 都意味着主机存活。
**并发：** `ThreadPoolExecutor(max_workers=discovery_threads)` — 默认 50 个工作线程，可通过 `--discovery-threads` 调整。
### 阶段 2a — 端口枚举 (`port_scanner.py`)
**TCP Connect 扫描**
对于每个端口，调用 `socket.connect_ex((target, port))` 并设置 `settimeout(timeout)`。返回码：
| 返回码 | 状态 |
|---|---|
| `0` | **open** |
| `ECONNREFUSED` (111) | **closed** |
| 超时 / 其他 | **filtered** |
默认仅返回 `open` 端口（verbose 模式包含所有状态）。
**Banner 抓取**（可选，使用 `--no-banners` 禁用）
成功连接后：
1. **被动 recv：** 针对立即发送数据的协议（SSH, FTP, SMTP, POP3, IMAP）。
2. **HTTP GET 探测：** 针对 HTTP/HTTPS 端口，发送最简的 `GET / HTTP/1.0` 请求。
3. **TLS 封装：** 针对 TLS 端口（443, 8443, 993…），第二次连接会使用 `ssl.create_default_context()` 封装套接字（对自签名证书禁用验证）。
**UDP 扫描** (`--udp`)
向众所周知的 UDP 端口发送特定协议的探测。状态推断：
| 结果 | 状态 |
|---|---|
| 收到响应 | **open** |
| `ConnectionRefusedError` (ICMP port-unreachable) | **closed** |
| 超时 | **open\|filtered** |
**并发：** `ThreadPoolExecutor(max_workers=threads)` — 默认 100 个工作线程，可通过 `--threads` 调整。
### 阶段 2b — 服务检测 (`service_detector.py`)
基于端口的正则解析器从原始 banner 中提取结构化元数据：
| 服务 | 解析器 | 提取字段 |
|---|---|---|
| SSH | `_parse_ssh()` | 产品，版本，OS 提示 |
| FTP | `_parse_ftp()` | 产品，版本 |
| SMTP | `_parse_smtp()` | 产品，版本 |
| HTTP | `_parse_http()` | 产品，版本，框架提示 |
| POP3 | `_parse_pop3()` | 版本字符串 |
| IMAP | `_parse_imap()` | 版本字符串 |
| MySQL | `_parse_mysql()` | 版本 (来自 Protocol v10 数据包) |
| Redis | `_parse_redis()` | 版本字符串 |
| RDP | `_parse_rdp()` | 静态标识 |
对于 TLS 端口，`ssl.SSLSocket.cipher()` 和 `getpeercert()` 提取：
- 协商的 TLS 版本 (TLSv1.2, TLSv1.3)
- Cipher suite 名称
- 证书 Common Name 和 SAN 列表
- 证书过期日期
### 阶段 3 — Nmap 增强 (`nmap_scanner.py`) *(可选)*
使用 `--nmap` 激活。需要同时满足：
- `$PATH` 中存在 `nmap` 二进制文件
- `pip install python-nmap`
**默认参数：** `-sV -O --version-intensity 5`
NVS 仅将**已发现的开放端口**传递给 Nmap，使得运行速度明显快于完整的 Nmap 扫描。
**合并策略：** 将 Nmap 数据叠加到现有的主机字典中：
- 仅当当前的 `product` 和 `version` 为空或“unknown”时，才进行回填。
- `os_guess` 和 `os_accuracy` 在主机级别设置。
- NSE 脚本输出存储在每个端口的 `extra.nmap_scripts` 字典中。
**NSE 脚本** (`--nmap-scripts "default,vuln"`)：执行 Nmap 内置的漏洞检测脚本。`vuln` 类别具有侵入性——仅在授权目标上使用。
### 阶段 4 — CVE 特征匹配 (`cve_mapper.py`)
使用四个匹配维度（跨维度采用 OR 逻辑），针对 `data/cve_patterns.json` 中的每个特征测试每个开放端口：
| 维度 | 条件 |
|---|---|
| **端口匹配** | 目标端口 ∈ `affected_ports` 且协议匹配 |
| **服务关键词** | `service_keywords[i]` 是检测到的服务名称的子字符串 |
| **Banner 模式** | `banner_patterns[i]` 是原始 banner（转换为小写后）的子字符串 |
| **版本范围** | 检测到的版本 ∈ [`version_min`, `version_max`]（语义化版本比较） |
结果按严重性排序：`CRITICAL → HIGH → MEDIUM → LOW → INFO`。
CVSS 严重性阈值（v3 标准）：
| CVSS 分数 | 严重性 |
|---|---|
| 9.0 – 10.0 | **CRITICAL** |
| 7.0 – 8.9 | **HIGH** |
| 4.0 – 6.9 | **MEDIUM** |
| 0.1 – 3.9 | **LOW** |
| 0.0 | **INFO** |
使用 `--min-cvss 7.0` 可以在初始分诊期间过滤杂音。
## 安装说明
### 前置条件
| 要求 | 版本 | 用途 |
|---|---|---|
| Python | ≥ 3.8 | 运行环境 |
| pip | 任意 | 包管理 |
| nmap binary | ≥ 7.0 | 阶段 3 (可选) |
| Root / sudo | — | ICMP ping, Nmap -O |
### 从源码安装
```
# Clone 仓库
git clone https://github.com/example/network-vuln-scanner.git
cd network-vuln-scanner
# 创建并激活虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate.bat # Windows
# 安装软件包（仅核心 — 无第三方依赖）
pip install -e .
# 可选：Nmap 集成
pip install -e ".[nmap]"
# 可选：完整开发安装
pip install -e ".[all]"
```
### 验证安装
```
nvs --help
python -m pytest tests/ -v
```
## 快速开始
```
# 扫描单个主机（前 100 个端口，无需 root）
nvs -t 192.168.1.10
# 扫描 /24 子网并保存 JSON 报告
sudo nvs -t 192.168.1.0/24 -p top-100 -r reports/scan.json
# 完整 TCP 端口范围 + UDP + Nmap OS 检测
sudo nvs -t 10.0.0.5 -p 1-65535 --udp --nmap -r full_scan.json
# 从文件读取目标，筛选 CVSS >= 7.0 的发现
nvs -f targets.txt -p 22,80,443,3389,8080 --min-cvss 7.0 -r report.json
# 跳过主机发现（假定所有目标都活跃）
nvs -t 10.0.0.100 -p top-100 --skip-discovery -v
# 使用自定义 CVE 数据库 + 运行 Nmap NSE 脚本
sudo nvs -t 10.0.0.1 -p top-100 --nmap --nmap-scripts "default,vuln" \
--cve-db /opt/my_cve_db.json -r vuln_report.json
```
## CLI 参考
```
usage: nvs [-h] (-t TARGET | -f FILE) [-p PORTS] [--udp] [--skip-discovery]
[--timeout S] [--threads N] [--discovery-threads N] [--no-banners]
[--nmap] [--nmap-args ARGS] [--nmap-scripts SCRIPTS]
[--no-cve] [--cve-db PATH] [--min-cvss SCORE]
[-r FILE] [--no-color] [-v] [-q]
```
### 目标指定
| 参数 | 描述 |
|---|---|
| `-t`, `--target TARGET` | 单个 IP、CIDR 块 (`192.168.1.0/24`) 或主机名 |
| `-f`, `--target-file FILE` | 包含 IP / CIDR / 主机名的换行符分隔文件（允许 `#` 注释） |
### 端口指定
| 参数 | 默认值 | 描述 |
|---|---|---|
| `-p`, `--ports PORTS` | `top-100` | `top-100` \| `22,80,443` \| `1-1024` \| 混合 |
| `--udp` | off | 在 TCP 之外探测常用 UDP 端口 |
| `--skip-discovery` | off | 将所有目标视为存活；跳过阶段 1 |
### 扫描调优
| 参数 | 默认值 | 描述 |
|---|---|---|
| `--timeout S` | `1.0` | 每个端口的连接超时时间（秒） |
| `--threads N` | `100` | TCP 扫描线程池大小 |
| `--discovery-threads N` | `50` | 主机发现线程池大小 |
| `--no-banners` | off | 跳过 banner 抓取（速度更快；服务信息更少） |
### Nmap 集成
| 参数 | 默认值 | 描述 |
|---|---|---|
| `--nmap` | off | 启用阶段 3 Nmap 增强 |
| `--nmap-args ARGS` | `-sV -O --version-intensity 5` | 原始 Nmap 参数字符串 |
| `--nmap-scripts SCRIPTS` | — | NSE 脚本（例如 `default,vuln`）。隐含 `--nmap`。 |
### CVE 映射
| 参数 | 默认值 | 描述 |
|---|---|---|
| `--no-cve` | off | 跳过阶段 4 CVE 特征匹配 |
| `--cve-db PATH` | `data/cve_patterns.json` | 自定义 CVE 特征 JSON 文件 |
| `--min-cvss SCORE` | `0.0` | 报告的最小 CVSS 分数（0.0 = 全部） |
### 输出
| 参数 | 默认值 | 描述 |
|---|---|---|
| `-r`, `--report FILE` | — | 将 JSON 报告写入 FILE |
| `--no-color` | off | 禁用 ANSI 颜色代码 |
| `-v`, `--verbose` | off | 显示 closed / filtered 端口 |
| `-q`, `--quiet` | off | 隐藏进度；仅输出发现结果 |
## 模块文档
### `scanner.utils`
整个流水线中使用的共享辅助工具。
```
from scanner.utils import (
validate_ip, # bool: is string a valid IPv4/v6?
validate_cidr, # bool: is string valid CIDR notation?
expand_cidr, # List[str]: CIDR → individual host IPs
resolve_hostname, # Optional[str]: forward DNS lookup
reverse_dns, # Optional[str]: PTR record lookup
parse_port_range, # List[int]: "22,80-90,top-100" → sorted int list
is_root, # bool: running as root / Administrator?
format_duration, # str: 3661.0 → "1h 1m 1s"
get_timestamp, # str: ISO-8601 current timestamp
Colors, # ANSI colour namespace; Colors.disable() for plain
ProgressBar, # In-place terminal progress bar
)
```
### `scanner.host_discovery`
标签：Python, Scrypt密钥派生, 加密, 插件系统, 数据统计, 无后门, 服务指纹识别, 漏洞扫描器, 端口扫描, 网络安全, 逆向工具, 隐私保护