Zannu-Opeyemi/Network-Vulnerability-Scanner
GitHub: Zannu-Opeyemi/Network-Vulnerability-Scanner
一款专为授权实验环境设计的防御性 Python 端口暴露扫描器，通过严格的白名单机制和保守的 TCP 连接检查帮助初学者安全地学习网络资产暴露分析。
Stars: 0 | Forks: 0
# 网络漏洞扫描器
一款防御性的 Python 暴露扫描器，专为已获授权的私有和环回实验系统设计。
该项目针对明确提供的单个 IP 地址和选定端口，执行缓慢且顺序的 TCP 连接检查。它会根据明确的 allowlist 验证目标，被动读取有限的服务器主动 banner，应用保守的暴露评级，并导出 JSON 或 CSV 报告。
## 项目概述
该扫描器专为初级到中级学习者设计，提供了一种透明的方式来解答以下问题：
- 哪些选定的 TCP 端口接受连接？
- 每个端口通常关联什么服务？
- 服务是否提供了服务器主动发送的 banner？
- 哪些暴露项应优先进行防御性审查？
- 如何一致地记录结果？
它不是漏洞利用扫描器。开放的端口被报告为一种暴露观察，而非存在漏洞的证明。
## 功能
- Python 3.11+
- 命令行界面
- 明确的单 IP 目标
- 强制性 CIDR allowlist
- 私有和环回实验地址强制执行
- 无 socket 活动的试运行验证
- 明确的逗号分隔 TCP 端口
- 禁用端口范围
- 每次运行最多 64 个选定端口
- 顺序 TCP 连接检查
- 可配置的有限超时
- 可配置的速率限制
- 被动的服务器主动 banner 读取
- 不传输应用 payload
- 基本服务识别
- 保守的暴露风险评级
- JSON 报告导出
- CSV 报告导出
- CSV 公式注入中和
- 清晰的错误和安全拒绝行为
- Pytest 测试套件
- 法律范围、架构、威胁模型和作品集文档
## 安全范围
### 允许的目标
代码仅接受：
- RFC 1918 IPv4：
- `10.0.0.0/8`
- `172.16.0.0/12`
- `192.168.0.0/16`
- IPv4 环回：`127.0.0.0/8`
- IPv6 唯一本地地址：`fc00::/7`
- IPv6 环回：`::1/128`
目标还必须属于该次运行提供的明确 allowlist。
### 拒绝的目标和行为
扫描器拒绝：
- 公共 IP 地址
- 主机名和 URL
- 目标范围
- allowlist 之外的目标
- 公共 allowlist 网络
- 诸如 `1-65535` 的端口范围
- 超过 64 个选定端口
- 超过五秒的超时
- 每秒超过十个连接的速率
扫描器不包含：
- 漏洞利用代码
- 暴力破解
- 凭证攻击
- UDP 扫描
- Raw socket 或 SYN 扫描
- 主机发现
- 子网扩展
- 并行扫描
- 隐蔽或规避
- CVE 利用或版本匹配
扫描前请阅读 [docs/legal-scope.md](docs/legal-scope.md)。
## 架构
```
flowchart LR
CLI["Explicit CLI input
target + ports + allowlist"] Safety["Safety validation
private lab IP + CIDR membership"] Dry["Dry-run plan
no sockets"] Scan["Sequential TCP connect
timeout + rate limit"] Banner["Passive bounded banner read
no payload sent"] Risk["Service label + exposure rating"] Report["JSON / CSV report"] CLI --> Safety Safety --> Dry Safety --> Scan Scan --> Banner Banner --> Risk Risk --> Report ``` 详细设计：[docs/architecture.md](docs/architecture.md) ## 安装 ### 要求 - Python 3.11 或更高版本 - Git 克隆代码库： ``` git clone https://github.com/YOUR-USERNAME/network-vulnerability-scanner.git cd network-vulnerability-scanner ``` 创建隔离环境： Windows PowerShell： ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` Linux 或 macOS： ``` python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` 运行时扫描器仅使用 Python 标准库。Pytest 是唯一的开发依赖项。 ## 用法示例 ### 务必从试运行开始 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --dry-run ``` 预期行为： - 验证 IP 字面量 - 验证 allowlist - 确认目标从属关系 - 验证端口、超时和速率 - 打印计划 - 不打开任何 socket ### 扫描选定的实验端口并导出 JSON ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --output reports/scan.json ``` ### 导出 CSV ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --output reports/scan.csv ``` ### 调整超时和速率 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --timeout 1.5 --rate 1 --output reports/scan.json ``` 此操作每秒最多执行一次顺序连接尝试。 ### 禁用被动 banner 收集 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --no-banner --output reports/scan.json ``` ### 安全的环回演示 ``` python main.py --target 127.0.0.1 --ports 80,443,8000 --allowlist 127.0.0.0/8 --dry-run ``` 请仅在你自己的机器上执行实际的环回扫描。 ## CLI 参考 | 参数 | 必需 | 用途 | |---|---:|---| | `--target` | 是 | 一个明确的 IPv4 或 IPv6 实验地址 | | `--ports` | 是 | 选定的逗号分隔 TCP 端口 | | `--allowlist` | 是 | 批准的 CIDR；可重复 | | `--dry-run` | 否 | 验证而不打开 socket | | `--timeout` | 否 | 每个端口的超时时间，`0.1`–`5.0` 秒 | | `--rate` | 否 | 每秒顺序尝试次数，`0.2`–`10.0` | | `--no-banner` | 否 | 禁用被动 banner 读取 | | `--output` | 否 | `.json` 或 `.csv` 报告路径 | | `--format` | 否 | 明确指定 `json` 或 `csv` | 没有默认目标或默认端口列表。 ## 报告格式 ### JSON JSON 报告包含： - 报告标题和生成时间 - 目标和 allowlist - 扫描策略 - 摘要计数 - 最高暴露评级 - 各端口发现 - 分析师指导 - 局限性 示例发现： ``` { "port": 22, "protocol": "tcp", "state": "open", "service": "ssh", "banner": "SSH-2.0-Example", "latency_ms": 1.42, "risk_rating": "medium", "risk_score": 2, "risk_rationale": "SSH is an administrative service; restrict access and use secure authentication.", "error": "" } ``` ### CSV CSV 报告为每个选定端口创建一行，包括扫描元数据、状态、服务、banner、延迟、暴露评级、依据和错误。 以电子表格公式字符开头的值会被安全地添加前缀。 ## 风险评级 评级用于确定审查优先级；它们并不断言存在漏洞。 | 评级 | 含义 | |---|---| | 高 | 需要立即审查的敏感、遗留、远程控制、文件共享或数据库暴露 | | 中 | 需要验证的管理、未加密、应用或数据库暴露 | | 低 | 仍然需要归属权、补丁和访问审查的开放服务 | | 信息性 | 在此次检查期间没有 TCP 服务接受连接 | 扫描器不检查版本与 CVE 数据库的匹配情况，也不生成 CVSS 分数。 ## 测试说明 ``` python -m pytest -q ``` 预期结果： ``` 16 passed ``` 测试验证： - 接受授权的私有目标 - 接受环回地址 - 拒绝 allowlist 之外的目标 - 拒绝公共目标 - 拒绝公共 allowlist - 拒绝主机名 - 拒绝端口范围 - 试运行无法调用扫描器活动 - banner 控制字符净化 - 风险评级 - JSON 报告生成 - CSV 报告生成和公式中和 ## 截图占位符 捕获： | 截图 | 证据 | |---|---| | `01-help.png` | CLI 参数和法律警告 | | `02-dry-run.png` | 无 socket 活动的已验证计划 | | `03-outside-allowlist-refusal.png` | 安全网关阻止未授权的实验目标 | | `04-public-target-refusal.png` | 公共 IP 策略已强制执行 | | `05-authorized-scan.png` | 针对你自己的实验 VM 的选定端口扫描 | | `06-json-report.png` | 结构化的暴露报告 | | `07-csv-report.png` | 适合电子表格的发现结果 | | `08-tests-passing.png` | 自动化测试 | | `09-architecture.png` | 安全性和数据流 | 未经许可，切勿发布真实的内部资产详细信息。 ## 局限性 - 仅限 TCP 连接检查 - 每次运行一个目标 - 最多 64 个选定端口 - 无 UDP - 无主机发现 - 无身份验证检查 - 无 TLS 证书分析 - 被动 banner 可能为空 - 防火墙可能导致服务显示为不可达 - 端口到服务的映射是启发式的 - 评级是暴露优先级，而非漏洞证明 - 无持续监控或资产盘点 - 不适用于生产规模的扫描 ## 未来改进 - 添加签名授权配置文件 - 添加加密报告哈希 - 添加可选的 TLS 证书元数据，无需协议测试 - 在批准的扫描日期之间添加报告比较 - 添加结构化日志和审计标识符 - 添加仅限本地的 Streamlit 报告查看器 - 添加 CI linting 和依赖项审查 - 添加 IPv6 测试覆盖率 - 添加可配置的组织批准风险策略 - 添加资产所有者和补救跟踪字段 未来的工作必须保留单目标、allowlist 限制、非利用的设计。 ## 作品集说明 本项目演示了： - Python socket 编程 - 输入和 CIDR 验证 - 防御性安全控制 - 速率限制和超时 - 服务暴露分析 - 风险沟通 - JSON 和 CSV 报告 - 单元测试 - 威胁建模 - 道德范围执行 使用 [docs/portfolio-writeup.md](docs/portfolio-writeup.md) 获取适合演示的案例研究。 ## 文档 - [架构](docs/architecture.md) - [法律和道德范围](docs/legal-scope.md) - [威胁模型](docs/threat-model.md) - [作品集说明](docs/portfolio-writeup.md) ## 免责声明 本项目用于授权的防御性教育。它不能确立开放服务是存在漏洞的，且不得用于在未经明确许可的情况下扫描系统。
target + ports + allowlist"] Safety["Safety validation
private lab IP + CIDR membership"] Dry["Dry-run plan
no sockets"] Scan["Sequential TCP connect
timeout + rate limit"] Banner["Passive bounded banner read
no payload sent"] Risk["Service label + exposure rating"] Report["JSON / CSV report"] CLI --> Safety Safety --> Dry Safety --> Scan Scan --> Banner Banner --> Risk Risk --> Report ``` 详细设计：[docs/architecture.md](docs/architecture.md) ## 安装 ### 要求 - Python 3.11 或更高版本 - Git 克隆代码库： ``` git clone https://github.com/YOUR-USERNAME/network-vulnerability-scanner.git cd network-vulnerability-scanner ``` 创建隔离环境： Windows PowerShell： ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` Linux 或 macOS： ``` python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` 运行时扫描器仅使用 Python 标准库。Pytest 是唯一的开发依赖项。 ## 用法示例 ### 务必从试运行开始 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --dry-run ``` 预期行为： - 验证 IP 字面量 - 验证 allowlist - 确认目标从属关系 - 验证端口、超时和速率 - 打印计划 - 不打开任何 socket ### 扫描选定的实验端口并导出 JSON ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --output reports/scan.json ``` ### 导出 CSV ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --output reports/scan.csv ``` ### 调整超时和速率 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --timeout 1.5 --rate 1 --output reports/scan.json ``` 此操作每秒最多执行一次顺序连接尝试。 ### 禁用被动 banner 收集 ``` python main.py --target 192.168.56.10 --ports 22,80,443 --allowlist 192.168.56.0/24 --no-banner --output reports/scan.json ``` ### 安全的环回演示 ``` python main.py --target 127.0.0.1 --ports 80,443,8000 --allowlist 127.0.0.0/8 --dry-run ``` 请仅在你自己的机器上执行实际的环回扫描。 ## CLI 参考 | 参数 | 必需 | 用途 | |---|---:|---| | `--target` | 是 | 一个明确的 IPv4 或 IPv6 实验地址 | | `--ports` | 是 | 选定的逗号分隔 TCP 端口 | | `--allowlist` | 是 | 批准的 CIDR；可重复 | | `--dry-run` | 否 | 验证而不打开 socket | | `--timeout` | 否 | 每个端口的超时时间，`0.1`–`5.0` 秒 | | `--rate` | 否 | 每秒顺序尝试次数，`0.2`–`10.0` | | `--no-banner` | 否 | 禁用被动 banner 读取 | | `--output` | 否 | `.json` 或 `.csv` 报告路径 | | `--format` | 否 | 明确指定 `json` 或 `csv` | 没有默认目标或默认端口列表。 ## 报告格式 ### JSON JSON 报告包含： - 报告标题和生成时间 - 目标和 allowlist - 扫描策略 - 摘要计数 - 最高暴露评级 - 各端口发现 - 分析师指导 - 局限性 示例发现： ``` { "port": 22, "protocol": "tcp", "state": "open", "service": "ssh", "banner": "SSH-2.0-Example", "latency_ms": 1.42, "risk_rating": "medium", "risk_score": 2, "risk_rationale": "SSH is an administrative service; restrict access and use secure authentication.", "error": "" } ``` ### CSV CSV 报告为每个选定端口创建一行，包括扫描元数据、状态、服务、banner、延迟、暴露评级、依据和错误。 以电子表格公式字符开头的值会被安全地添加前缀。 ## 风险评级 评级用于确定审查优先级；它们并不断言存在漏洞。 | 评级 | 含义 | |---|---| | 高 | 需要立即审查的敏感、遗留、远程控制、文件共享或数据库暴露 | | 中 | 需要验证的管理、未加密、应用或数据库暴露 | | 低 | 仍然需要归属权、补丁和访问审查的开放服务 | | 信息性 | 在此次检查期间没有 TCP 服务接受连接 | 扫描器不检查版本与 CVE 数据库的匹配情况，也不生成 CVSS 分数。 ## 测试说明 ``` python -m pytest -q ``` 预期结果： ``` 16 passed ``` 测试验证： - 接受授权的私有目标 - 接受环回地址 - 拒绝 allowlist 之外的目标 - 拒绝公共目标 - 拒绝公共 allowlist - 拒绝主机名 - 拒绝端口范围 - 试运行无法调用扫描器活动 - banner 控制字符净化 - 风险评级 - JSON 报告生成 - CSV 报告生成和公式中和 ## 截图占位符 捕获： | 截图 | 证据 | |---|---| | `01-help.png` | CLI 参数和法律警告 | | `02-dry-run.png` | 无 socket 活动的已验证计划 | | `03-outside-allowlist-refusal.png` | 安全网关阻止未授权的实验目标 | | `04-public-target-refusal.png` | 公共 IP 策略已强制执行 | | `05-authorized-scan.png` | 针对你自己的实验 VM 的选定端口扫描 | | `06-json-report.png` | 结构化的暴露报告 | | `07-csv-report.png` | 适合电子表格的发现结果 | | `08-tests-passing.png` | 自动化测试 | | `09-architecture.png` | 安全性和数据流 | 未经许可，切勿发布真实的内部资产详细信息。 ## 局限性 - 仅限 TCP 连接检查 - 每次运行一个目标 - 最多 64 个选定端口 - 无 UDP - 无主机发现 - 无身份验证检查 - 无 TLS 证书分析 - 被动 banner 可能为空 - 防火墙可能导致服务显示为不可达 - 端口到服务的映射是启发式的 - 评级是暴露优先级，而非漏洞证明 - 无持续监控或资产盘点 - 不适用于生产规模的扫描 ## 未来改进 - 添加签名授权配置文件 - 添加加密报告哈希 - 添加可选的 TLS 证书元数据，无需协议测试 - 在批准的扫描日期之间添加报告比较 - 添加结构化日志和审计标识符 - 添加仅限本地的 Streamlit 报告查看器 - 添加 CI linting 和依赖项审查 - 添加 IPv6 测试覆盖率 - 添加可配置的组织批准风险策略 - 添加资产所有者和补救跟踪字段 未来的工作必须保留单目标、allowlist 限制、非利用的设计。 ## 作品集说明 本项目演示了： - Python socket 编程 - 输入和 CIDR 验证 - 防御性安全控制 - 速率限制和超时 - 服务暴露分析 - 风险沟通 - JSON 和 CSV 报告 - 单元测试 - 威胁建模 - 道德范围执行 使用 [docs/portfolio-writeup.md](docs/portfolio-writeup.md) 获取适合演示的案例研究。 ## 文档 - [架构](docs/architecture.md) - [法律和道德范围](docs/legal-scope.md) - [威胁模型](docs/threat-model.md) - [作品集说明](docs/portfolio-writeup.md) ## 免责声明 本项目用于授权的防御性教育。它不能确立开放服务是存在漏洞的，且不得用于在未经明确许可的情况下扫描系统。
标签：GPT, MSSQL, Python, 占用监测, 插件系统, 文档结构分析, 无后门, 漏洞管理, 网络安全, 网络扫描器, 资产管理, 逆向工具, 隐私保护