zmaniyar/ueba-lite
GitHub: zmaniyar/ueba-lite
一个轻量级开源的用户与实体行为分析流水线，结合规则、统计和机器学习三种方法在认证日志中检测内部威胁，提供可解释告警和交互式仪表板。
Stars: 0 | Forks: 0
# UEBA-Lite
一个轻量级的**用户与实体行为分析 (UEBA)** 流水线，通过结合使用基于规则、统计和监督式 ML 方法，在身份验证日志中检测内部威胁和账户被盗用情况。
## 为什么会有这个项目
商业 UEBA 工具（Splunk UBA、Exabeam、Securonix）的成本高达六位数，并且作为黑盒运行。**UEBA-Lite** 是一个透明、开源的实现，可以在笔记本电脑上运行，能够接入真实的身份验证日志，并向分析师展示*为什么*每条异常会被标记。
它的代码量足够小，一个下午就能读完；准确性也足够高，能在公开的基准数据集中发现真实的攻击；而且具有极佳的可解释性，每个警报都会附带人类可读的原因。
## 它的功能
- **接入**以下两种来源之一的身份验证日志：
- **真实模式**：解析来自 MACCDC 2012（中大西洋大学网络防御竞赛）数据集中的 `auth.log`
- **合成模式**：生成带有注入攻击场景的逼真 SSH/sudo/文件访问事件
- **构建行为特征**（按每个用户 × 每小时）：失败登录次数、登录失败率、唯一源 IP 数、新 IP 标志、非工作时间活动、文件访问量、sudo 命令频率
- **并行运行三种检测器**并如实进行对比：
| 方法 | 类型 | 优点 | 缺点 |
|---|---|---|---|
| 基于规则 | 固定阈值 | 精确度完美，零误报 | 会漏掉新型的多信号攻击 |
| Z-score | 单特征统计偏差 | 召回率完美，能捕捉所有异常 | 误报率较高——需要分析师进行甄别 |
| Isolation Forest | 基于树的无监督 ML | 平衡性好，无需标签 | 对特征集和 contamination 参数敏感 |
- **生成带有特征级解释的排名警报**（例如：_"高失败登录次数；来自新的/未见过的 IP 登录；在非工作时间活动"_）
- **通过 Streamlit 仪表板公开所有内容**以进行交互式甄别
## 快速开始
```
git clone https://github.com/zmaniyar/ueba-lite.git
cd ueba-lite
pip install -r requirements.txt
# 端到端合成数据 + 启动 dashboard
python run.py
# 或使用真实 MACCDC 2012 auth.log
python run.py --mode real
# 跳过 dashboard 启动
python run.py --no-ui
```
仪表板将在 `http://localhost:8501` 上打开。
## 系统架构
```
flowchart LR
A[Raw Logs
auth.log or synthetic] --> B[Ingest
parse + clean] B --> C[Feature Engineering
per-user × per-hour] C --> D{Anomaly Detection} D --> E[Rule-Based
fixed thresholds] D --> F[Z-Score
statistical] D --> G[Isolation Forest
unsupervised ML] E --> H[Ranked Alerts
+ explanations] F --> H G --> H H --> I[Markdown Report] H --> J[Streamlit Dashboard] ``` ## 示例结果 在 MACCDC 2012 数据集上运行（13,816 个事件，538 个用户，1 个月的活动）： | 指标 | 值 | |---|---| | 分析的总时间窗口 | 5,506 | | 发现的 Z-score 异常 | 65 | | Isolation Forest 异常 | 56 | | 基于规则的警报（高召回率，原始） | 4,000 | 顶部警报示例（自动生成解释）： 完整的示例报告位于 [`outputs/report.md`](outputs/report.md)。 ## 威胁模型 该流水线旨在捕捉三大类攻击模式： | 威胁 | 攻击模式 | 主要检测信号 | |---|---|---| | **暴力破解登录** | 10 分钟内失败登录 50 次以上 | `fail_login_count` z-score | | **账户被盗用** | 来自新 IP 的非工作时间登录 | `new_ip_flag` + `off_hours_flag` | | **数据窃取** | 一小时内读取 200 个以上文件 | `file_access_count` z-score | ## 技术栈 - **Python 3.10+** 与 pandas、NumPy - **scikit-learn** — Isolation Forest、RobustScaler - **Streamlit** — 交互式仪表板 - **Plotly** + seaborn + matplotlib — 可视化 - **Faker** — 合成事件生成 ## 仓库结构 ``` ueba-lite/ ├── src/ │ ├── config.py Thresholds, paths, hyperparameters │ ├── ingest.py Synthetic-mode entry point │ ├── ingest_authlog.py Real-mode parser for auth.log (MACCDC 2012) │ ├── generate_data.py Synthetic event generator with injected attacks │ ├── features.py Per-user × per-hour feature engineering │ ├── model.py Three anomaly detectors + composite scoring │ └── report.py Markdown report generator ├── dashboard/ │ └── app.py Streamlit UI ├── outputs/ Sample alerts.csv + report.md ├── data/ Sample raw + processed data ├── run.py End-to-end orchestration ├── requirements.txt └── README.md ``` ## 局限性及改进方向 - **概念漂移**——用户行为会随时间改变；基线应该每月重新训练。 - **冷启动**——新用户没有行为历史；基于规则的检测器可在第一周作为备用方案。 - **对抗性规避**——有耐心的攻击者可以保持在每小时的阈值之下（低速缓慢的数据窃取）。多窗口 LSTM 模型可以弥补这一缺陷。 - **缺乏正式评估**——需要在带有标签的数据集（Zenodo UEBA 或 CERT Insider Threat）上测试 ROC/PR 曲线，以量化精确率/召回率。 - **同级群体比较**——目前是将每个用户与全局总体进行比较。与基于角色的同级群体进行比较（例如开发人员与财务人员）将大幅减少误报。 - **容器化**——打包为 Docker 镜像将使其能够部署到真实的 SOC 流水线中。 ## 致谢 - **MACCDC 2012 数据集** — [SecRepo](https://www.secrepo.com/maccdc2012/)（NSA 网络防御演习流量的公共镜像） - **Faker** 用于合成事件生成 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 由 **Zaid Maniyar** 构建 • [GitHub](https://github.com/zmaniyar) • [LinkedIn](https://linkedin.com/in/zmaniyar)
auth.log or synthetic] --> B[Ingest
parse + clean] B --> C[Feature Engineering
per-user × per-hour] C --> D{Anomaly Detection} D --> E[Rule-Based
fixed thresholds] D --> F[Z-Score
statistical] D --> G[Isolation Forest
unsupervised ML] E --> H[Ranked Alerts
+ explanations] F --> H G --> H H --> I[Markdown Report] H --> J[Streamlit Dashboard] ``` ## 示例结果 在 MACCDC 2012 数据集上运行（13,816 个事件，538 个用户，1 个月的活动）： | 指标 | 值 | |---|---| | 分析的总时间窗口 | 5,506 | | 发现的 Z-score 异常 | 65 | | Isolation Forest 异常 | 56 | | 基于规则的警报（高召回率，原始） | 4,000 | 顶部警报示例（自动生成解释）： 完整的示例报告位于 [`outputs/report.md`](outputs/report.md)。 ## 威胁模型 该流水线旨在捕捉三大类攻击模式： | 威胁 | 攻击模式 | 主要检测信号 | |---|---|---| | **暴力破解登录** | 10 分钟内失败登录 50 次以上 | `fail_login_count` z-score | | **账户被盗用** | 来自新 IP 的非工作时间登录 | `new_ip_flag` + `off_hours_flag` | | **数据窃取** | 一小时内读取 200 个以上文件 | `file_access_count` z-score | ## 技术栈 - **Python 3.10+** 与 pandas、NumPy - **scikit-learn** — Isolation Forest、RobustScaler - **Streamlit** — 交互式仪表板 - **Plotly** + seaborn + matplotlib — 可视化 - **Faker** — 合成事件生成 ## 仓库结构 ``` ueba-lite/ ├── src/ │ ├── config.py Thresholds, paths, hyperparameters │ ├── ingest.py Synthetic-mode entry point │ ├── ingest_authlog.py Real-mode parser for auth.log (MACCDC 2012) │ ├── generate_data.py Synthetic event generator with injected attacks │ ├── features.py Per-user × per-hour feature engineering │ ├── model.py Three anomaly detectors + composite scoring │ └── report.py Markdown report generator ├── dashboard/ │ └── app.py Streamlit UI ├── outputs/ Sample alerts.csv + report.md ├── data/ Sample raw + processed data ├── run.py End-to-end orchestration ├── requirements.txt └── README.md ``` ## 局限性及改进方向 - **概念漂移**——用户行为会随时间改变；基线应该每月重新训练。 - **冷启动**——新用户没有行为历史；基于规则的检测器可在第一周作为备用方案。 - **对抗性规避**——有耐心的攻击者可以保持在每小时的阈值之下（低速缓慢的数据窃取）。多窗口 LSTM 模型可以弥补这一缺陷。 - **缺乏正式评估**——需要在带有标签的数据集（Zenodo UEBA 或 CERT Insider Threat）上测试 ROC/PR 曲线，以量化精确率/召回率。 - **同级群体比较**——目前是将每个用户与全局总体进行比较。与基于角色的同级群体进行比较（例如开发人员与财务人员）将大幅减少误报。 - **容器化**——打包为 Docker 镜像将使其能够部署到真实的 SOC 流水线中。 ## 致谢 - **MACCDC 2012 数据集** — [SecRepo](https://www.secrepo.com/maccdc2012/)（NSA 网络防御演习流量的公共镜像） - **Faker** 用于合成事件生成 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 由 **Zaid Maniyar** 构建 • [GitHub](https://github.com/zmaniyar) • [LinkedIn](https://linkedin.com/in/zmaniyar)
标签：IAM, Isolation Forest, Kubernetes, Python, SSH安全, Streamlit, sudo审计, UEBA, Z-score, 内部威胁检测, 基于规则检测, 孤立森林, 安全分析管道, 安全运营, 开源安全工具, 异常检测, 扫描框架, 数据科学, 无后门, 无监督机器学习, 日志解析, 特征工程, 用户与实体行为分析, 统计分析, 网络安全, 认证日志分析, 访问控制, 证书伪造, 账号被盗检测, 资源验证, 身份与访问管理, 逆向工具, 逆向工程平台, 隐私保护