VloneAle21/soc-monitor

## 🧠 这是什么？ **SOC Monitor** 是一个轻量级、无依赖的 **安全运营中心 (Security Operations Center)** 工具包，使用纯 Python 编写。它可以实时解析 syslog / `auth.log` 流，并在发现蓝队分析师常见的攻击模式时发出警报： - 🔓 **SSH 暴力破解** — 在一个滑动时间窗口内，来自同一 IP 的大量失败身份验证 - 📡 **端口扫描** — 来自单个源的大量针对不同端口的连接 - 🌪️ **身份验证失败风暴** — 跨服务的身份验证失败聚集发生 该项目旨在提供易于阅读、可修改的代码，并方便通过自定义检测器进行扩展。 ## ✨ 功能 | | 功能 | 描述 | |---|---|---| | 🧩 | **可插拔检测器** | 每个检测器为每个源 IP 维护一个滚动窗口。你可以通过继承 `Detector` 来添加自己的检测器。 | | 📊 | **多输出目标 (Sinks)** | 同时将警报输出到控制台（彩色）、JSONL 和 CSV。 | | ⏱️ | **实时追踪模式** | `--follow` 像 `tail -f` 一样追踪日志文件，实现实时监控。 | | 🧪 | **演示模式** | `--demo` 运行内置的攻击场景 —— 无需真实日志。 | | 🚫 | **零依赖** | 仅使用标准库。只需运行 `python soc_monitor.py`。 | | 🧱 | **清晰的架构** | Parser → Detectors → Engine → Sinks。易于测试和推理。 | ## 🚀 快速开始 ``` # Clone git clone https://github.com/VloneAle21/soc-monitor.git cd soc-monitor # 运行内置攻击场景（无需 logs） python soc_monitor.py run --demo # 或者分析真实的 auth.log python soc_monitor.py run /var/log/auth.log # 实时 tail log python soc_monitor.py run /var/log/auth.log --follow # 在查看 console 的同时将 alerts 保存为 JSON + CSV python soc_monitor.py run auth.log --json alerts.jsonl --csv alerts.csv ``` ### 演示输出 ``` [15:38:39] [HIGH ] SSH brute-force from 203.0.113.5 ↳ 5 failed SSH auth attempts from 203.0.113.5 within 60s ↳ source: 203.0.113.5 · detector: ssh_bruteforce [15:38:39] [MEDIUM ] Port scan from 203.0.113.5 ↳ 10 connections to 10 distinct ports (5100,5101,…) within 30s ↳ source: 203.0.113.5 · detector: port_scan [15:38:39] [MEDIUM ] Auth failure storm from 203.0.113.5 ↳ 20 authentication failures across services from 203.0.113.5 within 120s ↳ source: 203.0.113.5 · detector: auth_fail_storm ``` ## 🛠️ 用法 ``` usage: soc-monitor [-h] [--version] {run,list} ... 🛡️ Lightweight SOC monitor — brute-force, port-scan & auth-fail detection. commands: run Analyze a log file or stream list List available detectors ``` ### `run` 选项 | 标志 | 描述 | |---|---| | `file` | syslog/auth 日志文件的路径 | | `-f, --follow` | 实时追踪文件（类似于 `tail -f`） | | `--demo` | 运行内置的攻击场景 | | `--json PATH` | 将警报追加到 JSONL 文件 | | `--csv PATH` | 将警报追加到 CSV 文件 | | `-q, --quiet` | 抑制控制台输出（适用于批处理作业） | ## 🧩 检测器 列出内置的检测器： ``` python soc_monitor.py list ``` ``` Available detectors: • ssh_bruteforce window=60s threshold=5 • port_scan window=30s threshold=10 • auth_fail_storm window=120s threshold=8 ``` ### 编写自己的检测器 ``` from soc_monitor import Detector, Event, Alert class MyDetector(Detector): name = "my_detector" window_seconds = 90 threshold = 3 def _evaluate(self, event: Event) -> Alert | None: # your logic here — return an Alert when a threshold is crossed ... # 在 engine 中注册它 engine = SOCEngine(detectors=[MyDetector()], sinks=[StdoutSink()]) engine.process(open("auth.log")) ``` 每个检测器都维护一个基于 IP 的 `deque` 窗口，该窗口会自动修剪 —— 因此即使在高吞吐量的日志下，内存消耗也能保持在有限范围内。 ## 🏗️ 架构 ``` ┌──────────┐ ┌────────────┐ ┌────────┐ ┌───────┐ log lines → │ Parser │ → │ Detectors │ → │ Engine │ → │ Sinks │ └──────────┘ └────────────┘ └────────┘ └───────┘ syslog brute-force orchestrates console regexes port-scan cooldown JSONL IP extract auth-fail CSV ``` - **Parser** — 将原始行标准化为 `Event(timestamp, source_ip, username, message)` - **Detectors** — 有状态的、基于 IP 的滚动窗口，用于发出 `Alert` - **Engine** — 连接解析器 + 检测器 + sinks，并通过冷却时间对警报进行去重 - **Sinks** — `StdoutSink`（彩色）、`JSONSink`、`CSVSink` ## 🧪 测试 ``` python -m pytest test_soc_monitor.py -v ``` ``` 11 passed in 0.10s ``` 测试涵盖了 syslog 解析器、每个检测器的阈值行为、警报严重性模型以及 JSON sink 的输出。 ## 📁 项目结构 ``` soc-monitor/ ├── soc_monitor.py # The whole toolkit (single file, ~600 lines) ├── test_soc_monitor.py # 11 pytest unit tests ├── sample_auth.log # Example attack log to play with ├── requirements.txt # Empty — stdlib only! └── README.md ``` ## 🛡️ 用例 - **家庭实验室 / 蓝队演练** — 将你的 `auth.log` 转化为实时警报 - **CTF / 培训** — 在合成流量上演示检测逻辑 - **嵌入式 SOC** — 在无法部署完整 SIEM 的地方部署一个微型 IDS - **学习** — 为新手提供易读且注释完善的检测代码 ## 📄 许可证 基于 **MIT License** 发布。详情请见 [LICENSE](LICENSE)。     **⭐ 如果这个项目对你有帮助，请给仓库点个 Star —— 这对我们帮助很大。** 由 **[Alejandro R.](https://github.com/VloneAle21)** 使用 🛡️ 制作