aimannurzharfan/netguard-sentinel

# NetGuard Sentinel **扫描一台主机，获取一份排序后的作战计划：每个 CVE 都按真实世界的可利用性进行评分，串联成攻击路径，并附带能第一时间阻断该路径的修复方案。** [](LICENSE) [](#quick-start) [](#quick-start) ## 功能 漏洞扫描器通常会给你一堆按 CVSS 排序的 CVE，这能告诉你一个漏洞可能有多严重，却无法说明是否真的有人在利用它。NetGuard Sentinel 会扫描主机，对每个服务进行指纹识别，并根据三个真实世界的信号对每个匹配到的 CVE 进行评分：CVSS 严重程度、EPSS 利用概率，以及 CISA 已知被利用漏洞状态。接着，一个六步 agent 流水线会将发现的问题按严重程度排序，映射到 MITRE ATT&CK，并将丰富后的数据交给 Microsoft Foundry 上的 Phi-4-mini-instruct，由其编写穿过该主机的可能攻击路径，以及为了第一时间阻断该路径而排序的针对各发现问题的修复建议。在演示主机上的结果是：Apache 2.4.49 (CVE-2021-41773，在 CISA KEV 中，EPSS ~0.97) 的排名高于那些没人利用但 CVSS 分数更高的漏洞，这正是人类分析师会做出的判断。 本项目衍生自 https://github.com/aimannurzharfan/Network-Scanner)，这是一个早期作为学习项目编写的 Python 端口扫描器。那个扫描器负责找出正在运行的服务；而 Sentinel 则决定对此采取什么行动，并内置了扫描步骤。 ## 演示  [](https://youtu.be/jJjYdlXD8PU) 截图展示了一键 localhost 扫描：三个故意设置存在漏洞的服务（Apache 2.4.49、OpenSSH 6.6.1p1、nginx 1.18.0），其中 CISA KEV 中的 Apache 漏洞被列为第 1 优先级。 ## 工作原理 六个阶段，全部自动化： 1. **端口扫描** —— 多线程 TCP 连接扫描，抓取 banner，并使用 regex 从 banner 中识别服务及版本指纹（Apache/2.4.49、SSH-2.0-OpenSSH_6.6.1p1、nginx/1.18.0 等）。 2. **漏洞信息丰富** —— 调用 `threat_intel_lookup` 工具，返回带有 CVSS 基础分数 (NVD)、EPSS 利用概率 (FIRST) 和 CISA KEV 已知被利用状态的 CVE。 3. **综合风险评分** —— 将这三个信号整合为每个 CVE 的 0-100 分数（公式见下文）。 4. **上下文优先级排序** —— 按严重程度优先对发现的问题进行排序。一个可访问且被积极利用的中危漏洞，其优先级高于一个无法访问的严重漏洞。 5. **攻击路径推理** —— 将发现的问题映射到 MITRE ATT&CK 技术，并将其串联成攻击者穿越主机的可能路径。 6. **修复方案合成** —— 编写针对各发现问题的修复建议，按第一时间阻断攻击路径的需求排序，并提供一行主机风险总结。 输出为严格的 JSON（schema 位于 `agent/schema.py`）。 ### 混合设计：确定性核心，Foundry 推理 阶段 1-3（解析、丰富、评分）始终作为确定性 Python 运行，因此 CVE 数据和综合分数始终具有权威性。当在 `.env` 中设置了 `FOUNDRY_ENDPOINT`、`FOUNDRY_MODEL_DEPLOYMENT` 和 `FOUNDRY_API_KEY` 时，阶段 4-6（排序、攻击路径推理、修复叙述）由通过 Microsoft Foundry 的 Phi-4-mini-instruct 处理。确定性流水线是在未配置 Foundry 或 Foundry 返回错误时的回退方案，因此演示绝不会中断。 Phi-4-mini-instruct 会对预先丰富的发现进行推理，返回上下文优先级排序、攻击路径叙述和针对各发现问题的修复文本。该模型无法更改 CVE 分数、捏造 CVE ID 或分配 MITRE ATT&CK 技术——这些只能来自确定性流水线。 威胁信息丰富本身在一个工具接口背后有两个可替换的后端：一个由 NVD、EPSS 和 CISA KEV 数据源构建的本地 JSON 缓存（默认），以及一个通过 AI Vector Search 查询的 Oracle 23ai 容器（`THREAT_BACKEND=oracle`）。 ### 综合评分公式 ``` composite = round(min(1, 0.30 * (cvss / 10) + 0.50 * epss + 0.20 * kev_flag) * 100) ``` CVSS 占 30%（严重程度基线）。EPSS 占 50%（真实世界的利用概率，最具预测性的信号）。KEV 占 20%（由 CISA 确认的积极利用）。一个没有已知利用的 CVSS 9.8 漏洞得分约为 29；而同样的漏洞如果在 KEV 中且 EPSS 为 0.97，则得分约为 91。 ### 网络暴露覆盖 分类流水线在综合评分后会应用一个上下文处理步骤。当扫描包含暴露数据时（存在于预置样本中，并由扫描器自动为 IP 地址添加），将触发两条规则： 1. **提升优先级**：具有 `bind_address == "0.0.0.0"` 或 `exposure == "internet"` 的敏感数据存储服务（MySQL 3306、PostgreSQL 5432、Redis 6379、MongoDB 27017）将被移至优先级列表的顶部，排在具有 CVE 评分的服务之前。无论缓存中是否存在匹配的 CVE，这些端口都是危险的。发现结果的理由会明确说明触发覆盖的原因。 2. **降低优先级**：已确认内部主机（`exposure == "internal"`）上的 SMB（端口 445）会被降低优先级。当主机无法从 Internet 访问时，横向移动的风险较低。 覆盖仅在扫描中实际存在数据时触发。没有 `exposure` 字段且没有 `bind_address` 值的扫描不会被修改。这在代码中被强制执行并由测试验证。 ### 可执行的修复命令 每个发现都包含一个 `remediation_command` 字段：一个可直接复制粘贴的单行 shell 命令，用于最紧急的修复步骤。示例： - 暴露在 0.0.0.0 上的 Redis：`sudo iptables -A INPUT -p tcp --dport 6379 -j DROP` - Apache httpd：`sudo apt-get install --only-upgrade apache2` - vsftpd 2.3.4（存在后门）：`sudo systemctl disable --now vsftpd` 该命令在 UI 中以等宽字体块的形式呈现在每个发现下。同时保留较长且人类可读的 `remediation` 文本。 ## 架构  整个流水线都在你的机器上运行。Web UI 将目标发送给 Flask 服务器，服务器会强制执行目标策略和速率限制，运行 TCP 扫描器，并将扫描 JSON 交给 agent。agent 通过 `threat_intel_lookup`（默认为本地 CVE 缓存，设置 `THREAT_BACKEND=oracle` 则使用 Oracle 23ai AI Vector Search）丰富每个服务的信息，计算综合分数，然后调用 Microsoft Foundry (Phi-4-mini-instruct) 生成攻击路径叙述和修复文本；当 Foundry 不可用时，则回退到确定性的本地流水线。你也可以通过 CLI 使用 `python -m netguard_sentinel ` 访问相同的流水线。 ## 快速开始 需要 Python 3.11 到 3.13。目前不支持 Python 3.14，因为 numpy 和 sentence-transformers 尚未提供 3.14 的 wheel。Docker Desktop 是可选的（仅用于 Oracle Layer 2 和演示目标）。 ``` git clone https://github.com/aimannurzharfan/netguard-sentinel.git cd netguard-sentinel python -m venv .venv .venv\Scripts\activate # Windows # source .venv/bin/activate # Linux/macOS pip install -r requirements.txt cp .env.example .env # 可选：设置 FOUNDRY_* 变量以进行 AI 推理（见下文）。 # 可选：如果你计划使用 Layer 2，请设置 ORACLE_PASSWORD。 # data/cache/cves.json 默认已提交，用于离线确定性演示。 # 仅当你想从 NVD/EPSS/KEV 刷新它时，才运行下面的命令。 # python -m data.fetch_cache pytest # run the test suite python -m web.server # start the UI at http://localhost:5000 ``` 构建好的 Web UI 位于 `web/dist` 中，因此不需要 Node.js 或 npm 步骤。如果要修改 UI 本身，请在 `frontend/` 中运行 `npm install && npm run build`。 ### 演示：扫描一个故意设置存在漏洞的本地目标 `docker-compose.demo.yml` 会在 localhost 上启动三个故意设置旧版本的服务，每个服务都有自己的端口并绑定到 `127.0.0.1`，因此在本机之外无法访问。一次扫描即可显示跨越三个服务的三个包含 CVE 的发现，并按严重程度排序。Apache CISA KEV 漏洞保持在第 1 优先级，位于 OpenSSH 和 nginx 发现之上。每个 banner 报告的都是受其匹配 CVE 影响的真实版本，因此演示仅使用真实的漏洞数据（实时的 NVD CVSS、FIRST EPSS、CISA KEV）。 | 服务 | 镜像 | 端口 | Banner 报告 | CVE | | --- | --- | --- | --- | --- | | Apache httpd | `httpd:2.4.49` | 8080 | `Apache/2.4.49` | CVE-2021-41773, CVE-2021-42013 (CISA KEV) | | OpenSSH | `rastasheep/ubuntu-sshd:14.04` | 22 | `OpenSSH_6.6.1p1` | CVE-2023-38408, CVE-2016-0777 | | nginx | `nginx:1.18.0` | 80 | `nginx/1.18.0` | CVE-2021-23017 | ``` docker compose -f docker-compose.demo.yml up -d python -m netguard_sentinel 127.0.0.1 --ports 22,80,8080 ``` 或者打开 http://localhost:5000，将主机保留为 `127.0.0.1`，然后点击 **Scan**。结果会在几秒钟内出现，显示按优先级排序的所有三个发现。每个发现仅列出其自身产品的 CVE（扫描器基于精确的产品键进行匹配，因此查询 Apache 绝不会返回 Apache Struts 的 CVE）。 ### CLI 用法 使用一条命令完成扫描和分类： ``` python -m netguard_sentinel 127.0.0.1 python -m netguard_sentinel 127.0.0.1 --ports 22,80,8080 # exactly the demo ports ``` 仅扫描（输出原始扫描 JSON）： ``` python -m scanner.scan 127.0.0.1 python -m scanner.scan 127.0.0.1 --ports 80,8080 --out scan.json ``` 仅分类：启动 `python -m web.server`，然后使用 `{"scan": ""}` POST 到 `/triage`。 ### 启用 Foundry 推理 在 `.env` 中设置三个变量： ``` FOUNDRY_ENDPOINT=https://.services.ai.azure.com/api/projects//openai/v1 FOUNDRY_MODEL_DEPLOYMENT=Phi-4-mini-instruct FOUNDRY_API_KEY= ``` `FOUNDRY_PROJECT_ENDPOINT` 也可作为回退方案被接受——客户端会自动附加 `/openai/v1`。设置这些变量后，`triage()` 会将丰富后的发现发送给 Phi-4-mini-instruct 以进行第 4-6 阶段，并在出现任何错误时回退到确定性流水线。 ### 切换威胁后端 ``` # Layer 1（默认）：从 data/cache/cves.json 读取 THREAT_BACKEND=cache python -m web.server # Layer 2：Oracle 23ai AI Vector Search # 首先启动 Oracle：docker compose up -d # 加载知识：python -m data.load_oracle THREAT_BACKEND=oracle python -m web.server ``` Oracle 默认设置：用户 `system`，DSN `localhost:1521/FREEPDB1`。只需在 `.env` 中设置 `ORACLE_PASSWORD` 即可。 ## 预期用途与免责声明 - NetGuard Sentinel 是为 Microsoft Agents League 黑客松 (AI Skills Fest 2026) 构建的，作为一个演示和教育项目。 - 本项目按“原样”提供，不提供任何形式的保证。不适用于生产环境的安全运营。 - 这是一个安全扫描工具。请仅针对你拥有或获得明确授权测试的系统运行它。未经授权的扫描在你的司法管辖区可能是非法的。 - 扫描器默认仅限 localhost 和私有 (RFC1918) 地址段。扫描公共目标需要设置显式的 `ALLOW_PUBLIC_TARGETS` 标志，这样做完全是用户自身的责任。 简短版本请参阅 [NOTICE.md](NOTICE.md)，MIT 许可证文本请参阅 [LICENSE](LICENSE)。 ### 安全态势 NetGuard Sentinel 是一个本地工具，不是托管服务，并且设计上不包含任何身份验证层。 - **默认拒绝扫描目标。** 扫描器和 `/scan` 端点仅接受解析为 localhost 或 RFC1918 私有范围（`10/8`、`172.16/12`、`192.168/16`、loopback）的目标。主机会经过验证，通过 DNS 解析，并且解析后的 IP 会根据策略重新检查，因此公共名称无法通过映射到内部地址而混水摸鱼。公共目标会被拒绝并返回明确消息。要扫描你已获授权测试的公共主机，请设置 `ALLOW_PUBLIC_TARGETS=1`；只要该标志处于活动状态，就会记录一条单行的授权使用警告。 - **仅 Socket 扫描。** 探测使用普通的 TCP 连接和 banner 读取。没有任何用户输入会到达 shell，并且扫描路径中没有任何地方使用 `subprocess` 或 `os.system`。扫描在有限的并发度和每连接 socket 超时的限制下运行，因此扫描不会挂起或耗尽资源。 - **速率限制。** 默认情况下，`/scan` 限制为每个客户端每分钟 10 个请求，可通过 `SCAN_RATE_LIMIT` 配置。超过限制将返回 HTTP 429。限制器在进程内运行，无外部依赖。 - **服务器加固。** 默认关闭 Flask debug 模式，请求体限制在 1 MB 以内，错误响应是通用的且不包含堆栈跟踪，未启用 CORS，并且响应包含 `X-Content-Type-Options: nosniff`、`X-Frame-: DENY` 和 `Referrer-Policy: no-referrer`。 - **密钥。** 不提交任何密钥。`.env`、`.mcp.json`、`_local/`、`.claude/` 和 `node_modules/` 已被 gitignored；`.env.example` 仅包含占位符。 localhost 演示之所以能开箱即用，是因为 `127.0.0.1` 满足默认策略。 ## 技术栈 | 层级 | 技术 | | --- | --- | | AI 推理 | Microsoft Foundry 上的 Phi-4-mini-instruct (Azure AI Foundry, 兼容 OpenAI 的 API) | | 威胁数据 | NVD (CVSS), FIRST EPSS, CISA KEV | | 向量搜索 (Layer 2) | Oracle Database 23ai AI Vector Search, sentence-transformers embeddings | | 后端 | Python 3.11+, Flask | | 扫描器 | Python 标准库 sockets (TCP 连接, banner 抓取) | | 前端 | React 19, TypeScript, Vite, Tailwind CSS | | 测试和工具 | pytest, ruff, ty, ESLint | ## 仓库结构 ``` scanner/ TCP connect scanner, banner fingerprinting netguard_sentinel/ End-to-end CLI entry point agent/ Six-step triage pipeline, output schema, Foundry client tools/ threat_intel tool, composite scoring, Oracle backend data/ NVD/EPSS/KEV fetcher, Oracle loader, embedding module samples/ Three scan files: badly exposed / moderate / clean frontend/ React SPA source (built output ships in web/dist) web/ Flask server and the built SPA tests/ Unit and integration tests docs/ Architecture diagram and demo screenshot ``` ## 许可证 MIT，详见 [LICENSE](LICENSE)。版权所有 (c) 2026 Aiman Nurzharfan。

标签：CISA项目, CVE漏洞分析, Microsoft Foundry, Oracle 23ai, 云存储安全, 威胁情报, 安全修复建议, 开发者工具, 插件系统, 漏洞优先级评估, 网络扫描, 请求拦截, 逆向工具