rvong65/breach-precursor-detector

# 入侵前兆检测器 针对凭据转储和进程注入的早期行为前兆往往能绕过基于特征签名的检测。本项目基于可解释的进程特征使用无监督异常检测，结合置信度门控和人类可读的解释，以揭示高价值信号事件——其灵感来自于 CrowdStrike 风格的 EDR 遥测，以及 SOC 工作流中对可操作且低误报告警的需求。 ## 目录 **新手入门** - [在线演示](#live-demo) - [功能](#features) - [快速开始](#quick-start) **概述** - [问题与动机](#problem-motivation) - [技术栈](#tech-stack) - [数据来源与致谢](#data-sources) **技术文档** - [架构与设计决策](#architecture-design-choices) - [开发历程](#development-journey) - [安全考量](#safety-considerations) - [CI/CD](#cicd) - [项目状态与构建日志](#project-status) - [仓库结构](#repository-layout) **法律与联系** - [开源协议](#license) - [联系方式 / 后续计划](#contact) ## 🚀 在线演示 **[▶ 在 Streamlit Cloud 中打开在线应用](https://breach-precursor-detector.streamlit.app/)** （建议使用桌面浏览器） **在打开应用之前：** - **冷启动：** 本应用运行在 Streamlit Community Cloud 上，可能会在闲置后休眠。如果你看到 **“Zzzz — This app has gone to sleep due to inactivity”**，请点击 **“Yes, get this app back up!”** 将其唤醒；任何人都可以执行此操作，无需联系维护者。点击后启动可能需要一分钟时间。 - **显示：** 本应用在**浅色模式**下显示效果最佳。如果深色模式下文字难以阅读，请切换你的浏览器/系统主题，或使用右上角菜单中的 Streamlit 主题选择器。这是我们正在努力改善的已知渲染怪癖。 **本地运行：** 在项目根目录下执行：`streamlit run app.py`。如果 `output/scored_events_gated.parquet` 已存在，请使用侧边栏中的 **加载示例数据** 直接加载，无需重新运行 pipeline。 **截图：**  ## ✨ 功能 - **无监督 Isolation Forest** — 在无需标注攻击数据进行训练的情况下，基于 12 个可解释的进程特征进行异常评分 - **多源日志摄取** — 通过 [loaders/](loaders/) 将 Falcon NDJSON、Sysmon XML 和 Windows 4688 解析为统一 schema - **置信度门控** — 仅在低异常评分*且*具备强领域指标（可疑父进程、转储前兆，或 ≥2 个隐藏标志）同时满足时才对事件进行标记 - **人类可读的解释** — 为每个被标记的事件提供基于规则的、对 SOC 友好的原因字符串 - **风险等级带** — 基于异常评分的百分位数划分 Critical / High / Medium / Low / Normal - **网络安全 UI** — 深色 SOC 主题、风险徽章、“工作原理”侧边栏以及侧边栏汇总图表 - **分析师分发** — 仅显示已标记事件的主表格，具备风险等级和关键词过滤、可排序列表以及完整的命令行展开器 - **CSV 导出** — 下载过滤后的标记事件；当 `output/` 中存在阈值配置时可供使用 - **上传验证** — `.csv` / `.parquet` 扩展名检查、必需列验证以及友好的错误提示（无原始 traceback） - **示例数据工作流** — 一键加载预评分的 parquet 门控数据，适用于无需重新运行 pipeline 的演示 ## ⚡ 快速开始 ``` git clone https://github.com/rvong65/breach-precursor-detector.git cd breach-precursor-detector pip install -r requirements.txt ``` 如果 `output/scored_events_gated.parquet` 已存在（例如来自之前的 pipeline 运行），启动应用并点击侧边栏中的 **加载示例数据**： ``` streamlit run app.py ``` 否则，按顺序运行 pipeline 以生成相关产物： ``` python load_events.py --data-dir data python feature_engineering.py --data-dir data --output-dir output python train_isolation_forest.py --x-path output/X_features.parquet --output-dir output python confidence_gating.py --scored-path output/scored_events.parquet --x-path output/X_features.parquet --output-dir output streamlit run app.py ``` 然后使用 **加载示例数据** 加载 `output/scored_events_gated.parquet`。 **本地运行测试** ``` pip install -r requirements-dev.txt pytest tests/ -q ``` ## 🎯 问题与动机 基于特征签名的检测和静态指标很难捕捉到新型攻击技术和“靠山吃山”二进制文件 (LOLBAS)。基于进程创建和访问事件的行为异常检测填补了这一空白，它关注的是进程之间*如何*关联（父-子链、命令行模式、时间点），而不仅仅是运行了*什么*。 本项目专注于凭据转储和进程注入的早期前兆：不寻常的父子进程对、高命令行熵值、使用 LOLBAS，以及已知的转储相关关键词（lsass、procdump、mimikatz、ntdsutil、vssadmin）。在完全被利用之前捕捉这些行为有助于入侵防御和事件分发。 系统内置了可解释性和人工监督。置信度门控确保我们仅在异常评分和领域启发式规则同时认可时才进行标记，并且每个被标记的事件都会获得一个简短的、SOC 友好的解释。这种设计减少了告警疲劳，并让分析师留在闭环中——这是为真实安全操作提供的实用设计。 ## 🛠️ 技术栈           ## 📊 数据来源与致谢 本项目使用了来自 [Splunk Attack Data repository](https://github.com/splunk/attack_data) 的精选攻击模拟日志（Apache License 2.0）。 **使用的数据集**（来自 `datasets/attack_techniques/T1003.003/atomic_red_team/`）： | 文件 | 描述 | |------|-------------| | `crowdstrike_falcon.log` | CrowdStrike Falcon 传感器事件（来自凭据转储模拟的进程汇总、父进程、命令） | | `windows-sysmon.log` | Sysmon Event 1/8/10（进程创建、远程线程注入、进程访问） | | `4688_windows-security.log` | Windows Security Event 4688（进程创建） | **开源协议合规** - © Splunk Inc. (Apache 2.0)。与 Splunk 或 CrowdStrike 无任何隶属关系。 - 数据仅用于**教育和研究目的**。 - 完整协议：[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)。 **复现原始文件** 1. 访问 [T1003.003 atomic_red_team](https://github.com/splunk/attack_data/tree/master/datasets/attack_techniques/T1003.003/atomic_red_team)。 2. 下载上述列出的三个 `.log` 文件（GitHub **Raw** → 另存为）。 3. 将它们放置在本地 `data/` 目录中（已被 gitignored）。 ## 🏗️ 架构与设计决策 ``` flowchart TB subgraph Client["Client Layer"] U[Analyst / Demo user] UI[Streamlit UI
app.py] end subgraph Ingest["Ingestion Layer — load_events.py + loaders/"] RAW[Falcon NDJSON · Sysmon XML · 4688 XML] LOAD[Per-source parsers
falcon · sysmon · windows_security_4688] SCHEMA[Unified schema
loaders/schema.py] end subgraph Features["Feature Layer — feature_engineering.py"] PREP[Event prep
paths · pid/ppid · completeness] FEAT[12 interpretable features
entropy · LOLBAS · dump keywords] LABEL[Heuristic labels
is_attack — eval only] end subgraph Model["Model Layer — train_isolation_forest.py"] IF[Isolation Forest
contamination 0.05 · 150 estimators] SCORE[anomaly_score · is_anomaly] end subgraph Gating["Gating Layer — confidence_gating.py"] RISK[risk_level
percentile bands] STRONG[strong_indicator
parent · dump · hidden flags] FLAG[flagged = low score AND indicator] EXP[Human-readable explanations] end subgraph Artifacts["Artifact Layer — output/"] PARQ[Parquet artifacts
X_features · scored_events_gated] CFG[threshold_config.json] end subgraph Guard["Safety Layer — app.py"] VAL[Upload validation
extension · schema · types] TRIAGE[Flagged-only triage
filters · sort · CSV export] end U --> UI UI --> VAL VAL -->|sample / valid upload| TRIAGE VAL -->|invalid / empty| UI RAW --> LOAD --> SCHEMA --> PREP --> FEAT FEAT --> LABEL FEAT --> IF IF --> SCORE SCORE --> RISK FEAT --> STRONG RISK --> FLAG STRONG --> FLAG FLAG --> EXP EXP --> PARQ RISK --> CFG PARQ --> UI CFG --> UI TRIAGE --> UI ``` **Pipeline 摘要：** 原始日志（CrowdStrike Falcon NDJSON、Windows Security 4688 和 Sysmon XML）被加载和解析（[load_events.py](load_events.py), [loaders/](loaders/)）为统一的 schema（时间戳、进程映像、父映像、命令行、pid、ppid 等）。事件经过准备并送入特征工程模块（[feature_engineering.py](feature_engineering.py)），该模块生成 12 个可解释特征（例如可疑父进程、异常父子链评分、命令行熵、转储前兆关键词、隐藏/编码标志、LOLBAS 比率、进程树深度、Sysmon 访问模式）。**Isolation Forest** 会在特征矩阵上进行训练（[train_isolation_forest.py](train_isolation_forest.py)）；随后对每个事件进行评分并合并追踪列。置信度门控模块（[confidence_gating.py](confidence_gating.py)）根据评分百分位分配风险等级，定义*强指标*（可疑父进程、转储前兆或多个隐藏标志），并仅在评分低于阈值*且*强指标为真时设置 **已标记**。系统会为每一行标记的记录生成人类可读的解释。**Streamlit** 仪表板（[app.py](app.py)）允许用户上传或加载示例评分数据，按风险和关键词进行过滤、排序并下载结果。 **核心设计决策** | 决策 | 原因 | |----------|-----------| | 无监督学习 | Isolation Forest 非常适合缺乏标注攻击数据的场景；启发式标签仅用于评估和特征分析 | | 可解释的特征 | 所有 12 个特征都是可解释的（父子进程规则、熵、关键词、LOLBAS 等），以便分析师理解事件为何被评分或标记 | | 置信度门控 | 仅在异常评分低于阈值*且*至少存在一个强指标时才进行标记 — 减少误报 | | 可复现性 | Pipeline 会输出 parquet 产物和阈值配置 (JSON)，使运行过程可审计且可调整 | ### 开发历程 ``` flowchart LR A[Multi-source log ingest
Falcon · Sysmon · 4688] --> B[Feature engineering
12 interpretable features] B --> C[Isolation Forest
unsupervised scoring] C --> D[Confidence gating
risk + explanations] D --> E[Streamlit UI
SOC theme + triage] E --> F[Upload validation
schema + type checks] F --> G[Sample parquet workflow
reproducible artifacts] G --> H[Streamlit Cloud deploy
MVP] H --> I[GitHub Actions CI
offline tests] ``` ## 🛡️ 安全考量 | 原则 | 实现方式 | |-----------|----------------| | 只读操作 | 不执行阻断、隔离、终端响应或利用工具 — 仅用于分发和导出 | | 人工干预闭环 | 被标记的事件仅供调查参考；最终决定权归属分析师 | | 置信度门控 | [confidence_gating.py](confidence_gating.py) 中的 `add_flagged()` 同时要求低异常评分和 `strong_indicator()` — 减少误报警报疲劳 | | 可解释性 | 12 个可解释特征加上基于模板的解释 — 拒绝纯粹的黑盒告警 | | 上传验证 | 扩展名白名单（`.csv`, `.parquet`）；检查必需列；时间戳/pid/ppid 类型检查；在 [app.py](app.py) 中遇到无效输入时触发 `st.stop()` | | 仅模拟数据 | 公开演示使用的是 Splunk Attack Data（T1003.003 模拟）— 非实时生产环境 EDR 数据流 | | 教育用途 | 攻击模拟数据仅用于教育和研究目的（见 [数据来源](#data-sources)） | | UI 无敏感信息 | 当前的 MVP 不需要 API 密钥或凭据；pipeline 和应用仅在本地/云环境中运行 | | 供应商免责声明 | 与 Splunk、CrowdStrike 或任何商业 EDR 供应商无隶属关系 | | 分析师免责声明 | UI 中的“工作原理”与 README 阐明：在采取行动前，请结合内部遥测数据和上下文对发现进行关联分析 | ## 🔄 CI/CD GitHub Actions 会在每次推送到 `main` / `master` 分支以及 pull request 时运行： | | | |--|--| | **工作流** | `.github/workflows/tests.yml` | | **范围** | 81 个离线单元测试（特征工程、置信度门控、schema 规范化器、Falcon NDJSON 解析、Isolation Forest 辅助函数、上传验证、pipeline 冒烟测试） | | **API 密钥** | **无** — CI 不调用外部 API，也不需要 EDR凭据 | | **Python** | 在 `ubuntu-latest` 上的 3.11 和 3.12 版本 | 这是一个用于保障回归安全的 **CI pipeline**；**CD**（持续部署）在合并到默认分支时由 Streamlit Cloud 处理。 ## 📈 项目状态与构建日志 | 步骤 | 重点 | 状态 | |------|-------|--------| | 1 | 多源日志摄取（Falcon、Sysmon、4688） | ✅ | | 2 | 特征工程 — 12 个特征 + 启发式标签 | ✅ | | 3 | Isolation Forest 训练 + 评分 | ✅ | | 4 | 置信度门控 + 解释 + 阈值配置 | ✅ | | 5 | Streamlit UI + 定制 SOC 主题 | ✅ | | 6 | 上传验证 + 友好的错误交互体验 | ✅ | | 7 | parquet 示例工作流 + 可复现产物 | ✅ | | 8 | Streamlit Cloud 部署 | ✅ | | 9 | 离线测试 + GitHub Actions CI | ✅ | **当前状态：** ✅ MVP 完成 — 已上线 Streamlit Cloud 并配备 GitHub Actions CI。 ## 📁 仓库结构 ``` ├── app.py # Streamlit UI — upload, filters, triage, export ├── load_events.py # CLI: combine multi-source logs into unified events ├── feature_engineering.py # Prep, 12 features, heuristic labels, EDA, RF importance ├── train_isolation_forest.py # Train Isolation Forest, score events, evaluation plots ├── confidence_gating.py # Risk levels, gating, explanations, threshold JSON ├── loaders/ # Per-format parsers + unified schema │ ├── falcon.py # CrowdStrike Falcon NDJSON │ ├── sysmon.py # Sysmon XML (events 1/8/10) │ ├── windows_security_4688.py │ └── schema.py # Unified column mapping ├── output/ # Pipeline artifacts (parquet, threshold_config.json) ├── data/ # Raw attack simulation logs (gitignored; download separately) ├── docs/screenshots/ # README demo images ├── tests/ # Offline unit + integration tests ├── .github/workflows/tests.yml # GitHub Actions CI ├── requirements.txt # Python dependencies ├── requirements-dev.txt # Dev deps (pytest) for CI and local testing ├── pytest.ini # Pytest configuration ├── LICENSE # MIT License └── README.md # Project overview (this file) ``` ## 📄 开源协议 **MIT License** — 见 [LICENSE](LICENSE)。 数据集的致谢和协议（Splunk Attack Data，Apache 2.0）已在 [数据来源与致谢](#data-sources) 中说明。数据仅用于**教育和研究目的**。与 Splunk 或 CrowdStrike 无任何隶属关系。 ## 🤝 联系方式 / 后续计划 欢迎提供反馈、建议以及符合项目愿景的合作。 **未来可能的探索方向**（不承诺时间表）： - 集成方法（Isolation Forest + autoencoder 或局部异常因子）以实现更好的前兆覆盖 - 从实时 EDR 数据流摄取数据（例如通过 Kafka 或文件监控器） - 整合基于轻量级 LLM 的摘要生成功能，用于处理被标记的事件 - 将相同的 pipeline 应用于其他 MITRE ATT&CK 技术（进程注入 T1055、权限提升 T1548 等）

标签：Apex, EDR, Isolation Forest, Kubernetes, Streamlit, 安全, 异常检测, 机器学习, 脆弱性评估, 访问控制, 超时处理, 逆向工具