Marckevf/mangekyo-cli
GitHub: Marckevf/mangekyo-cli
结合 Nmap 扫描与多源威胁情报，利用机器学习模型为每台主机生成可解释的风险优先级评分的命令行工具。
Stars: 3 | Forks: 0
# mangekyo-cli
攻击面侦察与 ML 风险评分。
Mangekyo 接收 Nmap 扫描结果，结合 NVD、EPSS、CISA KEV 和 MITRE ATT&CK 对每个开放端口进行 enrichment，然后通过训练好的 Random Forest 处理结果，在几秒钟内免费为你提供每个主机的优先级排序和可解释的风险评分，且没有任何黑盒操作。
## 功能说明
- 使用 Nmap 扫描目标或导入现有的 Nmap XML 文件
- 查询 NVD 以获取每个检测到的服务版本的 CVSSv3 分数
- 使用 EPSS（来自 [FIRST.org](https://www.first.org/epss/) 的漏洞利用概率）和 CISA KEV（来自 [CISA](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) 的野外确认利用情况）对每个 CVE 进行 enrichment
- 通过三层映射器将 CVE 映射到 MITRE ATT&CK 技术：直接 STIX bundle 查找 → 精选的 KEV 补充 → 通过实时 NVD 进行 CWE 回退
- 使用 Random Forest 代理模型对每台主机进行 0–100 评分（在真实的 5 折 CV 中 R² 为 0.9963）
- 使用 SHAP 解释每个分数 — 明确指出是哪些信号推动了风险以及推动了多少
- 在模型分数之上应用可选的 YAML 定义策略规则（绝不会覆盖模型分数）
- 输出终端表格或整洁的 JSON，供下游 pipeline 使用
## 前置条件
- Python 3.11+
- 已安装 [Nmap](https://nmap.org/download.html) 并将其添加到你的 PATH 中
- 一个 [NVD API key](https://nvd.nist.gov/developers/request-an-api-key)（免费，申请约需 30 秒）
## 安装
### Docker（推荐 Windows/Linux 使用）
```
docker pull ghcr.io/marckevf/mangekyo-cli:latest
docker run --rm -it \
-e NVD_API_KEY=your_key_here \
-v ~/.mangekyo:/root/.mangekyo \
ghcr.io/marckevf/mangekyo-cli:latest \
mangekyo explain 45.33.32.156
```
该卷挂载会在多次运行之间持久化你的 NVD 缓存和配置。`model.pkl` 已内置在镜像中 — 无需单独下载。
多平台镜像（linux/amd64, linux/arm64）— 已测试并确认可在 Windows 和 Apple Silicon（M 系列）Mac 上通过 Docker 和原生安装方式正常运行。
### 从源码安装
```
git clone https://github.com/Marckevf/mangekyo-cli
cd mangekyo-cli
# Mac/Linux
python -m venv venv && source venv/bin/activate
# Windows
python -m venv venv && venv\Scripts\activate
pip install -e .
```
将 `.env.example` 复制到 `.env` 并添加你的 NVD API key：
```
NVD_API_KEY=your_key_here
```
从[最新的 GitHub Release](https://github.com/Marckevf/mangekyo-cli/releases/latest) 下载 `model.pkl` 并将其放置在项目根目录中。
## 使用说明
### `mangekyo scan`
运行实时 Nmap 扫描并立即对每台主机进行评分。
```
mangekyo scan 192.168.1.0/24
mangekyo scan example.com --top 5
mangekyo scan 10.0.0.1 --output json
```
### `mangekyo score`
对现有的 Nmap XML 文件进行评分。当你已经有扫描输出，或者需要使用自定义 flags 或提升的权限单独运行 Nmap 时，请使用此命令。
```
mangekyo score scan.xml
mangekyo score scan.xml --top 10 --all-cves
mangekyo score scan.xml --output json > results.json
```
### `mangekyo explain`
针对单台主机运行实时 Nmap 扫描，并生成完整的风险分解报告 — 包括带有端口归属的 CVE、SHAP 驱动因素、ATT&CK 技术以及置信度分解。
```
mangekyo explain 45.33.32.156
mangekyo explain scanme.nmap.org --all-cves
# 从现有的 XML 文件进行解释，而不是实时扫描
mangekyo explain --from-xml scan.xml 45.33.32.156
```
## Flags
| Flag | 命令 | 描述 |
|------|----------|-------------|
| `--output json` | scan, score | 机器可读的 JSON 输出 |
| `--top N` | scan, score | 仅显示 N 个风险最高的主机 |
| `--no-color` | all | 纯文本输出，不带 ANSI 代码 |
| `--all-cves` | score, explain | 显示所有 CVE，而不是按 EPSS 排序的前 10 个 |
| `--version-intensity {0-9}` | scan, explain | Nmap 服务检测强度（默认：5）。值越高速度越慢，但在扫描条件不利时成功的可能性更大。 |
| `--from-xml FILE` | explain | 从现有的 Nmap XML 加载主机，而不是进行实时扫描 |
| `--version` | — | 打印版本并退出 |
## 输出
### 终端（默认）
```
HOST RISK TIER CONFIDENCE OPEN PORTS
45.33.32.156 100.0 CRITICAL HIGH (90) 22,80,9929,31337
192.168.1.105 74.0 HIGH MEDIUM (61) 22,80,443
192.168.1.1 31.0 LOW HIGH (88) 22,80
Scanned 3 host(s) | CRITICAL: 1, HIGH: 1, MEDIUM: 0, LOW: 1 | 12s
```
### 风险层级
| 层级 | 分数范围 |
|------|-------------|
| CRITICAL | 90–100 |
| HIGH | 70–89 |
| MEDIUM | 40–69 |
| LOW | 0–39 |
### 置信度评分
每台主机都会获得一个置信度分数（0–100），该分数分为三个子分数，这些子分数会根据数据质量动态下降：
| 子分数 | 最大值 | 衡量内容 |
|---|---|---|
| CPE 匹配 | 30 | 是否所有服务都使用有效的 CPE 字符串进行了标识 |
| 威胁情报 | 50 | NVD 和 EPSS 是否为所有 CPE 返回了数据 |
| 版本数据 | 20 | Nmap 是否检测到了所有服务的版本字符串 |
当覆盖率较差时，会出现内联警告，因此你始终知道该对该分数给予多少信任。
### `mangekyo explain` 详情
```
HOST: 45.33.32.156 (scanme.nmap.org)
RISK SCORE : 100.0 CRITICAL
CONFIDENCE : HIGH (90/100)
CPE Match 30/30
Threat Intel 50/50
Version Data 10/20 — Partial version coverage — CVE matches broader than ideal.
OPEN PORTS : 22,80,123,31337
TOP SIGNALS : KEV + EPSS 100.0 + NVD 9.8
RISK DRIVERS
[+17.7] max_epss_score Exploitation probability 100.0 — actively exploited in the wild
[+16.4] max_nvd_score Max CVSS 9.8 — critical severity
[+2.1 ] kev_port_count 4 ports have CISA KEV-confirmed CVEs
[+1.3 ] mean_nvd_score Average CVSS 4.9 across all services
[+0.6 ] unique_service_count 3 distinct services detected
CVES FOUND: 120 total (showing top 10 by exploitation probability)
----------------------------------------------------
CVE-2021-40438 [KEV ✓ EPSS 100.0] → 80/tcp
CVE-2024-38475 [KEV ✓ EPSS 100.0] → 80/tcp
CVE-2021-44790 [EPSS 97.1] → 80/tcp
...
+ 110 lower-priority CVEs not shown (use --all-cves to see complete list)
ATT&CK MAPPINGS (8 of 120 CVEs mapped)
----------------------------------------------------
Initial Access
T1190 Exploit Public-Facing Application [Tier 2]
CVE-2021-40438 [KEV ✓ EPSS 100.0]
Mitigations: M1016, M1026, M1030, M1035, M1037
Privilege Escalation
T1068 Exploitation for Privilege Escalation [Tier 3 (CWE-787 Out-of-bounds Write)]
CVE-2006-20001 [EPSS 3.5]
Mitigations: M1019, M1038, M1048, M1050, M1051
```
### JSON 输出
```
{
"hosts": [
{
"host": "45.33.32.156",
"risk_score": 100.0,
"tier": "CRITICAL",
"confidence": "HIGH",
"confidence_score": 90,
"open_ports": [22, 80, 9929, 31337],
"cve_count": 120,
"cve_by_port": {
"80/tcp": ["CVE-2021-40438", "CVE-2024-38475", "..."],
"22/tcp": ["CVE-2023-38408", "..."]
},
"top_signals": ["KEV + EPSS 100.0 + NVD 9.8"],
"shap_top": [
{"feature": "max_epss_score", "shap": 17.7, "value": 100.0, "direction": "up"},
{"feature": "max_nvd_score", "shap": 16.4, "value": 9.8, "direction": "up"}
],
"attack_techniques": [
{"cve_id": "CVE-2021-40438", "technique_id": "T1190",
"technique_name": "Exploit Public-Facing Application", "tactic": "Initial Access"}
],
"policy_override": null
}
],
"summary": {
"total_hosts": 1,
"tier_counts": {"CRITICAL": 1, "HIGH": 0, "MEDIUM": 0, "LOW": 0},
"highest_risk": {"host": "45.33.32.156", "risk_score": 100.0, "tier": "CRITICAL"}
}
}
```
当置信度较低且覆盖率不足时（参见上文网络注意事项），JSON 输出将包含一个额外的 `scan_quality_note` 字段，解释可能的原因并建议后续步骤。当覆盖率足够时，将完全省略此字段。
```
{
"confidence_score": 0,
"scan_quality_note": "Low confidence may reflect scan conditions (network variability or target-side rate limiting) rather than a genuinely low-risk host. Consider re-running the scan or trying --version-intensity 7-9."
}
```
## 策略规则 (`mangekyo.yaml`)
在项目根目录中创建一个 `mangekyo.yaml` 来定义自定义风险规则。规则在模型评分**之后**应用 — 它们从不修改底层风险分数，仅影响显示的层级。
```
rules:
- name: "RDP always critical"
type: force_tier
port: 3389
tier: CRITICAL
- name: "Any database exposed"
type: min_tier
service: mysql
tier: HIGH
- name: "Suppress internal monitoring"
type: suppress
cidr: 10.0.0.0/8
performance:
max_tier3_mappings: 5 # Max live NVD CWE lookups per run (default: 5)
```
当规则触发时，输出会记录发生的变化及原因：`policy_override: {rule: 'RDP always critical', original_tier: 'HIGH', forced_tier: 'CRITICAL'}`。
## 性能
| 场景 | 时间 |
|----------|------|
| 首次运行，冷缓存 | 22–85 秒（取决于 NVD） |
| 热缓存 | ~10 秒 |
冷缓存时间取决于未缓存 CPE 的 NVD API 延迟 — 无论客户端配置如何，某些 CPE 的 NVD 服务器端查询时间都会超过 10 秒。在同一 CPE 上的后续运行会命中本地 SQLite 缓存（7 天 TTL），并且几乎是瞬时的。
**如果没有 NVD API key**，请求将被限制为每 30 秒 5 次（有 key 则为 50 次）。针对大量 CVE 目标的运行速度将明显变慢。请在 [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) 获取免费 key。
## 网络注意事项
实时扫描（`scan` 和 `explain`）取决于 Nmap 能否针对其发送的每个服务探测及时收到目标的响应。对于任何实时目标 — 尤其是像 `scanme.nmap.org` 这样的共享公共测试主机 — 由于网络状况、目标端的速率限制或激进的扫描时序（`-T4`），每次运行的结果可能会有所不同。
在测试中，针对同一目标的相同命令在重复运行中产生了不同的结果：有时是完整的服务版本和 CVE 数据，有时则是零个已识别的服务。这是针对共享的、被频繁扫描的公共目标进行主动网络扫描时的预期行为 — 并不是 Mangekyo 中的 bug。当发生这种情况时，Mangekyo 的置信度层会如实报告（低置信度、覆盖率不足警告），而不是将不确定的结果作为确认的发现呈现出来。
如果你看到 `CPE Match 0/30` 或较低的版本数据分数，并伴有 `[!] Some services could not be identified` 警告：
```
mangekyo explain --version-intensity 7
```
从 7 开始而不是直接跳到 9 — 强度越高，发送的探测越多，这在条件不利时会有所帮助，但同时也会显著减慢速度。如果结果仍然不一致，请尝试重新运行扫描，或者使用 `--from-xml` 加载单独生成的扫描文件。
这是主动网络扫描的一般特征，并非 Mangekyo 特有 — 它会影响任何基于 Nmap 构建的工具。
## 威胁情报来源
| 来源 | 提供的内容 | 使用方式 |
|--------|-----------------|---------------|
| [NVD](https://nvd.nist.gov/) | CVSSv3 严重性分数 | 占公式权重的 60%；本地缓存（7 天 TTL） |
| [FIRST.org EPSS](https://www.first.org/epss/) | 利用概率 (0–1) | 占公式权重的 20% |
| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | 野外确认利用情况 | 每台主机上每个 KEV CVE 增加 15.0 奖励分 |
| [MITRE ATT&CK](https://attack.mitre.org/) | 对手技术映射 | 三层映射器：STIX → KEV 补充 → CWE 回退 |
## 模型工作原理
Mangekyo 使用 **Random Forest 代理模型** — 一个训练用于重现确定性四信号评分公式的模型：
```
risk = (nvd_risk × 0.60) + (base_risk × 0.15) + (epss × 0.20) + (kev_bonus × 15.0)
```
该模型从 17,113 行带标签的训练数据中学习此公式。R² 0.9963 意味着它能以近乎完美的保真度重现该公式。在留出测试集上，模型的 R² 得分为 0.9975。这并不意味着被评分为 CRITICAL 的主机中有 99.63% 会被攻破。
ML 层的存在是为了让 SHAP 能够解释是什么信号推动了每个分数。如果没有它，该工具将只是一个没有任何可解释性的加权和。有了它，你就能确切地看到哪个特征改变了结果以及改变了多少。
所有信号均来自权威来源。没有任何数据是凭空捏造的。
## 环境变量
| 变量 | 描述 |
|---|---|
| `NVD_API_KEY` | NVD API key — 将速率限制从每 30 秒 5 次请求提高到 50 次 |
| `MANGEKYO_HOME` | 覆盖数据目录（模型、缓存、配置） |
| `MANGEKYO_DEBUG` | 设置为 `1` 以在出错时获取完整的 traceback |
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
*献给我的表兄弟，Tony Chery。带着爱。*
标签：Apex, CTI, LSASS转储, 插件系统, 攻击面测绘, 机器学习, 请求拦截, 逆向工具