Lordsofzzzz/Behavioral-Threat-Hunting
GitHub: Lordsofzzzz/Behavioral-Threat-Hunting
一款基于日志的模式与行为双驱动威胁狩猎工具，专注于实时检测与可解释告警。
Stars: 0 | Forks: 2
# 行为威胁狩猎 - 日志哨兵
日志哨兵（Log Sentinel）是一款轻量级、实时的 Nginx 风格访问日志监控工具。它使用模式规则、速率限制和 404 垃圾信息启发式检测常见的 Web 攻击，并可选择在检测到威胁时提供实时仪表板以展示告警与统计信息。
## 功能特性
- 检测 SQL 注入、XSS、路径遍历与命令注入
- 标记已知扫描器的 User-Agent
- 对每个 IP 进行速率限制与 404 垃圾信息检测
- 控制台告警与基于文件的告警日志记录
- 可选仪表板（提供 API 端点）
- 对常见 Nginx 日志变体具备健壮的解析能力
- 重复告警抑制以减少噪音告警
- 动态风险评分（0-100）与基于分数的严重等级
- 行为异常检测（新端点、新用户代理、请求突增）
- 可解释的告警（附带机器可读的原因代码）
- 事件关联（将相关告警聚合成类似事件的活动）
## 发布亮点（2026 年 2 月）
- 通过配置验证、路径标准化、去重和基于分数的严重等级加固检测管道。
- 新增行为异常智能检测，并在每个增强告警中提供可解释的原因代码。
- 新增事件关联（`/api/incidents`）与仪表板事件面板，加快分析师分诊速度。
- 新增可复现的评估框架，支持学术指标（精确率、召回率、F1、延迟、吞吐量、内存）。
- 新增一键式 Docker 演示堆栈（`sentinel`、`dashboard`、`simulator`）。
- 新增开源成熟度资产：CI 工作流、LICENSE、贡献模板、行为准则、安全策略。
## 发布亮点（2026 年 3 月）
- 通过迁移至线程化 HTTP 服务器，提升高并发请求下的仪表板可靠性。
- 在仪表板 API 中新增线程安全的告警解析缓存，避免竞态条件与陈旧读取。
- 集成团队风格的 Portal 栈（FastAPI + Next.js + Postgres），支持可定制的仪表板工作流。
- 新增由版本标签（`vX.Y.Z`）触发的自动化 GitHub Release 工作流，用于发布核心与完整可下载包。
## 发布亮点（2026 年 4 月）
- **代码审计与精简**：重构核心引擎以提升可维护性（DRY 检测逻辑）。
- **仪表板清理**：从轻量级仪表板服务器中移除遗留的可观测性代理逻辑。
- **项目结构优化**：移除冗余启动脚本并清理项目根目录。
## 项目结构
- .github/：CI 与贡献模板
- workflows/release.yml：标签触发的构建与发布管道
- docs/：架构与演示文档
- log-sentinel/
- sentinel.py：日志监控与检测引擎
- config.yaml：运行时设置
- Dashboard-server.py：仪表板 HTTP 服务器
- dashboard.html：仪表板 UI
- demo_simulator.py：Docker 演示流量生成器
- rules/：检测模式文件
- evaluation/：基准数据集与指标脚本
- data/：运行时日志文件（被 .gitignore 忽略）
- test.sh：日志攻击模拟器（bash）
- apps/
- portal-api/：用于仪表板注册、布局持久化和摘要 API 的 FastAPI 服务
- portal-ui/：带有嵌入式仪表板工作区的 Next.js 分析器 UI
- infra/
- grafana/、prometheus/、loki/、promtail/：可观测性堆栈配置（可选 Docker Compose 配置）
- PHASED_IMPROVEMENT_PLAN.md：最终年实施路线图
## 要求
- Python 3.8+（核心引擎与仪表板）
- Node.js 20+ 与 npm（Portal UI 本地开发）
- Docker Desktop（推荐用于完整集成堆栈）
- Python 依赖文件：
- `log-sentinel/requirements.txt`（当前为 `PyYAML>=6.0,<7.0`）
- `apps/portal-api/requirements.txt`
## 安装与设置
1. 创建虚拟环境（可选）并安装依赖：
```
pip install -r log-sentinel/requirements.txt
pip install -r apps/portal-api/requirements.txt
```
2. （可选，用于本地 Portal UI 开发）安装 UI 依赖：
```
cd apps/portal-ui
npm install
cd ../..
```
3. 如有需要，在 log-sentinel/config.yaml 中更新日志路径与设置。
## 运行日志哨兵
在 log-sentinel 目录中执行：
```
python sentinel.py
```
日志哨兵会跟踪配置的日志文件，并将告警写入 `log-sentinel/data/alerts.log`。
## 运行仪表板
在另一个终端中，从 log-sentinel 目录执行：
```
python Dashboard-server.py
```
然后在浏览器中打开 http://localhost:8888。
## 运行 Portal UI/API（推荐）
在仓库根目录（使用 Docker）：
```
docker compose --profile portal up --build
```
然后访问：
- Portal UI：`http://localhost:3001`
- Portal API：`http://localhost:8080`
Portal API 已与日志哨兵仪表板 API 集成。
## 一键式 Docker 演示
快速启动矩阵：
| OS / Shell | 启动完整堆栈 |
|---|---|
| Linux/macOS/Windows | `docker compose --profile full up --build` |
## 模拟攻击
测试脚本会将示例攻击行追加到配置的日志中。
```
bash test.sh
```
注意：在 Windows 上，请在 Git Bash 或 WSL 中运行此脚本。
## 配置
log-sentinel/config.yaml 中的关键设置：
- log_file：要监控的访问日志路径
- alert_log：告警输出文件
- enable_*_detection：启用/禁用检测器
- rate_limit_*：速率限制设置
- enable_404_detection / max_404_per_minute：404 垃圾检测开关与每分钟上限
- whitelist_ips：跳过检测的逗号分隔 IP 列表
- dedup_enabled / dedup_window_seconds：在时间窗口内抑制重复告警
- max_path_length：限制控制台输出的超长路径
- enable_behavioral_detection：启用基于请求行为的异常检测
- behavior_*：调整基线历史阈值与突增倍数
## 规则
检测模式位于 log-sentinel/rules/ 目录中：
- sqli_patterns.txt
- xss_patterns.txt
- traversal_patterns.txt
- cmdi_patterns.txt
- scanner_patterns.txt
模式被视为不区分大小写的正则表达式。
## 输出
告警会写入 `log-sentinel/data/alerts.log`，并可选择性地打印到控制台。仪表板读取该文件并提供以下端点：
- GET /api/alerts（最近 100 条告警）
- GET /api/stats（统计摘要）
- GET /api/incidents（按 IP 与时间窗口聚合的事件）
Portal API 消费这些端点，并对 Portal UI 摘要与仪表板工作流进行标准化处理。
## 注意事项
- Nginx 日志正则表达式期望默认的 combined 日志格式。
- 告警级别标记为 INFO/WARNING/CRITICAL，但代码中尚未强制执行最低级别过滤。
## 最终年追踪
- 项目现已包含第一阶段与第二阶段的硬化改进（代码中）。
- 详见 PHASED_IMPROVEMENT_PLAN.md，了解涵盖行为分析、开源成熟度与评估的完整多阶段路线图。
## 评估（最终年指标）
运行内置的基准测试框架以生成可测量结果：
```
python log-sentinel/evaluation/generate_dataset.py
python log-sentinel/evaluation/evaluate.py
```
输出结果包括：
- `log-sentinel/evaluation/dataset.jsonl`
- `log-sentinel/evaluation/report.json`
报告的指标涵盖精确率、召回率、F1、延迟、吞吐量、内存使用量以及每种攻击类型的召回率。
## 开源准备度
- 许可证：MIT（`LICENSE`）
- 贡献指南：`CONTRIBUTING.md`
- 行为准则：`CODE_OF_CONDUCT.md`
- 安全策略：`SECURITY.md`
- 社区模板：`.github/ISSUE_TEMPLATE/` 与 `.github/pull_request_template.md`
- CI 检查：`.github/workflows/ci.yml`
## 演示文档
- 架构概览：`docs/ARCHITECTURE.md`
- 两分钟演示流程：`docs/DEMO_SCRIPT.md`
标签：404 垃圾检测, API 接口, AV绕过, Docker, DOE合作, F1, FastAPI, IP 封禁, Nginx 变体, Nginx 日志, Portal 栈, Postgres, SQL 注入, User-Agent 检测, Web 攻击检测, XSS, 事件关联, 仪表盘, 内存, 动态评分, 原因码, 召回率, 可解释性, 吞吐量, 告警去重, 告警控制台, 命令注入, 威胁情报, 安全策略, 安全防御评估, 延迟, 开发者工具, 开源成熟度, 开源框架, 异常检测, 持续集成, 提示词设计, 攻击链, 文件日志, 新端点识别, 日志解析, 机器学习可解释, 漏洞情报, 演示栈, 爬虫识别, 用户代理异常, 竞态条件, 精确率, 线程安全, 缓存, 行为异常, 行为检测, 证书伪造, 评估基准, 请求拦截, 请求突增, 贡献指南, 路径遍历, 逆向工具, 重复告警抑制, 重现性评估, 频率限制, 风险评分