Sudeep72/nano-siem
GitHub: Sudeep72/nano-siem
一个用纯 Python 构建的生产级极简 SIEM 引擎，集成了 Sigma 检测、攻击链关联和 ML 异常评分，帮助企业从零理解并实践安全事件检测。
Stars: 0 | Forks: 0
# NanoSIEM
**一个从零开始使用 Python 构建的生产级、极简依赖的 SIEM 引擎。**
[](https://github.com/Sudeep72/nano-siem/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
[](tests/)
[](https://oasis-open.github.io/cti-documentation/stix/intro)
*Sigma 检测 · 攻击链关联 · ML 异常评分 · STIX 2.1 导出*
## 什么是 NanoSIEM？
NanoSIEM 是一个用大约 4,500 行纯 Python 编写的全功能 SIEM 引擎。
它实现了企业级安全平台所使用的相同检测 pipeline——但
没有抽象的迷雾。每个组件都是可读、可测试且有文档记录的。
作为学习 SIEM 理论的“动手实践”替代方案而构建。如果你想
了解检测工程在代码层面上究竟是如何运作的，请阅读这个代码库。
```
Log sources → Parse → Normalize → Sigma Eval → Correlate → ML Score → Alert → STIX 2.1
```
## 功能矩阵
| 功能 | 详情 |
|---|---|
| **日志摄取** | Syslog RFC 5424, Syslog RFC 3164, CEF, JSON, 纯文本 — 自动检测 |
| **传输方式** | UDP syslog, TCP syslog (RFC 6587), TCP JSON, 本地文件 tail |
| **Sigma 引擎** | 自定义 AST 解析器 — `and`/`or`/`not`/`1 of`/`all of`, 字段修饰符 (`contains`, `startswith`, `endswith`, `re`) |
| **关联分析** | 6 个内置攻击链, 滑动时间窗口, 源 IP 分组, 去重 |
| **ML 检测** | Isolation Forest, 31 个特征提取器, 百分位校准评分, XAI 归因 |
| **告警** | 统一告警管理器, 严重性过滤, 按 fingerprint 去重 |
| **输出** | STIX 2.1 JSON bundles, NDJSON 告警日志, SQLite 环形缓冲区 |
| **CLI** | 通过 Typer 实现 `run`, `tail`, `parse-line`, `stats` 命令 |
| **测试** | 234 个通过的测试, 6 个测试模块覆盖所有组件 |
| **依赖项** | `pyyaml`, `stix2`, `scikit-learn`, `typer`, `rich`, `joblib` — 没有其他依赖 |
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ Log Sources │
│ UDP Syslog · TCP Syslog · TCP JSON · File Tail │
└────────────────────────────┬────────────────────────────────────┘
│ RawMessage queue (asyncio, bounded 10k)
▼
┌─────────────────────────────────────────────────────────────────┐
│ Ingestion Pipeline │
│ │
│ parser.py normalizer.py schema.py │
│ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │
│ │RFC 5424 │ │ IP extract │ │NormalizedEvent│ │
│ │RFC 3164 │──────▶│ Username │───────▶│ (common │ │
│ │CEF │ │ Auth tags │ │ schema) │ │
│ │JSON │ │ Port parse │ └──────┬───────┘ │
│ │Plaintext │ └────────────┘ │ │
│ └──────────┘ │ │
└───────────────────────────────────────────────────┼────────────┘
│
┌─────────────────────────────────────┤
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Sigma Rule Engine │ │ Correlation Engine │
│ │ │ │
│ loader.py │ │ window.py │
│ ┌─────────────────┐ │ │ ┌─────────────────┐ │
│ │ YAML → SigmaRule│ │ │ │ Per-source deque │ │
│ └────────┬────────┘ │ │ │ Sliding window │ │
│ │ │ │ │ LRU eviction │ │
│ ast.py │ │ │ └────────┬────────┘ │
│ ┌────────▼────────┐ │ │ │ │
│ │ Condition → AST │ │ │ chainer.py │
│ │ and/or/not/1of │ │ │ ┌────────▼────────┐ │
│ └────────┬────────┘ │ │ │ Sequence finder │ │
│ │ │ │ │ 6 built-in chains│ │
│ evaluator.py │ │ │ Alert callbacks │ │
│ ┌────────▼────────┐ │ │ └─────────────────┘ │
│ │ Walk AST vs │ │ └─────────────────────────┘
│ │ NormalizedEvent │ │
│ └─────────────────┘ │ ┌─────────────────────────┐
└─────────────────────────┘ │ ML Anomaly Scorer │
│ │
│ features.py │
│ ┌─────────────────┐ │
│ │ 31-dim extractor │ │
│ │ temporal/network │ │
│ │ program/message │ │
│ └────────┬────────┘ │
│ │ │
│ baseline.py │
│ ┌────────▼────────┐ │
│ │ IsolationForest │ │
│ │ Calibrated score │ │
│ │ XAI attribution │ │
│ └─────────────────┘ │
└─────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Alert Manager │
│ │
│ Sigma + Correlation + ML │
│ Fingerprint deduplication │
│ Severity routing │
└──────────┬──────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────────┐ ┌──────────┐
│STIX 2.1 │ │ NDJSON alert │ │ SQLite │
│ Bundles │ │ log │ │ Ring │
└──────────┘ └──────────────┘ │ Buffer │
└──────────┘
```
## 快速开始
### 安装
```
git clone https://github.com/Sudeep72/nano-siem.git
cd nano-siem
pip install -e .
```
### 运行演示（无需设置）
```
bash demo.sh
```
这将对合成日志数据执行全部 5 个检测阶段，并展示真实的检测结果。
### 启动实时 pipeline
```
# Terminal 1 — 启动 nano-siem
nano-siem run
# Terminal 2 — 发送模拟攻击 kill chain
bash examples/send_kill_chain.sh
```
### Tail 本地日志文件
```
nano-siem tail /var/log/auth.log
```
### 解析并检查单行日志
```
nano-siem parse-line '<34>1 2026-06-02T03:00:01Z web-01 sshd 1234 - - Failed password for root from 203.0.113.5 port 22'
```
## 检测层
### 第 1 层 — Sigma 规则评估
NanoSIEM 内置了 7 条 Sigma 规则，并支持加载任何兼容 Sigma 的 YAML：
| 规则 | 级别 | MITRE 技术 |
|---|---|---|
| SSH 暴力破解尝试 | HIGH | T1110.001 |
| SSH 成功登录 | LOW | T1021.004 |
| 通过 Sudo 进行权限提升 | MEDIUM | T1548.003 |
| 检测到端口扫描 | MEDIUM | T1046 |
| Web 管理面板访问尝试 | MEDIUM | T1190 |
| 高严重性 CEF 事件 | HIGH | — |
| 可疑的 Root 进程执行 | HIGH | T1059 |
在 `rules/` 中添加你自己的规则 — 任何 `.yml` 文件都会被自动加载。
### 第 2 层 — 攻击链关联
6 个内置的 kill-chain 模式，在滑动时间窗口内按源 IP 分组：
| 链 | 步骤 | 窗口 | 严重性 |
|---|---|---|---|
| 暴力破解 → 成功登录 | 2 | 10 分钟 | CRITICAL |
| 端口扫描 → 暴力破解 | 2 | 5 分钟 | HIGH |
| 登录 → 权限提升 | 2 | 15 分钟 | CRITICAL |
| 端口扫描 → Web 管理探测 | 2 | 3 分钟 | HIGH |
| 完整入侵 Kill Chain | 4 | 30 分钟 | CRITICAL |
| 重复认证失败 (×3) | 3 | 2 分钟 | MEDIUM |
### 第 3 层 — ML 异常检测
在 2000 个事件的正常 Linux 流量合成基线上训练的 Isolation Forest。
涵盖时间、网络、程序、消息和严重性信号的 31 维特征向量。
检测没有规则覆盖的威胁 — 包括新颖的攻击模式。
**XAI 归因**通过驱动异常评分的核心特征解释了每一个异常分数：
```
🤖 ML [ANOMALOUS] score=0.987 | drivers: is_error_severity=1.00, is_off_hours=0.84, dest_port_norm=0.67
```
## 输出
### STIX 2.1 Bundles
每个告警都会在 `alerts/YYYY-MM-DD/` 中生成一个有效的 STIX 2.1 bundle：
```
{
"type": "bundle",
"spec_version": "2.1",
"objects": [
{ "type": "indicator", "name": "SSH Brute Force Attempt", "confidence": 80 },
{ "type": "sighting", "count": 3, "first_seen": "2026-06-02T03:00:01Z" },
{ "type": "observed-data", "custom_properties": {
"x_nano_siem_severity": "high",
"x_nano_siem_anomaly_score": 0.691,
"x_nano_siem_xai_features": [{"feature": "has_failure_keyword", "deviation": 1.0}]
}}
]
}
```
### NDJSON 告警日志
`alerts/alerts-YYYY-MM-DD.ndjson` — 每行一个 JSON 对象，易于通过管道传输到任何下游工具。
## 配置
所有设置都在 `config.yaml` 中：
```
ingestion:
syslog_host: "0.0.0.0"
syslog_port: 5140
syslog_protocol: "tcp" # tcp | udp
json_port: 5141
ml:
train_on_startup: true
anomaly_threshold: 0.62 # 0.0–1.0, higher = stricter
alerting:
dedup_window_seconds: 300
min_severity: "low" # low | medium | high | critical
stix_output: true
```
## 向 NanoSIEM 发送日志
```
# TCP Syslog (RFC 5424)
echo '<34>1 2026-06-02T03:00:01Z web-01 sshd - - - Failed password for root from 1.2.3.4' \
| nc -q1 localhost 5140
# TCP JSON
echo '{"host":"web-01","process":"nginx","message":"GET /admin HTTP/1.1 403","level":"warn"}' \
| nc -q1 localhost 5141
# CEF (通过 TCP syslog 端口)
echo 'CEF:0|Snort|IDS|2.9|1000001|Port Scan Detected|8|src=192.168.1.5 dst=10.0.0.1' \
| nc -q1 localhost 5140
```
## 运行测试
```
pip install pytest
python -m pytest tests/ -v
```
```
234 passed in 3.13s
```
测试覆盖了所有 5 个检测层：
| 模块 | 测试 |
|---|---|
| `test_parser.py` | 27 — RFC5424, RFC3164, CEF, JSON, 纯文本 |
| `test_normalizer.py` | 26 — 字段映射, IP/端口/用户提取, 认证标记 |
| `test_sigma.py` | 47 — loader, AST 构建器, 评估器, 引擎集成 |
| `test_correlation.py` | 42 — 窗口缓冲区, 步骤匹配, 链检测 |
| `test_ml.py` | 50 — 特征提取, 训练, 评分, XAI |
| `test_alerting.py` | 42 — 告警构建, 去重, STIX 输出 |
## 项目结构
```
nano-siem/
├── nano_siem/
│ ├── schema.py # NormalizedEvent — the pipeline's common language
│ ├── main.py # Async pipeline orchestrator
│ ├── ingestion/
│ │ ├── parser.py # RFC5424 / RFC3164 / CEF / JSON / plaintext
│ │ ├── normalizer.py # ParsedLog → NormalizedEvent + field extraction
│ │ └── listener.py # UDP, TCP syslog, TCP JSON, file tail listeners
│ ├── sigma/
│ │ ├── loader.py # Sigma YAML → SigmaRule dataclass
│ │ ├── ast.py # Detection block → evaluable AST
│ │ └── evaluator.py # AST evaluation + SigmaEngine
│ ├── correlation/
│ │ ├── chains.py # 6 built-in ChainRule definitions
│ │ ├── window.py # Per-source sliding time-window buffer
│ │ └── chainer.py # Sequence detection + Correlator
│ ├── ml/
│ │ ├── features.py # 31-dimensional feature extractor
│ │ ├── baseline.py # IsolationForest trainer + corpus generator
│ │ └── scorer.py # Per-event anomaly scoring + XAI
│ ├── storage/
│ │ └── ringbuffer.py # SQLite-backed event ring buffer
│ ├── alerting/
│ │ ├── manager.py # Alert dedup, severity routing
│ │ └── stix_output.py # STIX 2.1 bundle serializer
│ └── cli/
│ └── app.py # Typer CLI
├── rules/sample/ # 7 built-in Sigma rules
├── tests/ # 234 tests across 6 modules
├── examples/ # Runnable usage examples
├── config.yaml # All configuration
└── demo.sh # End-to-end 5-phase demo
```
## 性能
在标准笔记本电脑上进行的基准测试 (Python 3.13, 单核)：
| 指标 | 数值 |
|---|---|
| 摄取吞吐量 | ~55,000 个事件/秒 |
| 解析 + 标准化延迟 | 0.018 毫秒/事件 |
| Sigma 评估 (7 条规则) | ~0.05 毫秒/事件 |
| ML 评分 (IsolationForest) | ~0.1 毫秒/事件 |
| 端到端 pipeline 延迟 | < 0.5 毫秒/事件 |
| 内存 (1000 个源, 每个源 500 个事件) | ~100 MB |
## 路线图
查看 [ROADMAP.md](ROADMAP.md) 了解完整的版本计划。
| 版本 | 重点 | 状态 |
|---|---|---|
| v1.0 | 核心检测平台 | ✅ 已发布 |
| v2.0 | 检测工程版 | 🔜 计划中 |
| v3.0 | SOC 运营版 | 🔜 计划中 |
| v4.0 | AI 推理版 | 🔜 计划中 |
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
由 Sudeep Ravichandran 构建 · 印第安纳大学伯明顿分校，网络安全风险管理硕士
标签：Apex, PB级数据处理, Python, SIEM系统, URL发现, 安全检测, 安全运维, 无后门, 机器学习, 计算机取证, 逆向工具