guado1983-star/Threat-Mapper
GitHub: guado1983-star/Threat-Mapper
ThreatMapper 是一个融合数字日志解析与物理传感器检测的威胁关联平台，通过 MITRE ATT&CK 映射和威胁评分帮助安全团队识别并响应混合型入侵行为。
Stars: 0 | Forks: 0
# ThreatMapper
一个物理-数字威胁检测与关联系统，能够解析安全事件，将它们映射到 **MITRE ATT&CK** 框架，并将数字入侵与现实世界的物理访问关联起来 —— 由 ESP32-CAM 传感器和实时 Web 仪表板驱动。
## 截图
## 功能
### 阶段 1 — 数字日志解析器
- 使用正则表达式模式匹配解析防火墙、SSH 身份验证和审计日志
- 从原始日志行中提取源 IP、用户名、端口和文件路径
- 通过 CLI 参数支持自定义日志文件路径
### 阶段 2 — 物理事件检测
- ESP32-CAM 串行网桥通过串口实时读取 JSON 事件
- 检测移动、徽章扫描、非工作时间入侵以及非法设备连接
- 输出与 threat_mapper 解析器兼容的日志行 —— 无需附加粘合代码
### 阶段 3 — MITRE ATT&CK 映射
- 每种事件类型都映射到一个 MITRE 技术 ID、名称和战术
- 涵盖 4 种战术下的 8 种技术：Credential Access、Discovery、Initial Access、Collection
- 辅助函数：`all_tactics()`、`techniques_by_tactic(tactic)`
### 阶段 4 — 关联引擎与威胁评分
- 基于规则的关联器在可配置的时间窗口内匹配物理和数字事件
- 六条关联规则生成包含 MITRE 映射和建议操作的 `CorrelatedThreat` 对象
- 评分器跨数字、物理和关联源聚合事件，生成排序后的 `ThreatScore` 对象
- 威胁等级：LOW / MEDIUM / HIGH / CRITICAL
### 阶段 5 — SOAR (Security Orchestration, Automation, and Response) *(进行中)*
- 自动响应引擎根据威胁分数阈值触发操作
- CRITICAL 威胁 → 电话警报 + 自动生成的事件报告
- HIGH 威胁 → 警报通知 + 记录建议的操作
- 可插拔的操作体系：封锁 IP、发送警报、创建报告
- 独立于硬件运行 —— 响应任何事件源（数字、物理或关联）
## MITRE ATT&CK 覆盖范围
| 事件 Key | 技术 ID | 名称 | 战术 |
|---|---|---|---|
| `SSH_LOGIN_FAILED` | T1110 | Brute Force | Credential Access |
| `PORT_SCAN` | T1046 | Network Service Scanning | Discovery |
| `HONEYFILE_ACCESSED` | T1083 | File and Directory Discovery | Discovery |
| `MOTION_DETECTED` | T0812 | Device Identification / Physical Recon | Discovery |
| `PHYSICAL_PRESENCE` | T1078 | Valid Accounts / Physical Access | Initial Access |
| `AFTER_HOURS_INTRUSION` | T0867 | Physical Intrusion | Initial Access |
| `CORRELATED_ATTACK` | T1200 | Hardware Additions | Initial Access |
| `HONEYFILE_PHYSICAL_CORRELATION` | T1074 | Data Staged / Insider Threat | Collection |
## 技术栈
| 层级 | 技术 |
|---|---|
| 核心语言 | Python 3.11+ |
| Web 框架 | FastAPI + Uvicorn |
| 模板引擎 | Jinja2 |
| 物理传感器 | ESP32-CAM |
| 固件 | Arduino (C++) |
| 串行网桥 | PySerial |
| 报告 | 纯文本 + REST JSON |
## 安装说明
**环境要求：** Python 3.11+
```
git clone https://github.com/guado1983-star/Threat-Mapper.git
cd Threat-Mapper
pip install -r requirements.txt
```
## 使用说明
### 解析日志文件
```
# 默认 sample log
python threat_mapper.py
# 自定义 log file
python threat_mapper.py logs/my_log.log
```
输出内容包括解析后的事件列表、事件类型摘要、MITRE 映射表以及排序后的威胁评分。带有时间戳的报告将保存到 `reports/` 目录下。
### 运行关联引擎
```
# Batch 模式 — 关联 sample log
python -m core.correlator
# 自定义 log 和时间窗口（秒）
python -m core.correlator --log logs/my_log.log --window 600
```
### 运行威胁评分器
```
python -m core.scorer
python -m core.scorer --log logs/my_log.log
```
### 运行 SOAR 响应器
```
# 评估 sample log 并为所有高于 LOW 的威胁编写 incident reports
python -m core.responder
# 通过 ntfy.sh 发送手机提醒（安装 ntfy app，订阅你的 topic）
python -m core.responder --ntfy-topic my-threat-alerts
# 同时通过 Windows Firewall 阻断 CRITICAL 源 IP（需要管理员权限）
python -m core.responder --ntfy-topic my-threat-alerts --block-ips
# 设置最低 alert level（默认：HIGH — 同时对 CRITICAL 发出警报）
python -m core.responder --ntfy-topic my-threat-alerts --min-alert-level CRITICAL
# 通过 environment variable 而非 flag 设置 topic
set NTFY_TOPIC=my-threat-alerts
python -m core.responder
```
SOAR 也会在每次运行 `python threat_mapper.py` 结束时自动运行，
并可通过仪表板 API `POST /api/respond` 访问。
### 运行 Web 仪表板
```
uvicorn dashboard:app --host 127.0.0.1 --port 3000 --reload
```
然后在浏览器中打开 **http://127.0.0.1:3000**。
| Endpoint | 描述 |
|---|---|
| `/` | 实时仪表板 UI |
| `/api/events` | 以 JSON 格式返回所有已解析的事件 |
| `/api/summary` | 威胁评分、事件计数和 MITRE 明细 |
| `POST /api/respond` | 触发 SOAR 响应（返回执行的操作） |
| `/api/docs` | 自动生成的 Swagger UI |
## 项目结构
```
Threat-Mapper/
├── threat_mapper.py # Log parser and CLI entry point
├── mitre_mapper.py # MITRE ATT&CK technique lookup
├── dashboard.py # FastAPI web dashboard
├── core/
│ ├── models.py # Shared dataclasses (SecurityEvent, PhysicalEvent, CorrelatedThreat, ThreatScore)
│ ├── correlator.py # Physical + digital correlation engine
│ ├── scorer.py # Aggregated threat scoring
│ └── responder.py # SOAR response engine (Phase 5)
├── esp32/
│ └── bridge.py # ESP32-CAM serial bridge
├── templates/
│ └── index.html # Dashboard frontend
├── logs/
│ └── sample_attack.log # Sample log with digital and physical events
└── reports/ # Auto-generated timestamped reports (gitignored)
```
## ESP32 硬件设置 *(即将推出)*
阶段 2 的物理检测需要通过 USB 串口连接的 **ESP32-CAM** 模块。
连接后，网桥会将物理事件与实时日志数据一起直接实时输入到关联引擎中。
## 作者
**guado1983**
- GitHub: [@guado1983-star](https://github.com/guado1983-star)
## 许可证
MIT
标签：AMSI绕过, AV绕过, FastAPI, Python, SOAR, 威胁检测, 安全运营, 扫描框架, 插件系统, 无后门, 物联网安全, 网络测绘, 逆向工具