filipemorasca/log-anomaly-detector

# 📊 日志异常检测器 [](https://www.python.org/) [](LICENSE) ## 🎯 问题所在 暴露在互联网上的服务器每天都会收到数千次 SSH 尝试和数百次 HTTP 扫描。**大部分都变成了噪音** —— 惯犯 IP、扫描机器人、脚本小子。但在这片噪音之中，如果你只盯着日志尾部，很容易错过**真正的攻击模式**。 专业工具（fail2ban、Wazuh、ELK）能很好地解决这个问题。但是： - **它们消耗内存/CPU**，而小型 VPS 缺乏这些资源 - **配置耗时**，如果你只是想了解正在发生什么 - **分析孤立的旧日志**进行事后排查**很困难 本项目旨在几秒钟内解决**"给我一份日志，告诉我有什么问题"**这一场景。 ## 💡 工作原理 ``` ┌─────────────┐ auth.log ───────▶│ Parser │──┐ access.log ─────▶│ (regex) │ │ └─────────────┘ │ ▼ ┌─────────────┐ │ pandas │ │ DataFrame │ └─────────────┘ │ ▼ ┌────────────────────────┴────────────────────────┐ ▼ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Brute │ │ HTTP │ │ Suspicious │ │ IP │ │ Force │ │ Scan │ │ User-Agent │ │ Reputation │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ ``` 每个检测器都是一个纯函数，接收 DataFrame 并返回一个发现列表。 ### 内置检测器 | 检测器 | 逻辑 | 目标日志 | |----------|--------|------| | `brute_force_ssh` | 同一 IP 在 M 分钟窗口内 ≥ N 次失败尝试 | `auth.log` | | `http_scan` | 同一 IP 在短窗口内 ≥ N 次 404/403 | `access.log` | | `suspicious_user_agent` | 用户代理字符串匹配已知扫描器 (nmap, nikto, sqlmap, masscan 等) | `access.log` | | `high_volume_ip` | 请求量位列前 1% 的 IP | 任意日志 | 所有阈值均可通过 CLI 配置。 ## 🚀 快速开始 ``` git clone https://github.com/filipemorasca/log-anomaly-detector.git cd log-anomaly-detector pip install -e . # 分析 SSH 日志（含样本） log-anomaly samples/auth.log --type ssh # 分析 HTTP 日志（含样本） log-anomaly samples/access.log --type nginx # 自定义暴力破解阈值（2 分钟内 5 次尝试） log-anomaly samples/auth.log --type ssh --bruteforce-attempts 5 --bruteforce-window 2 # 输出为 CSV 供外部分析 log-anomaly samples/auth.log --type ssh --output findings.csv ``` ### 输出示例 ``` 📊 log-anomaly-detector Arquivo: samples/auth.log Tipo: ssh Linhas analisadas: 1247 Período: 2026-03-15 02:14 → 2026-03-15 18:30 🚨 Findings: [BRUTE_FORCE_SSH] IP 203.0.113.42 → 127 tentativas em 4 minutos para usuário 'root' Primeira: 02:14:18 Última: 02:18:02 [BRUTE_FORCE_SSH] IP 198.51.100.7 → 42 tentativas em 8 minutos para múltiplos usuários Primeira: 14:02:11 Última: 14:10:33 [HIGH_VOLUME_IP] IP 203.0.113.42 → 127 requisições (99.2 percentil) ``` ## 📂 项目结构 ``` log-anomaly-detector/ ├── src/log_anomaly/ │ ├── __init__.py │ ├── cli.py # Entry point │ ├── parsers.py # Regex + pandas DataFrame para cada formato │ └── detectors.py # Lógica de detecção (funções puras) ├── tests/ │ └── test_parsers.py ├── samples/ │ ├── auth.log # Log SSH com padrão de brute-force │ └── access.log # Log nginx com padrão de scan ├── pyproject.toml └── README.md ``` ## 🧪 运行测试 ``` pip install -e ".[dev]" pytest -v ``` ## ⚙️ 如何添加新检测器 1. 编辑 `src/log_anomaly/detectors.py` 2. 添加函数：`def my_detector(df: pd.DataFrame, **kwargs) -> list[Finding]:` 3. 在文件顶部的 `DETECTORS_FOR_TYPE` 中注册 4. 在 `tests/` 中添加测试 检测器是 `(DataFrame, params) → list[Finding]` 的纯函数。没有状态，也没有副作用，使测试变得简单直接。 ## ⚠️ 已知限制 - **不能替代 SIEM。** 对于生产环境，请使用 Wazuh/ELK/Loki + Grafana。 - **仅支持经典格式。** `auth.log`（标准 rsyslog）和 `access.log`（nginx 默认的 combined 格式）。不支持 JSON 格式的日志、二进制的 journald 或自定义格式。 - **不跨源关联。** 每个文件都是独立分析的。要关联认证和 HTTP 日志，需要运行两次并交叉比对发现。 ## 🎓 本项目展示内容 - **使用 Pandas 进行时间序列分析**（滚动窗口、分组聚合） - **针对异构格式的实用正则表达式** - **设计良好的 CLI** (argparse + rich) - **蓝队思维模式**：使用简单、易于解释和审计的启发式规则 - **模块化代码**：检测器是纯函数，易于扩展和测试 ## 🏷️ 建议话题 (在 GitHub 上配置) `security` · `blue-team` · `log-analysis` · `python` · `pandas` · `siem` · `threat-detection` · `incident-response` · `devsecops` · `ssh-bruteforce` · `nginx` ## 📜 许可证 MIT — 详情参见 [LICENSE](LICENSE)。

标签：Nginx日志, pandas库, SSH日志, 异常检测, 攻击模式识别, 服务器日志, 网络安全, 自动化分析, 跨站脚本, 轻量级安全, 逆向工具, 隐私保护