supermhel/argiem
GitHub: supermhel/argiem
一款面向工业中小企业的开源 SIEM 系统，将多源安全日志规范化为 OCSF 格式并提供本地 AI 告警甄别与 OpenSearch 存储。
Stars: 0 | Forks: 0
# ARGIEM
**面向欧洲工业中小企业（Mittelstand）的开源 SIEM —— 将您的
工厂和 IT 日志转化为符合 NIS2/DORA 要求的证据，其 AI 甄别功能绝不会离开您的
网络。**
ARGIEM 从多个来源摄取日志，将其规范化为统一的 schema
（[OCSF](https://schema.ocsf.io/)），在滑动窗口上运行关联规则，
并在仪表板中展示警报。每个服务都是独立的，仅通过消息总线
与系统的其余部分进行通信，因此您可以扩展或替换任何部分
而无需重写其他部分。
与通用的自托管 SIEM 相比，它有三个不同之处：
- **原生 OCSF，非后期改造。** 每个来源从第一天起就规范化为相同的开放
schema —— 一次性检测，保持可移植性，无供应商日志格式
锁定。
- **OpenSearch，非 Elastic。** 存储引擎上没有许可证星号（限制）——
开源的故事没有附属细则。
- **绝不离开您网络的 AI 甄别。** 默认使用本地 Ollama，并带有
文档化的存根降级方案 —— 您的警报数据绝不会通过
第三方 LLM API 进行传输。
v0.4 中的新功能：包含了该切入领域实际所需的解析器包 —— MCP/AI-agent
工具调用审计日志、工业 OPC UA 控制系统事件，以及 n8n 自动化平台
日志 —— 外加一个事件报告草稿钩子（这是 NIS2/DORA
合规证据功能开放的一半；请参阅 [`contracts/reporting.md`](contracts/reporting.md)）。
## 快速开始（10 分钟）
```
git clone https://github.com/supermhel/argiem.git && cd argiem
make preflight # doctor: checks vm.max_map_count, Docker RAM, free ports
make demo # docker compose up -- a real SSH brute-force alert appears
# in the dashboard within ~30-60s, no manual step
# 打开 http://localhost:8080
```
手头没有 Docker？整个检测管道可以在零基础设施下运行：
`make e2e` 在完全没有 Redis/OpenSearch/Docker 的情况下，证明了相同的 SSH 暴力破解 → 真实警报 → 幂等重放
路径。
## 演示
观看 ARGIEM 将真实的 SSH 暴力破解突发流量转化为真实警报 —— **零
基础设施**（无需 Docker、Redis、OpenSearch）：
```
bash tools/demo.sh
```
这会将来自同一 IP 的 10 次失败的 SSH 登录尝试通过整个管道
（规范化 → 检测 → 甄别 → 索引），展示生成的暴力破解**警报**，
并重放该事件以证明该警报是**幂等的**（去重，而非
重复）。
### 自己尝试
```
# Zero-infra：SSH brute-force -> 真实告警，在 replay 下幂等（无需 Docker）。
make e2e # runs demo_e2e.py (fast, no narration)
bash tools/demo.sh # same test with banner + story narration
# # Windows：powershell -File tools\demo.ps1
# 完整 live stack（collect -> normalize -> detect -> index -> dashboard）：
make up # docker compose up -d
# ...然后打开位于以下地址的 ARGIEM 告警控制台：
# http://localhost:8080
make down # stop the stack and remove volumes
```
## 实际功能（v0.3 已发布，v0.4 进行中）
ARGIEM 提供了一个**可工作的检测管道**。我们对于什么是
已实现和什么是计划中非常明确 —— 这是一个安全工具，因此准确性比
冗长的功能列表更重要。
| 功能 | 状态 | 备注 |
|---|---|---|
| **检测管道**（收集 → 规范化 → 检测 → 索引 → 仪表板） | ✅ 正常工作 | 自 v0.1 起实现端到端 |
| **解析器（10个）** | ✅ 正常工作 | Cisco ASA、Active Directory、VMware vSphere、Linux SSH、通用 syslog、Windows Event Log（包含账户变更 4720/4722/4726/4728/4732）、数据库审计（GRANT/REVOKE/ALTER）、MCP/AI-agent 工具调用审计、OPC UA/OT 审计、n8n 自动化平台审计 —— 全部 → OCSF |
| **检测规则（17条）** | ✅ 正常工作 | 暴力破解、端口扫描、横向移动、密码喷洒、特权组授权、非工作时间管理、不可能的行程、银行数据库提权、DC 批量虚拟机删除、代理凭证文件访问/工具调用突发/提示注入指示器、OT 维护外写入/新建工程连接/配置变更、n8n 新暴露的 webhook/非工作时间修改的工作流 |
| **规则语法** | ✅ 正常工作 | 布尔逻辑、比较运算符（`gt/gte/lt/lte/ne`）、白名单抑制（`not_in`，CIDR + 精确匹配）、时间段（`outside_hours`）—— 在格式错误的输入上全部失败关闭 |
| **规则预过滤** | ✅ 正常工作 | 规则按 `class_uid` 等值选择进行分桶；事件仅根据候选规则进行评估（修复了 O(规则×事件) 的扫描问题） |
| **防休眠防护** | ✅ 正常工作 | CI 门控中的 `tools/check_rule_producers.py` 证明了每个规则的选择都可以由真实解析器实际发出的值所满足 |
| **AI 甄别**（本地 Ollama） | ✅ 正常工作 | 通过 `OLLAMA_URL` 进行真正的本地 LLM 甄别；在零基础设施下降级为文档化的透传存根 |
| **甄别工作流** | ✅ 正常工作 | 每个警报的状态和分析师备注，通过 WS-3 甄别 API 持久化，可在仪表板中编辑；并发写入在两个层面受到保护（进程内锁 + OpenSearch 乐观并发控制） |
| **事件报告草稿钩子** | ✅ 正常工作（v0.4） | `POST /alerts/{id}/report` 根据警报事实渲染通用的 Markdown 事件报告，始终标记为 `status: draft` 并附带免责声明；受监管内容的后端为付费的可选附加组件（`contracts/reporting.md`） |
| **可选认证** | ✅ 正常工作（v0.4） | 甄别/库存 API 上的共享密钥 `ARGIEM_API_KEY`，可选的仪表板 basic-auth，可选的 Redis `AUTH` —— 未设置（默认）保持完全开放，与 v0.1-v0.3 的行为一致 |
| **Syslog UDP 监听器**（WS-1） | ✅ 正常工作 | 实时数据报 → `raw.events` |
| **甄别工作流** | ✅ 正常工作（v0.3） | 每个警报的状态和分析师备注，通过 WS-3 甄别 API 持久化，可在仪表板中编辑。容器到容器的 Nginx 路径已通过配置审查验证，但尚未通过实际堆栈冒烟测试验证 |
| SNMP 解析器 | 🚧 计划中 | 延期 —— [很好的第一个问题](CONTRIBUTING.md) |
| NetFlow 解析器 | 🚧 计划中 | 延期（二进制格式） |
| 自定义 JSON 解析器 | 🚧 计划中 | 延期 |
## 前置条件
- **Docker Desktop**（或 Docker Engine + Compose v2），并且为 Docker 分配了 **≥ 4 GB 内存**。
- **操作系统：** Linux、macOS 或 **通过 WSL2 运行的 Windows**。（演示堆栈运行 Linux 容器；
预检查和演示脚本是 POSIX `sh`。）
- **Python 3** —— 仅当您想运行契约测试或贡献解析器时才需要。
您**不需要** Docker 即可添加解析器（请参阅[贡献指南](#contributing)）。
## ⚠️ 预检查 —— 启动堆栈前请阅读此内容
在具有默认内核设置的 Linux/WSL2 上，OpenSearch（存储引擎）**将无法启动**。
它需要提高 `vm.max_map_count` 限制。**每台机器运行一次**
（重启后会重置）：
```
sudo sysctl -w vm.max_map_count=262144
```
使其在重启后永久生效：
```
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-argiem.conf
```
`make preflight`（见下文）会为您检查此项，如果有任何缺失，会打印出确切的修复方法。
## 快速开始
```
# 1. 检查您的机器是否已准备就绪（vm.max_map_count、Docker RAM、可用端口）
make preflight
# 2. 启动 full stack
make demo
```
`make demo` 运行预检查，然后使用 Docker Compose 启动所有服务。
所有服务都是长时间运行的守护进程，带有 `/health` 端点和重启策略。
其他便捷的目标命令：
```
make e2e # zero-infra ACCEPTANCE test: SSH brute-force -> real alert (no Docker)
make test # run the full zero-infra contract test suite (no Docker needed)
make up # start the stack detached (docker compose up -d)
make down # stop the stack and remove volumes
```
## 端口
| 端口 | 服务 | 描述 |
|------|---------|------------|
| 6379 | `redis`（`siem-bus`） | 服务间的消息总线 |
| 9200 | `opensearch`（`siem-store`） | 事件/警报存储 + 查询 API |
| 5601 | `dashboards`（`siem-dashboards`） | OpenSearch Dashboards |
| 8000 | `ws6-inventory` | 库存 API（IP/MAC 历史记录） |
| 8080 | `ws7-dashboard` | ARGIEM 警报控制台 |
| 5514/udp | `ws1-collectors` | 实时 syslog 摄取（未认证 —— 仅限受信任的网段） |
| 8013 | `ws3-indexer` | 甄别 API —— **仅限内部**，仪表板通过容器到容器的方式代理到此；不发布到主机 |
`make preflight` 会在您启动前检查已发布的端口是否空闲。
## 如何查看警报
v0.1 的验收测试是一个真实的**暴力破解警报**，而非模拟数据：
1. **信号。** 60 秒内来自同一源 IP 的 10 次失败认证事件。
ARGIEM 从 Linux SSH 的 `Failed password` 行或
Windows 的 `EventID 4625` 生成这些事件 —— 两者都规范化为相同的 OCSF Authentication 事件
（`class_uid: 3002`，`activity_id: 4`）。
2. **规则。** [`contracts/rules/common_bruteforce.yml`](contracts/rules/common_bruteforce.yml)
匹配这些事件，按 `src_endpoint.ip` 分组，具有 `threshold: 10` 和
`window_seconds: 60`。它与来源无关，因此无论在 SSH 还是 AD 上触发效果完全相同。
3. **警报。** 当来自同一 IP 的第 10 次失败落在时间窗口内时，
检测服务会发出一个警报，该警报流向索引器并进入仪表板
警报列表。
查看**整个管道**在**无基础设施**的情况下生成警报 ——
验收测试注入了 10 次失败的 SSH 登录，并断言真实的暴力破解警报
到达索引，并且重放相同的事件会重用相同的警报 ID
（幂等，因此至少一次投递永远不会产生重复警报）：
```
make e2e # or: python tools/demo_e2e.py
```
预期结尾：
```
ALERT: Authentication brute-force from single source src=203.0.113.5 score=70 id=...
T7 OK: replay reused alert_id ... -> deduped (alerts count stayed 2)
[OK] ARGIEM v0.1 acceptance: SSH brute-force -> real alert in the index, idempotent under replay. Zero infra.
```
倾向于单元级别的检查？WS-4 检测契约测试断言规则在第
10 次尝试时触发：`cd services/ws4-detection && python test_contract.py`。
对于完整的 Docker 化堆栈（收集 → 规范化 → 检测 → 索引 → 仪表板），运行
`make demo` 并在 打开仪表板。
## 架构
```
WS-1 Collectors ─raw.events─▶ WS-2 Normalization ─normalized.events─┬─▶ WS-3 Indexer ─▶ OpenSearch
(Cisco ASA / AD / (parsers → OCSF) ├─▶ WS-6 Inventory (IP/MAC)
VMware / Linux SSH) └─▶ WS-4 Detection ─scored.events─▶ WS-3
│ alerts ─▶ WS-3 / WS-7
└─ai.requests─▶ WS-5 AI (stub) ─▶ WS-3/WS-7
WS-7 Dashboard ◀── WS-6 API + alerts
```
服务之间**唯一**的耦合是消息总线。其他一切都是
[`contracts/`](contracts/) 下的冻结契约。所有的源格式异构性都在
边缘被吸收（WS-2 中每个来源一个解析器）；系统的内部只处理单一的
schema（OCSF）。
| WS | 服务 | 角色 | v0.1 状态 |
|----|---------|------|-------------|
| 1 | `services/ws1-collectors` | 收集日志 → `raw.events` | ✅ |
| 2 | `services/ws2-normalization` | 解析器 → 验证过的 OCSF 事件 | ✅（4 个解析器） |
| 3 | `services/ws3-indexer` | 路由 + OpenSearch 索引（幂等） | ✅ |
| 4 | `services/ws4-detection` | 关联规则 + 评分 + 窗口化 | ✅ |
| 5 | `services/ws5-ai` | 甄别 | 🚧 透传存根（AI 在 v0.2 中） |
| 6 | `services/ws6-inventory` | IP/MAC 库存 API（SQLite） | ✅ |
| 7 | `services/ws7-dashboard` | 警报控制台 | ✅ |
有关完整的设计、范围决策和路线图，请参阅
[v0.1 构建计划](docs/superpowers/specs/2026-06-27-argiem-v0.1-build-plan.md) 和
[`docs/PHASE0_README.md`](docs/PHASE0_README.md)。
## 安全性
ARGIEM v0.1 服务专为**localhost / Docker-Compose 网络**设计，并且
**未**针对互联网暴露进行硬化。**v0.1 中设计为没有身份验证**，
并且检测引擎会执行规则文件 —— 因此请仅运行您信任的规则。
有关完整的威胁边界以及如何报告漏洞，请参阅
**[SECURITY.md](SECURITY.md)**。
## 许可证
ARGIEM 采用 **Apache License 2.0** 授权。请参阅 [LICENSE](LICENSE)。
标签：AI风险缓解, OCSF, 安全合规, 安全运营, 扫描框架, 搜索引擎查询, 本地AI, 版权保护, 网络代理, 请求拦截, 逆向工具