CikolataliPuding/MergenSec

## 什么是 MergenSec？ MergenSec 会扫描目标网络，检测开放的服务，并自动将它们映射到国家漏洞数据库 (NVD) 中已知的 CVE 记录。它会生成交互式风险仪表板和可下载的 JSON 报告 —— 仅需一条命令即可替代数小时的手动安全审计。 ## 功能特性 - **异步网络扫描** — 使用 `python-nmap` 和 `asyncio` 发现开放的 TCP/UDP 端口 - **自动 CVE 查询** — 查询 NVD API 并返回匹配的漏洞记录 - **CVSS 风险评分** — 将每个发现分类为严重、高危、中危或低危 - **交互式仪表板** — 通过 Streamlit 实时可视化结果 - **JSON 报告** — 为每次扫描会话导出结构化的安全报告 ## 架构 ``` User enters target IP or CIDR range │ ▼ AsyncScanner ← python-nmap + asyncio (port & service discovery) │ ▼ CVEFetcher ← NVD API + aiohttp (fetch matching CVE records) │ ▼ VulnMapper ← pandas + CVSS scoring (match services → CVEs) │ ┌──────┴──────┐ ▼ ▼ Dashboard JSON Report (Streamlit) (reports/) ``` ## 前置条件 在安装之前，请确保您具备以下条件： - **Python 3.12+** — [下载](https://www.python.org/downloads/) - **Nmap** — [下载](https://nmap.org/download.html) 并添加到系统 PATH - **NVD API Key** — [免费申请](https://nvd.nist.gov/developers/request-an-api-key) 验证您的设置： ``` python --version # Python 3.12+ nmap --version # Nmap 7.x ``` ## 安装说明 **1. 克隆仓库** ``` git clone https://github.com/YOUR_USERNAME/mergensec.git cd mergensec ``` **2. 创建并激活虚拟环境** ``` python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate ``` **3. 安装依赖** ``` pip install -r requirements.txt ``` **4. 配置环境变量** ``` cp .env.example .env ``` 打开 `.env` 并添加您的 NVD API 密钥： ``` NVD_API_KEY=your_api_key_here DATABASE_URL=sqlite:///mergensec.db ``` **5. 初始化数据库** ``` python -c "from database.db import init_db; init_db()" ``` **6. 启动仪表板** ``` streamlit run dashboard/app.py ``` 仪表板将在 `http://localhost:8501` 打开。 ## 使用方法 1. 输入目标 IP 地址或 CIDR 范围（例如 `192.168.1.1` 或 `192.168.1.0/24`） 2. 点击 **Start Scan**（开始扫描） 3. 查看风险摘要、CVE 表格和 CVSS 分布图表 4. 使用 **Export Report** 按钮下载 JSON 报告 ## 项目结构 ``` mergensec/ ├── core/ │ ├── scanner.py # AsyncScanner — async port and service discovery │ ├── cve_fetcher.py # CVEFetcher — NVD API integration │ ├── vuln_mapper.py # VulnMapper — CVE matching and CVSS scoring │ └── report_generator.py # JSON report generation ├── database/ │ ├── models.py # SQLAlchemy ORM models │ └── db.py # Database connection and initialization ├── dashboard/ │ └── app.py # Streamlit web interface ├── tests/ │ ├── test_scanner.py │ ├── test_cve_fetcher.py │ └── test_vuln_mapper.py ├── reports/ # Generated scan reports (gitignored) ├── .env.example # Environment variable template ├── requirements.txt ├── CONTRIBUTING.md └── README.md ``` ## 运行测试 ``` # 运行所有测试并输出 verbose 结果 pytest tests/ -v # 运行特定 module 的测试 pytest tests/test_scanner.py -v # 生成 coverage 报告 pytest tests/ --cov=core --cov-report=term-missing ``` ## 贡献指南 MergenSec 采用**功能分支工作流**。所有贡献均通过针对 `dev` 分支的 Pull Request 进行。 ``` # 从最新的 dev branch 开始 git checkout dev git pull origin dev # 创建你的 feature branch git checkout -b feature/your-feature-name # Push 并打开一个 Pull Request → target: dev git push origin feature/your-feature-name ``` 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取有关分支命名、提交消息格式和代码风格要求的完整指南。 ## 常见问题 | 错误 | 原因 | 解决方法 | |---|---|---| | `nmap: command not found` | 未安装 Nmap | 从 [nmap.org](https://nmap.org/download.html) 安装 | | `KeyError: NVD_API_KEY` | 缺少 `.env` 文件 | 运行 `cp .env.example .env` 并添加您的密钥 | | `429 Too Many Requests` | 超出 NVD 速率限制 | 速率限制会自动处理；请等待 30 秒后重试 | | `PermissionError` | Nmap 需要提升权限 | 在 Linux/macOS 下使用 `sudo` 运行，或在 Windows 下以管理员身份运行 | | `ModuleNotFoundError` | 虚拟环境未激活 | 请先运行 `source venv/bin/activate` | ## 团队 | 姓名 | 角色 | 模块 | |---|---|---| | Egemen Korkmaz | 首席开发者 | 扫描引擎、集成、协调 | | Selameddin Tirit | 后端开发者 | CVE 获取器、NVD API | | Çağrı Doğan | 后端开发者 | 漏洞映射器、JSON 报告 | | Mustafa Bite | 前端开发者 | Streamlit 仪表板 | | Zid Alkahni | 数据库与 QA | SQLAlchemy 模型、Pytest | ## 许可证 本项目基于 MIT 许可证授权 —— 详见 [LICENSE](LICENSE) 文件。 ## 致谢 作为 Fırat 大学 **YMH220/YMH210 Python 项目** 的一部分构建。 漏洞数据由 [National Vulnerability Database (NVD)](https://nvd.nist.gov/) 提供。

标签：asyncio, ATT&CK 框架, CVE扫描器, CVSS评分, GPT, JSON报告, Kubernetes, MergenSec, Nmap, NVD API, Python, Streamlit, 安全仪表盘, 密码管理, 开源安全工具, 异步编程, 插件系统, 数据统计, 无后门, 无线安全, 服务发现, 漏洞管理, 端口扫描, 结构化查询, 网络安全, 网络资产扫描, 自动化安全, 自动漏洞映射, 虚拟驱动器, 计算机取证, 访问控制, 逆向工具, 逆向工程平台, 隐私保护