raghubirrajmahato15/HackDev-LogSentinel
GitHub: raghubirrajmahato15/HackDev-LogSentinel
基于 Isolation Forest 无监督机器学习的 Web 服务器访问日志异常检测命令行工具。
Stars: 0 | Forks: 0
# HackDev-LogSentinel
基于 ML 的 Web 服务器日志异常检测器，使用 Isolation Forest。
LogSentinel 是一个命令行工具，它可以从基准 Apache/Nginx 访问日志（combined 格式）中学习“正常”流量的特征，然后标记目标日志文件中的异常请求——例如 SQL 注入探测、路径遍历尝试、XSS
payload，或是与基准流量明显不同的异常请求。它使用无监督的 `IsolationForest` 模型，因此不需要标记的攻击数据：你只需要一个代表典型、合法流量的日志文件。
## 功能
- 用于标准 Apache/Nginx **combined** 日志格式的 Regex 解析器，可平滑处理格式错误/无法解析的行（跳过并计数，并在最后提供警告汇总）
- 单个请求的特征提取：URL 长度、查询参数数量、路径+查询中的特殊字符比例、查询字符串的 Shannon 熵、响应 payload 大小，以及编码为整数的 HTTP 方法
- `fit` 子命令：在基准日志上训练 `StandardScaler` + `IsolationForest` 模型，并使用 `joblib` 将其保存到磁盘
- `scan` 子命令：使用保存的模型对目标日志进行评分，并报告异常请求及其原始特征值和异常分数
- 文本和 JSON 输出模式，以及统计摘要（总行数、已解析、发现的异常）
- 可配置的 contamination 率，用于调整灵敏度
- 附带 `sample_access.log`，这是一个约 30 行的示例日志（主要为正常流量，外加几条类似 SQLi/XSS/路径遍历的请求），方便你立即进行测试
## 安装说明
```
git clone https://github.com/raghubirrajmahato15/HackDev-LogSentinel.git
cd HackDev-LogSentinel
pip install -r requirements.txt
```
要求 Python 3.10+。
## 用法
从已知正常的日志文件中训练基准模型：
```
python logsentinel.py fit sample_access.log -o baseline_model.joblib --contamination 0.1
```
使用该模型扫描目标日志文件以查找异常：
```
python logsentinel.py scan sample_access.log --model baseline_model.joblib
```
获取 JSON 输出并将其写入文件：
```
python logsentinel.py scan sample_access.log --model baseline_model.joblib --format json -o results.json
```
详细日志记录（对调试解析问题很有用）：
```
python logsentinel.py -v fit sample_access.log -o baseline_model.joblib
```
### JSON 扫描输出示例（节选）
```
{
"stats": {
"total_lines": 30,
"parsed": 30,
"unparsed": 0,
"anomalies_found": 4
},
"anomalies": [
{
"line_number": 25,
"ip": "203.0.113.9",
"path": "/products?id=1 UNION SELECT username,password FROM users--",
"status": 500,
"anomaly_score": 0.187432,
"features": {
"url_length": 60,
"param_count": 1,
"special_char_ratio": 0.216667,
"entropy": 3.845,
"payload_length": 480,
"method_encoded": 0
}
}
]
}
```
## CLI 参数参考
| 参数 | 子命令 | 描述 | 默认值 |
|---|---|---|---|
| `baseline_log_file` | `fit` | 基准访问日志文件的位置参数路径 | 必填 |
| `target_log_file` | `scan` | 目标访问日志文件的位置参数路径 | 必填 |
| `-o`, `--output` | `fit`, `scan` | `fit`：保存模型 bundle 的路径。`scan`：可选的用于写入结果的路径 | `logsentinel_model.joblib` (fit) / 无 (scan) |
| `--model` | `scan` | 由 `fit` 保存的模型+scaler bundle 路径 | 必填 |
| `--contamination` | `fit` | 基准数据中预期的异常比例 | `0.05` |
| `--format` | `fit`, `scan` | 输出格式：`text` 或 `json` | `text` |
| `-v`, `--verbose` | all | 启用详细 (DEBUG) 日志记录 | 关 |
| `-h`, `--help` | all | 显示帮助信息并退出 | — |
## 法律声明
LogSentinel 是一款防御性的蓝队工具。它仅用于分析你拥有或获得明确授权访问和分析的 Web 服务器访问日志（例如，你自己的基础设施，或你有书面许可评估的系统）。
请勿在未经授权的情况下，对该工具针对的日志或系统使用此工具。
标签：Apex, Caido项目解析, CISA项目, Python, URL发现, 安全检测, 异常检测, 无后门, 机器学习, 逆向工具