omobolajiadeyan/behaviorsense

# BehaviorSense BehaviorSense 是一个用于安全日志的本地行为异常检测器。它为用户和基于 IP 的实体构建画像，将其行为与整体基准进行比较，并对高认证失败率、多个源 IP、广泛的 endpoint 访问、大流量传输以及非工作时间活动等模式添加显式的安全信号加成。 它旨在进行可解释的分级评估，而非黑盒判定。其输出会显示风险评分、贡献信号、MITRE ATT&CK 风格的技术提示以及建议的分析师行动。 ## 开发动机 传统的基于规则的工具只能捕获已知的模式。BehaviorSense 专注于偏离基准的可疑行为： - 来自多个 IP 且有多次登录失败的用户 - 伴随广泛 endpoint 活动的非工作时间访问 - 异常的数据传输量 - 在统计学上与同类不同的实体行为 BehaviorSense 在本地运行，并且仅使用 Python 标准库。不会将任何日志数据发送到外部服务。 ## 外部审查人员须知 如果您正在评估此项目，请从这里开始： - [外部评估人员指南](docs/EVALUATOR_GUIDE.md) - 五分钟审查路径、预期结果和信任边界 - [示例输出](docs/SAMPLE_OUTPUT.md) - 内置 demo 应产生的结果 最快的安全 demo： ``` python3 detector.py sample_data/ --verbose python3 detector.py sample_data/ --output report.json ``` 内置示例有意包含了一个 `CRITICAL` 实体。当存在严重发现时，CLI 会 以退出代码 `2` 退出；这意味着检测生效了。 ## 功能 - 跨行为维度对用户和 IP 进行画像 - 针对观察到的群体进行 Z-score 偏差分析 - 针对分析师相关模式的安全信号加成 - 用于分类评估上下文的 MITRE ATT&CK 风格技术提示 - 针对可疑实体的建议下一步行动 - 支持 SSH 认证日志、Web 访问日志、CSV、JSON 和 NDJSON - 用于 SIEM/SOAR 移交或报告的 JSON 导出 - 零运行时依赖 - 经过单元测试的解析器、评分和 CLI 行为 ## 检测模型 BehaviorSense 结合了两层： 1. **群体偏差：** z-score 将每个实体与数据集基准进行比较。 2. **安全信号：** 确定性加成捕获已知的可疑组合，这些组合在小型数据集上可能会被 z-score 低估。 当前的安全信号： | 信号 | 触发条件 | |---|---| | `high_failure_rate` | 至少 50% 的失败事件且至少有 3 次失败 | | `many_source_ips` | 5 个或更多唯一的源 IP | | `broad_endpoint_access` | 5 个或更多唯一的 endpoint | | `large_data_volume` | 传输 5 MB 或更多数据 | | `high_event_volume` | 10 个或更多事件 | | `off_hours_activity` | 在 06:00 之前或 22:00 之后的平均活动 | 这是一个分类评估引擎。它可能会产生误报和漏报，尤其是在小型或合成数据集上。 ## 安装说明 ``` git clone https://github.com/omobolajiadeyan/behaviorsense.git cd behaviorsense python --version # Python 3.10+ required ``` 可选的本地安装： ``` python -m pip install . behaviorsense sample_data/ --verbose ``` ## 用法 ``` # 分析 sample data python detector.py sample_data/ # 显示完整 z-score、signal、technique 和 action 上下文 python detector.py sample_data/ --verbose # 显示风险最高的 10 个实体 python detector.py sample_data/ --top 10 # 仅显示 HIGH 和 CRITICAL 实体 python detector.py sample_data/ --threshold HIGH # 导出为 JSON python detector.py sample_data/ --output report.json # 分析 real logs python detector.py /var/log/auth.log python detector.py /var/log/nginx/ ``` 退出代码： - `0`：完成，未发现严重问题 - `1`：输入无效或运行时错误 - `2`：发现至少一个 `CRITICAL` 实体 ## 示例输出 ``` BEHAVIORSENSE REPORT ============================================================== Events analyzed : 23 Entities profiled : 5 CRITICAL : 1 HIGH : 0 MEDIUM : 0 NORMAL : 4 TOP 1 ENTITIES BY RISK SCORE #1 mallory [CRITICAL] Risk Score : 100.0% Events : 12 | Failed logins: 7 Unique IPs : 8 | Endpoints: 5 Data moved : 8,324,480 bytes Top anomaly : Failure Rate Security signals: - high failure rate: 7 failed events across 12 total events - many source ips: 8 unique source IPs - broad endpoint access: 5 unique endpoints - large data volume: 8,324,480 bytes transferred - high event volume: 12 events - off hours activity: average activity hour 2.0 Technique hints: - T1110 Brute Force - T1078 Valid Accounts - T1083 File and Directory Discovery - T1041 Exfiltration Over C2 Channel ``` ## JSON 导出 ``` python detector.py sample_data/ --output report.json ``` 导出的报告包含： - `total_events` - `total_entities` - 排序后的 `results` - 每个实体的 `z_scores` - 安全 `signals` - `technique_hints` - `recommended_actions` ## 架构 ``` behaviorsense/ ├── detector.py # CLI entrypoint and report renderer ├── parser.py # Log parsers and event normalization ├── profiler.py # Per-entity behavioral profiling ├── scorer.py # Z-score, security-signal, and risk ranking logic ├── sample_data/ │ └── activity.csv # Synthetic sample data with an anomalous entity ├── tests/ # Unit tests for parser, scoring, and CLI behavior └── .github/workflows/ # CI test workflow ``` ## 验证 ``` python -m unittest discover -s tests -v python detector.py sample_data/ --verbose ``` ## 路线图 - [ ] 采用时间窗口的基准，以检测慢速隐蔽型攻击 - [ ] 按部门、角色或服务账户类型进行同侪组比较 - [ ] 导出 Sigma 或检测规则，用于下游安全工具 - [ ] 具有置信度级别的更丰富的 MITRE ATT&CK 映射 - [ ] 从 JSON 输出生成的可选 dashboard 或 HTML 报告 - [ ] 在显式额外依赖项背后的可选 Isolation Forest 模式 ## 作者 **Omobolaji Adeyan** - 网络安全工程师 GitHub: https://github.com/omobolajiadeyan · Website: https://omobolajiadeyan.com ## 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。

标签：Python, UEBA, 安全, 异常检测, 文档结构分析, 无后门, 超时处理, 逆向工具