AdiMikeyHariharan/Threat-Hunting-Package

# siem-threat-hunter 一个威胁狩猎引擎，它**提取了 SIEM 的一项核心能力——检测规则引擎（如 [Wazuh](https://wazuh.com) 和厂商中立的 [Sigma](https://github.com/SigmaHQ/sigma) 标准中所包含的）——并通过三项原生规则引擎所缺乏的增强功能对其进行了强化**： 1. **MITRE ATT&CK 丰富化** —— 每一次检测都会与**完整的 ATT&CK Enterprise 矩阵**（包含 697 项技术，从官方 MITRE STIX bundle 编译而来）进行比对，解析出其技术名称和战术，从而自动将每项发现映射到杀伤链上。 2. **频率 / 阈值关联** —— Wazuh 风格的有状态规则，将众多无害的单一事件（如“一次登录失败”）转化为一条有意义的发现（如“来自某一个 IP 的暴力破解”）。 3. **统计异常猎手** —— 一个无监督的离群点检测器（基于中位数和 MAD 的修正 z 分数），能够揭示那些尚未编写签名规则的*未知*威胁。 所有流程都通过**详尽的结构化日志机制**（JSON 格式、运行关联、自动轮转）进行处理，使得整个 pipeline 自身完全可审计——这正是 SIEM 的核心意义所在。 ## 为什么这满足了作业要求 | 要求 | 如何实现 | |---|---| | 从知名的 SIEM 中提取一项功能 | `siem_hunter/rule_engine.py` 重新实现了 Sigma/Wazuh 的检测规则核心：命名选择、字段修饰符，以及一个布尔 `condition` 语言。 | | 增强它 | ATT&CK 丰富化 (`attack.py`)、有状态频率关联 (`rule_engine.py` 阈值规则) 以及统计异常猎手 (`anomaly.py`)。 | | 详尽且规范的日志 | `logging_config.py`：将结构化的 JSON 输出到轮转文件 + 可读的控制台，每次运行生成一个绑定到每一行的 `run_id`，使用 ISO-UTC 时间戳，记录模块/函数的调用位置，并带有阶段性的摘要/耗时日志。 | ## 快速开始 ``` cd siem-threat-hunter python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 分析捆绑的 auth.log 样本 python -m siem_hunter.cli \ --log sample_data/auth.log \ --rules rules \ --format syslog \ --out logs/detections.json ``` 你应该会看到 9 个发现，其中包括 SSH 暴力破解关联、一次 root 登录，以及异常猎手独立标记了同一个攻击者 IP。结构化日志会被写入到 `logs/siem_hunter.jsonl`（每行一个 JSON 对象）；检测报告会被写入到 `logs/detections.json`。 ### CLI 选项 ``` --log log file to analyse (required) --rules directory of YAML rules (default: rules) --format syslog | json (default: syslog) --out detection report path (default: logs/detections.json) --anomaly-field entity field to baseline on (default: src_ip) --log-level DEBUG | INFO | WARNING | ERROR (default: INFO) --quiet suppress console logs (file still written) ``` ## Web 仪表板 (可视化 UI) 检测结果可以在一个 **React (Vite) 仪表板**中进行可视化探索，该仪表板由一个封装了同一 Python 引擎的 **FastAPI** 服务器提供支持——引擎始终保持作为唯一的真值源；API 只是通过 HTTP 将其暴露出来。 ``` # 1. Backend（从项目根目录，venv 激活） pip install -r requirements.txt uvicorn web.backend.app:app --port 8000 # 2. Frontend（在第二个终端） cd frontend npm install npm run dev # opens http://localhost:5173 ``` 仪表板会显示 KPI 卡片（发现 / 事件 / pipeline 耗时 / 严重性分布）、按引擎组件划分的细分（签名 对比 关联 对比 异常），以及一个发现表格，其中每一行都可以展开以显示 ATT&CK 技术、关联上下文和相关事件 ID。你可以从顶部栏切换示例日志或上传你自己的日志。 API endpoints：`GET /api/analyze?source=`、`POST /api/analyze` (文件上传)、`GET /api/samples`、`GET /api/rules`、`GET /api/health`。 ## 检测目录 内置规则反映了真实 SOC 所运行的检测内容（SigmaHQ、Elastic Security、Splunk ESCU），并针对 Linux auth/syslog 和网络遥测数据进行了适配。每一条规则都与当前的 MITRE ATT&CK 技术保持一致。 | 规则 | 检测内容 | 类型 | 严重度 | ATT&CK | |---|---|---|---|---| | SSH-BRUTE-0001 | SSH 暴力破解 (多次失败，单一 IP) | correlation | High | T1110.001 | | PWD-SPRAY-0001 | 密码喷洒 (单一 IP，多个账户) | correlation | High | T1110.003 | | CRED-STUFF-0001 | 凭据填充 (单一账户，多个 IP) | correlation | High | T1110.004 | | PORT-SCAN-0001 | 端口扫描 (多个不同端口，单一 IP) | correlation | High | T1046 | | SSH-INVALID-USER-0001 | 非存在用户的登录 (枚举) | signature | Medium | T1110 | | SSH-ROOT-LOGIN-0001 | 成功的 root SSH 登录 | signature | High | T1078 | | OFFHOURS-ROOT-0001 | 业务时间外的 root 登录 | signature | High | T1078 | | PRIVGRP-0001 | 用户被添加到 sudo/wheel/admin 组 | signature | High | T1098 | | SUDO-ROOT-SHELL-0001 | 通过 sudo 获取的交互式 root shell | signature | High | T1548.003 | | ROOT-ACCOUNT-0001 | 创建了 UID=0 (等同 root) 的账户 | signature | Critical | T1136.001 | | NEW-ACCOUNT-0001 | 创建了新的本地账户 | signature | Medium | T1136.001 | | FW-DISABLE-0001 | 主机防火墙被禁用 / 清空 | signature | High | T1686 | | PASSWD-CHANGE-0001 | 本地账户密码被更改 | signature | Medium | T1098 | | SUDO-ABUSE-0001 | sudo 认证失败 | signature | Medium | T1548.003 | | ANOMALY-VOLUME-0001 | 统计型流量异常 (无签名) | anomaly | Med/High | — | 查看它们端到端的触发过程：`python -m siem_hunter.cli --log sample_data/enterprise_sim.log --rules rules`。 ## 编写规则 规则采用 [Sigma](https://github.com/SigmaHQ/sigma) 风格的 YAML。一个文件可以包含多条由 `---` 分隔的规则。 **签名规则：** ``` id: SSH-INVALID-USER-0001 title: SSH login attempt for non-existent (invalid) user level: medium # low | medium | high | critical type: detection detection: selection: program: sshd message|contains: "Invalid user" condition: selection mitre: [T1110, T1078] ``` **频率 (阈值) 规则 —— 关联增强：** ``` id: SSH-BRUTE-0001 title: SSH brute force - repeated failed logins from one source level: high type: threshold detection: selection: program: sshd message|contains: "Failed password" condition: selection group_by: src_ip threshold: count: 5 window_seconds: 60 mitre: [T1110.001, T1021.004] ``` **不同值阈值 —— 端口扫描检测：** 在阈值规则中添加 `distinct: `，它将根据*不同*值的数量（而非原始数量）触发。来自同一源对许多不同端口的连接 = 一次扫描；对同一端口的重复连接不会触发它。 ``` id: PORT-SCAN-0001 title: Port scan - many distinct ports probed from one source level: high type: threshold detection: selection: message|contains: "connection from" condition: selection group_by: src_ip threshold: count: 15 window_seconds: 10 distinct: dst_port # 15+ distinct ports in 10s from one IP mitre: [T1046] ``` **字段修饰符：** `field|contains`、`|startswith`、`|endswith`、`|re` (regex)、`|gte`、`|lte`，或者直接使用 `field:` 来表示相等。列表值表示“其中的任意一个” (OR)。 **条件语言：** 选择名称可以通过 `and` / `or` / `not`、括号，以及量词 `all of them` / `N of them` 进行组合。格式错误的条件会在加载时被拒绝，而不会在运行期间才报错。 ## 模拟真实攻击 (nmap) `scripts/simulate_scan.py` 会执行一次 **端到端** 的演示（而非合成数据）：它绑定一系列本地端口，对这些端口运行一次真实的 `nmap` 连接扫描，并记录实际的连接情况——随后引擎会将其标记为一次端口扫描。 ``` python scripts/simulate_scan.py # runs nmap vs localhost python -m siem_hunter.cli --log sample_data/portscan.log --rules rules # -> PORT-SCAN-0001 (High) 触发，映射到 T1046 Network Service Discovery ``` 仅扫描 `127.0.0.1`，因此它是完全独立且安全的。你可以随时使用 `python scripts/build_attack_map.py` 重新生成完整的 ATT&CK 查询数据。 ## 测试 ``` pip install pytest python -m pytest -q # 18 tests: parser, engine, threshold, anomaly, ATT&CK ``` ## 项目布局 ``` siem_hunter/ logging_config.py structured JSON logging setup (run_id, rotating file) models.py Event / Detection dataclasses parser.py syslog + JSON log normalisation rule_engine.py *** extracted feature *** selections, condition lang, threshold correlation attack.py MITRE ATT&CK enrichment (enhancement) anomaly.py statistical outlier hunter (enhancement) pipeline.py ingest -> detect -> hunt -> report orchestration cli.py command-line entry point rules/ bundled Sigma-style detection rules sample_data/ example auth.log with a planted attack tests/ pytest suite docs/ARCHITECTURE.md design rationale + report skeleton ```

标签：Python, 云计算, 安全规则引擎, 异常检测, 无后门, 规则引擎, 逆向工具