AtharvKashyap/Automated_Vulnerability_Scanner

# 自动化 CVE 漏洞扫描器    安全团队经常收到过多的 CVE，却缺乏足够的上下文。该工具将原始漏洞源转化为优先级明确、可审查的报告，包含 CISA KEV 富化、LLM 生成的分析师备注、人工审查保障、Excel 仪表板、高管 PDF 摘要以及可选的邮件发送功能。 Excel 工作簿包含详细的 CVE 报告和摘要 仪表板，带有 KPI 卡片、严重程度分布、资产风险排名、热门 CVE、 人工审查跟踪和图表。PDF 为管理者或利益相关者提供了简明的高管视图， 他们无需打开完整的工作簿即可了解关键发现和建议的后续 行动。启用邮件发送功能后，扫描器可以将这两份最终报告作为附件发送给配置的收件人。 ## 截图 ### 摘要仪表板  ### 高管摘要 PDF  ### CVE 报告  ### 运行时日志  ## 示例输出 `examples/` 目录中包含了经过脱敏处理的示例资产清单和报告： - `examples/sample_assets.csv` - `examples/sample_cve_report.xlsx` - `examples/sample_executive_summary.pdf` ## 要求 - Python 3.11+ - 免费的 NVD API key: https://nvd.nist.gov/developers/request-an-api-key - 免费的 OpenRouter API key: https://openrouter.ai - `requirements.txt` 中的 Python 依赖项，包括用于输出 Excel 的 `openpyxl` 和用于生成 PDF 的 `reportlab` - 可选的 SMTP 提供商凭证，用于邮件发送，例如 Brevo、Microsoft 365 SMTP、SendGrid、Mailgun 或其他兼容 SMTP 的服务 ## 设置 ### 1. 克隆仓库 ``` git clone https://github.com/AtharvKashyap/Automated_Vulnerability_Scanner.git cd Automated_Vulnerability_Scanner ``` ### 2. 创建并激活虚拟环境 ``` python3 -m venv auto_vuln_venv source auto_vuln_venv/bin/activate # macOS / Linux auto_vuln_venv\Scripts\activate # Windows ``` ### 3. 安装依赖项 ``` pip install -r requirements.txt ``` ### 4. 配置环境变量 ``` cp .env.example .env # 编辑 .env 并添加你的 NVD_API_KEY 和 OPENROUTER_API_KEY ``` 必需的 `.env` 值： ``` NVD_API_KEY=your_nvd_api_key OPENROUTER_API_KEY=your_openrouter_api_key ``` 可选的 `.env` 值： ``` SCAN_DAYS=7 OUTPUT_DIR=output ASSETS_FILE=assets.txt LOG_DIR=logs EMAIL_ENABLED=false SMTP_HOST=smtp-relay.brevo.com SMTP_PORT=587 SMTP_USERNAME=your_smtp_login SMTP_PASSWORD=your_smtp_key_or_password EMAIL_FROM=verified_sender@example.com EMAIL_TO=recipient1@example.com,recipient2@example.com EMAIL_USE_TLS=true ``` ### 5. 检查你的资产清单 扫描器同时支持简单的文本清单和更丰富的 CSV 清单。 #### 简单的文本清单 使用 `assets.txt` 进行快速扫描。每行添加一个产品名称： ``` Google Chrome VMware ESXi nginx ``` 每一行都将被视为资产名称和 NVD 产品搜索的关键字。 #### CSV 业务上下文清单 当你希望在 Excel 报告中包含业务上下文时，请使用 CSV 清单： ``` asset_name,product,version,owner,criticality,internet_facing Finance Browser Fleet,Google Chrome,124.0.6367.91,Endpoint Team,High,No Customer Portal Web Server,nginx,1.24.0,Platform Team,Critical,Yes Prod Virtualization Cluster,VMware ESXi,8.0,Infrastructure Team,Critical,Yes ``` 运行命令： ``` python3 run_scanner.py --assets-file examples/sample_assets.csv ``` 必需的 CSV 列： - `asset_name` - `product` 可选的 CSV 列： - `version` - `owner` - `criticality` - `internet_facing` 有效的 `criticality` 取值包括 `Critical`、`High`、`Medium` 和 `Low`。 有效的 `internet_facing` 取值包括 `Yes` / `No`、`True` / `False`、`Y` / `N` 和 `1` / `0`。 ## 用法 使用默认设置运行扫描器： ``` python3 run_scanner.py ``` 默认情况下，扫描器使用： - 7 天的回溯窗口 - `assets.txt` 作为资产清单 - `output/` 作为报告目录 要进行业务上下文报告，请使用 `--assets-file` 传入 CSV 清单。 输出将保存至： ``` output/cve_report_YYYY-MM-DD.xlsx output/cve_report_YYYY-MM-DD_executive_summary.pdf ``` 如果启用了邮件发送功能，在最终的工作簿和 PDF 保存完毕后，这两个文件也将作为电子邮件附件发送。 生成的 Excel 工作簿包含两个工作表： - `Summary Dashboard`：重新设计的经理/分析师仪表板，包含 KPI 卡片、严重程度分布、业务上下文资产风险排名、发布趋势表、热门 CVE、人工审查队列和图表。 - `CVE Report`：详细的逐条 CVE 发现，包含原始 NVD 数据和分析师补充信息。 生成的 PDF 包含一份高管摘要，具有： - 扫描概述和报告健康度 - CVE 总数、Critical、High、CISA KEV 和人工审查发现的关键指标 - 需优先审查的热门 CVE - 按风险评分排序的热门资产 - 建议的后续行动 ### 命令行选项 显示所有可用选项： ``` python3 run_scanner.py --help ``` 扫描距离当前 UTC 时间自定义天数的历史记录： ``` python3 run_scanner.py --scan-days 14 ``` 扫描明确的日期范围： ``` python3 run_scanner.py --start-date 2026-05-01 --end-date 2026-05-28 ``` 日期必须使用 `YYYY-MM-DD` 格式。如果提供了明确的结束日期，扫描器会在内部将其转换为 UTC 时间的次日午夜，从而包含整个结束日期。 将 Excel 报告保存到自定义目录： ``` python3 run_scanner.py --output-dir reports ``` 使用自定义资产清单文件： ``` python3 run_scanner.py --assets-file assets_test.txt ``` 使用包含资产所有者、版本、关键性和互联网暴露状态的 CSV 清单： ``` python3 run_scanner.py --assets-file examples/sample_assets.csv ``` 选项可以组合使用： ``` python3 run_scanner.py --scan-days 30 --output-dir reports --assets-file assets_test.txt ``` 命令行参数将覆盖 `.env` 中的值。如果未提供命令行参数或可选的 `.env` 值，则使用上述默认值。 ### 人工审查后备方案与重试机制 如果 LLM 富化失败、超时、触及提供商速率限制或返回不完整的输出，扫描器仍会将该 CVE 行写入 Excel 报告。分析师富化的单元格将被标记为红色，并标记为需要人工审查。 在扫描结束时，扫描器会对标记为人工审查的行重试一次。如果重试成功，现有的 Excel 行将被原地更新，并移除红色的人工审查标记。如果重试失败，该行将保持标记为需人工分析师审查的状态。 这确保了潜在的重要 CVE 不会仅仅因为 LLM 富化失败而被遗漏。 ### 高管摘要 PDF 创建 Excel 仪表板后，扫描器还会将一份 PDF 高管摘要写入与工作簿相同的输出目录中。 该 PDF 专为需要简明概述而非完整技术表格的经理、客户或利益相关者设计。它汇总了报告健康度、关键指标、优先 CVE、高风险资产以及建议的后续行动。 示例输出： ``` output/cve_report_YYYY-MM-DD_executive_summary.pdf ``` ### 可选邮件发送功能 扫描器可以选择使用 SMTP 将最终的 Excel 工作簿和高管摘要 PDF 发送给配置的收件人。这在需要将报告发送给安全主管、经理、客户或分发列表时非常有用。 默认情况下，邮件发送功能处于禁用状态。要启用它，请在 `.env` 中配置 SMTP 设置： ``` EMAIL_ENABLED=true SMTP_HOST=smtp-relay.brevo.com SMTP_PORT=587 SMTP_USERNAME=your_smtp_login SMTP_PASSWORD=your_smtp_key_or_password EMAIL_FROM=verified_sender@example.com EMAIL_TO=recipient1@example.com,recipient2@example.com EMAIL_USE_TLS=true ``` 发件人地址必须对 SMTP 提供商有效。例如，Brevo 要求经过验证的发件人或已验证的发信域名，然后才会发送来自该地址的邮件。 该邮件包含： - 作为附件的 Excel CVE 报告 - 作为附件的高管摘要 PDF - 以修复为中心的简明摘要，包括 CVE 总数、Critical 发现、High 发现、CISA KEV 发现以及人工审查数量 邮件发送失败将单独记录，与报告生成过程分离，以确保即使发送失败，已完成的扫描仍会将 Excel 和 PDF 报告保留在磁盘上。 #### Brevo SMTP 设置 Brevo 可用作报告发送的 SMTP 提供商。这在 Microsoft 365 SMTP 被禁用，或者你希望使用专门的交易邮件提供商来发送扫描器通知时非常有用。 基本设置步骤： 1. 创建或登录 Brevo 账户。 2. 转到 SMTP/API 设置，如果尚未启用，请启用交易 SMTP。 3. 创建一个新的 SMTP 密钥。 4. 在 Brevo 中验证发件人电子邮件地址或验证发信域名。 5. 将 SMTP 值添加到 `.env` 中。 6. 使用 `EMAIL_ENABLED=true` 运行一次小型测试扫描，并确认收件人收到了 Excel 和 PDF 附件。 Brevo 的 `.env` 配置示例： ``` EMAIL_ENABLED=true SMTP_HOST=smtp-relay.brevo.com SMTP_PORT=587 SMTP_USERNAME=your_brevo_smtp_login SMTP_PASSWORD=your_brevo_smtp_key EMAIL_FROM=your_validated_sender@example.com EMAIL_TO=recipient1@example.com,recipient2@example.com EMAIL_USE_TLS=true ``` 重要注意事项： - `SMTP_USERNAME` 应为 Brevo 显示的 SMTP 登录名，不一定是你的常规电子邮件地址。 - `SMTP_PASSWORD` 应为 Brevo SMTP 密钥，而不是你的 Brevo 账户密码。 - `EMAIL_FROM` 必须是在 Brevo 中经验证的发件人或已验证域名上的地址。 - 如果不希望每次扫描器运行都发送电子邮件，在正常开发期间请保持 `EMAIL_ENABLED=false`。 - 切勿提交 `.env`、SMTP 密钥、API 密钥或真实的报告输出。 如果 Brevo 接受了邮件但收件人未收到，请首先检查 Brevo 的交易日志。邮件可能因为发件人未经验证、域名未验证、邮件仍在挂起状态，或者收件人的邮件系统隔离了附件而被阻止。 ### Excel 报告功能 Excel 工作簿专为分析师审查而设计： - CVSS 分数在可用时会写入为 Excel 数值，以便正确进行排序、筛选和绘图。 - 使用 CSV 清单时，`CVE Report` 工作表包含资产名称、产品、安装版本、所有者、关键性和互联网暴露状态等资产业务上下文。 - 发布日期在可解析时会被写入为 Excel 日期值。 - 需要人工审查的行会在分析师富化列中标记为红色。 - `Summary Dashboard` 工作表通过 KPI 卡片、严重程度统计、资产风险排名、发布趋势表、热门 CVE、人工审查队列和图表来汇总扫描结果。 - 资产风险排名结合了漏洞严重程度、CVSS 分数、CISA KEV 状态、人工审查状态、业务关键性和互联网暴露情况。 - 仪表板图表放置在主要可见的仪表板区域，而不是工作表的最右侧列。 - 仪表板仅冻结标题区域，使表格和图表更易于导航。 - 工作簿在写入每个 CVE 后都会保存，因此即使运行中断，也会保留部分报告。 ### 业务上下文风险评分 仪表板结合漏洞严重程度和资产业务上下文对资产进行排名。这有助于优先处理影响关键或外部可访问系统的漏洞发现，而不是平等对待每一个产品匹配。 风险评分包括： - Critical、High、Medium、Low 和 Pending 发现的严重程度权重 - 观察到的资产最高 CVSS 分数 - 已知被利用漏洞的 CISA KEV 加分 - 仍需分析师验证的发现的人工审查加分 - 来自 CSV 清单的业务关键性加分 - 来自 CSV 清单的互联网暴露加分 例如，面向互联网的客户门户网站上的 Critical CVE 排名应高于类似的内部低关键性工作站发现，即使两者出现在同一扫描窗口中。 ### 输入验证 扫描器在执行 API 调用之前会验证用户提供的选项： - `--scan-days` 必须是正整数，且不能超过 120 天。 - 明确的日期范围不能超过 120 天，因为 NVD 日期范围筛选器限制为连续的 120 天。 - 日期必须使用 `YYYY-MM-DD` 格式。 - `--output-dir` 和 `--assets-file` 必须是相对项目路径。绝对路径、根路径和包含 `..` 的路径将被拒绝。 - 文本清单的资产名称必须至少包含一个字母或数字，且不得超过 100 个字符。 - CSV 清单必须包含 `asset_name` 和 `product` 列。 - 提供时，CSV 的 `criticality` 值必须是 `Critical`、`High`、`Medium` 或 `Low`。 - CSV 的 `internet_facing` 值必须是可识别的布尔值，如 `Yes` / `No`、`True` / `False` 或 `1` / `0`。 ## 运行时日志记录 扫描器在运行时会输出简要的进度日志。日志显示： - 当前资产编号和资产总数 - 每个资产发现的 CVE 数量 - 该资产内的当前 CVE 编号 - 严重程度、CVSS 分数和 CISA KEV 状态 - 已写入的 Excel 行 - LLM 富化状态 - 人工审查重试结果 - 摘要仪表板生成情况 - 高管摘要 PDF 生成情况 - 可选的邮件发送状态 - 最终报告和 PDF 路径 详细的日志文件也会写入配置的 `LOG_DIR` 目录中。 ## 利益相关者仪表板 自动化漏洞扫描器现在会生成一个交互式的利益相关者仪表板，旨在让非技术人员也能更容易地理解漏洞发现。 虽然 Excel 报告和高管摘要为安全分析师提供了详细的技术分析，但利益相关者仪表板将高优先级的发现转化为通俗易懂的解释，帮助经理、高管和资产所有者在无需网络安全专业知识的情况下了解风险。 ### 主要功能 #### 高管概述 * 显示高级指标，例如： * Critical/High CVE 总数 * 高风险资产 * 严重程度分布 * 需要立即关注的资产 #### 资产风险可视化* 交互式图表突出显示了需要注意的资产以及整个环境中风险集中的位置。 * 使利益相关者能够快速识别安全风险最大的系统。 #### 通俗易懂的 CVE 摘要 * 将技术性漏洞信息转化为简明且对利益相关者友好的解释。 * 帮助解答诸如以下问题： * 为什么这个漏洞很重要？ * 潜在的业务影响是什么？ * 应该采取什么行动？ * 修复的紧迫性如何？ #### 按需提供的技术上下文 * 技术细节仍然可以通过可展开部分查看。 * 允许技术和非技术用户在不同细节层次上查阅同一份报告。 ### 仪表板工作流程 ``` NVD + CISA KEV + Asset Inventory ↓ Vulnerability Scan ↓ LLM Enrichment ↓ Excel Report Generation ↓ Executive Summary PDF ↓ Stakeholder Dashboard ``` ### 输出 扫描完成后，扫描器会生成： * Excel 漏洞报告 (`.xlsx`) * 高管摘要 PDF (`.pdf`) * 交互式利益相关者仪表板 (`stakeholder_dashboard.html`) 利益相关者仪表板作为扫描工作流程的一部分自动生成，并反映最新的扫描结果。 ### 目的 该仪表板通过将原始的 CVE 发现转化为可执行的安全情报，弥合了技术漏洞分析与业务决策之间的差距。这使得高管、经理、资产所有者和其他非技术利益相关者能够在不需要深入了解网络安全知识的情况下，理解组织风险并确定补救工作的优先级。 ## 数据库层 扫描器包含一个轻量级的 SQLite 数据库层，作为跨扫描的持久漏洞跟踪系统。这确保了发现不会被当作无状态的扫描输出处理，而是作为与每个资产关联的、不断更新的安全记录。 数据库本地存储于： ``` databases/vulnerability_management.db ``` ### 模式概述 ``` findings ``` 表存储了所有的 CVE 与资产的关联关系，包含原始漏洞数据和分析师生成的上下文： - CVE 元数据（cve_id、严重程度、CVSS 分数、源 URL） - 资产上下文（资产名称、组、安装版本、关键性、互联网暴露情况） - CISA KEV 状态 - LLM 生成的分析字段 - 人工审查跟踪 - 时间戳（首次检测、最后发现） - 审查生命周期状态 ### 审查状态生命周期 该系统的一项关键增强功能是引入了 3 种状态的审查跟踪模型： - ``` not_required ``` → CVE 不需要分析师审查（自动接受或低风险） - ``` pending_review ``` → CVE 需要分析师验证，或 LLM 富化失败 - ``` reviewed ``` → CVE 已经由分析师手动验证 这使得扫描器能够像有状态的漏洞管理系统一样运作，而不是无状态的报告工具。 一旦发现被标记为 ```bash reviewed ```，扫描器将保留分析师输入的补充信息，并防止其被新的 LLM 输出覆盖。 ### 持久化行为 每次扫描时： - 使用 (cve_id, asset) 键检索现有发现 - 重用之前已审查的发现，而不会重新触发 LLM 分析 - 仅将新的或待处理的发现发送给 LLM 进行富化 - 使用 UPSERT 策略执行更新，以保持历史连续性 ### 核心函数 数据库层公开了以下核心函数： - ``` init_db() ```→ 初始化模式并应用安全迁移 - ``` upsert_finding() ```→ 插入或更新漏洞记录 - ``` get_finding() ``` → 检索存储的分析和审查状态以供重用 ### 设计目标 该数据库旨在： - 防止跨扫描的重复 CVE 分析 - 随时间保留分析师的决定 - 减少不必要的 LLM API 调用 - 为未来扩展到仪表板、工单系统或 SIEM 集成提供基础 ## 运行测试 ``` pytest tests/ -v ``` 仅运行配置和输入验证测试： ``` pytest tests/test_config.py -v ``` 仅运行摘要仪表板测试： ``` pytest tests/test_summary.py -v ``` 摘要测试还会验证高管摘要 PDF 的创建。 ## CI 和仓库自动化 本仓库包含用于验证和维护的 GitHub 自动化： - `CI`：在 Linux、macOS 和 Windows 上跨受支持的 Python 版本运行语法检查和完整的 pytest 套件。 - `Lint`：运行 Ruff 静态分析以捕获常见的代码质量问题。 - `Secret Scan`：运行 Gitleaks 来检测意外提交的 API 密钥、SMTP 凭证和其他机密信息。 - `Dependabot`：每周检查 Python 和 GitHub Actions 依赖项，并开启更新拉取请求。 这些工作流程有助于在合并更改之前捕获跨平台问题、依赖项问题和回归。 ## 项目结构 ``` vuln-scanner/ │ ├── .github/ │ ├── dependabot.yml # Weekly dependency update checks │ ├── pull_request_template.md # Pull request checklist │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md │ │ └── feature_request.md │ └── workflows/ │ ├── ci.yml # Cross-platform test workflow │ ├── lint.yml # Ruff lint workflow │ └── secrets.yml # Gitleaks secret scanning workflow │ ├── .env # API keys and config (never committed) ├── .env.example # Template showing required keys (committed) ├── .gitignore # Excludes .env, venv, output files, etc. ├── README.md # Setup, usage, and project overview ├── requirements.txt # All pip dependencies │ ├── assets.txt # Default simple monitored assets inventory │ ├── run_scanner.py # Entry point, run this to execute the scan │ ├── scanner/ # Core package │ ├── __init__.py # Makes scanner/ a Python package │ ├── config.py # Loads .env, defines constants (dates, paths) │ ├── nvd_client.py # All NVD API logic │ ├── cisa_client.py # CISA KEV download and lookup │ ├── llm_client.py # OpenRouter / LLM API call and prompt │ ├── excel_writer.py # openpyxl formatting, row writing, row updates │ ├── email_client.py # Optional SMTP delivery for Excel/PDF reports │ ├── summary.py # Post-scan Excel dashboard, charts, and executive PDF │ └── models.py # Dataclasses: Asset, CveEntry, LlmAnalysis, ScanResult │ ├── prompts/ │ └── analysis_prompt.txt # The LLM prompt template (externalized) | ├── docs/ # Additional project documentation │ └── outputformat.md # Notes on generated report structure and fields | └── SECURITY.md # Security policy and data-handling guidance │ ├── examples/ # Sanitized sample inventories, reports, and screenshots │ ├── sample_assets.csv │ ├── sample_cve_report.xlsx │ ├── sample_executive_summary.pdf │ └── images/ │ ├── summary_dashboard.png │ ├── cve_report.png │ ├── executive_summary_pdf.png │ └── runtime_logs.png │ ├── output/ # Default generated Excel and PDF report directory │ └── .gitkeep # Keeps folder in git without committing reports │ ├── logs/ # Default runtime log directory │ └── .gitkeep │ └── tests/ ├── __init__.py ├── test_config.py # Unit tests for configuration and input validation ├── test_nvd_client.py # Unit tests for NVD parsing ├── test_cisa_client.py # Unit tests for KEV lookup ├── test_llm_client.py # Unit tests for prompt formatting and parsing ├── test_excel_writer.py # Unit tests for Excel row generation and updates ├── test_email_client.py # Unit tests for optional SMTP report delivery ├── test_summary.py # Unit tests for dashboard tables, charts, risk scoring, and PDF output └── fixtures/ # Static sample data for tests (no real API calls) ├── sample_nvd_response.json └── sample_kev.json ``` ## 免费 LLM 说明 本项目通过 `scanner/llm_client.py` 使用 OpenRouter 的免费层级。 由于免费模型的可用性可能会发生变化，如果配置的模型变得不可用， 请从 https://openrouter.ai/models?q=free 中选择一个当前可用的免费模型， 并更新 `scanner/llm_client.py` 中的 `FREE_MODEL`。 ## 当前局限性 - 资产匹配目前是通过 NVD API 基于关键字的。这适用于扫描产品名称，但它尚未成为一个完全支持 CPE/版本识别的漏洞管理平台。 - 扫描器支持简单的文本清单、CSV 业务上下文清单以及业务上下文风险评分，但它尚未成为一个完整的 CMDB、集成 EDR 的资产数据库或支持 CPE/版本识别的漏洞管理平台。 - 邮件发送使用 SMTP 附件，并依赖于配置的提供商接受发件人、收件人、凭证和附件类型。它尚不支持将报告直接上传到 SharePoint、Teams、Jira 或工单平台。 - LLM 生成的评论被视为对分析师的辅助，而非权威的漏洞证据。NVD、CISA KEV 和供应商参考资料应始终作为补救决策的真实来源。

标签：GPT, 安全运营, 扫描框架, 漏洞管理, 自动化报告, 逆向工具